CASE STUDYSystem
SagUI: a design system built for AI agents.
A design system with two kinds of user: people and AI agents. When an agent builds a new app, it should assemble SagUI instead of inventing a UI — so the result looks designed, stays accessible, and needs almost no design work afterwards.
- ROLE
- Designer & builder: design, tokens, components, docs, MCP server
- STACK
- Figma variables · React · Tailwind v4 · Radix · Motion · Storybook · MCP
- Production components
- 85
- Primitive → semantic tokens
- 2-tier
- Storybook stories
- 127
- Themes from one token set
- Light + dark

Why I built it
I’ve spent 16+ years designing enterprise SaaS. At 7-Eleven I built 7-UI, which taught me that a design system succeeds or fails on adoption. Tokens and components only matter if the people building products use them correctly.
That “people” now includes AI. More and more UI is generated, not hand-coded — and it fails in predictable ways:
- It invents thingsComponents, variants and props that don't exist.
- It hardcodes valuesHex colors and p-[13px] break theming.
- It driftsEvery screen looks slightly different.
- It forgets accessibilityMissing labels, removed focus rings.
- It can't tell “when not to”A Dialog where a Confirm morph fits.
Agents don’t browse docs; they follow whatever context they’re given, literally. So I designed SagUI so that its documentation is also its instructions.
Five principles
- 01
Constrain, then compose
A finite, well-named set of parts, so assembling always beats inventing.
- 02
Semantic over raw
Every decision goes through a token that says what it's for.
- 03
One source, many surfaces
Figma, CSS, Storybook and MCP all come from the same structure.
- 04
Write for the literal reader
Explicit, testable, always-on rules. When in doubt: ask, don't improvise.
- 05
Quality is built in
Accessibility, keyboard and reduced motion live inside components.
How it’s structured
All five surfaces share one contract: the “Rules for AI” page.
Two layers of tokens
Primitives are raw values with no meaning — color ramps, sizes, radii. Brand 1 is a deep teal that drives the accent; Brand 2 is raspberry for highlights.
Semantic tokens say what a value is for — bg-canvas, fg-muted, accent-default. Components only read these, so a rebrand is a handful of pointer changes.
- Hand-tuned contrastAccent uses brand-1-700 in light, 400 in dark.
- Solid tintsNot transparency, so they hold on any background.
- Paired text-on-fillEach fg-on-* keeps contrast in both themes.
- Radius by rolecontrol · container · overlay · pill — corners stay concentric.
- Fixed scales4 elevation levels, motion tokens, 4px spacing, one type scale.
- Safe migrationOld token names still map to new ones.



85 components, grouped by job
Button, Split, Button group, Copy, Confirm morph
Input, Password, Inline edit, Money, Phone, Tag input, Form
Checkbox, Radio cards, Select, Combobox, Switch, Segmented
AppShell, AppTopBar, Page, Tabs, Stepper, Command palette
Data table, Timeline, Line / Bar / Donut / Treemap, Sparkline
Card, Metric card, Empty state, Alert, Toast
Dialog, Drawer, Bottom sheet, Popover, Tooltip
Approval card — human-in-the-loop questions before an agent acts · Text shimmer · Text morph






Documentation as instructions
Every component is documented the same way — in Figma, Storybook and the MCP response: what it maps to in code, when to use it, when not to and what to use instead, its API, and keyboard, accessibility and motion notes.
“When not to use” turns a list of components into a decision tree.

Rules for AI
The first page of the Figma file. Always on, and enforced the same way in Figma, in code and through the MCP server.
- COMPONENTSUse existing first. Never invent a component, variant or prop. One primary button per view.
- COLORSemantic tokens only. No hex. Dark mode is automatic. Status never by color alone.
- SCALESNo arbitrary sizes, spacing or shadows. Radius by role.
- MOTION · ICONSToken durations, reduced motion respected. Tabler icons; icon-only controls get a label.
- ACCESSIBILITYReal labels, announced errors, visible focus. Non-negotiable.
How an agent builds with SagUI
- 01Discover —
search_componentsfinds the part by job. - 02Learn —
get_componentreturns usage, props, a11y notes. - 03Style —
get_tokensfor anything custom. - 04Check —
validate_usagecatches invented props and raw colors. - 05Set up —
get_installone package, one stylesheet.
Outcomes & learnings
What this enables
- Minimal design effort for new apps
- Consistency by default — no off-system values
- Accessibility you don’t have to remember
- One-line rebrands, in both themes
- Figma, Storybook and MCP in step
What I learned
An agent is the most literal reader you’ll ever have. Vague guidance gets ignored; testable rules get followed.
“When not to use” matters more than “when to use.”
Reach matters. For people it’s Figma and Storybook; for agents it’s an MCP server — docs as a tool call.
validate_usage as a CI checkCode Connect mappings Figma → @sagui/uiMore agent-native patterns