Taking a design system to 1.0

What needed to change

When I joined, the initial system had been assembled in roughly a month. There were components, tokens, Figma designs, and an early Storybook, with a short deadline to finish coverage and get components into products. I joined that effort, building components and supporting infrastructure.

Some components accepted style overrides and others didn't. Common variants were missing, and APIs had accumulated props that made them confusing. Some components were application-specific wrappers whose place in the shared library needed reconsidering.

Deciding what belonged in 1.0

I had broad latitude to decide the technical scope. We made styling overrides more consistent, added common variants, and simplified APIs. We also reviewed what belonged in the shared core, consolidating components and separating out application-specific wrappers. Alongside that work, the team improved Figma/code consistency, documentation, and accessibility, with WCAG AA as our target.

Completing the migration

The API changes included breaking changes. We made it possible to import old and new versions together, so teams could move components over incrementally rather than upgrade an entire application at once.

We supplied a migration guide, a codemod, and dedicated support. We also got into consumer code ourselves and submitted pull requests to keep the work moving through completion.

Other selected work

Icons that only bundled what you used

I owned an earlier icon-library overhaul, from implementation through migration support. Icons had inconsistent sizes and variants, incomplete Figma coverage, and no documentation. Using one icon could pull the entire collection into a bundle.

A generation script produced consistent React components and Storybook documentation from SVGs. The library covered the full Figma inventory and supported tree-shaking, so applications only bundled the icons they used. We kept a comparable API: migration mostly meant changing imports and, for some design-system components, an icon property.

Packaging for teams outside the monorepo

Most unauthenticated flows lived in other repositories, and the library wasn't initially packaged for those teams to use. I reworked its entry points to avoid unnecessary bundle growth and provided compiled JavaScript with CommonJS compatibility. We later added build conditions for both native TypeScript and compiled JavaScript consumption, distributing packages through private npm in Artifactory.

I worked with engineers on those teams to test and adjust the package against their applications while maintaining compatibility.