Использование DESIGN.md для генерации UI через AI-агентов

Использование DESIGN.md для генерации UI через AI-агентов

Разбираем репозиторий awesome-design-md: как файлы DESIGN.md помогают AI-агентам создавать интерфейсы, соответствующие дизайн-системам известных брендов.

Проблема разрыва между дизайном и кодом

Проблема разрыва между дизайном и кодом

Когда мы говорим об автоматизации верстки или генерации интерфейсов через AI-агентов, мы часто сталкиваемся с классической проблемой: код выглядит рабочим, но он «чужой». Если вы попросите LLM собрать компонент кнопки, она выдаст что-то вполне функциональное, но это будет кнопка из стандартного набора CSS-фреймворка, а не часть вашей корпоративной дизайн-системы.

С практической точки зрения, разрыв происходит на этапе передачи контекста. Дизайнеры работают в Figma, где визуальные решения описаны через слои, эффекты и компоненты. Разработчики работают с кодом, где эти решения должны превратиться в конкретные значения свойств. AI-агенты же, если им не дать четкую спецификацию, склонны к галлюцинациям в области стилей: они выбирают «на глаз» подходящие цвета или отступы, что полностью убивает предсказуемость интерфейса.

Почему AI ошибается в стилях

Основная причина ошибок — отсутствие единого источника истины (Single Source of Truth). Без структурированного описания правил, AI-агент пытается угадать визуальный язык, опираясь на свои обучающие данные. В итоге вместо брендового синего цвета #0055FF вы получаете стандартный blue из браузера или случайный оттенок, который «похож».

Если мы посмотрим на процесс генерации без использования DESIGN.md, то увидим, что агент получает только текстовое описание задачи. Например: «Создай карточку товара».

Результат в коде будет выглядеть примерно так:

