# How to build an AI-ready design system

An AI-ready design system exposes its implemented components, semantic tokens, and usage rules in forms an agent can inspect. Audit one flow, document the components it needs, and test whether an agent can reuse them correctly before migrating more screens.

By The Design Project. Updated 2026-10-21.

## What you will make

A small, documented component set and a repeatable reuse test.

## Before you start

- Access to the implemented component library
- A representative product flow
- Agreement on which design and code sources are authoritative

## What makes a design system AI-ready?
An AI-ready design system gives people and coding agents a dependable route from a product requirement to approved tokens, components, and behavior. It combines working code with usage rules, examples, and checks. The goal is to make the correct implementation discoverable and reviewable, rather than relying on an agent to infer your conventions from screenshots.

A Figma library can show what a button looks like. The implementation determines what that button actually does. A component contract explains when to choose it, which combinations are supported, and what to avoid. Your system needs all three to agree. Giving an agent access to Figma or a repository does not resolve disagreements between them.

TDP’s [AI-ready design system article](https://designproject.io/blog/ai-ready-design-system/) introduces the migration approach. This walkthrough turns it into a practical project: audit one flow, repair its foundations, document one component, and prove that another person or agent can build with it. The sample paths and specifications below are illustrative; adapt them to your existing stack.

## Diagnose the problem before rebuilding
When generated screens drift, first identify what the agent could actually find. A new button may mean the approved one was undocumented, inaccessible, unsuitable for the task, or simply ignored. Each diagnosis needs a different fix. Installing another library will not repair missing product decisions.

| Symptom | Evidence to collect | First intervention |
| --- | --- | --- |
| New hardcoded colors appear | Compare the generated diff with the token source | Make semantic roles discoverable and check token usage |
| A second button implementation appears | Look for existing exports and the agent’s imports | Document the approved import path and examples |
| Figma and production disagree | Capture the same component, theme, and state in both | Resolve the disagreement with the component owner |
| The default state works but errors fail | Exercise loading, empty, error, and permission cases | Add state requirements and representative stories |
| Different agents make different choices | Inspect the instructions each host actually loads | Establish a tested entry point for each tool |

Treat this as an evidence exercise. “The system is old” is too vague to guide a migration. “Our invite form uses three field implementations and none documents server errors” gives the team a bounded place to begin.

## Step 1. Inventory one complete product flow
Choose a flow small enough to understand but rich enough to expose real behavior. Inviting a teammate is a useful exercise: it includes a field, a role choice, submission, feedback, and a permission rule. Capture the current screen and the states around it before changing anything.

Record the actual implementation paths. If the product imports `Button` through a package export, record that public import as well as the source file. An agent should not have to guess whether to import an internal file, recreate the control, or use an older package with the same name.

```text
Audit the invite-member flow without modifying files.
For each component, report:
- source file and public import path
- matching Figma component and story, if available
- tokens and supported states
- duplicates or conflicting definitions
- evidence for each finding
Separate verified facts, recommendations, and unknowns.
```

The deliverable is an inventory, not a redesign. For every disagreement, name an owner and a decision. Keep a screenshot or source reference beside the finding so someone else can reproduce it. If the agent cannot access Figma, label that part of the audit incomplete; a repository-only answer is not a cross-tool comparison.

## Step 2. Repair token relationships before styling components
Start with the difference between a primitive and a semantic token. A primitive stores a value, such as a particular orange. A semantic token names a job, such as an action background. Several semantic tokens may resolve to the same primitive while retaining different meanings.

In TDP’s Figma-to-Storybook demonstration, the audit found semantic colors using raw values, incomplete primitive coverage, opacity differences, and duplicate tokens. The useful lesson is the sequence: inspect first, propose mappings, apply a small approved change, then inspect again. The demonstration also shows that a generated swatch can render incorrectly even after the agent reports progress.

Use an audit table that preserves meaning:

| Semantic role | Current source | Proposed mapping | Decision needed |
| --- | --- | --- | --- |
| Primary action background | Raw color | Approved brand primitive | Confirm theme-specific choice |
| Error surface | Tinted raw color | Error surface token | Confirm opacity and background |
| Secondary text | Shared gray primitive | Keep current role | Verify contrast in each theme |
| Divider | Same value as field border | Keep separate semantic names | Different roles may diverge later |

Do not merge two roles just because their colors match today. A divider and an interactive control boundary can require different treatment. Likewise, a light-mode value is not automatically a dark-mode value. Review the foreground, background, and state together.

The [semantic color token guide](https://designproject.io/resources/guides/create-semantic-color-tokens/) covers the mapping in more detail. If your tooling exchanges token files, use its documented format; the [Design Tokens Community Group format](https://www.designtokens.org/tr/2025.10/format/) is a reference for typed tokens and aliases, not a requirement to rename every existing file.

## Step 3. Choose a migration boundary
If the existing components can support the intended behavior, improve them in place through focused pull requests. If a replacement is justified, isolate it in a sibling package or another explicit boundary. TDP’s migration article uses a sibling package so the team can develop the new system before switching production consumers.

```text
packages/
  ui/                 existing production components
  ui-next/            proposed replacement, if needed
    tokens/
    components/
    stories/
```

A sibling package is an option, not a default requirement. It introduces temporary duplication and needs a retirement plan. Before using it, agree on which flow will migrate first, which package owns shared tokens, and how to reverse the consumer change if a regression appears.

Avoid combining a framework migration, a brand redesign, and a new documentation system in the first pilot. It becomes difficult to tell which change caused a problem. Keep the initial objective concrete: the invite flow should use approved components and preserve its current product behavior.

## Step 4. Write a component contract that answers decisions
Choose one component and document the questions a designer or engineer would ask before using it. A list of props is necessary, but it does not explain purpose. A button with a `destructive` variant still needs guidance about consequences, placement, and the surrounding confirmation flow.

In the Figma-to-Storybook walkthrough, Dianne compares the design with the existing implementation before building. The audit surfaces conflicting dimensions, colors, typography, missing pressed states, and unclear usage rules. Those are design decisions for the team to resolve. The agent should present evidence and recommendations, not silently choose whichever source it finds first.

| Contract area | What to record | Button example |
| --- | --- | --- |
| Purpose | The job this component serves | Trigger an action; use a link for navigation |
| Anatomy | Named parts and their relationships | Container, label, optional leading icon |
| Properties | Allowed inputs and defaults | Variant, size, disabled state, label |
| States | Appearance and behavior together | Focus remains visible; unavailable actions do not activate |
| Composition | Where it belongs | Form footer or dialog actions |
| Invalid combinations | Unsupported or misleading configurations | Two competing primary actions in the same decision group |
| Content | Label and icon rules | Use a specific verb; name icon-only actions |
| Evidence | Source and approval | Implementation, design reference, decision record |

Keep the contract close to the implementation. JSON, TypeScript metadata, Markdown, and JSDoc can all work; choose a representation your team can maintain. A file named `meta.ts` has no special ability to enforce rules by itself.

```json
{
  "component": "Button",
  "source": "src/components/ui/Button.tsx",
  "importFrom": "@product/ui",
  "purpose": "Trigger an action",
  "variants": {
    "primary": "The main action within one decision group",
    "secondary": "A supporting action",
    "destructive": "An action with a destructive consequence"
  },
  "alternatives": {
    "navigation": "Use the approved Link component"
  },
  "examples": "src/components/ui/Button.stories.tsx",
  "openQuestions": ["Confirm the pending-state behavior with engineering"]
}
```

This sample intentionally leaves an unresolved question visible. Do not turn a plausible assumption into an approved requirement. Once the team decides, update the implementation, stories, and contract together.

## Step 5. Connect product context to the system
Keep the entry document short enough to navigate. Product context explains the audience, goals, constraints, and approved feature behavior. Design context explains the visual rules and where the components live. Task-specific procedures belong in skills or focused workflow documents.

TDP’s [agentic design-system context article](https://designproject.io/blog/agentic-design-system-context/) separates these responsibilities into repository instructions, skills, product direction, and design rules. The important relationship is routing: the agent can find the right depth when it needs it.

```text
Before implementing UI:
1. Read PRODUCT.md for audience, constraints, and product intent.
2. Read DESIGN.md for tokens and component discovery.
3. Open the contract and examples for components you will use.
4. List conflicts or missing behavior before changing those decisions.
5. Report the source files consulted with the implementation summary.
```

Put that instruction in the entry point your agent host supports, and test that it loads. Different tools have different discovery mechanisms. Simply creating `design.md` does not prove the agent read it. Ask for the relevant file paths and compare the generated code with them.

## Step 6. Make examples inspectable in Storybook
A component library becomes easier to review when its states are reproducible. Show a default example, meaningful variants, longer content, unavailable states, and the surrounding layout that affects hierarchy. Select states your product supports rather than generating every theoretical combination.

Storybook can combine generated documentation with additional prose and examples. Its [documentation guide](https://storybook.js.org/docs/writing-docs/index) explains those building blocks. Use the configuration appropriate to your installed version and framework; this guide does not require a particular addon or API version.

For the invite flow, review the field with a real label and error message, the action group inside a dialog, and the feedback after submission. A button that looks correct in isolation can still compete with another primary action when placed on a page.

Write down what each story proves. “Long label” should reveal wrapping or truncation behavior. “Permission denied” should make the blocked action and explanation understandable. Stories are review fixtures; they do not replace application-level permission enforcement or a complete user-flow test.

## Step 7. Run a bounded agent pilot
Give the agent the original flow and ask it to build with the documented system. Avoid including every answer directly in the prompt: the pilot should test whether the agent can discover the rules, not whether it can copy a fully specified screen.

```text
Implement the invite-member flow from the approved feature brief.
Use the existing token source and component library.
Before editing, identify the components and contracts you will use.
Do not create a new variant to resolve an undocumented product decision.
After implementation, report:
- changed files and reused components
- checks run and observed results
- remaining questions or unsupported cases
```

Review two tracks. First inspect the code: imports, raw values, duplicate implementations, and unsupported variants. Then use the running interface: keyboard order, labels, errors, permission behavior, and the final outcome. A successful build answers a different question from a successful task.

Record the failure at its source. If the agent invented a control because the component index omitted it, fix discovery. If the right component lacks an error state, fix the component. Repeating “follow the design system” will not repair either issue.

## Step 8. Expand with an owner and a maintenance loop
Only expand after the pilot can be repeated by someone who did not write the documentation. Add the next flow using the same inventory and decision process. Reuse the contract structure while letting the content vary: a combobox needs different interaction rules from a static badge.

Make system changes part of ordinary review. A new supported variant should include its implementation, guidance, and example. An approved product rule should update the feature brief. Retired components need a migration instruction so agents do not rediscover them as attractive alternatives.

Track useful evidence over successive tasks: which components were reused, which rules were missed, and which questions required intervention. These observations can show whether the system is becoming easier to use. They are more informative than claiming that a particular metadata format guarantees correct output.

## Troubleshooting common failures
| What happened | What to inspect | Practical response |
| --- | --- | --- |
| Agent says it followed the system but creates new CSS | Actual imports and token references | Compare the diff with approved examples |
| Metadata contradicts the implementation | Contract history and current code | Resolve ownership, then update both in one change |
| Figma audit returns only repository findings | Integration access and referenced node IDs | Re-run the missing inspection explicitly |
| A story passes but the feature fails | Application context and acceptance criteria | Test the complete task with realistic data |
| Instructions grow into an unreadable document | Repeated details and stale decisions | Keep a short index and move detail beside its source |

## Completion checklist
- The pilot flow has an inventory with real design and implementation references.
- Semantic tokens describe roles and retain intentional theme differences.
- Each pilot component has an approved contract and runnable examples.
- The agent’s entry point routes to the relevant product and design context.
- Code review and functional review both have recorded evidence.
- Open decisions have owners; migration has a rollback path.
- Another teammate can repeat the workflow without a verbal explanation.

## Common questions
### Do we need shadcn/ui to build an AI-ready design system?
No. TDP’s migration article uses it as one implementation approach. The broader requirement is a maintained library with discoverable tokens, contracts, examples, and checks. Evaluate your current components before replacing them.

### Should Figma or code be the source of truth?
The shipped implementation determines runtime behavior. Figma can express approved design intent that has not yet reached production. Record which source is authoritative for the decision being made, and resolve conflicts explicitly. Declaring one tool universally correct can hide real drift.

### How much documentation is enough?
Enough for another contributor to select and compose the component without guessing about behavior. Start with the questions exposed by one real flow. Add detail when an observed failure shows it is missing, and remove duplicated information that is maintained elsewhere.

### Does machine-readable metadata guarantee consistent AI output?
No. It makes the intended rules available. The agent still needs to retrieve them correctly, interpret the task, and produce a result that passes review. Keep the human decision points and verification steps visible.

## Sources and next steps
- [TDP: AI-ready design systems](https://designproject.io/blog/ai-ready-design-system/) — migration strategy and the relationship between tokens, code, and metadata.
- [TDP: agentic design-system context](https://designproject.io/blog/agentic-design-system-context/) — how repository instructions, product context, design rules, and skills fit together.
- [TDP: design.md and the component library](https://designproject.io/blog/design-md-component-library/) — keep the entry document light and link to deeper contracts.
- [Figma-to-Storybook guide](https://designproject.io/resources/guides/figma-to-storybook/) — apply the audit to one component, with the related TDP video walkthrough.
- [Component documentation guide](https://designproject.io/resources/guides/document-component-library/) — expand the contract and review examples.


## Don't Build a Design System from Scratch (Advanced Claude Code + Figma Workflow)

See an advanced Claude Code and Figma workflow for an existing design system. Use it as context for auditing and extending the components you already have.

[Watch the TDP walkthrough](https://www.youtube.com/watch?v=B7xXKTfBxhE)

## Related guides

- [How to document a component library for people and AI](https://designproject.io/resources/guides/document-component-library/)

- [How to write a design.md file: a step-by-step guide](https://designproject.io/resources/guides/write-design-md/)

- [Figma to Storybook: document and build one component](https://designproject.io/resources/guides/figma-to-storybook/)

[Product design glossary](https://designproject.io/resources/glossary/)

Canonical: https://designproject.io/resources/guides/build-ai-ready-design-system/

## Keep learning

- [How to write a design.md file: a step-by-step guide](https://designproject.io/resources/guides/write-design-md/)
- [Figma to Storybook: Build a component library AI can use](https://designproject.io/blog/figma-storybook-ai-components/)
- [Extract a design system](https://designproject.io/resources/skills/extract-design-system/)