AI рисует не в вашем стиле: как заставить его соблюдать дизайн-систему

Объяснил AI что кнопки называются Button/Primary, акцент #E94560, шрифт Bricolage Grotesque. В этой сессии всё правильно. Закрыл чат. Открыл новый — снова Inter, снова синяя кнопка, снова shadcn по умолчанию.

AI не хранит память между сессиями. Каждый раз с чистого листа. Объяснять вручную каждый раз — это не воркфлоу, это потеря времени.

## Два механизма почему AI сбивается

Distributional convergence. Без контекста модель сэмплирует из статистического центра обучающих данных. Центр выглядит как shadcn с Inter и синим акцентом. Это математика, не баг — изменить поведение можно только явным контекстом.

Контекст не персистентен между сессиями. Claude Code, Cursor, v0 — все работают без памяти между сессиями. Объяснил в одной сессии — в следующей AI снова не знает.

Решение: не объяснять каждый раз. Создать файлы которые AI читает автоматически при каждом старте работы с проектом.

## Уровень 1: DESIGN.md — визуальные правила

Файл в корне репозитория. Claude Code читает его при первом обращении к проекту в сессии. Содержит визуальные правила продукта.

# DESIGN.md

## Typography
Heading (H1–H2): Fraunces, weight 700
Body text: Bricolage Grotesque, weight 400
Code, numbers: JetBrains Mono

ЗАПРЕЩЕНО: Inter, Roboto, Open Sans, Arial, системные шрифты

## Colors — ТОЛЬКО через CSS-переменные
Primary background: var(--color-background-primary) → #1A1A2E
Accent (CTA, active): var(--color-brand-accent) → #E94560
Surface (cards): var(--color-background-surface) → #F5F5F0

ЗАПРЕЩЕНО:
- Фиолетово-синие градиенты на белом фоне
- Glassmorphism без функциональной причины
- Захардкоженные hex значения в коде

## Spacing — ТОЛЬКО через var(--spacing-*)
4px grid: 4, 8, 12, 16, 24, 32, 48, 64px
ЗАПРЕЩЕНО: произвольные значения (13px, 22px, 37px)

## Components — ТОЛЬКО существующие
Кнопки: Button/Primary, Button/Secondary, Button/Ghost, Button/Danger
Карточки: Card/Default, Card/Featured, Card/Compact
Поля: Input/Default, Input/Search, Input/Textarea

ЗАПРЕЩЕНО: создавать новые варианты без добавления в библиотеку

## Visual Anti-patterns — ЗАПРЕЩЕНО
- Три одинаковые карточки в ряд без вариации контента
- Постоянно анимирующийся фон в рабочих интерфейсах
- Hero с фиолетово-синим градиентом на белом фоне

## Уровень 2: AGENTS.md — рабочие конвенции

Дополняет DESIGN.md рабочими правилами — не про внешний вид, а про процесс.

## Файловая структура
src/components/ui/  — системные компоненты (только чтение)
src/components/     — продуктовые компоненты (можно создавать)
src/lib/billing/    — НЕ ТРОГАТЬ без явного запроса
src/lib/auth/       — НЕ ТРОГАТЬ без явного запроса

## Работа с компонентами
Перед созданием нового: проверить есть ли в src/components/ui/
Если есть — использовать. Если нет — сказать явно.

## Обязательно для каждого компонента
- TypeScript интерфейс для всех пропсов
- Состояния loading/error/empty везде где есть данные
- aria-label для иконок без текста, alt для изображений
- Все цвета через CSS-переменные токенов

## Уровень 3: Golden Screen

Один эталонный экран в Figma — использует максимальный набор системных элементов. Все типографические уровни, все типы кнопок, карточка, форма, навигация. Закреплён как Reference.

В промптах где важна консистентность:

Новый экран должен быть консистентен с Golden Screen
(страница Reference/Dashboard в Figma через MCP).
Используй те же компоненты, отступы, иерархию.

Golden Screen — якорь. AI не дрейфует если ты явно на него ссылаешься.

## Уровень 4: Автоматическая проверка в CI

// .eslintrc.js — запрет захардкоженных hex
'no-restricted-syntax': ['error', {
  selector: 'Literal[value=/^#[0-9a-fA-F]{3,6}$/]',
  message: 'Используй CSS-переменную. Например: var(--color-brand-accent)'
}]

Ловит самое частое нарушение — hex в коде. Остальное через ревью.

## Почему DESIGN.md эффективнее промптов

Кажется что можно просто добавлять правила в каждый промпт. Это работает — но плохо масштабируется по трём причинам.

Промпт с правилами конкурирует с описанием задачи за внимание модели. Длинный промпт — хуже и правила, и задача. DESIGN.md читается один раз в начале сессии и остаётся в контексте без конкуренции с задачей.

Разные люди в команде пишут промпты по-разному. Один добавил правила, другой забыл. DESIGN.md — единственный источник для всей команды. Нет разночтений.

При длинной сессии AI может «забыть» правила из начала разговора. DESIGN.md можно упоминать в начале каждого промпта одной строкой: «Прочитай DESIGN.md». Это дешевле чем объяснять всё заново.

## Что делать когда AI продолжает нарушать

Каждое нарушение — сигнал что документация неполная. Не «AI плохой».

