DESIGN.md для ИИ-агентов: генерация UI по гайдлайну бренда

Коллекция DESIGN.md от VoltAgent содержит разбор популярных дизайн-систем. Положите файл в проект — кодинг-агент сгенерирует UI по гайдлайну бренда.

Что такое DESIGN.md и зачем он кодинг-агентам

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

В контексте awesome-list DESIGN.md от VoltAgent файл становится исполняемой спецификацией: он фиксирует design-tokens, правила компонентов и ограничения, которые агент использует при генерации UI. Это не просто описание внешнего вида — это техническое задание, которое превращает абстрактные правила бренда в конкретный код.

DESIGN.md как техническое задание для ИИ

Кодинг-агент читает DESIGN.md так же, как человек читает ТЗ: он извлекает токены, правила компонентов и ограничения, затем генерирует интерфейс. Разница в том, что агент не утомляется и не пропускает абзац про отступы между кнопками.

Во-первых, файл фиксирует дизайн-токены: цвета, типографику, отступы, радиусы скругления. Агент использует их как переменные, а не угадывает значения на глаз.

Во-вторых, DESIGN.md описывает компоненты и их состояния. Кнопка в обычном состоянии, при наведении, в disabled — всё это прописано явно. Агенту не нужно додумывать, как должен выглядеть инпут с ошибкой.

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

markdown
# Design System — Acme Corp

## Tokens
colors:
  primary: "#0066cc"
  textPrimary: "#1a1a1a"
  background: "#ffffff"

spacing:
  unit: "8px"
  scale: [4, 8, 16, 24, 32, 48]

borderRadius:
  sm: "4px"
  md: "8px"
  lg: "12px"

## Components
Button:
  base:
    padding: "8px 16px"
    fontSize: "14px"
    fontWeight: 500
    borderRadius: "md"
  variants:
    primary:
      background: "colors.primary"
      color: "#ffffff"
    secondary:
      background: "transparent"
      border: "1px solid colors.primary"
      color: "colors.primary"

Input:
  base:
    height: "40px"
    padding: "0 12px"
    borderRadius: "md"
  states:
    error:
      borderColor: "#d32f2f"

Когда агент видит такой файл, он генерирует React- или Vue-компоненты с жёсткой привязкой к токенам. Предсказуемость конфигураций здесь ключевая: изменить primary-цвет в одном месте DESIGN.md — и агент пересоберёт все компоненты, использующие этот токен.

Если мы посмотрим на рабочий процесс, он выглядит так:

Разработчик кладёт DESIGN.md в корень репозитория.
Кодинг-агент получает задачу: «создай форму входа».
Агент читает токены и компоненты из файла, генерирует код формы.
Результат соответствует брендбуку без дополнительных согласований.

Подробнее про разбор популярных DESIGN.md можно почитать в материале Анализ DESIGN.md файлов популярных дизайн-систем.

Отличие от Figma-макета и стилегайда

Figma-макет показывает, как должен выглядеть интерфейс. Это картинка со слоями, ограничениями и автораскладкой. Человек открывает макет, смотрит на него и пишет код вручную. Агент не может «посмотреть» на Figma так же, как человек — ему нужен текстовый контракт.

Стилегайд — это документация для людей. Он описывает правила словами: «кнопка основного действия имеет синий цвет и скругление 8 пикселей». Стилегайд быстро устаревает: дизайнер меняет цвет в Figma, забывает обновить стилегайд, разработчик верстает по старому правилу.

DESIGN.md занимает промежуточное положение. Это не макет, не документация, а исполняемая спецификация. Если в Figма изменили primary-цвет, разработчик обновляет токен в DESIGN.md, и агент при следующей генерации подтянет новое значение.

Разница на примере:

Figma: дизайнер рисует кнопку, разработчик смотрит на макет и пишет <button className="btn-primary">.
Стилегайд: в вики написано, что primary-кнопка синяя. Разработчик помнит это или заглядывает в вики перед каждой версткой.
DESIGN.md: в репозитории лежит файл с токенами. Агент читает colors.primary и подставляет #0066cc в сгенерированный компонент автоматически.

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

