Published: Reading time: 7 min read

Design Tokens for AI Agents: Names That Keep Claude on Brand

Summarize with AI

Table of contents
  1. What design tokens are
  2. Why the names matter more when an agent writes the code
  3. Where design tokens should live
  4. Name your Figma variables after the tokens
  5. How to make the agent use them
  6. A worked example from our own site
  7. Where to start
  8. FAQs

Design tokens are the named values behind an interface: colours, font sizes, spacing, radii and motion. When an AI agent writes your code, each token’s name decides whether it picks the right one. A token called --color-accent tells Claude what the value is for. A token called --blue-500 only tells it what the value looks like, so it still has to guess where it belongs, and when it guesses wrong the page drifts off brand.

So give your tokens two tiers (raw primitives, then semantic tokens named by job), keep them in one file in the repository as CSS variables or W3C format JSON, name your Figma variables after them, tell the agent in CLAUDE.md to use only the semantic ones, and add a lint check that rejects raw hex values so a slip fails instead of shipping.

This article goes deep on tokens. For the whole system an agent builds from, read design systems AI agents can build with.

What design tokens are

A design token is a name paired with a value. Instead of writing the brand blue as #0561ff in every file that needs it, each button, link and focus ring refers to one name, and the value lives in one place. Change it there and every screen follows, in every theme.

Tokens hold the decisions that should be made once: the palette, the type scale and font families, spacing, radii, shadows and animation timing. A design system is built on top of them. If you’re a founder, think of tokens as your brand guidelines in a form code can read. If you’re a designer, they’re your Figma variables, as long as both sides use the same names.

Why the names matter more when an agent writes the code

A designer on your team knows which blue is for links on white and which one is for dark backgrounds. An agent knows only what’s written down, and without it a model falls back on what it has seen most often. Anthropic’s own frontend guidance warns Claude that it tends to converge toward generic output, and its advice for colour is to use CSS variables for consistency.

Variables alone don’t settle it. If the file only has --blue-500 and --blue-400, Claude still has to decide which one a link gets, in which theme. If it has --color-accent, there’s one answer.

Use two tiers

  • Primitives hold the raw palette and scale: --navy-950, --blue-500, --space-4. They exist only to define the next tier.
  • Semantic tokens say what each value is for (text, background, border, accent) and point at a primitive. Components use these, and only these.

The split is what makes themes work without the agent thinking about them. On our site --color-text is navy in the light theme and near-white in the dark one, and --color-bg is white in light and a near-black grey in dark. One primitive can also feed several jobs: our brand blue is the accent text in the light theme and every button fill in both.

