ash burkeThe problem
The product had outgrown its system
Components lived in three places (Figma, the codebase and a README) and none of them agreed. Nobody could trust the documentation, so designers redrew what already existed and engineers rebuilt it.
The cost showed up on the dashboard. It was redesigned by hand, even though all 19 of its components already existed in code. The result drifted in every dimension at once, and none of it was caught until build.
At the same time we were moving onboarding to an AI-led experience. A system humans couldn't keep straight was never going to guide an AI model either.
My role
Sole designer on the rebuild, from audit to contribution rules.
I audited what existed, defined the token and component architecture, built and documented the system with Claude Code, and set the rules for how Design, Product and Engineering contribute to it. Engineers reviewed and merged; product helped prioritise.
The approach
Five moves
- 01
Start from the code, not the file
I used Claude Code to read the live codebase and inventory every component, prop and style in production. The audit took days, not weeks, and gave us one honest list.
- 02
Build atomically: tokens → components → patterns
136 tokens for colour, spacing, radius, type and icons, then components on top. 31 primitives cover what every screen needs, so nobody draws a button by hand again.
- 03
Make the documentation machine-readable
Docs are generated from the compiled component and indexed by need (“nothing to show”, “status”, “feedback”). The catalogue that helps a new designer is the one an AI model reads.
- 04
Make drift impossible to miss
The catalogue regenerates when the system changes, and refuses to publish if the guide names a component that doesn't exist. Every design passes eight checks before handoff.
- 05
Close the loop with Claude Design and Claude Code
Designers compose from published components. Anything missing is marked as a proposed component with a spec. Handoffs become implementable briefs, not pictures.
run the checks on a sample screen.
Key decisions
What I chose, and what I gave up
Code as the source of truth
Figma-first was familiar, but it recreates the gap we were closing. Docs generated from compiled components can never claim something the code doesn't do.
Organise by need, not by history
Components were grouped by where they came from. Nobody looking for an alert would find one. I kept the old groups for engineers and added a need-based index for designers and AI.
Unmarked drawings are a bug
The dashboard drifted because a hand-drawn component looked identical to a real one. Marking every proposed component turned an invisible problem into a visible backlog.
Rules over policing
Contribution and update rules shared by Design, Product and Engineering took inconsistencies down 40%, and let the system keep up as the product changes.
How I used Claude Code
My job was the architecture, the judgement calls and the review. Claude did the volume.
I used Claude Code to audit the codebase, scaffold components against the token scales, write the catalogue generator and the design checks, and package the system as skills that Claude Design and Claude Code load when someone designs or builds a screen.
{
"name": "EmptyState",
"need": ["nothing to show"],
"props": {
"title": "string",
"action": "Button?"
},
"source": "compiled"
}
One source, two readers.
The same workflow now runs my day-to-day design: one pass does ideation, a copy check against Swoop's tone of voice and a prototype build, cutting concept-to-prototype from two days to about 30 minutes.
Results
to an engineering-ready system: 87 components, 31 primitives, 136 tokens
design-to-build inconsistencies after contribution rules were introduced
from concept to prototype, down from 2 days
mapped, so new screens hand off to Claude Code with every component resolved
underpinning the new AI-led onboarding
What I'd do next
The biggest risk to any design system is that it quietly goes stale. Ours now fails loudly when it does, but regeneration still depends on someone remembering to run it. Next I'd move it into CI so the catalogue rebuilds on every merge, and add usage analytics to see which components teams reach for, and which they work around.
Up next · Swoop · 2025