Практическое применение описано в руководстве Использование DESIGN.md для генерации UI.

Что входит в коллекцию VoltAgent/awesome-design-md

Коллекция VoltAgent/awesome-design-md: Анализ дизайн-систем для генерации UI — это подборка DESIGN.md-файлов из популярных дизайн-систем. Идея проста: положите такой файл в проект, и кодинг-агент будет ориентироваться на него при генерации интерфейса. Не нужно объяснять ИИ каждый раз, какой отступ между кнопками или какой оттенок синего используется в бренде — всё это уже описано в DESIGN.md.

С практической точки зрения, DESIGN.md работает как единый источник правды для агента. Если в файле описаны токены и компоненты, результат будет предсказуемым — не придётся переделывать сгенерированный UI под гайдлайн после факта.

Разбор брендов: от токенов до компонентов

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

Во-первых, в разбор входят дизайн-токены — цветовая палитра, типографика, радиусы скругления, тени, отступы. Это базовые «кирпичи» интерфейса.

Во-вторых, семантические токены — как базовые значенияпятся на роли интерфейса: primary, surface, error и так далее. Без этого слоя агент не поймёт, какой цвет использовать для кнопки «Отправить», а какой для сообщения об ошибке.

В-третьих, компоненты — кнопки, поля ввода, карточки, модальные окна. Описаны не картинками, а правилами: какие токены используются, какие состояния есть (hover, focus, disabled), какая иерархия.

Пример фрагмента DESIGN.md для вымышленного бренда:

markdown
# DESIGN.md

## Tokens
- color-primary: #0066cc
- color-surface: #ffffff
- spacing-xs: 4px
- spacing-md: 16px
- radius-md: 8px

## Components
### Button
- variant: primary
  background: color-primary
  color: #ffffff
  padding: spacing-xs spacing-md
  border-radius: radius-md
- variant: secondary
  background: transparent
  border: 1px solid color-primary

Кодинг-агент читает этот блок и генерирует компонент, который визуально соответствует гайдлайну. Не нужно присылать скриншоты из Figma и объяснять, «сделай как у конкурентов» — всё уже в токенах.

Подробнее о том, как разобраны конкретные дизайн-системы, можно прочитать в материале Анализ DESIGN.md файлов популярных дизайн-систем или Анализ DESIGN.md файлов популярных дизайн-систем.

Как добавить DESIGN.md в свой проект

Добавить файл в проект проще, чем настроить линтер. Положите DESIGN.md в корень репозитория — большинство агентов ищут его там по умолчанию. Если проект большой и дизайн-система вынесена в отдельный пакет, можно положить файл рядом с исходниками компонентов, например в packages/ui/DESIGN.md.

Пример минимального DESIGN.md для старта:

markdown
# DESIGN.md

## Brand
name: Моя Компания
primary-color: #0066cc
font-family: Inter, system-ui, sans-serif

## Components
### Button
- size: sm
  padding: 6px 12px
  font-size: 14px
- size: md
  padding: 8px 16px
  font-size: 16px

После этого кодинг-агент будет подхватывать файл автоматически при генерации UI. Если агент не видит файл, проверьте, что он лежит в доступной директории и не добавлен в .gitignore по ошибке.

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

Если хотите понять общую концепцию дизайн-систем и токенов, начните со статьи design-system.

Интеграция с кодинг-агентами и генерация UI

DESIGN.md от VoltAgent — это не просто документация о цветах и шрифтах. Это контекст, который кодинг-агент читает до того, как напишет первый компонент. Положи файл в корень проекта — и Claude Code, Cursor или Copilot будут ориентироваться на токены бренда, а не придумывать свои оттенки синего.

Подробный разбор популярных дизайн-систем есть в Анализе DESIGN.md файлов популярных дизайн-систем, а практическое руководство по генерации — в Использовании DESIGN.md для генерации UI.

Подготовка контекста для Claude Code и других агентов

