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

Описание и применение

Агенты часто генерируют непредусмотренные цвета и размеры, если в запрос включён полный набор токенов. Решение – использовать сокращённый список допустимых токенов, явно запрещать сырые значения и проверять PR‑ы через CI‑скрипт, чтобы гарантировать соблюдение шкалы.

Задача

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

Результат

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

Рабочий процесс

• 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.

Доказательства

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

Источник

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

Источник

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

Источник

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

Источник

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

Источник

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

Источник