Building an Evolving Design System

None of us are writing that much code by hand anymore. We prompt our favorite agent, and if we're more diligent, we plan, have the agent execute, and have a second agent review to make sure the first one did what it was supposed to do. What would take a whole pod of engineers, PMs, and designers a quarter to execute now gets done in a week by a single engineer empowered to use AI well.

As a UI engineer, a lot of my work can be automated. The aesthetics, the taste, and consistency in that visual output across an engineering team cannot. Not reliably. Not without some creativity.

The old-school fix of having someone from "Frontend" or "Design" double-check every PR, backed by expensive, flaky snapshot tests, can't keep up when output is this fast. So for someone focused on UI quality, the job stops being telling engineers what to fix one-off at a time. It becomes setting up a process that grows with the codebase: steering the agents, and leaving a final review the engineers own.

We were already using Storybook before my time at Mach9. It was buggy, and its directory organization had outgrown how much we were building. The worst part: almost everyone, designers included, ran Storybook locally instead of finding the Chromatic link. The light theme was broken. The dark theme showed components, but all the text was dark gray on top of a darker gray background.

There was dead code, and over 90 color tokens used sporadically. Themed colors were implemented, but the agents writing our code grabbed whatever color token the design system had rather than its themed variant.

The other big issue: we were all iterating on components, making new ones and expanding their variations, but nobody was sure when to create a story, whether something should have a story at all, or what testing belonged around it.

I personally love Brad Frost's Atomic Design principles. I've seen them work on other teams. I've also seen them hit friction once you move past the complexity of Organisms, where things get fuzzy and overbearing to maintain. Templates and Pages are lovely in theory. In practice, they meant slowing down changes and improvements to the UI with all the process.

So I wanted a system based on atomic principles that gave us at Mach9 the flexibility to change it to suit our current needs.

Step one was auditing the existing system. I had Fable, in plan mode, go through the whole frontend codebase and write me a document on the current state of our components: the number and type, which ones seemed similar, and whether they were even used. My prompt:

"Look through Mach9 Storybook and the current code in the main repo. I prefer Atomic principles, but used loosely to best fit the mental model of the team and features.

Give me some suggestions on how to organize the current stories. The suggestions don't have to follow my suggested structure. Also find components that are duplicates or can be combined into variants. Similarly, find colors, sizes, and typography that can be removed or reasonably combined."

Fable came back with a plan outlining three different approaches. This is where the real discussion happened: what we would compromise on and what we wouldn't.

I picked and tuned what I wanted. We kept the Atomic naming, but Templates are examples and docs only. Pages don't need to be a full composition of a page. Instead, they hold complex components specific to a page or feature: not really reusable, but in need of visual documentation so we can share information as the team works across the feature. I even had Fable estimate the work needed to execute each approach, and once I'd picked the one I thought would work best, break it down into smaller issues in Linear.

The first of those issues was to write up the plan and the audit results in Notion, then cut a PR updating our storybook-stories.mdc with the new plan: the directory structure, the Storybook code cleanup, the component consolidation, the color and theme token fixes. I shared it with the designers and the rest of the dev team, tuned it further on their PR feedback, and had Claude update the Linear issues to reflect the required changes.

Once the docs were committed and pushed to main, the big benefit showed up quietly. Even as I worked through the legacy code, slowly moving existing components to the new organization, the Cursor and Claude rules in storybook-stories.mdc did the same for the rest of the dev team automatically. Nobody needed to prompt for it.

The directory restructure, which really was just changing the titles on the stories, went into main next. Then I set up a bot with cosmos.augmentcode.com to run on every PR and check whether new work followed the required Storybook structure, and created component stories and tests as needed.

Our designer had already taken it a step further, adding a baseline UX audit that warned engineers when things like poor contrast or the wrong border outline showed up. My checks folded into that same pass, auditing the quality of the stories generated, and the ones that weren't. It even pushes back on unnecessary new stories and checks whether a story would be better as a variant of an existing component.

By no means is this perfect. The Pages section by far still makes way too many stories. Especially when we're working on a new feature, the AI-generated code opts to create more stories than necessary.

But the best part is that as I edit, audit, and tune our stories through the rest of the Linear issues, I keep tuning the rules for the AI too: improving the quality, and prudently trimming the quantity.

At Mach9, our design system is no longer static. It rarely gets stale as we build new things; it keeps up with the changes the team makes at a rapid pace. Best yet, engineering, design, and less technical teams can view our stories, see changes as they get pushed up, and reuse the components in their own vibe-coded projects, whether that's a demo, an experiment on a feature idea, or a small bug fix. They prompt their agents and reliably get UI built from our design system components.

It is now no longer about building the output, but building a documented system that generates the output. Put the requirements where the code gets written instead: a rules file the agents read before they touch a component, and another agent that checks the result. The human reviewer's job becomes tuning the rules for optimal performance, not catching the same mistake for the fortieth time.