Design systems
Rewriting our design system so AI tools can follow it
Our AI tool kept putting Save on the wrong side.
It had no way to know our rules, so I wrote them down. Then its screens matched our product.
3 or 4 daysfrom Jira story to engineering-ready screen, down from one or two weeks
The same request, given to the AI twice
Before the skills
- Save on the wrong side
- Link in a button color
- Side nav left out: docs said 19 components, the file had 20
With the skills
- Save on the right
- Link takes the link color
- Side nav in place: audit matched docs to file, 20 of 20
Illustration in a demo brand, not a client screen.
The AI kept generating screens that didn't look like ours
Sales demos and handoffs from business analysts to developers both had to wait on mockups. Developers judge whether something is feasible from screens, not from specs, and slow demos slipped in the middle of live sales cycles. Every mockup drawn by hand pulled a senior designer off product work, so I brought in AI to speed things up. The screens it made weren't usable.
The first one put Save on the left. Every designer here puts it on the right.
Button · Description
The habit lived in our heads, and now it's one line the AI reads before every screen.
Where the AI put Save on the same panel
Same requestSame componentsdifferent rules
Before the skills
Rule in the system: none
0lines saying where Save goes
With the skills
“Primary on the right, Secondary on the left.”
1line, now in a skill the AI reads first
Illustrations with generic names, not client screens. Quotes come from the skill files.
Nothing in our Figma file told it otherwise. The system was six years old and its components had no descriptions, so rules like where Save goes or which color a link takes lived only in designers' heads. The AI could read every component we had, but none of our rules.
Diagram · what the AI had to work with
The AI isn't good enough yet, so prompt harder.
Our design system was never written down in a way a machine could follow.
I rewrote the design system instead of tuning prompts
The expected answers were to wait for better AI, write better prompts, or hire more designers. A better prompt would have been fine if I only had to design one screen, one time. But this was never one scenario. The designers on my team and I would be using it many times a day, for all kinds of screens.
So my gut said the only way was to build a system first, then plug in skills that could give us the right result every time. Nobody had asked for that, and I couldn't find anyone who had made a six-year-old design system readable by AI, so there was no process to follow. I decided to build one anyway.
I wrote the rules down as skill files, starting from tokens
An AI agent doesn't need to know how many components you have. It needs the rules, like which color a link takes or which grid a page sits on. I could have added richer descriptions in Figma and hoped the agent worked out the rest, but I wrote the whole system as a set of linked skill files in plain markdown instead.
I started with tokens and built up from there, so every component knows which tokens it uses and the system stays consistent as it grows. One system now themes five client brands through modes, with semantic colors, type named by use, a 12-column grid, 43 component sets, 3 density modes and 141 described variables.
The skill library
A design system an agent can read
ReferenceWhat the system is
BuildHow to make a screen
UpkeepHow it stays honest
Build · build-screen.md
The workflow: read the Jira story, classify the page, pick the shell, compose approved components, then check its own work.
Works with
- brands, by mode
- 5
- component sets
- 43
- described variables
- 141
- density modes
- 3
- column grid
- 12
I made the AI build from real components and check its own work
Even with the tokens, grid and components written down, the output still broke. The screens looked fine at a glance but weren't actually wired to the system, so I fixed three things.
Composition
App shells and a build workflow. The AI picks the shell, uses only approved components and runs a checklist before it's done.
A system that can grow
The skills say when to reuse a component, when to add a variant and when to build something new.
Instances, not redraws
AI agents like to redraw elements from scratch. Now every element is a real instance, which is cheaper and traceable.
Build-screen workflow
From Jira story to a verified screen
- 1Read the story“As a member, I want to compare dental plans side by side so I can pick the right coverage.”
- 2Classify the pageSecured page · plan comparison
- 3Pick the shellapp-shells / secured, two-column
- 4Compose approved componentsHeader ◆ Title ◆ PlanCard ◆ ×3 Button ◆
- 5Self-verifyRun the checklist before handing back
Waiting for the story…
I kept the skills portable, so any AI tool can use them
We were using Figma's agent, which was free while it was in beta, and beta pricing ends. So I kept the skill files in plain markdown that any agent can read. They run on Figma's agent today and can move to Claude Code or another agent through a Figma MCP.
I also had to stop the new system drifting the way the old one had. Even with the rules written down, the docs once said 19 components while the file had 20. Unchecked patches like that are how the old system drifted, so now an audit compares the docs with the file every session, and a memory skill carries decisions forward.
What changed
New-client and demo mockups used to take about two days, and now they take three or four hours. Working with business analysts, a Jira story gets to an engineering-ready screen in three or four days instead of one or two weeks. Overall we spend about 40% less time on design production, and one system covers five client brands and three platforms.
The AI drafts the screens and designers make the decisions, and the time we save goes into research, flows and edge cases. All four designers on my team use it, and the organization's UAT team chose it for their projects too, without me having to sell it.
I built it in four to five weeks across five brands and three platforms, and I could do it again in one or two. These figures are what the team has seen. Managers, business analysts and leadership have recognized them, but they're not in our sprint metrics yet.
Diagram · how it spread
What I'd do differently
Nobody asked me to build this. I built it, proved it, then brought the team in. I haven't handed it to business analysts yet, and that's on purpose, because I think they'd likely skip the UX thinking that has to come before the screens.
If I started again, I'd track before and after from day one, so the gains were measured and not just acknowledged.