Marcus Andrey Study
Ler em português Library

AI for UX · Step 2 · 5 min read

AI-ready design systems

AI tools now read your design system to generate screens and code. What makes a system readable by machines as well as people: tokens in the DTCG format, components linked to code, files structured with intent, written usage rules, and connectors such as MCP. With a checklist to audit your own.

Your design system has a new reader. When a designer asks an AI tool to "build this screen with our components", the tool reads your files, your tokens and your docs, and copies what it finds, including the mess. A system with clear names, linked code and written rules gets used correctly. One that lives in people's heads gets guessed at. Making a system AI-ready is mostly the same work that makes it good for people, done more carefully.

What you'll be able to do after reading:

  • Explain what AI tools read from a design system, and how
  • Describe tokens in the DTCG format and why a standard format matters
  • Prepare Figma files, components and docs so AI uses them correctly
  • Audit your own system with a short checklist

Products and versions are as of November 2026; the field moves fast.


1. What AI tools read

1Tokens

Named decisions as data, with descriptions.

DTCG 2025.10 JSON
2Components

Linked to real code, with variants and states.

Code Connect, Storybook
3Files

Components, variables, auto layout, real names.

No "Frame 427"
4Rules

When to use, when not, what instead.

Usage lines, examples
5Connectors

How AI tools reach all of the above.

MCP servers, context files
Five layers an AI tool reads from your design system. Each gap becomes a guess. Diagram: Marcus Andrey, CC BY 4.0.
Wooden drawers of a library subject catalogue, each with a printed label; one drawer is open, full of index cards.
A subject catalogue works because every drawer is named the same way and every card follows the same format. A design system readable by AI needs the same discipline. Photo: Dr. Marcus Gossler, Wikimedia Commons, CC BY-SA 3.0.

2. Tokens in a shared format (DTCG)

Design tokens are the named decisions of your system: colours, type, spacing, radii. The W3C Design Tokens Community Group published the first stable version of its format, 2025.10, on 28 October 2025 (announcement). Tokens are JSON files (.tokens or .tokens.json), each with a value, a type and an optional description (format).

{
  "color": {
    "action": {
      "primary": {
        "$type": "color",
        "$value": "#1F5BD6",
        "$description": "Primary buttons and links. Never for errors."
      }
    }
  }
}

Note the honest label: it's a "Final Community Group Report", not a W3C Standard. It's still the format most tools now read and write. The $description is where you tell people, and machines, how to use the token.


3. Components linked to code

  • Figma Code Connect links each Figma component to the real code component, so AI tools and developers see your actual code instead of a guess (docs). It needs a Dev or Full seat on a Professional, Organization or Enterprise plan; Professional is limited to one library and one framework.
  • The Figma MCP server (beta since June 2025) gives AI tools your design context, variables and Code Connect mappings, and can also write to the canvas (docs). See MCP and Figma AI.
  • Storybook's MCP add-on (preview, React first, since March 2026) lets agents read your documented components and stories (docs). shadcn/ui has an MCP server that works with any compatible component registry, including private ones (docs).

4. Files structured with intent

Figma's own guide for better AI-generated code asks for: components instead of loose layers, variables instead of hard-coded values, purposeful layer names, auto layout, and annotations for behaviour (Figma, Structure your Figma file). None of this is new. AI just makes the cost of skipping it visible on every generated screen.


5. Rules written for a reader who can't ask

  • A usage line per component: when to use it, when not to, and what to use instead.
  • States and content rules next to the component: empty, loading, error, long text.
  • A project-level brief for AI tools. Google Labs' DESIGN.md is an early format "for describing a visual identity to coding agents" (version alpha, Apache 2.0, GitHub); AGENTS.md and CLAUDE.md do the same for rules in general. See Context files.
  • Examples of good use, not only the component in isolation.

Most guidance on writing docs for AI still comes from tool vendors (Figma, Storybook). Treat it as a starting point and test what works with your tools.


6. Common mistakes

  • Detached instances and hard-coded colours: the AI copies them.
  • Layer names like "Frame 427".
  • Tokens without descriptions, so the AI picks by colour, not by meaning.
  • Usage rules only in a slide deck or someone's head.
  • Connecting AI tools to the system before cleaning it up.

7. Vocabulary

Term Meaning
Design token A named design decision (colour, spacing, type) stored as data
DTCG format The community format for tokens, stable version 2025.10
Code Connect Figma's link between a design component and its code
MCP A standard way for AI tools to connect to other apps and data
Registry A shared catalogue of components that tools can install from
Context file Standing instructions an AI tool reads in every session

8. Try it (no code needed)

  1. Pick one screen and one core component from your system.
  2. Run the checklist below on them. Count the gaps.
  3. Write the usage line for that component: when to use it, when not, what instead.
  4. Ask an AI tool to build a simple screen with your system. Note every place it guessed wrong, and which gap caused it.

Reflection questions: Which of your design system's rules exist only in people's heads? What would a new designer who could only read get wrong first?


9. If you lead a team

  • Make AI-readability part of the design system's definition of done: names, variables, descriptions, usage lines.
  • Set up Code Connect (or the equivalent) for the most-used components first.
  • Review AI-generated screens for system drift, and fix the source, not just the screen.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Design specs for AI · Figma AI · Generating design with Claude Code · Prototyping with AI · MCP · Context files

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close