Tailwind Design System

Starting with an honest audit

Before designing a single token, I audited the product as it actually existed. I captured every screen, pulled every color value out of the codebase, and grouped components that were meant to be the same thing. The results made the case on their own: dozens of near-identical grays, inconsistent spacing values, and four different buttons doing one job.

I shared the audit with engineering leads instead of a proposal deck. Seeing the inconsistency side by side did more to win buy-in than any argument about efficiency.

Rolling it out without stopping the product

A full rewrite was never on the table; the product had to keep shipping. We agreed on an incremental approach:

• New work uses the system. Every new feature is built with system tokens and components from day one.
• Touch it, migrate it. When a squad changes an older screen, moving it onto the system is part of the work.
• Tokens first. Colors, spacing and typography were migrated globally early on, so even untouched screens moved closer to consistency.

Bridging two very different tools

The hardest technical problem was keeping Figma and code genuinely in sync. The Tailwind config is the source of truth, but Figma’s variables don’t speak OKLCH natively, so tokens had to be converted carefully to stay visually identical in both places. Rather than maintain that mapping by hand, we generated it from the config, so changes flow from code into the design file and never the other way around.

The human side mattered as much. Engineers were wary of a designer-owned system slowing them down. Building it in their language (utility classes, small composable components, documented props) and reviewing component pull requests together turned it into a shared project rather than a mandate.

A system owned by design and engineering together

The system only works because engineering treats it as theirs too. I held a regular sync with the front-end leads to review upcoming work, agree on new components before anyone built a one-off, and retire patterns that had stopped earning their place.

Design QA moved into the pull request. Instead of comparing screenshots after release, I reviewed component changes alongside engineers, which caught drift while it was still cheap to fix and helped me understand the constraints they were working with.

Documentation was written for both audiences. Each component entry explains when to use it and when not to, shows the Figma and code versions side by side, and lists its props and variants. New engineers now learn the product’s visual language from the registry rather than by copying whatever screen looks closest.

Keeping it alive

A design system that isn’t maintained becomes another source of drift. New components follow a lightweight path: a proposal with real use cases, a build reviewed by design and engineering, and documentation in the registry before release. That same registry later became the foundation of the AI Figma Plugin, the clearest sign the system was built on solid ground.