Constraining agent CSS to design tokens (without pasting the whole theme)

Description and use

Agents often generate unintended colors and sizes when given the full token set. The solution is to use a concise list of allowed tokens, explicitly ban raw values, and enforce compliance with a CI lint script to ensure the design scale is respected.

Problem

Agents often invent colors, spacing, radius, or shadows when given a full design token dump, leading to inconsistent UI and hidden palette growth.

Outcome

Agents produce CSS that strictly uses the predefined design tokens, eliminating raw values and unauthorized custom properties, and ensuring consistent UI across features.

Workflow

• 1. Create a token cheat sheet listing legal tokens and forbidden raw values.
• 2. Include the cheat sheet in the agent prompt with explicit instructions and bans.
• 3. Add a CI lint script (check-no-raw-css-values.sh) to scan changed UI files for raw CSS values and arbitrary Tailwind utilities.
• 4. Allow exceptions by adding RAW_OK comments for known cases like 1px hairlines.
• 5. Update PR template with a token compliance checklist.
• 6. Review PRs for token miss, new --* declarations, and arbitrary values, providing feedback or blocking as needed.

Evidence

I used to drop the entire tokens.css into the agent prompt so it “wouldn’t invent colors.” It still invented colors.

Source

Pasting the whole theme teaches the model what exists. It does not teach it that everything else is illegal.

Source

Here’s the thinner constraint that actually stuck in our agent UI PRs.

Source

My default ask looks like this: Style X using only the Legal tokens below. Do not invent colors, spacing, radius, or shadows.

Source

scripts/check-no-raw-css-values.sh — run on changed UI files

Source

A short checkbox beats another paragraph in the system prompt: ### Token compliance - [ ] No raw color / space / radius / shadow values in the diff

Source