Кодинг-агент не угадает гайдлайн бренда. Ему нужно явно сказать, где лежит источник истины. Во-первых, положи DESIGN.md в корень репозитория рядом с README.md. Во-вторых, добавь ссылку на него в инструкцию агента — например, в .claude/CLAUDE.md для Claude Code или AGENTS.md для Cursor.

Пример DESIGN.md:

markdown
# DESIGN.md

## Дизайн-токены
- Цвета: --color-primary: #0066cc; --color-text: #1a1a1a;
- Типографика: --font-family: 'Inter', sans-serif; --font-size-base: 16px;
- Отступы: --space-1: 4px; --space-2: 8px; --space-3: 16px;

## Компоненты
### Кнопка (Button)
- Варианты: primary, secondary, ghost
- Размеры: sm, md, lg
- Состояния: default, hover, active, disabled
- Правило: primary-кнопка всегда использует --color-primary и --space-3 для padding

## Антипаттерны
- Не использовать произвольные hex-цвета вне токенов
- Не задавать margin через style-атрибут

Теперь агент знает, что --color-primary — это не предложение, а требование. С практической точки зрения, контекст должен быть коротким. Если DESIGN.md раздут до ста страниц, агент перестанет его читать. Оставь только токены, правила компонентов и список того, чего делать нельзя. Это даёт предсказуемость конфигураций, которой не хватает большинству сгенерированных интерфейсов.

Пример инструкции для Claude Code (.claude/CLAUDE.md):

markdown
# Claude Code instructions

Всегда сверяйся с DESIGN.md в корне проекта перед генерацией UI-компонентов.
Используй только CSS-переменные из раздела «Дизайн-токены».
Не изобраняй новые варианты кнопок — выбирай из primary, secondary, ghost.

Если работаешь с React, добавь в контекст пример уже существующего компонента. Агент скопирует структуру и подставит свои токены.

tsx
// src/components/Button/Button.tsx — эталон, на который ориентируется агент
import { cn } from '@/lib/utils'

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
}

export function Button({ variant = 'primary', size = 'md', children }: ButtonProps) {
  return (
    <button className={cn('btn', `btn--${variant}`, `btn--${size}`)}>
      {children}
    </button>
  )
}

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

Проверка сгенерированного интерфейса на соответствие

Агент может сгенерировать компонент, который выглядит похоже, но использует #ff0000 вместо --color-error. Проверка нужна сразу, а не после релиза.

Сначала проверь сгенерированный код вручную. Открой файл и убедись, что нет жёстко заданных цветов и отступов. Если видишь style={{ backgroundColor: '#0066cc' }} — верни агенту на доработку.

Для автоматизации подключи Storybook с аддонами для дизайн-токенов. Напиши стори для каждого компонента и сравни визуально с макетом из Figma. Если команда использует визуальную регрессию, настрой Chromatic или Percy — они покажут, где агент отклонился от гайдлайна.

Пример простого теста на соответствие токенам (Playwright):

ts
import { test, expect } from '@playwright/test'

test('кнопка primary использует цвет из DESIGN.md', async ({ page }) => {
  await page.goto('/button')
  const btn = page.locator('.btn--primary')
  await expect(btn).toHaveCSS('background-color', 'rgb(0, 102, 204)')
})

Если агент регулярно нарушает одно и то же правило, не ругайте его — доработайте DESIGN.md. Добавьте отрицательное ограничение: «Не использовать !important в компонентах», «Не задавать font-size пикселями, используйте rem». Агент лучше следует правилам, когда они сформулированы как запреты, а не рекомендации.

Итог практический: DESIGN.md работает, только если агент его читает, а команда проверяет результат. Без проверки получается обычный самодеятельный UI, который через неделю никто не сможет поддержать.

Ограничения подхода и когда он не подходит

DESIGN.md от VoltAgent — удобная отправная точка. Положите файл в проект, и кодинг-агент сгенерирует кнопку, карточку или модальное окно по гайдлайну бренда. Но это не значит, что достаточно одного markdown-файла, чтобы закрыть вопрос дизайна в продакшене. Подход упирается в конкретные ограничения, о которых стоит знать до того, как полагаться на генерацию UI.

