Creating an agentic design system
Creating an agentic design system
Creating an agentic design system
Every agentic design-to-code workflow rests on one thing: a design system structured so a machine can reason about it.
Role
Staff Designer
Company
Proctorio
Task
Lead an overhaul of the legacy design system with the goal of aligning with a company rebrand with a new modernized agentic design system.
Stack
Figma, Figma MCP, Claude Code
Role
Staff Designer
Task
Lead an overhaul of the legacy design system with the goal of aligning with a company rebrand with a new modernized agentic design system.
Stack
Figma, Figma MCP, Claude Code
What change is needed
An agent doesn't read your design system the way a huamn does. It needs clear structure, not prose.
An agent doesn't read your design system the way a huamn does. It needs clear structure, not prose.
Three failure points do most of the damage:
raw tokens the agent hardcodes
component docs written for humans
conflicting sources of truth
The fixes:
a three-tier token architecture
JSON component metadata
one canonical source everything else derives from
Fix 1: Tokens the agent can reason about
Raw values are the first thing that breaks. Hand an agent #008b8b and it will cheerfully hardcode that hex in forty places. The moment you rebrand, every one of them is wrong, and no amount of prompting reliably stops it.
primitives
Primitives are raw values — teal-500: #008b8b, space-4: 16px. The agent should never sees these. If it does, it hardcodes them.
semantics
Semantics are intent-named aliases — color/action/primary, color/danger/background. This is the only layer the agent reads and writes. The name describes the job, not the value, so a rebrand updates one alias and everything downstream follows.
component tokens
Component tokens are optional —
button/background/default → color/action/primary. Skip them until you're doing multi-brand work.
Fix 2: Component metadata
Most component documentation is written in prose, for humans. An agent needs a contract with explicit keys, explicit values, no ambiguity. The emerging consensus surfaced across talks from Indeed, GitHub, and others at the AI Design Systems Conference 2026, is: JSON metadata per component, covering four things:
Most component documentation is written in prose, for humans. An agent needs a contract with explicit keys, explicit values, no ambiguity. The emerging consensus surfaced across talks from Indeed, GitHub, and others at the AI Design Systems Conference 2026, is: JSON metadata per component, covering four things:
The four points of context
props
the states and variants that already exist in Figma. Five states in Figma, five states in the metadata. No interpretation.
relationships
what the agent must know before placing the component. Is it a form child? A toolbar item? What can it not sit next to? This is the context a human infers and an agent can't.
tokens
which semantic tokens the component consumes. Load-bearing in an agentic system, not decorative.
usage
what it's for, and the anti-patterns. Not the obvious ones ("don't put two primary buttons side by side"), but the specific ones only your team knows.
An agent can auto-generate the first draft of this metadata, but it comes back about 80% right and 20% generic. It'll list the obvious anti-patterns and miss the ones that actually bite: "never use a destructive button in onboarding," "loading state shows after 200ms, not immediately."
Fix 3: One source of truth
The fix is architectural, not editorial. Pick one canonical source, and for us, the design system components linked to Figma via Code Connect (or rich component descriptions, which do the same job without enterprise tooling).
Everything else derives from it or maps to it. The Figma library, the docs site, the token files: none of them are independent truth. They're all projections of the one contract.
The fix is architectural, not editorial. Pick one canonical source, and for us, the design system components linked to Figma via Code Connect (or rich component descriptions, which do the same job without enterprise tooling).
Everything else derives from it or maps to it. The Figma library, the docs site, the token files: none of them are independent truth. They're all projections of the one contract.
What it changed
The fix is architectural, not editorial. Pick one canonical source and everything else derives from it or maps to it. The Figma library, the docs site, the token files: none of them are independent truth. They're all projections of the one contract.
What it changed
The fix is architectural, not editorial. Pick one canonical source, and for us, the design system components linked to Figma via Code Connect (or rich component descriptions, which do the same job without enterprise tooling).
Everything else derives from it or maps to it. The Figma library, the docs site, the token files: none of them are independent truth. They're all projections of the one contract.
