Design Tokens and CLAUDE.md Rules That Stop Generic AI UI

Why does Claude keep producing the same purple, Inter-font UI?

Anthropic has named the problem itself. In its November 2025 post on improving frontend design through Skills, it explains that models sample from statistical patterns in their training data, so without direction they converge on generic, on-distribution output, which users call the AI slop aesthetic. The post lists the usual suspects: overused fonts such as Inter, Roboto, Arial and system fonts, and cliched colour schemes, particularly purple gradients on white. The model is not choosing purple because it likes purple; nothing in the conversation or the repository made a different choice more likely. A one-off prompt such as "make it look premium" shifts the odds for one response. A design system committed to the repo, loaded into every session and enforced by tooling, shifts them permanently. Our pillar post, Why AI websites look the same and how to make Claude design better, covers the diagnosis; this one is the fix at the source.

• •Defaults win when the context is empty: no palette, no type scale, no component inventory means the agent invents them.
• •Instructions given only in chat do not carry over; Anthropic's memory docs say to put them in CLAUDE.md so they persist and survive compaction.
• •Tailwind ships a large default palette, so bg-indigo-500 or bg-violet-600 always compiles unless you remove it.
• •Anthropic's own advice is blunt: telling Claude to avoid Inter and Roboto improves results immediately, which is exactly what a rules file does on every request.

What are design tokens, and is the W3C format stable yet?

Design tokens are named design decisions, such as colour.brand.primary or radius.card, stored as data instead of being scattered through stylesheets as raw hex codes and pixel values. The Design Tokens Community Group, a W3C community group, published the first stable version of its specification, version 2025.10, on 28 October 2025. It is a Final Community Group Report rather than an official W3C Recommendation, but it is the vendor-neutral format the major tools are converging on. Files are JSON with the recommended extension .tokens or .tokens.json and the media type application/design-tokens+json. Every token has a $value, an optional $type that can be inherited from its group, and references to other tokens use curly-brace syntax such as {color.saffron.500}. Supported types include color, dimension, fontFamily, fontWeight, duration, cubicBezier and number, plus composites such as shadow, border, typography, transition and gradient. The W3C announcement adds full support for Display P3, OKLCH and the other CSS Color Module 4 spaces, and names Style Dictionary, Tokens Studio and Terrazzo as reference implementations, so one token file can generate the CSS variables your Tailwind theme consumes.

How do Tailwind v4 @theme tokens make off-brand classes impossible?

Tailwind CSS v4 moved configuration from tailwind.config.js into CSS. Variables declared inside an @theme block are not plain CSS variables: the Tailwind docs explain that they instruct Tailwind to create utility classes, so --color-saffron-500 produces bg-saffron-500, text-saffron-500 and the rest. The namespaces map directly to a design system: --color-*, --font-*, --text-*, --font-weight-*, --tracking-*, --leading-*, --spacing, --radius-*, --shadow-* and --breakpoint-*. The decisive line for AI work is the namespace reset. Writing --color-*: initial removes every default colour utility, so after it bg-indigo-500 simply does not exist in your project and only your brand colours remain. Do the same for fonts, radii and shadows and the agent's favourite defaults have nothing to compile against. Use @theme for tokens that should become utilities, :root for variables that should not, and @theme inline when a theme variable points at another variable. Paste the block below into app/globals.css and rename.

Where does shadcn/ui theming fit with your tokens?

If your stack uses shadcn/ui, as many AI-built sites do, you already have a semantic token layer. shadcn/ui themes through CSS variables with a surface and foreground convention: the base token controls the surface colour and the -foreground token controls the text and icons on it, so bg-primary pairs with text-primary-foreground. The default theme ships tokens for background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input and ring, plus sidebar variants and chart-1 to chart-5, written in OKLCH and overridden inside a .dark selector. That is why so many shadcn sites look alike: nobody changes the neutral defaults. The fix is to point those semantic variables at your brand ramps, as the :root and .dark blocks above do, and tell the agent in CLAUDE.md to style components with the role names, never the ramps.

