Как заставить AI-агента писать CSS только через дизайн-токены без заливки всего Theme

#AI coding#design tokens#agentic workflows#frontend

В работе с AI-помощниками для фронтенда часто сталкиваюсь с одной и той же проблемой: генерируемый CSS выходит из-под контроля. Пытаешься дать агенту весь дизайн-токен файл целиком, чтобы он не придумывал цвета и отступы на глаз — а он всё равно рисует «почти правильные» значения, которые не соответствуют нашей системе. В итоге приходится вручную ловить и откатывать лишние хардкоды — hex, px, нестандартные радиусы и тени.

В этой статье расскажу, как я пришёл к подходу, который реально сдерживает AI и заставляет его работать в рамках заданной системы токенов. Тут нет магии — просто правильные ограничения и контроль.

Почему вставлять весь theme в prompt — не работает

Моя первая идея была очевидной: бери весь tokens.css (иногда до 800 строк CSS-переменных) и вставляй в prompt агента. Логика — пусть AI знает, что уже есть, и не придумывает новые цвета или размеры.

Реальность: агент воспринимает это как moodboard — настольную доску с образцами стилей, а не жёсткое правило. Он пытается «сделать красиво» и оптимизирует под «похожесть на продукт», а не под «запрещённые значения». В ответах появляются:

В итоге получается, что AI просто «фристайлит» внутри moodboard. Мы же хотим, чтобы он не играл, а строго следовал правилам.

Четыре жёстких правила ограничения CSS от агента

Чтобы исправить ситуацию, я зафиксировал в prompt не просто «используй дизайн-систему», а набор конкретных запретов и требований:

  1. No raw values
    Запрещены любые raw-значения в цветах, отступах, радиусах и тенях. Никаких hex, rgb(), bare px/rem, hsl и т.п.

  2. Import / reference allowlist
    Разрешено использовать только именованные токены из публичного набора, например var(—space-4), theme(‘spacing.4’), tokens.space[4].

  3. No local token invention
    Запрещено создавать новые кастомные свойства с —* в CSS компонентов без одобрения дизайн-команды.

  4. Closest-token rule
    Если дизайн просит значение вне существующего масштаба, агент должен остановиться и назвать этот пропуск — не придумывать «почти подходящее» значение.

Эти правила — не просто в голове, а чётко прописаны в prompt и в чек-листе для PR.

Лаконичный cheat sheet токенов вместо полного theme

Вместо тысячи строк я держу небольшой срез токенов — 40–60 строк, который обновляю по мере изменений в дизайн-системе. Вот пример:

/* LEGAL TOKENS */

/* Color */
--color-bg-default
--color-bg-subtle
--color-fg-default
--color-fg-muted
--color-accent-primary
/* No raw hex, no opacity hacks */

/* Space */
--space-1
--space-2
--space-3
--space-4
/* No eyeballed px */

/* Radius */
--radius-sm
--radius-md
--radius-lg
--radius-full
/* No rounded-[10px] */

/* Shadow */
--shadow-sm
--shadow-md
--shadow-lg
/* No one-off box-shadow */

/* Type */
--font-size-sm
--font-weight-regular
--font-weight-medium

И как это использовать в коде:

Автоматический контроль и запреты

Промпт с правилами — это хорошо, но без автоматического контроля всё быстро пойдёт наперекосяк. Для этого:

rg -n --pcre2 \
  '(#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|\b\d+(\.\d+)?px\b|rounded-\[[^\]]+\]|bg-\[[^\]]+\]|p-\[[^\]]+\]|gap-\[[^\]]+\])' \
  src/components src/app \
  -g '!**/tokens/**' \
  -g '!**/*.test.*' \
  && exit 1 || exit 0

Как выглядит идеальный запрос к агенту

Style the settings panel using only the Legal tokens below.

Do not invent colors, spacing, radius, or shadows.

If a value isn’t on the scale, stop and name the missing token — don’t approximate.

Prefer existing utility/token classes over new CSS files.

When done, paste the Acceptance checklist with pass/fail and list every token you used.

Forbidden: Tailwind arbitrary values for color/space/radius (bg-[#…], p-[18px], rounded-[10px]).

И чек-лист в конце PR:

Это сразу переключает ревьюеров с «нравится/не нравится» на «есть ли нарушение правил токенов».

Пример из жизни: padding 18px vs var(—space-4)

В одном из PR агент сгенерировал CSS:

.settings-panel {
  padding: 18px;
}

В ревью стало ясно, что 18px — это не значение из нашей системы spacing. Правильный токен — var(--space-4), соответствующий 16px.

Согласно правилам, агент должен был остановиться и создать issue на новый токен или согласовать с дизайном. Вместо этого он придумал «почти то». На практике это приводит к размытию границ дизайн-системы и ухудшению согласованности UI.

Кому и когда это помогает

Где риски и ограничения

Что попробовать дальше


В итоге я убедился, что ограничивать агента — это не про «дать ему все правила», а про чётко сузить словарь допустимых значений. Полный theme в prompt — это разводка, а вот короткий cheat sheet и автоматический lint — вот настоящая сила. Такой подход не только экономит время, но и сохраняет визуальную целостность продукта, когда код пишет AI.


Попробуй сам: Cursor — AI-редактор для разработчиков.


Источник: https://dev.to/sherotree/constraining-agent-css-to-design-tokens-without-pasting-the-whole-theme-19o8