Legacy design system documentation migration

A top-ranked research university relied on an internal design system to keep a large digital ecosystem consistent. I joined as a contractor during a migration away from a legacy platform that was no longer being maintained.

My job was to bring legacy components and patterns into a modern Astro/Starlight-based documentation site while preserving the output developers still relied on. There was no automated path, limited documentation, and very little room for the new system to drift from the old one.

This was not just a visual migration. The example HTML needed to remain trustworthy when copied into legacy environments, which meant structure and output patterns mattered as much as rendering.

The challenge

The hardest part was that the legacy system still mattered even while the new one was being built.

The new documentation site needed to render components correctly, but the example HTML also had to remain usable when copied into legacy templates. That meant the migration could not focus only on layout parity. It had to preserve the output contract teams were already depending on.

There was also no complete playbook for how to do the migration. A lot of the approach had to be worked out component by component until stable implementation patterns emerged.

Constraints

There was no reliable export/import workflow, so the migration had to be handled manually.

Legacy output needed to remain predictable, documentation examples had to stay aligned with real implementation, and the new doc site needed to be maintainable for a multi-contributor team. As the work progressed, the migration process itself had to become more structured so it could scale.

My role

I supported the migration by moving legacy code and patterns into the new codebase and making sure the results were dependable.

My work focused on translating legacy components into the new system, validating rendered layouts in the Astro environment, and ensuring example HTML still produced the expected outcome in legacy contexts. As patterns became repeatable, I helped turn them into Cursor rules so future implementation could move faster and stay consistent.

Approach

I treated the legacy platform as a contract, not just a reference.

Instead of refactoring too early, I focused on parity: migrate the code, compare the rendered result, verify the example output, and adjust until the new implementation matched expected legacy behavior. That reduced risk and kept the migration grounded in what the team actually needed.

As stable patterns emerged, we pushed toward a cleaner authoring model where components owned markup and documentation passed props into those components. That reduced duplication, made docs easier to maintain, and lowered the chances of example code drifting away from implementation.

Once the workflow proved reliable, I created Cursor rules to reinforce the pattern and speed up future migrations.

Implementation

The new documentation environment used Astro and Starlight, giving the team a modern foundation for component documentation.

Because there was no automation path, the work required manual component-by-component migration, verification of rendered output against legacy expectations, and careful alignment between documentation examples and real component behavior. The goal was to ensure contributors could copy example markup with confidence, even when the target environment was still legacy.

As part of making the effort maintainable, we established a structure where documentation stayed focused on usage and content while the components handled structure and rendering. That helped the site stay consistent as more contributors began migrating additional patterns.

Outcome

The project reduced uncertainty in a migration with no automated path by turning trial-and-error work into a repeatable process.

The immediate value was that the team could continue moving legacy patterns into the new documentation platform with more confidence that rendered layouts and code examples would hold up. Just as importantly, the migration work became easier to scale once the implementation pattern was established and reinforced through conventions and rules.

Why this project matters

This case study shows I do more than front-end development in the narrow sense.

I can step into an ambiguous technical process, work through legacy constraints, preserve critical output, and help shape a system that is more maintainable going forward. That mix of implementation, translation, and process-building is a big part of the value I bring to projects.