Когда DESIGN.md недостаточно для продакшена

С практической точки зрения, DESIGN.md решает задачу первичного прототипирования, но не заменяет полноценную дизайн-систему с процессами поддержки. Вот где подход ломается.

Версионирование токенов

Дизайнер меняет первичный цвет в Figma с #007bff на #0056b3. DESIGN.md в репозитории остаётся со старым значением. Агент продолжает генерировать компоненты с предыдущим цветом, и расхождение замечают уже после релиза.

Пример DESIGN.md, который быстро устаревает:

markdown
# DESIGN.md
tokens:
  colors:
    primary: "#007bff"
    secondary: "#6c757d"
  spacing:
    sm: "8px"
    md: "16px"
components:
  Button:
    variant: primary
    size: md

Без автоматизированной проверки нет способа понять, что токены в markdown не совпадают с актуальным гайдлайном. Я сталкивался с этим на проекте для интернет-магазина: агент нагенерировал десятки кнопок с корпоративным синим, а к моменту релиза брендбук уже поменял цвет на тёмно-синий. Пришлось переделывать вручную.

Доступность (a11y)

DESIGN.md редко описывает ARIA-атрибуты, управление фокусом и клавиатурную навигацию. Агент генерирует визуально правильную кнопку, но без aria-label или с неверной ролью.

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

jsx
<button className="btn btn-primary">
  Отправить заявку
</button>

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

jsx
<button
  type="submit"
  className="btn btn-primary"
  aria-label="Отправить заявку"
  disabled={isSubmitting}
>
  {isSubmitting ? 'Отправка…' : 'Отправить заявку'}
</button>

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

Сложные компоненты

Кнопку или инпут описать в markdown несложно. С датапикером, таблицей с виртуальной прокруткой или модальным окном с анимацией уже сложнее. DESIGN.md не содержит достаточно контекста для генерации такого компонента с учётом всех пограничных состояний.

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

markdown
components:
  Select:
    variant: default
    size: md

Агент сгенерирует внешний вид, но логику поведения придётся дописывать вручную. Это как собирать мебель по картинке на коробке: понятно, как должна выглядеть полка, но неясно, как крепить боковины.

Несколько тем и белый ярлык

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

Интеграция с существующим интерфейсом

Когда в проекте уже есть legacy-компоненты или чужой UI, сгенерированный по DESIGN.md блок будет выглядеть чужеродно. Агент не знает про старые CSS-классы, не учитывает специфичность селекторов и не понимает, как вписаться в текущую архитектуру стилей.

Что работает, а что нет

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

Для предсказуемости результата DESIGN.md стоит использовать вместе с описанием из Анализ DESIGN.md файлов популярных дизайн-систем и практическими примерами из Использование DESIGN.md для генерации UI. Если нужно понять, как другие команды решают похожие задачи, полезно ознакомиться с VoltAgent/awesome-design-md: Анализ дизайн-систем для генерации UI по гайдлайну бренда. Для базовых понятий стоит заглянуть в обзор design-system.

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

Нужно ли быть дизайнером, чтобы написать DESIGN.md?

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

Работает ли DESIGN.md только с агентами VoltAgent или с любыми кодинг-агентами?

Формат markdown универсален, поэтому файл можно положить в любой проект и дать почитать любому агенту, который поддерживает чтение файлов из репозитория. VoltAgent просто собрала подборку готовых примеров под популярные дизайн-системы. Свои правила вы можете описать в том же формате и использовать с Cursor, Copilot или другим инструментом.

Что произойдёт, если я изменю цвет в DESIGN.md, а компоненты уже сгенерированы?

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

Защитит ли DESIGN.md от разнобоя в интерфейсе, если в команде несколько разработчиков?

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

Достаточно ли описать только токены, или нужно расписывать каждый компонент?

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

DESIGN.md для ИИ-агентов: генерация UI по гайдлайну бренда