cssКопировать
/* Типичный результат без контекста дизайн-системы */
.product-card {
  padding: 16px;
  border-radius: 8px;
  background-color: white;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

Здесь нет никакой связи с глобальными переменными проекта. Если завтра бренд-бук изменится и отступы станут 12px, а радиус скругления — 4px, вам придётся переписывать каждый сгенерированный компонент вручную. Это именно то «решение на коленке», которого стоит избегать при построении автоматизированных процессов.

Роль дизайн-токенов в автоматизации

Чтобы сделать генерацию интерфейсов предсказуемой, нужно перевести визуальный язык на язык данных. Здесь на сцену выходят дизайн-токены — атомарные единицы стиля (цвета, типографика, отступы, тени), представленные в виде структурированных файлов (JSON или YAML).

Вместо того чтобы заставлять AI гадать, мы даём ему набор токенов. Это позволяет превратить задачу из «нарисуй красиво» в «собери интерфейс, используя эти переменные». Если вы уже изучали использование DESIGN.md для генерации интерфейсов, то знаете, что именно наличие такой спецификации позволяет агенту соблюдать консистентность.

Пример типичного файла токенов (tokens.json), который служит фундаментом для работы агента:

jsonКопировать
{
  "color": {
    "brand": {
      "primary": { "value": "#0055FF" },
      "secondary": { "value": "#6C757D" }
    },
    "background": {
      "surface": { "value": "#FFFFFF" }
    }
  },
  "spacing": {
    "small": { "value": "8px" },
    "medium": { "value": "16px" },
    "large": { "value": "24px" }
  },
  "radius": {
    "button": { "value": "4px" }
  }
}

Теперь, когда мы используем DESIGN.md для генерации UI, агент не пишет произвольный CSS. Он обращается к существующим переменным. Сгенерированный код становится частью системы:

cssКопировать
/* Результат с использованием токенов */
.product-card {
  padding: var(--spacing-medium);
  border-radius: var(--radius-button);
  background-color: var(--color-background-surface);
}

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

Обзор репозитория awesome-design-md

Обзор репозитория awesome-design-md

Когда мы говорим об автоматизации разработки, мы привыкли мыслить категориями CI/CD, инфраструктуры как кода или контейнеризации. Но с приходом AI-агентов на первый план выходит другая проблема: как передать модели не просто «сделай красиво», а конкретные технические параметры, которые не нарушат целостность интерфейса. Репозиторий awesome-design-md предлагает решение этой задачи через стандартизацию описания визуальных правил.

С практической точки зрения, это не просто список ссылок, а структурированная база знаний о том, как описывать дизайн-системы в текстовом формате, понятном для LLM (Large Language Models). Это мост между визуальным макетом в Figma и кодом, который генерирует агент.

Что такое файлы DESIGN.md

Если вы привыкли работать с дизайн-токенами в JSON или YAML, то формат DESIGN.md может показаться избыточным. Однако его главная ценность — в семантической плотности. Файл DESIGN.md — это декларативное описание визуального языка проекта, которое превращает абстрактные понятия вроде «основной цвет» в конкретные инструкции для генерации кода.

Вместо того чтобы заставлять AI угадывать отступы или скругления углов, мы предоставляем ему файл, который работает как жесткий контракт. Если мы рассматриваем использование DESIGN.md для генерации интерфейсов, становится ясно, что этот файл служит «источником истины» (Single Source of Truth), аналогично тому, как Terraform описывает состояние инфраструктуры.

Типичная структура такого файла включает в себя:

• Design Tokens: значения цветов, типографики, теней и отступов.
• Component Rules: правила поведения элементов (например, как меняется кнопка при наведении).
• Layout Patterns: сетки и правила позиционирования.

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

markdownКопировать
## Color Tokens

### Brand Colors
- primary-500: #007AFF (Main action color)
- primary-600: #005BBF (Hover state)
- secondary-500: #5856D6 (Accent color)

### Semantic Colors
- success: #34C759
- error: #FF3B30
- warning: #FF9500

Такая предсказуемость критически важна. Без четкого описания AI-агент может создать кнопку, которая визуально «вписывается» в контекст, но по факту нарушает гайдлайны бренда.

Анализ подходов популярных брендов

Репозиторий аккумулирует примеры того, как крупные игроки индустрии подходят к описанию своих систем. Это позволяет не изобретать велосипед, а использовать проверенные паттерны.

Если мы проанализируем подходы, представленные в коллекции, можно выделить два основных направления:

1. Токенно-ориентированный подход. Здесь акцент сделан на максимально мелких единицах — цветах, размерах шрифтов и интервалах. Это наиболее гибкий метод, который позволяет использовать DESIGN.md для генерации UI с высокой степенью точности, так как агент оперирует конкретными значениями.
2. Компонентный подход. В этом случае описание фокусируется на высокоуровневых сущностях: «Input Field», «Modal», «Card». Это упрощает задачу для агентов, которым нужно собрать страницу из готовых блоков, соблюдая их внутреннюю логику.

Разбор этих подходов помогает понять, как правильно выстроить процесс: от простого перечисления цветов до сложной иерархии компонентов. Для тех, кто планирует использование DESIGN.md для генерации UI через AI, изучение этих примеров — обязательный этап проектирования промптов.

С точки зрения системного инженера, это похоже на выбор между конфигурацией на уровне ядра и настройкой прикладного ПО: первый вариант дает полный контроль, второй — быстрее в реализации, но требует понимания базовых принципов.

Практическое применение в разработке

Интеграция файлов в проект

С практической точки зрения, внедрение DESIGN.md в рабочий процесс не требует перестройки CI/CD или изменения архитектуры приложения. Это декларативный подход: мы просто добавляем в корень репозитория файл, который служит «источником истины» для визуальной части.

Если вы работаете с существующей дизайн-системой, я рекомендую не копировать её целиком, а вычленить ключевые токены. Чтобы обеспечить предсказуемость интерфейса, файл должен содержать конкретные значения: отступы, палитру цветов и типографику.

Для удобства управления я обычно размещаю такие файлы в директории .design/, чтобы они не смешивались с программным кодом, но при этом были доступны для контекстного чтения AI-агентами. Структура может выглядеть так:

textКопировать
my-project/
├── .design/
│   ├── core-tokens.md    # Базовые цвета, сетка, шрифты
│   └── components.md     # Спецификации кнопок, инпутов и т. д.
├── src/
├── package.json
└── DESIGN.md             # Главный входной файл для агента

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

Настройка промптов для AI-агентов

Когда файл готов, основная задача — правильно «скормить» его агенту. Если вы просто скажете: «Сделай форму регистрации», вы получите стандартный Bootstrap-подобный результат, который будет конфликтовать с вашим брендом.

Чтобы добиться соответствия дизайн-системе, промпт должен содержать жёсткую связку между инструкцией и файлом спецификации. Я использую метод явного указания контекста. Вместо общих фраз нужно давать команду на использование конкретных сущностей из DESIGN.md.

Пример эффективного промпта для агента (например, для Cursor или GitHub Copilot):

textКопировать
Используй спецификации из файла .design/core-tokens.md для создания нового компонента "UserCard". 

Требования:
1. Цветовая схема: только те значения, которые указаны в секции [Colors].
2. Отступы: используй только шаги сетки из [Spacing].
3. Типографика: примени стили из [Typography] для заголовков и основного текста.
4. Не используй inline-стили, создай Tailwind-классы или CSS-переменные, соответствующие токенам.

Результат должен быть предсказуемым и не выходить за рамки заданной дизайн-системы.

С точки зрения системного инженера, такой подход превращает генерацию кода из «лотереи» в контролируемый процесс. Вы задаёте границы, внутри которых AI может проявлять креативность, не нарушая визуальную целостность.

Если вы только начинаете путь в автоматизации UI, рекомендую изучить использование DESIGN.md для генерации UI, чтобы понять, как правильно структурировать первичные инструкции. Это поможет избежать ситуации, когда агент генерирует рабочий, но визуально «чужеродный» для проекта код.

Ограничения и предсказуемость результата

Ограничения и предсказуемость результата

Когда мы переходим от теории к практике, важно понимать: наличие качественного DESIGN.md не превращает AI-агента в полноценного UI-дизайнера. Файл служит декларативным описанием правил, но он не гарантирует, что нейросеть поймёт контекст использования этих правил в сложных сценариях.

С практической точки зрения, основная проблема заключается в том, что LLM (Large Language Models) склонны к «галлюцинациям» в деталях, которые не описаны в токенах напрямую. Если в вашем дизайн-файле указаны только цвета и типографика, агент может самостоятельно решить, что отступы между карточками должны быть 24px, хотя ваша система подразумевает только кратные 8px.

Когда генерация интерфейса даёт сбой

Сбои обычно происходят в трёх сценариях: нарушение иерархии, логические ошибки в компоновке и «смешивание» стилей.

Во-первых, агент может проигнорировать специфику дизайн-токенов при создании сложных состояний (например, hover или disabled). Если в DESIGN.md прописан основной цвет brand-primary: #0055ff, агент может создать состояние нажатия, просто затемнив его на глаз, вместо того чтобы использовать системный токен brand-primary-dark.

Во-вторых, проблема композиции. AI хорошо справляется с генерацией отдельных кнопок или инпутов, но когда дело доходит до целых страниц, нарушается предсказуемость макета. Агент может создать визуально приятный интерфейс, который невозможно реализовать в рамках существующей верстки или который нарушает правила доступности (Accessibility).

Пример типичной ошибки в сгенерированном CSS, когда агент пытается «угадать» значения вместо использования токенов:

cssКопировать
/* Плохо: агент проигнорировал DESIGN.md и использовал hardcoded значения */
.submit-button {
  background-color: #0055ff; /* Вместо var(--color-brand-primary) */
  padding: 12px 24px;        /* Вместо var(--spacing-md) */
  border-radius: 5px;        /* Вместо var(--radius-sm) */
}

/* Хорошо: агент строго следует системе */
.submit-button {
  background-color: var(--color-brand-primary);
  padding: var(--spacing-md) var(--spacing-lg);
  border-radius: var(--radius-sm);
}

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

Необходимость ручной верификации

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

Процесс верификации стоит разделить на два этапа:

1. Технический аудит. Проверка того, что агент действительно использует CSS-переменные или токены, описанные в вашем репозитории, а не подставляет произвольные значения. Это можно автоматизировать с помощью линтеров или простых скриптов, которые ищут hardcoded hex-коды в сгенерированных стилях.
2. Визуальный контроль. Сравнение результата с эталоном из Figma. Даже если код технически корректен, композиция может «разваливаться» на разных разрешениях экрана.

Для автоматизации части проверок можно использовать инструменты вроде Storybook. Вы можете настроить его так, чтобы он подсвечивал компоненты, которые выходят за рамки заданных параметров.

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

FAQ

Как DESIGN.md влияет на точность генерации кода

DESIGN.md выступает в роли «единого источника истины» (Single Source of Truth) для AI-агента. Без него модель опирается на свои внутренние веса, что приводит к галлюцинациям в отступах, цветах или размерах шрифтов. Когда у агента есть файл с четко описанными дизайн-токенами, он перестаёт «угадывать» и начинает использовать конкретные значения.

С практической точки зрения это повышает предсказуемость результата. Если в токене указано color-primary: #007bff, агент применит именно его, а не похожий синий из своей обучающей выборки. Подробнее о том, как это работает на практике, можно прочитать в материале Использование DESIGN.md для генерации интерфейсов.

Можно ли использовать DESIGN.md вместо Figma

Figma — это инструмент для визуального проектирования, а DESIGN.md — это текстовое описание этой системы для машин. Они не заменяют, а дополняют друг друга. В идеальном рабочем процессе дизайнер обновляет компоненты в Figma, а затем эти изменения экспортируются в формат дизайн-токенов, которые попадают в DESIGN.md.

Если вы хотите автоматизировать этот процесс, стоит изучить подходы к использованию DESIGN.md для генерации UI, где описывается связка визуального дизайна и текстовых спецификаций.

Какие AI-агенты лучше всего работают с этим форматом

Лучше всего справляются с такими спецификациями агенты, которые имеют доступ к контекстному окну с поддержкой длинных системных инструкций и умеют работать с файловой структурой репозитория. Это могут быть как специализированные агенты, так и продвинутые LLM в режиме чата, если вы передаёте им содержимое файла.

Для эффективной работы убедитесь, что агент понимает иерархию токенов. Например, если вы используете использование DESIGN.md для генерации UI через AI, агент должен уметь сопоставлять абстрактный токен spacing-md с конкретным значением 16px в CSS или Tailwind-конфиге.

Как внедрить DESIGN.md в существующий проект

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

Пример базовой структуры токенов в файле:

markdownКопировать
## Design Tokens

### Colors
- primary-500: #3b82f6
- secondary-500: #6b7280

### Spacing
- sm: 8px
- md: 16px
- lg: 24px

После этого при запросе «создай кнопку в стиле primary» агент будет использовать именно #3b82f6. О том, как масштабировать этот подход, читайте в руководстве Использование DESIGN.md для генерации UI.

Нужно ли описывать каждый компонент в DESIGN.md

Нет, описывать каждый мелкий элемент — избыточная трата ресурсов. Достаточно описать атомарные значения (цвета, шрифты, отступы) и правила их комбинирования. Описание сложных компонентов (например, модальных окон) лучше оставить в виде примеров использования, чтобы агент понимал паттерны, а не просто заучивал свойства.

Если вы планируете глубокую интеграцию, рекомендую изучить использование DESIGN.md для генерации UI через AI, чтобы не перегружать контекстное окно лишней информацией.

Часто задаваемые вопросы

Можно ли использовать DESIGN.md для существующих проектов?

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

Чем DESIGN.md лучше обычного текстового описания стилей?

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

Поможет ли этот метод избежать лишнего кода в компонентах?

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

Нужно ли прописывать в DESIGN.md каждый мелкий элемент интерфейса?

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