Guide
What is an agentic design system?
A design system that a coding agent can use as well as a person can: it ships the rules, references and checks an agent needs to build screens that stay on brand.The short definition
A traditional design system is written for people: a Figma library, a documentation site, a component package. People learn its conventions over time. A coding agent starts every task from zero, reads only what is in front of it and fills every gap with a guess. Point it at a component library alone and you get screens that compile but drift: one-off spacing, colors outside the palette, custom markup where a component already exists.An agentic design system closes those gaps. Next to the components and tokens, it ships the context an agent needs, in a form it can read in a few steps, and a way to check what it wrote.What makes a design system agentic
Rules an agent can hold in context
The conventions a senior designer would explain in a review, written as a short rules file the agent loads before every UI task: which component to reach for, which props replace custom CSS, what never to do.A catalog to choose from
A machine-readable list of every component, what it is for and how it is imported. The agent picks a Card or a Dialog by purpose instead of inventing a div with a class name.Tokens, not values
Spacing, color, radius and type are named tokens. An agent that writes padding="24" and onBackground="neutral-weak" can't drift off the scale or the palette, and a theme change reaches every screen it built.Examples for the whole task
Agents copy structure well. Complete, reviewed examples for common tasks (a pricing page, a dashboard, a settings form) show how the parts fit together, not just what each part does.A check after the code is written
A validator that reads the generated file and flags props that don't exist, raw HTML where a component belongs and imports from the wrong entry point, so mistakes surface before review.Instructions where agents look
AGENTS.md, CLAUDE.md and editor rules in the project itself, so the agent finds the design system's rules without being told every session.How Once UI does it
Once UI ships an agent harness inside the npm package. An agent reads the rules and one task bundle, writes the screen, then runs the validator.ai/manifest.json
The entry point. Lists every harness file and each package entry point with its exports.ai/rules.compact.md
A few kilobytes of rules, loaded before any UI task.ai/catalog.json
Every component by purpose, with the icon names.ai/tasks + ai/bundles
Intent to task (pricing, dashboard…), then one bundle with every component, type and gotcha that task needs.ai/examples
Gold examples to mimic, plus production blocks for higher fidelity.once-ui-validate-ai-code
Checks a generated file against the spec and the rules.
