Skip to content

Design tokens that AI agents can follow (Tailwind v4)

Design tokens AI coding agents use correctly: semantic names, a small closed set, one set for light and dark, Tailwind v4 classes, motion presets, a lint check.

By , MiniDev11 min read

AI agents are good at following a vocabulary and bad at inventing a consistent one. Give an agent the full Tailwind palette and every screen it builds will be slightly different: gray-50 here, slate-100 there, a shadow typed by hand. Give it twenty named roles and a rule that nothing else is allowed, and screen ten looks like screen one. This guide shows how to shape design tokens for that, using the token set MiniDev UI ships as the worked example.

Why agents drift

  • Too many valid choices. Tailwind's default palette has hundreds of colour classes. The model picks whichever it has seen most near similar code.
  • Names that describe the value, not the job. gray-200 says what it looks like. It does not say whether it is a border, a hover state or a disabled background, so the agent guesses.
  • Dark mode as a second set of classes. Every bg-white dark:bg-zinc-900 pair is a chance to forget half of it.
  • Values the theme cannot reach. A hex colour or a shadow-[...] ignores your theme, so the next theme change leaves it behind.

Name tokens by role

Semantic tokens are named for what they do. Each one answers a question an agent can answer from the markup it is writing: is this the page, a card, a pressed-in well, primary text, secondary text, a hairline, the brand action?

RoleMiniDev token classUse it for
Pagebg-bgThe app and page background
Surfacebg-surfaceCards, panels, inputs
Raisedbg-raisedMenus, popovers, dialogs
Sunkenbg-sunkenWells, code, table headers, hover fills
Inkbg-ink + text-on-inkPrimary buttons, strong emphasis
Accentbg-accent + text-on-accent, bg-accent-soft, text-accent-fgThe brand action, selection, links
Texttext-fg, text-fg-muted, text-fg-subtlePrimary, secondary and hint text
Linesborder-border, border-border-strongHairlines and input borders
Statussuccess, warning, danger, infoState, never decoration

That is the whole colour vocabulary. It is small enough to list in a rules file, and each name narrows the choice to one or two candidates. Values are written in OKLCH, so lightness steps look even and the dark set is easy to derive.

One set of tokens, light and dark

Define the roles once as CSS variables and redefine them under .dark. Components only ever reference the role, so they are correct in both modes without a single dark: class. This is a trimmed version of MiniDev's stylesheet:

app/tokens.csscss
:root {
  --bg: oklch(0.985 0.0015 264);
  --surface: oklch(1 0 0);
  --sunken: oklch(0.967 0.0025 264);
  --border: oklch(0.917 0.004 264);
  --fg: oklch(0.185 0.012 268);
  --fg-muted: oklch(0.45 0.012 266);
  --accent: oklch(0.53 0.215 283);
  --on-accent: oklch(0.99 0.004 283);
  --danger: oklch(0.54 0.2 25);
}

.dark {
  --bg: oklch(0.145 0.004 270);
  --surface: oklch(0.172 0.005 270);
  --sunken: oklch(0.125 0.004 270);
  --border: oklch(0.262 0.006 270);
  --fg: oklch(0.965 0.003 270);
  --fg-muted: oklch(0.73 0.01 270);
  --accent: oklch(0.7 0.165 285);
  --on-accent: oklch(0.16 0.02 285);
  --danger: oklch(0.7 0.17 25);
}

Notice the dark accent is lighter and its on-accent text flips to dark: a role keeps its meaning, not its value. Check each text and surface pair with a contrast checker when you derive your own set.

Turn tokens into Tailwind classes

Tailwind CSS v4 creates utilities from @theme variables. Using @theme inline makes each class reference the CSS variable directly, so when .dark changes --surface, bg-surface follows. Now the agent writes ordinary Tailwind and the vocabulary is enforced by what classes exist.

app/globals.csscss
@import "tailwindcss";
@import "./tokens.css";

@custom-variant dark (&:is(.dark *));

@theme inline {
  --color-bg: var(--bg);
  --color-surface: var(--surface);
  --color-sunken: var(--sunken);
  --color-border: var(--border);
  --color-fg: var(--fg);
  --color-fg-muted: var(--fg-muted);
  --color-accent: var(--accent);
  --color-on-accent: var(--on-accent);
  --color-danger: var(--danger);
}

If you also use shadcn/ui components, map its variable names onto your roles (--background: var(--bg), --card: var(--surface), --primary: var(--accent), --muted-foreground: var(--fg-muted)) so both sets of components read one palette. MiniDev's stylesheet does this, which is why shadcn components dropped into a MiniDev project match.

Depth, shape and space are tokens too

Colour is where drift is most visible, but shadows, radius and spacing drift the same way. Close those sets as well:

ScaleAllowedRule an agent can follow
Shadowshadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlayCards shadow-raised; menus and dialogs shadow-overlay. No shadow-[...]
Radiusrounded-lg, rounded-xl, rounded-2xlControls lg, cards xl, overlays 2xl. Nested radius = outer minus padding
SpacingEven steps on a 2px gridPaddings, gaps and heights are even numbers
Control height28, 32, 36, 44, 48pxUse the component's size prop, not a custom h-
Numberstabular-numsEvery figure in a table, stat or counter
Loading the live Stat Card…
Stat CardStatCard uses only surface, border, text and status tokens, so it is correct in light, dark and every material.Docs

