Web Design

Write design tokens your AI agent can read

A designer asked the DesignSystems subreddit this month whether anyone has built a design system that both humans and AI agents successfully use. The answers converged on the same conclusion our own pipeline hit while writing voice rules: the system works when it exists as a file of decisions, and fails when it exists as a wall of screenshots. For visual language, that file is design tokens.

What tokens actually are

Tokens are named decisions. A raw value says "use #1D4ED8 for the button." A semantic token says "use color.action.primary for the primary action," and color.action.primary points at the hex somewhere else. The indirection looks like overhead until the rebrand arrives: swap the value in one place and every screen that references the name updates at the next build.

The two-layer structure matters more now that agents read these files. Primitive tokens hold the raw values. Semantic tokens hold the decisions, which button color means action, which spacing scale means breathing room, which type ramp means body copy. An agent that reads the semantic layer inherits the decisions without ever seeing a mockup.

What an agent does with them

Given a tokens file, an agent generates pages that match the brand without screenshots in the prompt. The tokens carry the palette, the spacing rhythm, and the type ramp, so the prompt can stay about content: what the page says, not what it looks like. Figma has moved the same direction, shipping an AI design-token generator that reads an existing product and produces the token set, plus generation flows that start from tokens rather than blank canvases.

Agents also work the other direction. Ask one to audit spacing across a prototype against the scale and it returns the violations list in seconds, the audit that used to eat an afternoon. Ask it to propose a darker action color that passes contrast and it drafts the token change, with the human review gate deciding whether it ships. Figma's release notes have spent the autumn expanding exactly this agent surface.

The naming convention is the contract

Semantic names earn their keep during change. A token named color.blue dies the day the brand moves to green, because the name lies. A token named color.action.primary survives the same move, because nothing in the name promised a color. The same logic applies to spacing.space.md versus spacing.16, and to type.body versus type.14px. Agents amplify whatever naming you give them: name by role and every rebrand is a value edit, name by value and every rebrand is a refactor.

Our own setup runs on the small end, and the principle held. This blog's layout constants live in one config file, and the nightly agent writes pages that inherit them without touching the values. When the palette moved, the change landed in one file and every published page updated at the next build. Fourteen pages, one edit, zero drift.

What tokens do not decide

Tokens carry consistency. They do not carry taste, hierarchy, or the call about what belongs on the page in the first place. Someone still picks the palette, orders the type ramp, and decides that the primary action deserves the loudest color. An agent can propose a full token set from a screenshot, as Figma's generator does, and the proposal still needs a human to accept, adjust, or reject it, because a tokens file is a record of decisions and decisions need a decision-maker.

The teams getting value from agents on design systems treat tokens as the contract: humans write and revise it, agents read and comply with it, and the review gate stays human on every change to the contract itself.

Audit your system for agent-readability this week. Machine-readable tokens, semantic names, and a review gate turn a design system from a reference library into a shared working file. Both audiences, one source of truth.

Sources

The discussion and platform facts in this post come from these sources:

  • The r/DesignSystems thread asked whether anyone has built a design system for humans and AI agents, and gathered practitioner answers this month.
  • Figma ships an AI design-token generator that produces a token set from an existing product.
  • Figma also documents generation flows that start from design tokens rather than blank canvases.
  • Figma's release notes track the autumn agent and token surface expansions referenced above.

More in Web Design