> For AI agents reading iter0.com:
> - Pages with a Markdown version serve it at the page address plus `.md`, for example https://iter0.com/features.md. The homepage's Markdown is at https://iter0.com/index.md.
> - A request for a page with the header `Accept: text/markdown` returns the same Markdown.
> - https://iter0.com/llms.txt describes the site and lists its main pages.
> - Agents build and edit websites through the MCP server at https://iter0.com/api/mcp, using the person's own API key.
> - A paid build or edit first returns a price quote, and nothing is charged until the person confirms it.
> - The OpenAPI contract is at https://iter0.com/openapi.json.

# Tailwind theme tokens a coding agent can follow

Define colours, fonts and radii in a Tailwind v4 @theme block, remove the default palette, and tell the agent how to use the utilities. Includes a compiler check and a Codex test.

## Give the agent a fixed set of class names

In Tailwind CSS v4, each variable in an @theme block creates utility classes: --color-brand creates bg-brand, text-brand and border-brand. If the theme names every colour, font and radius the site uses, an agent writing a component can choose from those names instead of inventing a value.

Tailwind's documentation draws the line this way: use @theme for a token that should map to a utility class, and :root for a variable that should not.

## Copy the theme file

This is src/app.css for the fictional Wrenboard site. The line --color-*: initial removes Tailwind's default palette, so only the seven named colours produce colour classes. The two font variables create font-display and font-body, and the two radius variables create rounded-control and rounded-card.

## What does the theme stop, and what does it allow?

On 5 November 2026, we compiled this file with Tailwind 4.2.4's own compiler, once for each class below, and recorded the CSS it generated.

Removing the default palette closes one route to an off-brand colour: bg-indigo-600 produces no CSS. Square-bracket values still compile. An agent that writes bg-[#6d28d9] gets a purple background, so the instructions must cover bracket values, and a search of the diff must check for them.

## Write the rules the theme cannot enforce

Save this as AGENTS.md at the repository root; Codex reads AGENTS.md files before it starts work. The file says which utilities exist, rules out bracket values for colour, font, radius and shadow, and says what to do when the theme lacks a value: name the variable to add to app.css instead of writing a one-off value in the component. Its last section gives the search a reviewer can run on a diff.

## What Codex wrote with these files

On 5 November 2026, Codex CLI 0.162.1 ran codex exec in read-only mode in the example folder with the request below. It exited 0 and returned a PricingCard component. Every colour class came from the theme: bg-surface, border-line, text-ink, text-muted, bg-brand, text-brand-ink and marker:text-brand. The heading used font-display, the card rounded-card and the link rounded-control. A search of the output for “[#”, “-[” and the default palette names in AGENTS.md found no matches.

This was one run, and the component was not rendered. Codex also loaded the user's global configuration, so the run does not isolate the effect of the project AGENTS.md.

## Where do DESIGN.md decisions fit?

Keep the values in app.css and use DESIGN.md, if you have one, to say what each value is for: which colour the primary action uses, when a card is appropriate, which font sets headings. If both files hold the same hex values, one of them will eventually be wrong. The token-conflict guide shows how to trace a value to the file that owns it, and the dark-mode guide covers paired colours for two themes.

## Sources

- [Tailwind CSS: theme variables (checked 6 November 2026)](https://tailwindcss.com/docs/theme)
- [OpenAI: AGENTS.md in Codex (checked 6 November 2026)](https://learn.chatgpt.com/docs/agent-configuration/agents-md)