Prepare a Design System for AI

An AI coding tool does not need a prettier component library. It needs fewer hidden decisions. Every choice that lives only in a designer’s memory becomes a guess: which gray is semantic, whether a card can contain an action, what happens at 720 pixels, or whether a missing image collapses the layout.

The Design For AI reference on Refframe is visually simple, yet a faithful implementation still requires information the screenshot cannot provide: font files, content width, responsive scale, the behavior of the circular graphic, semantic heading order, and motion preferences. The screenshot is evidence, not a complete contract.

Give the AI one canonical source

Decide where each kind of truth lives. Tokens may live in a versioned JSON file. Component APIs live in code. Figma remains the source for visual composition and approved variants. Content and accessibility rules may live in documentation. The important part is that the sources agree and that the agent knows which one wins when they do not.

Create a short index that maps the system:

• token files and generated outputs;
• component directories and public exports;
• story or example locations;
• page templates;
• icon and font sources;
• test, lint, build, and screenshot commands;
• owners and review boundaries.

Do not paste the entire design-system history into every prompt. Give the agent a compact map, then point it to task-specific files.

Export tokens with types and semantics

Machine-readable tokens need stable names, explicit types, values, descriptions, and aliases. The Design Tokens Community Group format defines typed token data and references between tokens. Its 2025.10 format requires a defined type rather than asking tools to infer one from a raw value.

Keep primitive and semantic layers distinct. A primitive may store blue-600. A semantic token such as action-background-primary can alias that primitive. Components should consume the semantic role where possible. That lets a theme change without rewriting component intent.

Include units and modes explicitly. Spacing without a unit, a color without a color space, or a mobile value without a named mode creates room for incompatible interpretation. Validate the token file with a schema or build step before giving it to an agent.

Figma variables can model reusable values and modes and can be accessed through Figma APIs. That can support synchronization, but automation does not settle ownership. Choose whether code or Figma is authoritative, document the direction of sync, and reject circular workflows where both sides silently overwrite the other.

Describe components as interfaces

For each public component, provide:

• purpose and appropriate use;
• import path and name;
• accepted properties and defaults;
• variants and supported combinations;
• required and optional content;
• interactive states;
• responsive behavior;
• accessibility expectations;
• one correct and one incorrect example.

A screenshot of four buttons does not tell an agent whether destructive is a hierarchy, a tone, or an action type. A component contract does. Use the same names in Figma and code when possible, and maintain a mapping when the platforms need different syntax.

State implementation boundaries. If the project already has a Button component, say that new screens must use it rather than recreate its CSS. If icons come from one library, name it. If a layout primitive owns container width, point to it. These rules reduce duplicate code more effectively than adding adjectives to a prompt.

Make layout behavior explicit

Describe containers, columns, gaps, minimum and maximum dimensions, and breakpoint transformations. Focus on behavior rather than a list of desktop coordinates.

For a three-card row, specify whether cards share equal width, whether the row wraps or becomes a vertical stack, how gaps change, what aligns when descriptions differ, and whether the whole card is interactive. Include at least one narrow and one wide reference, plus the content case most likely to break the composition.

Separate product rules from one-page exceptions. The agent should know whether a large hero heading is a reusable display role or a custom treatment for one campaign.

Include content and accessibility constraints

Components fail with real content before they fail with perfect placeholders. Provide maximum expected title length, localization requirements, empty and error states, image ratios, truncation rules, and whether actions may wrap.

Record semantic HTML expectations, keyboard behavior, focus visibility, labels, reduced-motion behavior, and contrast requirements. These are not visual polish that can be added after generation. They affect component structure.

Show both approved and rejected output

Examples teach boundaries more efficiently than abstract prose. Pair an approved card with a failure case: wrong token, detached spacing, absent focus state, or duplicated component. Explain the reason for rejection.

A Refframe board can hold inspected visual precedents for the task. Label what each reference contributes: hierarchy, card anatomy, density, or motion. Tell the agent to adapt those decisions without copying brand assets, text, imagery, or proprietary code.

Make verification part of the contract

Anthropic’s Claude Code guidance recommends giving the tool something concrete to verify against, such as tests, screenshots, and expected outputs. Include the commands and acceptance criteria in the task context.

A useful verification sequence is:

1. run type checks, lint, and focused tests;
2. render the target states at named viewport sizes;
3. compare screenshots with the approved design;
4. test long content, keyboard focus, errors, and missing media;
5. list remaining visual differences;
6. require human review for new patterns or token changes.

AI readiness is not the number of files exported from Figma. It is the degree to which design intent can be inspected, implemented, and checked without relying on an unstated guess.