What format should design tokens be in for an AI agent?

Any clear JSON works if each value is named by its role. The W3C Design Tokens Community Group format, whose first stable version (2025.10) was released in October 2025, is the closest thing to a standard.

Which colours does an agent need?

Background, surface, text, muted text, border, accent and the colour on the accent, for each theme you support.

Do I need tokens for motion?

Yes, if the design moves: durations, easing curves and which properties animate. Without them agents either add no motion or add generic transitions everywhere.

How do I check text colours are readable?

Check contrast: WCAG asks for at least 4.5:1 for normal text and 3:1 for large text.

Design Tokens for AI Coding Agents: What to Hand Over

By @andymarrows · Updated 2026-10-25 · 6 min read

The short answer

An AI coding agent needs tokens by role, not just values: background, surface, text, muted text, border and accent colours (for light and dark), a type scale with sizes, weights, line heights and letter spacing, a spacing scale, radii, border widths, shadows and motion durations and easing. Name them by what they're for, so the agent puts each one in the right place.

Roles beat raw values

Given twelve hex codes, an agent has to guess which is the page background and which is the border. Given roles, it can't get it wrong. Name colours by job:

tokens.json

{
  "palette": {
    "background": "#efeee8",
    "surface": "#f8f7f3",
    "text": "#151513",
    "textMuted": "#5c5a54",
    "border": "#e4e2dc",
    "accent": "#0d7268",
    "onAccent": "#ffffff"
  }
}

If your design has a dark theme, give it the same roles. The agent can then build both themes from one component.

The tokens that matter most

Type scale: each step's size, weight, line height and letter spacing, plus the font families. Headings that tighten as they grow are a big part of a design's feel.
Spacing: the base unit (4px or 8px) and the values actually used. Agents over-pad without one.
Radii: the main radius and where pills are used.
Borders and shadows: whether depth comes from hairlines or soft shadows. Agents add shadows by default.
Motion: durations and easing curves, and which properties animate.

Tokens by role, with what an agent gets wrong without them
Token group	What to include	Without it, agents tend to
Colour roles	Background, surface, text, muted text, border, accent, on-accent (each theme)	Guess roles from hex codes and reuse the accent everywhere
Type scale	Families, sizes, weights, line heights, letter spacing	Use one font at default sizes
Spacing	Base unit and the values used	Over-pad or space unevenly
Radii and borders	Main radius, pill use, border widths	Round everything the same
Shadows	Whether depth comes from shadows or hairlines	Add soft shadows by default
Motion	Durations, easing, animated properties	Skip motion or add generic transitions

Measure, don't guess

Tokens copied from a screenshot drift: colours are off by a few points and the spacing scale is invented. Measuring the rendered page gives the values the site really uses and how often, so the dominant ones become the defaults. That's what Livery does: it renders a site at desktop, tablet and phone widths and measures every visible element, then writes tokens.json with roles, shares and the reasons behind them.

Questions

What format should design tokens be in for an AI agent?: Any clear JSON works if each value is named by its role. The W3C Design Tokens Community Group format, whose first stable version (2025.10) was released in October 2025, is the closest thing to a standard.
Which colours does an agent need?: Background, surface, text, muted text, border, accent and the colour on the accent, for each theme you support.
Do I need tokens for motion?: Yes, if the design moves: durations, easing curves and which properties animate. Without them agents either add no motion or add generic transitions everywhere.
How do I check text colours are readable?: Check contrast: WCAG asks for at least 4.5:1 for normal text and 3:1 for large text.

Sources

Try it on a site you love

Paste a link and get an installable design kit in about a minute. Free.

Create a kit Browse kits

More guides