How to build an AI-ready design system

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 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.

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.

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:

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 covers the mapping in more detail. If your tooling exchanges token files, use its documented format; the Design Tokens Community Group 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.

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.

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.

{
  "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 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.

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 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.

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

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 — migration strategy and the relationship between tokens, code, and metadata.
• TDP: agentic design-system context — how repository instructions, product context, design rules, and skills fit together.
• TDP: design.md and the component library — keep the entry document light and link to deeper contracts.
• Figma-to-Storybook guide — apply the audit to one component, with the related TDP video walkthrough.
• Component documentation guide — expand the contract and review examples.