Правило слишком расплывчатое. «Используй правильную типографику» → «Используй Bricolage Grotesque для body, Fraunces для H1–H2. Никогда Inter». Конкретность работает.

Правило похоронено в длинном файле. AGENTS.md до 200 строк — длиннее и важные правила теряются. Критичные правила — ближе к началу.

AI соблюдает в начале но нарушает к концу длинной сессии. Добавляй напоминание в каждый промпт: «Прочитай DESIGN.md. Только компоненты из списка». Две строки, никакого дублирования содержимого.

## Тест качества: как понять что система работает

Тест консистентности (раз в 2 недели).

Условия: дай только DESIGN.md и AGENTS.md, без других инструкций.
Задача: создай экран списка пользователей с поиском и фильтром.

Проверяю:
☐ Шрифт Bricolage Grotesque (не Inter)
☐ Кнопки из DESIGN.md (Button/Primary), не новые
☐ Цвета через var(--color-*), не hex
☐ Карточки Card/Default или Card/Compact (не новый компонент)
☐ Нет трёх одинаковых карточек в ряд без вариации

Каждое нарушение → добавить явный запрет в DESIGN.md.

## Промпт с полной защитой

Прочитай DESIGN.md и AGENTS.md перед началом работы.

Задача: [описание]

Ограничения специфичные для этой задачи:
- Только компоненты из DESIGN.md, не создавать новые
- Все цвета через var(--color-*), никакого hex
- Шрифт: Bricolage Grotesque для текста, Fraunces для заголовков
- Сверься с Golden Screen (Reference в Figma через MCP)

После завершения:
- Перечисли все компоненты которые использовал (точные имена)
- Перечисли CSS-переменные цветов которые применил
- Если создал что-то новое (не из библиотеки) — отметь явно

## Как DESIGN.md эволюционирует вместе с продуктом

DESIGN.md написанный один раз и не обновляемый — это устаревший документ который вводит AI в заблуждение. Через полгода без обновлений он описывает продукт каким он был, а не каким является.

Практика которая работает: обновлять DESIGN.md в том же PR в котором меняется визуальная система. Изменился акцентный цвет — обновил токен в CSS и значение в DESIGN.md в одном коммите. Добавили новый вариант компонента — добавили в список разрешённых компонентов.

Ещё одна практика: раз в месяц просматривать DESIGN.md и убирать устаревшее. Компонент который удалили из системы — убрать из списка. Правило которое добавили но оно никогда не нарушается — возможно стало излишним.

DESIGN.md который активно поддерживается — это живой инструмент. DESIGN.md который не трогали три месяца — скорее всего устарел.

## Команда и DESIGN.md: как вовлечь всех

DESIGN.md максимально эффективен когда вся команда его знает и понимает. Несколько практик которые помогают:

Онбординг нового человека: первый день включает чтение DESIGN.md и AGENTS.md. Не «посмотри когда будет время» — явная часть онбординга.

Ревью через систему: при проверке PR спрашивать «нарушает ли это что-то в DESIGN.md?» вместо субъективных суждений о красоте. Объективный критерий снимает споры.

Обновление через PR с описанием: изменение в DESIGN.md — это PR с описанием почему правило добавлено или изменено. Создаёт историю решений и позволяет команде обсуждать до применения.

## Антипаттерн: слишком много правил

DESIGN.md с 500 строками правил — хуже чем DESIGN.md с 50 строками.

Когда документация слишком объёмная, AI начинает применять правила некорректно: добавляет aria-label к каждому элементу включая те которым он не нужен, или пытается применить typography-токены к иконкам. Перегруз правилами создаёт новые проблемы.

Принцип: только правила которые AI нарушает без них. Если AI никогда не ставит transition: all — не нужно запрещать это в DESIGN.md. Если AI иногда использует Inter — запрети явно.

Лучший способ определить что добавить: тест из предыдущего раздела. Что AI нарушил — то запрети. Что не нарушил — не добавляй превентивно. Документация растёт от реальных проблем, не от предполагаемых.

## Реальная оценка: сколько времени экономит система

Команда из 3 человек (1 дизайнер, 2 разработчика) без системы тратит в среднем:

• 3 часа в неделю на вопросы «как правильно»
• 2 часа в неделю на исправление расхождений дизайн/код
• 4 часа в неделю на правки AI-генерации которая «немного не то»

Итого: 9 часов в неделю. При стоимости часа $50 — $450 в неделю, $1800 в месяц.

С системой (DESIGN.md + AGENTS.md + MCP) эти цифры падают примерно до 2–3 часов в неделю. Экономия: $300 в неделю. Время создания системы — около 40 часов. Окупается за 2 месяца.

Это не маркетинговые цифры — это реальный расчёт который можно показать стейкхолдерам.

☐ DESIGN.md: типографика + цвета + компоненты + anti-patterns
☐ AGENTS.md: файловая структура + запрещённые директории
☐ Оба файла в корне репозитория
☐ Golden Screen в Figma, ссылка в промптах
☐ ESLint-правило против hex в коде
☐ Тест раз в 2 недели: DESIGN.md + AGENTS.md → стандартный экран
☐ Нарушения в тесте → обновить документацию (не ворчать на AI)