Primitive token Semantic token Job
--navy-950 (#03111c) --color-text Text and headings, light theme
--paper (#f5f5f5) --color-text Text and headings, dark theme
--white (#ffffff) --color-bg Page background, light theme
--neutral-950 (#0f0f0f) --color-bg Page background, dark theme
--blue-500 (#0561ff) --color-accent Links and accent text, light theme
--blue-400 (#478bff) --color-accent The same accent, dark theme
--blue-500 (#0561ff) --color-accent-fill Button backgrounds, both themes
Components only use the semantic tokens in the middle column, so the agent chooses a colour by what it's for.

Our semantic colour tokens

The DesignMe styleguide, Colour: semantic tokens as swatches, from --color-bg and --color-text to --color-accent, --color-accent-fill and --color-focus in brand blue
Screenshot: designme.agency/styleguide, captured 16 November 2026

Three naming habits help:

  • Job first, then the variant: --color-text, --color-text-muted, --color-border-strong.
  • No values in semantic names. A name like --color-link-blue stops being true the day the brand colour changes.
  • One prefix per category (--color-, --text-, --space-, --radius-), so the whole set turns up in a single search.

Where design tokens should live

In the repository, in one file the agent can read. Tokens that exist only as Figma styles are invisible to a coding agent working in your code, so it guesses.

When we moved our own site from Framer to code in October 2026, we counted what had piled up one section at a time: 191 colour values, 37 font sizes and 53 font families. They collapsed into one tokens file, and that file is now the first thing Claude builds from.

191
colour values on our Framer site
37
font sizes
53
font families

CSS variables

If your product is web only, CSS custom properties in one file are enough. Ours writes every theme-aware colour once with light-dark(), which returns the first value when the colour scheme is light and the second when it’s dark. MDN lists it as Baseline 2024. An excerpt from our src/styles/tokens.css, with the comments shortened:

/* Primitives */
--navy-950: #03111c;
--blue-500: #0561ff;
--blue-400: #478bff;

/* Semantic: what each value is for */
--color-text: light-dark(var(--navy-950), var(--paper));
--color-accent: light-dark(var(--blue-500), var(--blue-400));
--color-text-muted: light-dark(rgb(3 17 28 / 0.62), rgb(245 245 245 / 0.62));

W3C design tokens JSON

If tokens need to feed design tools, iOS or Android as well as the web, use the W3C Design Tokens Community Group format. Its first stable version, 2025.10, came out on 28 October 2025. A token is a JSON object with a $value, plus an optional $type that can also be set once on a group. Groups nest, a token’s path joins the names with dots, and an alias points at another token with curly braces:

{
  "blue": {
    "500": {
      "$type": "color",
      "$value": { "colorSpace": "srgb", "components": [0.0196, 0.3804, 1], "hex": "#0561ff" }
    }
  },
  "color": {
    "accent": { "$type": "color", "$value": "{blue.500}" }
  }
}

Two details catch people out. A colour’s $value is an object with a colour space and components, with the hex code only as an optional fallback, so a bare "#0561ff" string isn’t valid under 2025.10. And names can’t contain dots or curly braces, because those carry the path and alias syntax.

It’s a Community Group report, not a formal W3C Standard. The group’s announcement names Style Dictionary, Tokens Studio and Terrazzo as reference implementations and lists Figma, Penpot, Sketch and Framer among the tools supporting or implementing it.

The first stable token format

Design Tokens Format Module 2025.10, Final Community Group Report, 28 October 2025, from the W3C Design Tokens Community Group
Screenshot: designtokens.org/tr/2025.10/format, captured 16 November 2026

Name your Figma variables after the tokens

Figma’s docs describe variables as reusable values you can use to implement design tokens, and they map onto the two tiers: a collection of primitives, and a collection of semantic variables that alias them. An alias links one variable to another of the same type, so changing the source updates everything that references it. Modes give a variable one value per theme, the job light-dark() does in our CSS.

Figma guide to variables

Figma Learn, Guide to variables in Figma: variables store reusable values for design properties and prototyping, for example to create design tokens
Screenshot: help.figma.com/hc/en-us/articles/15339657135383, captured 16 November 2026

Use the same names on both sides: color/accent in Figma for --color-accent in code, not “Blue 500”. Figma also lets you set a variable’s code syntax, one name each for Web, Android and iOS, and that name appears in Dev Mode code snippets. Set the Web code syntax to the CSS variable, and anyone inspecting a frame sees the token, not a hex value.

Treat the tokens file as the source. When a designer changes a value, it reaches the file as a pull request, and the agent picks it up the next time it builds.

How to make the agent use them

Write the rule where Claude reads first

Claude Code reads CLAUDE.md at the start of every session, so the token rule goes there, with the path to the file. Anthropic’s docs ask for instructions concrete enough to verify. Ours says to use semantic tokens (--color-text, --text-2xl, --space-6) in components, and never to hard-code a hex value, px font size or Framer value.

Keep the file short. Anthropic suggests under 200 lines per CLAUDE.md, and rules that matter only for some files can live in .claude/rules/ with a paths field, so a token rule loads only when Claude works on stylesheets or components.

Then make breaking it fail

Anthropic’s docs say Claude treats CLAUDE.md as context, not enforced configuration, and their best practices are direct about the fix: “If something has to happen every time, make it a hook.”

So the token rule needs a check in code. Stylelint’s own rules cover it:

{
  "ignoreFiles": ["src/styles/tokens.css"],
  "rules": {
    "color-no-hex": true,
    "declaration-property-unit-disallowed-list": { "font-size": ["px"] },
    "declaration-property-value-allowed-list": { "font-family": ["/^var\\(--font-/"] }
  }
}

The first rule rejects hex colours, the second pixel font sizes, and the third any font family that isn’t a token. The tokens file is skipped, since that’s where the primitives hold raw values.

The Stylelint color-no-hex rule

Stylelint docs, color-no-hex: disallow hex colors, with an example that flags #333
Screenshot: stylelint.io/user-guide/rules/color-no-hex, captured 16 November 2026

In Claude Code, a PostToolUse hook can run the linter after every Edit or Write. When it exits with code 2, its error output is shown to Claude, so the hex value becomes a token in the same turn. A Stop hook that exits with code 2 keeps Claude from finishing until the check passes. Run the same check in CI too, so changes made outside Claude are held to it.

How a raw hex value gets caught

  1. The rule

    CLAUDE.md says semantic tokens only.

  2. An edit

    Claude writes a component with a hex value in it.

  3. The hook

    Stylelint runs after the edit and fails.

  4. The feedback

    The error goes back to Claude in the same turn.

  5. The fix

    The hex value becomes a token, and CI runs the same check.

A worked example from our own site

Three details from our tokens file show what semantic names buy you when an agent does the editing.

Contrast got fixed once. On Framer, muted text was the brand ink at 50% opacity, which measured 3.6:1 and failed WCAG AA. In the tokens file --color-text-muted became 62%, which passes at 5.4:1 on white and 7:1 on the dark theme. Every muted label that uses the token got the fix.

A brand colour change went through the primitive. In November 2026 the brand blue moved from #116ff8 to #0561ff. The new value went into --blue-500, and the semantic tokens that point at it (--color-accent, --color-accent-fill and --color-focus) followed without being edited.

Old names still resolve. Nothing visible on our site rounds more than 4px, so the file keeps --radius-md, --radius-lg and --radius-xl as names and points all three at 4px. Older CSS doesn’t break, and an agent reaching for a bigger radius still lands on the house style.

The full walkthrough, from this tokens file to the components, CLAUDE.md lines and review steps built on it, is in our free guide, A design system Claude can build with.

Where to start

  1. Search your code for raw hex values and pixel font sizes.
  2. Group the values into primitives, then name the semantic tokens your components need.
  3. Put both tiers in one file in the repo, and give your Figma variables the same names.
  4. Add the rule and the file’s path to CLAUDE.md.
  5. Turn on the lint rules, and run them after every edit and in CI.

Sources

  1. W3C Design Tokens Community Group, Design Tokens Format Module 2025.10 (accessed 16 November 2026) (opens in a new tab)designtokens.org
  2. W3C Design Tokens Community Group, Design Tokens Color Module 2025.10 (accessed 16 November 2026) (opens in a new tab)designtokens.org
  3. W3C Design Tokens Community Group, Design tokens specification reaches first stable version (accessed 16 November 2026) (opens in a new tab)w3.org
  4. Figma, Guide to variables in Figma (accessed 16 November 2026) (opens in a new tab)help.figma.com
  5. Figma, Create and manage variables and collections (accessed 16 November 2026) (opens in a new tab)help.figma.com
  6. Anthropic, Prompting for frontend aesthetics, published 21 October 2025 (accessed 16 November 2026) (opens in a new tab)platform.claude.com
  7. Anthropic, How Claude remembers your project (accessed 16 November 2026) (opens in a new tab)code.claude.com
  8. Anthropic, Best practices for Claude Code (accessed 16 November 2026) (opens in a new tab)code.claude.com
  9. Anthropic, Automate actions with hooks (accessed 16 November 2026) (opens in a new tab)code.claude.com
  10. Anthropic, Hooks reference (accessed 16 November 2026) (opens in a new tab)code.claude.com
  11. MDN, light-dark() (accessed 16 November 2026) (opens in a new tab)developer.mozilla.org
  12. Stylelint, color-no-hex (accessed 16 November 2026) (opens in a new tab)stylelint.io
  13. Stylelint, declaration-property-unit-disallowed-list (accessed 16 November 2026) (opens in a new tab)stylelint.io
  14. Stylelint, declaration-property-value-allowed-list (accessed 16 November 2026) (opens in a new tab)stylelint.io
  15. Stylelint, Configuring (accessed 16 November 2026) (opens in a new tab)stylelint.io

Press Escape to close.

Need more info?

Questions about design tokens for AI agents

Adrian

Can't find your answer?

Book a call and let's talk.

Or email us  hello@designme.agency

How do I get an AI to use my own design tokens instead of generic styles?

Put your tokens in one file in the repository, in two tiers: primitives for the raw values and semantic tokens named by job, such as --color-text or --color-accent. Tell the agent in CLAUDE.md, with the path to that file, to use only the semantic tokens and never a raw hex value or pixel font size. Then add lint rules that reject raw hex values and pixel font sizes, and run them after every edit and in CI so a slip fails instead of shipping.

Why do semantic token names matter for AI coding agents?

An agent only knows what is written down. A token called --blue-500 says what a value looks like, so the agent still has to guess where it belongs. A token called --color-accent says what it is for, so there is one answer. Semantic tokens also make light and dark themes work without the agent thinking about them, because each one points at a different primitive in each theme.

Should design tokens be CSS variables or JSON?

If your product is web only, CSS variables in one file are enough. If the tokens also need to feed design tools, iOS or Android, use JSON in the W3C Design Tokens Community Group format, whose first stable version came out on 28 October 2025. Either way, the file lives in the repository, where a coding agent can read it.

What does a design token look like in the W3C JSON format?

A token is a JSON object with a $value and an optional $type, which can also be set once on a group. Groups nest, a token's path joins the names with dots, and an alias points at another token with curly braces, such as {blue.500}. In version 2025.10 a colour's $value is an object with a colour space and components, with the hex code only as an optional fallback.

Should Figma variables use the same names as code tokens?

Yes. Name them after the tokens, color/accent in Figma for --color-accent in code, with primitives in one collection and semantic variables that alias them in another. Set each variable's Web code syntax to the CSS variable so Dev Mode code snippets show the token name, and treat the tokens file in the repository as the source.

How do I stop Claude from hard-coding hex colours?

Write the rule in CLAUDE.md, then back it with a check, because Anthropic's docs say Claude treats CLAUDE.md as context, not enforced configuration. Stylelint's color-no-hex rule rejects hex colours; skip the tokens file, where the primitives live. Run it from a Claude Code hook after every edit, which shows the error to Claude in the same turn, and again in CI.

You've reached the end, so now…

Tell us what you’re building.

We’ll help you map the right scope, team, timeline, and next steps.

Book a call