All work

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

  1. Save on the wrong side
  2. Link in a button color
  3. 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.

Result
3 or 4 daysfrom Jira story to engineering-ready screen, down from one or two weeks
Role
UX Lead
Context
Mphasis · US health-insurance platform
Timeline
Built Aug to Sep 2026
Domain
Enterprise SaaS · US health insurance
The productOne story in, one screen out. The AI reads the skill files first, builds from real components and checks its own work.Animated in a demo brand. The rules shown are quoted from the skill files.

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 old button's description (as I remember it)

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

Spending account
SaveCancel

Rule in the system: none

0lines saying where Save goes

With the skills

Spending account
CancelSave

“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

in the Figma file · the AI could read itcomponentscolor variablestype styleswhich color is a linkwhich grid per pagehow screens composein designers' heads · never written down, never reached the AIthe AIoff-brandin the Figma file · the AI could read itcomponentscolor variablestype stylesthe AIoff-brandin designers' heads · never reached the AIwhich color is a linkwhich grid per pagehow screens compose
The AI could read every component and variable in the file. The rules for using them were never written down, so they never reached it, and each screen came back off-brand. Illustration with generic names.
What I was asked

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
Select a skill to see what it holds and what it works with.Redrawn with demo brands and illustrative data. No client screens or internal files.

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

  1. 1Read the story“As a member, I want to compare dental plans side by side so I can pick the right coverage.”
  2. 2Classify the pageSecured page · plan comparison
  3. 3Pick the shellapp-shells / secured, two-column
  4. 4Compose approved componentsHeader ◆ Title ◆ PlanCard ◆ ×3 Button ◆
  5. 5Self-verifyRun the checklist before handing back
Replay the run, or switch to the stale system to see how it failed before.Redrawn with demo brands and illustrative data. No client screens or internal files.

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

mebuilt, proved4 designersmy teamthe org's UAT teamchose it for their projectsbusiness analystsnot yet, on purposethe UAT group is not shown to scalemebuilt, proved4 designersmy teamthe org's UAT teamchose it for their projectsbusiness analystsnot yet, on purposenot to scale
No mandate. I built it and proved it, my four designers moved onto it, and a team outside mine chose it for their own projects. Business analysts are held back on purpose: they could mock screens with it, but would likely skip the UX thinking first.

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.