Motion presets as named values

Agents invent durations and easing curves freely, and that is where generated UI feels most off. Give motion the same treatment: a handful of named springs in one file, and a rule that movement uses one of them. MiniDev's five presets:

lib/motion.tsts
import type { Transition } from "motion/react"

// The only springs in the product. Agents pick one by name; nobody types a duration.
export const SPRING = {
  snappy: { type: "spring", bounce: 0.18, duration: 0.42 }, // toggles, tabs, thumbs
  morph: { type: "spring", bounce: 0.16, duration: 0.5 }, // panels, size and shape changes
  roll: { type: "spring", stiffness: 260, damping: 28, mass: 0.9 }, // numbers
  release: { type: "spring", stiffness: 400, damping: 40 }, // after a drag
  data: { type: "spring", bounce: 0.12, duration: 0.7 }, // chart lines and areas
} satisfies Record<string, Transition>

Usage is then a name, plus the reduced-motion rule that makes every animation instant for people who ask for it:

components/thumb.tsxtsx
"use client"
import { motion, useReducedMotion } from "motion/react"
import { SPRING } from "@/lib/motion"

export function Thumb({ on }: { on: boolean }) {
  const reduce = useReducedMotion()
  return (
    <motion.span
      data-slot="switch-thumb"
      className="block size-4 rounded-full bg-surface shadow-sm"
      animate={{ x: on ? 16 : 0 }}
      transition={reduce ? { duration: 0 } : SPRING.snappy}
    />
  )
}

Tell the agent, then check

Tokens only help if the agent knows them. List the class names, the scales and the bans in your AGENTS.md or Cursor rule, and in your llms.txt if you publish a library. Then make a script the judge. This one walks the tracked .tsx and .jsx files and fails on anything outside the vocabulary:

scripts/check-tokens.mjsts
// Fails when UI code reaches past the tokens. Run it in CI and tell your agent to run it.
// shortcut: line-based regexes, not a parser; upgrade to an ESLint rule if false positives pile up.
import { readFileSync } from "node:fs"
import { execFileSync } from "node:child_process"

const RULES = [
  [/(?<![\w&])#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?\b/, "raw hex colour: use a token class"],
  [/\b(?:bg|text|border|ring|fill|stroke|from|to|via)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}\b/, "palette step: use a semantic token"],
  [/\bbg-(?:white|black)\b/, "bg-white/bg-black: use bg-surface or bg-ink"],
  [/\bshadow-\[/, "hand-written shadow: use the shadow scale"],
  [/\bdark:(?:bg|text|border)-/, "dark: variant: tokens already switch in dark mode"],
]

const files = execFileSync("git", ["ls-files", "*.tsx", "*.jsx"], { encoding: "utf8" }).split("\n").filter(Boolean)
let problems = 0
for (const file of files) {
  readFileSync(file, "utf8").split("\n").forEach((line, i) => {
    for (const [re, why] of RULES) {
      if (re.test(line)) {
        console.log(`${file}:${i + 1}  ${why}`)
        problems++
      }
    }
  })
}
if (problems) {
  console.log(`\n${problems} token problem(s)`)
  process.exit(1)
}

Run it in CI and name it in the rules file's "done means" list. Expect a few legitimate hits, such as a theme-color meta tag or a colour picker, and exclude those files by path rather than loosening the rules.

Common mistakes

  • Semantic names that are really colours. --purple or --brand-blue is a palette entry with a new name. Name the job: --accent.
  • Too many roles. If you have surface-1 to surface-6, the agent is back to guessing. Most products need page, surface, raised and sunken.
  • Opacity variants on surfaces. bg-surface/80 is a new colour nobody defined, and it breaks themes that change the surface (MiniDev's glass and metal materials, for example).
  • Tokens in the CSS but not in the rules. The agent does not open your stylesheet unless told to. List the classes where it will read them.
  • Docs examples that break the rules. Agents copy examples. Lint the examples with the same script.

Components used in this guide

Frequently asked questions

What are semantic design tokens?

Named values that describe a role rather than a colour, such as surface, fg-muted or danger. Components reference the role, and the theme decides the value, so light, dark and brand themes change without touching component code.

How do I stop AI agents from using random Tailwind colours?

Expose a small set of semantic token classes through @theme inline, list them in AGENTS.md or a Cursor rule with the banned patterns, and run a check that fails on hex colours, palette steps such as blue-500, bg-white and dark: variants.

Should I use dark: variants with design tokens?

Not for colour. Redefine the token variables under .dark and let the classes follow. Components then have no dark: classes to forget, which is the most common dark mode bug in generated code.

Do design tokens work with shadcn/ui?

Yes. shadcn/ui reads CSS variables such as --background, --card and --primary. Map those to your semantic roles in one place and both shadcn and your own components use the same palette.

More guides