DESIGN.md: обучаем ИИ-агентов дизайн-системе

DESIGN.md — это файл в формате Markdown с YAML-шапкой, который предоставляет ИИ-агентам постоянное и структурированное понимание дизайн-системы. Он объединяет два важнейших слоя:

1. Машиночитаемые Токены (YAML-шапка): точные значения для цветов, типографики, отступов и компонентов.
2. Человекочитаемое Обоснование (Текст Markdown): контекст и рекомендации, объясняющие, почему эти значения существуют и как их применять.

Эта двойная структура критически важна. Как обнаружила команда Vercel, простое описание визуального языка в прозе приводит к тому, что разные модели интерпретируют его совершенно по-разному. Токены обеспечивают конкретную и однозначную основу.

---
version: alpha
name: Heritage
description: Архитектурный минимализм встречает журналистскую серьезность.
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
  on-tertiary: "#FFFFFF"
  border: "#E5E0D8"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
    fontWeight: 400
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
---

## Обзор

Архитектурный минимализм встречает журналистскую серьезность. Интерфейс напоминает дорогую матовую отделку — элитную газету или современную галерею.

## Цвета

Палитра основана на семантических токенах. Используйте роль (например, `{colors.primary}`) — никогда не используйте шестнадцатеричное значение напрямую — при создании компонентов.

Порядок Разделов и Псевдонимы

Разделы можно опускать, но те, которые присутствуют, должны следовать именно этому порядку. Линтер укажет на любое отклонение.

Основные Типы Токенов

DESIGN.md использует структурированный набор типов токенов для определения дизайн-системы.

Структура Компонентов

Компоненты связывают имя с группой свойств-токенов, что позволяет создавать детализированные и согласованные элементы UI.

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: "12px 20px"
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

Допустимые свойства компонентов: backgroundColor, textColor, typography, rounded, padding, size, height и width. Варианты (например, при наведении, активный, нажатый) описываются как отдельные записи компонентов со связанными ключами.

Путь Vercel с DESIGN.md является наиболее полным практическим примером. Они эволюционировали от наивного «промпт-ориентированного» подхода к сложной трёхчастной системе, которая кардинально повысила качество и согласованность создаваемого ИИ дизайна.

Три уровня системы

1. DESIGN.md (Руководство и Текст)

Этот файл содержит высокоуровневые указания. Он показывает агентам, как структурировать информацию для читателя, выстраивать доказательства и выбирать композицию. Он также явно называет и запрещает распространенные «рефлексы сгенерированного дизайна» (например, универсальный центрированный заголовок с последующей сеткой карточек или декоративные градиенты), к которым агенты часто склоняются.

2. Публичная Таблица Стилей (CSS)

Она полностью избавляет модель от необходимости придумывать стилизацию. Вместо того чтобы изобретать типографику и отступы, агент использует документированный набор CSS-классов и токенов, предоставленных таблицей стилей. Агент никогда не читает саму таблицу стилей, он только ссылается на имена классов в HTML, которые затем стилизуются при рендеринге страницы в браузере. Это экономит ценное контекстное пространство для более важных дизайн-указаний.

3. Цикл Оценки

Это двигатель, заставляющий работать первые две части. Он использует повторяемый набор фиксированных сценариев (промпты + тестовые данные) для проверки каждого изменения в DESIGN.md. Проверяющие-люди сравнивают результаты, и их обратная связь кодируется обратно в DESIGN.md в виде текстовых правил или в кодовую базу в виде детерминированных проверок.

Отказ от «Рефлексов Сгенерированного Дизайна»

Одним из самых мощных аспектов DESIGN.md от Vercel является явный список паттернов, которых следует избегать. Называя эти распространенные шаблоны по имени, агенты могут гораздо надежнее распознавать и избегать их. Вот несколько ключевых запретов:

1. Заглавные буквы или разреженные врезки, кикеры и верхние линейки.
2. Декоративные градиенты, свечения, размытые пятна или эффекты стекла.
3. Универсальный центрированный текст в герое с последующей сеткой карточек.
4. Карточки, вложенные в другие карточки, или использование границ для исправления слабой иерархии.
5. Темный скругленный прямоугольник вокруг каждого графика или калькулятора.
6. Декоративные графики или избыточные визуализации.
7. Повторяющиеся полноширинные полосы, не имеющие общей шкалы или не отображающие видимых различий.

Этот подход превращает агента из генератора шаблонных паттернов в более вдумчивого дизайнера.

Основываясь на опыте Vercel и официальной спецификации, вот пошаговое руководство по созданию вашего собственного DESIGN.md.

1. Начните с одного артефакта

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

2. Сохраните базовую версию

Сгенерируйте страницу без каких-либо указаний из DESIGN.md. Сохраните промпт, входные данные, конфигурацию и скриншот. Это ваша картина «до» для оценки улучшений.

3. Соберите ваши последние десять правок

Просмотрите отзывы из дизайн-ревью, запросов на слияние или Slack. Переформулируйте каждую правку как наблюдаемое действие. Например:

1. Нечетко: «Сделай таблицу менее тесной».
2. Наблюдаемо: «Дайте таблицам с данными использовать всю доступную ширину».

4. Структурируйте ваш первый файл

Создайте DESIGN.md со следующими ключевыми разделами:

1. Обзор: Краткое заявление о стиле и философии вашего бренда.
2. Цвета: Определите семантические цветовые токены (например, primary, secondary).
3. Типографика: Определите четкую шкалу размеров с fontFamily, fontSize и fontWeight.
4. Макет/Отступы: Определите шкалу отступов (sm, md, lg).
5. Рекомендации: Перечислите ваши наблюдаемые правки как четкие правила.

5. Используйте официальный CLI

Интерфейс командной строки @google/design.md необходим для валидации и экспорта.

Примечание для Windows: используйте псевдоним designmd вместо design.md в командах, чтобы избежать конфликтов с ассоциациями файлов в PowerShell.

6. Запустите цикл оценки

Сгенерируйте страницу снова, на этот раз с загруженным вашим DESIGN.md. Сравните её вслепую с базовой версией, используя рубрику. Что все еще требует ручной правки? Обновите файл соответственно. Запустите тест снова. Повторяйте.

Цикл оценки — это то, что отличает полезный промпт от надежной системы. Опыт Vercel показывает, что это систематический процесс:

1. Запуск сценария: генерация страниц на основе фиксированных промптов и тестовых данных.
2. Обзор: люди проверяют результат, выявляя ошибки.
3. Кодирование исправления: правка помещается в самое узкое место, которое может её применить. Текстовые правки попадают в DESIGN.md. Повторяющиеся механики попадают в таблицу стилей. Механические ошибки становятся детерминированными проверками в коде.
4. Повторный запуск: проверка, что изменение сработало и не навредило другим сценариям.

Этот цикл привел к измеримому улучшению. В одном тесте страницы, сгенерированные с DESIGN.md, показали на 57% меньше известных механических ошибок, чем страницы, созданные без него.

DESIGN.md — это больше, чем просто файл, это процесс. Он обеспечивает структурированный способ преодоления разрыва между человеческим дизайнерским замыслом и генерацией, выполняемой ИИ. Объединяя четкую спецификацию, валидирующий CLI и цикл обратной связи, основанный на оценке, команды могут перейти от простого направления агентам к настоящему обучению их визуальной идентичности.

Пример Vercel доказывает, что значительное улучшение согласованности и качества достижимо. Ключ в том, чтобы не написать один идеальный файл, а создать систему, которая кодирует правки, итеративно развивается на основе реальной обратной связи и постоянно улучшает результат.