Design.md: как описать дизайн‑систему для AI‑агентов

design agents rules

AI-агенты (Claude, GPT, Cursor) всё чаще пишут UI-код. Но у них есть фундаментальная проблема: они не знают вашу дизайн-систему. Каждая сессия начинается с нуля. Каждое визуальное решение: догадка.

Design.md решает это. Это структурированная спецификация дизайн-системы, которую AI читает в начале каждой сессии. Вместо догадок: поиск по документу.

Проблема: 200 разумных догадок

Когда AI пишет интерфейс, он принимает сотни микрорешений: какой отступ у карточки, какой оттенок синего для ссылки, какой радиус скругления у кнопки. Каждое решение выглядит нормально. Но 200 «нормальных догадок» не складываются в консистентный дизайн.

Hardik Pandya точно описывает три ограничения LLM:

Фабрикация значений. AI не ищет ваши токены, а генерирует правдоподобные. Если в системе --space-200 = 8px, AI напишет padding: 12px, потому что 12, разумное число. Оно не неправильное. Оно просто не ваше.
Нет памяти между сессиями. Каждая новая сессия начинается с нуля. AI не помнит, что вчера использовал #2563EB для ссылок. Сегодня он выберет другой синий. К пятой сессии у вас три разных синих в одном прототипе.
Не читает дизайн-намерение из кода. AI видит API компонентов: импортировать Button, передать appearance="primary". Но он не понимает, когда использовать модалку вместо инлайн-сообщения, или какой отступ ставить между секциями. Это знание живёт в головах дизайнеров.

Что такое Design.md

Design.md: файл в корне репозитория, который описывает вашу дизайн-систему в формате, пригодном для AI. Для Cursor он живёт в .cursor/rules/. Для Claude: в CLAUDE.md. Для любого агента: в контексте сессии.

Идея простая: AI не должен решать «какой синий использовать для ссылки». Он должен найти var(--color-link) в спецификации.

AirOps пошли дальше: их бренд-гайдлайн имеет два представления: живой визуальный гайдлайн для людей и структурированная инструкция для AI-агентов. Один источник правды, два формата потребления.

Что включать

Токены

Полная карта CSS-переменных с значениями и контекстом. Не просто --color-primary: #2563EB, а когда и где его использовать:

## Цвета

- `--color-text`: #171717 — основной текст
- `--color-text-sub`: #525252 — вторичный текст, описания
- `--color-link`: #2563EB — ссылки и интерактивные элементы
- `--color-bg`: #fafafa — фон страницы
- `--color-border`: #e5e5e5 — разделители и границы

## Отступы (base 4px)

- `--space-100`: 4px — минимальный, между иконкой и текстом
- `--space-200`: 8px — внутри компонента
- `--space-300`: 12px — между связанными элементами
- `--space-400`: 16px — стандартный padding
- `--space-600`: 24px — между блоками
- `--space-800`: 32px — между секциями

Компоненты

Для каждого компонента: когда использовать, когда не использовать, какие токены задействованы, какие состояния есть:

## Button

Когда: основное действие на странице
Когда НЕ: навигация (используй Link)

Варианты: primary | secondary | ghost
Размеры: sm (32px) | md (40px) | lg (48px)

Токены:
- Фон: var(--color-primary)
- Текст: var(--color-on-primary)
- Скругление: var(--radius-md)
- Паддинг: var(--space-300) var(--space-400)

Состояния: default, hover, active, focus, disabled

Паттерны

Правила компоновки, которые AI не может вывести из кода: отступы между секциями, поведение сетки, принципы адаптивности. Это то, что обычно живёт в головах дизайнеров и нигде не записано.

Трёхслойная архитектура токенов

Hardik Pandya предлагает структуру из трёх слоёв, которая защищает от дрейфа:

Upstream-токены из дизайн-системы: --ds-text: #171717
Алиасы проекта со ссылкой и фолбэком: --color-text: var(--ds-text, #171717)
Компоненты используют только алиасы: color: var(--color-text)

Алиас: защитный слой. Если upstream-система переименует токен, вы меняете один алиас. Тёмная тема, высокий контраст, любая будущая тема: всё разрешается автоматически через цепочку.

Аудит: ловить то, что AI пропустил

Design.md даёт AI правильные ответы. Аудит-скрипт ловит случаи, когда AI всё равно догадался. Простой скрипт сканирует CSS-файлы на захардкоженные значения и предлагает конкретный токен:

src/components/Nav.css
  L42: color: #2563EB → используй var(--color-link)
  L78: padding: 12px → используй var(--space-300)

Ошибок: 2 | Предупреждений: 0

Скрипт возвращает exit code 1 при ошибках, можно поставить в CI. Ноль нарушений = можно мержить.

Как поддерживать

Спецификация живёт в репозитории рядом с кодом, не в Figma-комментарии и не в Notion. Когда компонент меняется в PR, спецификация в том же диффе. Три правила:

Новый компонент: пиши спеку до или во время разработки
Обновление дизайн-системы: обнови затронутые секции Design.md
Аудит в CI: скрипт автоматически проверяет каждый PR

Маленькая точная спецификация лучше большой устаревшей.

Результат

Ваша десятая AI-сессия даёт такое же визуальное качество, как первая. AI не угадывает, а ищет. Не фабрикует, а ссылается. Не дрейфует, а проверяется аудитом.

Design.md: это не документация. Это инфраструктура.