Skip to content
← Work

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
SagUI design system sheets laid out at an angle: typography, color, buttons, radius, selection controls, charts, metrics, inputs, a stepper, agent-native components and the app shell

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

  1. 01

    Constrain, then compose

    A finite, well-named set of parts, so assembling always beats inventing.

  2. 02

    Semantic over raw

    Every decision goes through a token that says what it's for.

  3. 03

    One source, many surfaces

    Figma, CSS, Storybook and MCP all come from the same structure.

  4. 04

    Write for the literal reader

    Explicit, testable, always-on rules. When in doubt: ask, don't improvise.

  5. 05

    Quality is built in

    Accessibility, keyboard and reduced motion live inside components.

How it’s structured

SOURCEtokens.jsonOne structure, matches Figma
DESIGN →Figma variablesAI GUIDELINES in every component
CODE →@sagui/ui85 React components
VISUAL →Storybook127 stories · 32 docs pages
AGENTS →MCP serversearch → get → validate

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.
Color panel: SagUI primitive ramps from the Figma library — brand teal, brand raspberry, neutrals and blue, steps 50 to 950Typography panel: SagUI type roles from display down to titleRadius panel: SagUI corner scale from xs to pill

85 components, grouped by job

BUTTONS

Button, Split, Button group, Copy, Confirm morph

INPUTS

Input, Password, Inline edit, Money, Phone, Tag input, Form

SELECTION

Checkbox, Radio cards, Select, Combobox, Switch, Segmented

APP SHELL

AppShell, AppTopBar, Page, Tabs, Stepper, Command palette

DATA & CHARTS

Data table, Timeline, Line / Bar / Donut / Treemap, Sparkline

CARDS & FEEDBACK

Card, Metric card, Empty state, Alert, Toast

OVERLAYS

Dialog, Drawer, Bottom sheet, Popover, Tooltip

AGENT-NATIVE

Approval card — human-in-the-loop questions before an agent acts · Text shimmer · Text morph

Buttons panel: primary, secondary, ghost and destructive SagUI buttonsSelection panel: SagUI radio cards, chip group and segmented controlData table panel: SagUI sortable data table with status badgesApp shell panel: SagUI app shell with sidebar and overview metricsAgent-native panel: SagUI approval card and command paletteCharts panel: SagUI line chart and donut chart

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.

SagUI component documentation page

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

  1. 01Discover — search_components finds the part by job.
  2. 02Learn — get_component returns usage, props, a11y notes.
  3. 03Style — get_tokens for anything custom.
  4. 04Check — validate_usage catches invented props and raw colors.
  5. 05Set up — get_install one package, one stylesheet.
PROMPT> Build an admin dashboard for refund requestsASSEMBLED FROMAppShell + AppTopBar — framePageHeading — status, actionsMetricCard × 3SortableDataTable — requestsApprovalCard — human decisionToast — confirmation✓ No new design needed. The system made the decisions.

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.

NEXT →validate_usage as a CI checkCode Connect mappings Figma → @sagui/uiMore agent-native patterns
NEXT CASE STUDY · PLATFORMMDM Platform →