The agentic
design system

I watched AI invent the system, live

A routine Claude Code test surfaced the core problem: nothing about Aero was machine-readable.

We pointed Claude Code at a Figma button and asked it to scaffold React and Storybook. It did, in minutes. Then we looked at the tokens: invented. Generic names that don't exist in Aero, color values quietly changed.

There was no machine-readable source to pull from, so it guessed, disclosed it, and kept going. The problem isn't that AI makes mistakes. It's that they look exactly like correct output.

It's already happening, just quietly

Designers prototype with AI that mimics Aero's look but not its structure, adding an invisible rebuild step.

AI defaults to Tailwind and mimics Aero's style, close enough that a PM or engineer in review can't tell. The prototype gets approved. Then someone rebuilds it with the real components. A second pass that shouldn't exist.

Nobody flags it because nothing looks broken. The drift is in the process, not the output.

The diagnosis, seven years in

Every adoption failure traced to one root cause: the system was never documented in a way anyone could reason from.

Tokens had no usage guidance. Components had no intent. The rules lived in people's heads and Slack threads. A group product manager named the cost in a leadership meeting:

He was right. Aero lives across 30+ micro-frontends, each pinned to a different version, with no governance layer to push a change automatically. The git history makes it sharper: the React DS repo peaked near 150 commits in January 2024, then dropped about 97% by mid-2024. One engineer has held it together alone since. The AI tools didn't create this problem. They made it impossible to ignore.

Everything was already here, just unconnected

The pieces existed at SpotOn. The missing one was the context layer that makes them legible.

A semantic token architecture, Token Alchemy in production, a hackathon MCP (13 tools, 7 prompts, on a branch), a token overhaul in motion. All unwired.

I wrote the diagnosis and brought one slide to my manager and the VP of Design. Without documentation: 47 tool calls, 3m 24s, wrong names. With v2.0 governance: 0 tool calls, 34 seconds, correct tokens, flags unknowns instead of guessing. That was the sign-off.

The plan: make the system legible, then let it maintain itself

A five-stage roadmap from written documentation to a self-maintaining system.

1. Foundation encode token and component decisions into writing, readable by humans and machines (live now)
2. Connected wire the hackathon MCP to that metadata; search-miss logging becomes the roadmap
3. Unified ship v2.0 docs alongside the Token Alchemy overhaul, not after
4. Observable drift detected automatically; a health dashboard shows compliance; VQA becomes a parity check
5. Agentic agents detect drift, suggest fixes, scaffold components; the lead role shifts to strategy

Stage 1 is live: 110 semantic token descriptions and the first component intent files. What that looks like in practice:

aiHints: {
  priority: "high",
  keywords: ["button", "action", "click", "submit", "cta", "delete", "confirm", "destructive"],
  context: "Use Button for any user-triggered action. Choose variant by emphasis:
            filled > tonal > outlined > text. Add destructive=true for irreversible
            actions. Do not use GhostButton in V2 work, it has no V2 equivalent.",
},

antiPatterns: [
  {
    scenario: "using multiple filled buttons in the same action zone",
    reason: "Two filled buttons create ambiguity about which is the primary action.",
    alternative: "Use one filled (primary) and one tonal or text for the secondary.",
  },
  {
    scenario: "using deprecated variant aliases ('primary', 'secondary', 'tertiary')",
    reason: "These are deprecated and may be removed in a future release.",
    alternative: "Use 'filled', 'tonal', and 'text' respectively.",
  },
]

Documentation written so a designer onboarding and an AI assistant reason from the same source, and get the same answer.

Foundation → Connected → Unified → Observable → Agentic

And the job changes from documenter to architect

When generation is cheap, the scarce skill is defining what correct means and encoding it in advance.

The bottleneck shifted from production to judgment. The work moves from documenter to encoder, reviewer to rule-writer, gatekeeper to architect.

Teams who've done this already have the numbers

Teams who built this report large drops in support load and big time savings.

A 70-80% drop in DS support questions (Miro), around 450 hours a year saved on asset management (WhatsApp), 30 components scaffolded in two weeks (Enara Health).

Most teams start with the MCP and hope the docs catch up. I'm building the documentation layer first, so the MCP has something real to query.

Data from Into Design Systems, 2026.