Machine-Readable Design Tokens for AI-Ready Component Libraries

A token file can list every color and spacing value in a product without explaining where any of them belong. Someone choosing gray-2 might recognize it from a mockup or ask a teammate how it’s used. An agent working from that name alone has little guidance about which surfaces or components it belongs on.

That missing context matters when the same choice gets repeated across generated screens. To use a library consistently, an agent needs access to the team’s decisions about token usage. Those decisions have to be recorded somewhere it can read, and the resulting components need checks that catch misuse.

How the Token Layers Fit Together

A design token is a named value that holds a design decision: color, spacing, type, radius, shadow. A button can reference color.background.brand for its background. Changing that token updates every component that uses it.

The three tiers give teams a way to separate the underlying palette from the decisions made for a product and its components.

Tier 1: Primitive Values

Primitives hold values with no product meaning attached: color.blue.500, size.4, font.weight.600. They supply the palette and scales that the rest of the system references. A name like color.blue.500 is useful here because this layer describes the value itself.

Tier 2: Semantic Tokens

Semantic tokens assign those values a role: color.text.primary, color.border.danger, spacing.layout.section. These are the names designers and engineers use for everyday decisions. During a rebrand, the value behind color.text.primary can change while its role in the product stays the same.

Tier 3: Component Tokens

Component tokens cover decisions specific to a component, including its states and variants: button.background.primary.hover, input.border.focus. They reference the semantic layer where those roles apply.

Add this layer where a component needs that control. A component with a growing list of narrowly scoped tokens may need clearer variants or slots. Review what its API is asking consumers to manage before adding more tokens.

Naming Tokens for Their Intended Use

A consistent naming convention makes it possible to find related tokens and check their usage. Start with the kind of value and its role. Include a component namespace or state where it helps distinguish a decision.

The appearance-based names can work as primitives. At the point of use, a name such as color.text.subtle gives someone choosing a token more context. If everyone has to choose directly from blue-100 through blue-900, each person still has to decide which shade belongs in each component.

Use the vocabulary already present in the product. If a component has a danger prop, make its mapping to the danger tokens explicit. The same applies to terms such as critical, caution, and selected.

Even role-based names need agreement. If the library contains both muted and subtle, document the difference with examples. When the team can’t explain when to choose each one, resolve the overlap before asking an agent to use them.

Documenting Where a Token Belongs

A name has limited room for context. The token’s description should explain its intended use and any restrictions. For color tokens, include the backgrounds they can appear on.

For example, a description for secondary text might look like this:

{
  "color.text.subtle": {
    "value": "{color.gray.600}",
    "type": "color",
    "description": "Secondary text on color.background.surface and color.background.raised. Do not use on brand or danger fills.",
    "deprecated": false
  }
}

The description gives an agent guidance it can’t get from the gray reference alone. It also gives a reviewer a specific rule to check. For your actual palette, test the allowed text and background pairings in each supported mode and record the results alongside the usage guidance.

Make these descriptions available with the token data. An agent using the library also needs the component APIs, supported variants, and accessibility rules. Keep that information current as the library changes; an outdated example can send someone toward a deprecated token even when the current documentation is correct elsewhere.

Connecting Tokens to Components and Modes

Follow a token through a component’s states. A button’s default background is only part of its behavior. Hover, focus, and disabled states need deliberate choices too. For other components, that can include selected, loading, and error states.

Define the themes and density settings the library supports early. The mappings for light and dark themes should preserve a token’s intended role. Check each mapping in context, including focus indicators and text on colored fills. Document the expected appearance and behavior of disabled states so consumers have guidance for those as well.

Keep the Figma and code names aligned, or maintain an explicit mapping between them. Otherwise a designer and an engineer can follow their respective libraries and still produce different results.

Overrides need a supported process. If a consumer needs a color or spacing value outside the available tokens, record the reason and review it with the system team. Recurring exceptions can reveal a missing variant or a rule that needs to change.

Maintaining the Token System

Treat published token names as an API that other teams depend on. Mark deprecations, identify replacements, and publish changes. A rename needs a migration path for the components and design files that still reference the old name. Changes to values also need review across their consumers.

Put checks where the work happens:

• Lint production components for hard-coded colors, one-off spacing, and invalid or deprecated token references.
• Check design files for local values and naming differences from the published library.
• Run accessibility checks and visual regression checks on affected component states and themes.

Documentation explains the intended usage. These checks help catch places where the implementation has diverged. The team still needs to decide which rules block a release and who reviews exceptions, including changes generated by agents.

Give design and engineering shared responsibility for that process, with input from accessibility, brand, and product. Someone needs to own each change through to its consumers.

Track whether the system is doing its job. Alongside adoption, look at accessibility failures caught before release and differences between Figma and production. When a shared value changes, check whether the expected components update with it. Adding a token for every one-off value can increase the count while leaving the underlying inconsistencies unresolved.

Start With One Component

Choose a component that people use regularly and trace its tokens from the design file through to production. Use these questions to find gaps:

1. Can you trace its semantic and component tokens back to the underlying values?
2. Are its states, size variants, and supported modes covered?
3. Have its text and background pairings and focus indicators been checked for accessibility?
4. Do Figma and code use the same names, or a maintained mapping?
5. Can an agent find the current token descriptions and valid component props?
6. Would the project’s checks catch invalid references, deprecated tokens, and unsupported overrides?

Work through the gaps with the people maintaining that component. Update its token descriptions and checks, then use the same process on the next component. This gives the team a manageable way to improve the library and verify what an agent has built from it.

See It in Practice

Altitude is our open design system and AI testbed. It uses all three token tiers, supports light and dark themes, and organizes components around atomic design principles. Its docs include Figma-to-code parity measurements, accessibility results from axe-core runs, and token contracts mapped to component APIs.

Read why we built Altitude, or see how we approach design systems work.