• •Keep two layers: brand ramps (saffron-500, ink-950) in @theme, semantic roles (primary, muted, border) in :root and .dark.
• •Components use roles only: bg-primary text-primary-foreground, never bg-saffron-500 inside a Button.
• •Leave cssVariables set to true in components.json, which shadcn/ui documents as the default, so new components inherit your roles.
• •Change the chart-1 to chart-5 tokens too, or every dashboard the agent builds will use the stock chart palette.
• •When you add a role, add it to :root, .dark and @theme inline in the same commit, then list it in CLAUDE.md.

What should a CLAUDE.md design rules section contain?

Claude Code loads CLAUDE.md at the start of every session, and the project file at ./CLAUDE.md or ./.claude/CLAUDE.md is shared with your team through version control. Anthropic's guidance is to write instructions that are concrete enough to verify, keep each file under about 200 lines because longer files reduce adherence, and group rules under headers and bullets. For design, that means naming roles and exact class names rather than adjectives. "Use a modern, clean look" gives the model nothing; "one accent, primary, used for the main CTA only" gives it a rule it can check against. Add to it whenever the agent makes the same visual mistake twice, the trigger Anthropic suggests for any CLAUDE.md entry.

A complete CLAUDE.md design section you can copy

Here is the section we would start a new marketing site with, sized to stay well inside the 200-line guidance alongside build commands and other conventions. It refers to the tokens by the class names Tailwind generates from the @theme block above, so the agent and the linter speak the same language. Keep the banned list specific: "no bg-gradient-* on heroes" is checkable, "avoid cliches" is not. If the file grows past what is useful in every session, Claude Code lets you move part of it into .claude/rules/ with a paths frontmatter field, for example a rule that only loads when the agent reads files under components/, so frontend rules cost nothing during backend work.

CLAUDE.md, AGENTS.md, Cursor rules or copilot-instructions.md: which file does each tool read?

Most teams use more than one agent, so the design rules have to reach all of them. AGENTS.md is the cross-tool convention: the agents.md site describes it as a README for agents, says it is now stewarded by the Agentic AI Foundation under the Linux Foundation, reports use in over 60,000 open-source projects, and lists tools including OpenAI Codex, Google Jules, GitHub Copilot, VS Code, Cursor, Zed, Devin, Gemini CLI, Warp and Windsurf. Claude Code can now read AGENTS.md directly from v2.1.277, but by default only when the repository has no CLAUDE.md; if you have both, add an @AGENTS.md import to the top of CLAUDE.md so Claude reads the shared rules and then its own extras. Cursor and GitHub Copilot read AGENTS.md alongside their own formats, summarised below.

How do you keep one design source of truth across every agent?

Murphy Trueman's May 2026 essay on design systems fragmenting into agent files makes the governance point well: AGENTS.md, SKILL.md and DESIGN.md do different jobs, and the risk is not the files themselves but nobody owning the seams between them. Brent Haskins argues in a May 2026 post that AI coding agents need structured, unambiguous data rather than a Storybook to browse, and that the high-impact 20 percent, colours, spacing, typography and core component variants, covers most of what agents generate. Our working order is below.

How do you enforce design tokens with ESLint, Stylelint and hooks?

CLAUDE.md is context, not enforcement: Anthropic's docs say plainly that Claude treats it as guidance and that hooks and settings are the deterministic layer. So back the rules with tools that fail. For Tailwind, eslint-plugin-better-tailwindcss supports v3 and v4 and includes no-unknown-classes, which reports classes not registered with your Tailwind config, and no-restricted-classes, which bans classes by regular expression with a custom message. Point its entryPoint setting at the CSS file holding your @theme block, and because you reset --color-*, any bg-indigo-500 the agent writes becomes an unknown class. Add patterns that ban arbitrary values like bg-[#7c3aed] and p-[13px]. For plain CSS and CSS modules, Stylelint's built-in color-no-hex rule disallows hex colours, with an ignoreFunctions option. Finally, close the loop inside Claude Code with a PostToolUse hook on Edit|Write that runs the linter on the changed file: per the hooks reference, a PostToolUse hook that exits with code 2 shows its stderr to Claude, so the agent sees the lint error and fixes it in the same turn.

What mistakes make design rules files fail?

Rules files tend to fail in a few predictable ways, each cheap to fix.

Frequently asked questions

Quick answers to the questions developers and founders ask most when they set up design tokens and rules files for AI coding agents.