Продвинутый

DESIGN.md и генерация UI с помощью ИИ-агентов

Алексей Кузнецов
Алексей Кузнецов
Системный администратор5 ноября 2026 г.11 мин чтения

Разбор коллекции DESIGN.md от VoltAgent: как подключить файл к проекту и заставить coding-агента сверстать интерфейс под бренд.

design-md
design-system
design-tokens
ai-coding

DESIGN.md и генерация UI с помощью ИИ-агентов

Разбор коллекции DESIGN.md от VoltAgent: как подключить файл к проекту и заставить coding-агента сверстать интерфейс под бренд.

Что такое DESIGN.md и зачем он нужен

Что такое DESIGN.md и зачем он нужен

DESIGN.md — это текстовый файл в репозитории, который описывает дизайн-систему в формате, понятном coding-агенту. Не картинка из Figma и не PDF-брендбук, а разметка: цвета, типографика, отступы, границы, правила компонентов. Агент подтягивает файл перед генерацией и получает техническое задание вместо угадывания.

Без такого файла агент обычно подставляет дефолтные цвета фреймворка — например, синий из Tailwind — и получается интерфейс, не имеющий отношения к бренду. С DESIGN.md агент знает, что основной цвет — #1A5F7A, заголовки — Inter 24 px, а скругление кнопок — 8 px. Результат становится предсказуемым.

От анализа бренда к коду

Путь от бренда к коду выглядит так:

  1. В Figma или брендбуке фиксируются цвета, шрифты, отступы.
  2. Эти значения переносятся в DESIGN.md вручную или скриптом.
  3. Coding-агент подключается к файлу и при генерации компонента ориентируется на описанные токены.

С практической точки зрения это работает так. Допустим, вы разрабатываете панель управления для клиента. В брендбуке указаны основной цвет #1A5F7A и акцентный #E8A33D. Без DESIGN.md агент может сгенерировать кнопку с цветом blue-500, и вам придётся переделывать вручную. Если файл подключён, агент сразу использует ваши токены.

Пример подключения в конфиге агента (VoltAgent):

yaml
# .voltagent/agent.yaml
design:
  source: ./DESIGN.md
  output: ./src/components/ui
  framework: react
  css: tailwind

После этого команда генерации компонента берёт значения из DESIGN.md:

bash
npx voltagent generate component Button --from-design

Агент создаст компонент, который уже соответствует бренду, а не дефолтной теме фреймворка.

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

Что внутри файла DESIGN.md

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

Пример минимального DESIGN.md:

markdown
# DESIGN.md

## Brand
name: Acme
primary: "#1A5F7A"
accent: "#E8A33D"
background: "#FFFFFF"
surface: "#F5F7FA"

## Typography
heading:
  family: "Inter"
  size: "24px"
  weight: 600
body:
  family: "Inter"
  size: "16px"
  weight: 400

## Spacing
unit: "8px"
scale:
  - "4px"
  - "8px"
  - "16px"
  - "24px"
  - "32px"

## Components
button:
  borderRadius: "8px"
  padding: "10px 20px"
  fontWeight: 500
input:
  borderRadius: "6px"
  border: "1px solid #D1D5DB"

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

Если вы работаете с Figma, значения токенов можно экспортировать автоматически — многие плагины выгружают цвета и типографику в JSON или Markdown. Остаётся только проверить вручную, чтобы ничего не потерялось при конвертации.

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

Как подключить DESIGN.md к проекту

Как подключить DESIGN.md к проекту

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

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

Установка awesome-design-md

VoltAgent собирает DESIGN.md популярных дизайн-систем в репозитории awesome-design-md. Самый простой способ подключить коллекцию — клонировать её в директорию проекта.

Во-первых, создайте папку для дизайн-токенов:

bash
mkdir -p .voltagent/design

Затем склонируйте репозиторий прямо в неё:

bash
git clone https://github.com/VoltAgent/awesome-design-md.git .voltagent/design

После этого в .voltagent/design окажутся DESIGN.md файлы Material Design, Ant Design, Tailwind UI и других систем. Если вам нужна только одна конкретная система, скопируйте соответствующий файл в корень проекта:

bash
cp .voltagent/design/material-design/DESIGN.md ./DESIGN.md

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

Настройка для coding-агента

Сам по себе файл DESIGN.md ничего не делает. Нужно объяснить coding-агенту, что им пользоваться. Способ зависит от того, какой агент вы используете — Cursor, Cline, Copilot или другой.

Ниже пример инструкции для Cursor. Создайте файл .cursor/rules/design.mdc:

markdown
# DESIGN.md

При генерации или изменении UI-компонентов опирайтесь на файл DESIGN.md в корне проекта.

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

Если вы используете Cline, добавьте аналогичное правило в .cline/rules/:

markdown
# Design system

Follow DESIGN.md in the project root when generating frontend code.

Теперь, когда вы попросите агента сверстать карточку товара, он заглянет в DESIGN.md и возьмёт оттуда границу, радиус и цвет текста, вместо того чтобы подставлять дефолтные значения Tailwind.

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

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

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

Примеры с популярными дизайн-системами

Когда DESIGN.md лежит в корне проекта, coding-агент сам подхватывает цвета, отступы и правила компонентов. Остаётся только решить, откуда взять сам файл. Можно писать с нуля, но проще посмотреть, как это сделано в больших дизайн-системах. Material Design и Ant Design уже выложили свои токены в открытый доступ, а из Figma их можно выгрузить автоматически.

Material Design и Ant Design

Material Design от Google и Ant Design от Ant Group — две самые популярные системы с открытыми DESIGN.md. У каждой своя структура, но общая логика одинаковая: цветовая палитра, типографика, отступы, компоненты и правила их использования.

Для Material Design файл обычно выглядит так:

markdown
# DESIGN.md

## Цвета
- primary: #6200ee
- secondary: #03dac6
- surface: #ffffff
- background: #f5f5f5

## Типографика
- h1: 32 px, font-weight: 400, line-height: 1.2
- body: 16 px, font-weight: 400, line-height: 1.5

## Компоненты
- кнопка: border-radius 4 px, padding 8 px 16 px

Ant Design использует меньше жёстких значений и больше переменных:

markdown
# DESIGN.md

## Дизайн-токены
- color-primary: #1890ff
- color-success: #52c41a
- font-size-base: 14 px
- line-height-base: 1.5

## Правила
- Все отступы кратны 8 px
- Радиус скругления по умолчанию — 4 px

Чтобы подключить файл к проекту, положите его в корень репозитория рядом с package.json. Coding-агент подхватит его автоматически, если в конфиге указан путь:

json
{
  "design": {
    "file": "./DESIGN.md",
    "provider": "material"
  }
}

С практичной точки зрения, разница между двумя системами в том, как они traktуют компоненты. Material Design диктует внешний вид до пикселя — это как готовая мебель из магазина: всё уже собрано, остаётся только поставить в комнату. Ant Design даёт больше свободы — как конструктор, где детали подходят друг к другу, но собирать приходится самому. Если нужно сверстать интерфейс быстро и без обсуждений с дизайнером — берите Ant Design. Если важна строгая визуальная идентичность бренда — Material Design.

Более подробный разбор популярных DESIGN.md можно найти в материалах сайта: Анализ DESIGN.md файлов популярных дизайн-систем и VoltAgent/awesome-design-md: Анализ дизайн-систем для генерации UI.

Figma и экспорт токенов

Figma не хранит DESIGN.md в готовив виде, но токены из стилей и переменных можно выгрузить. Есть два пути: ручной экспорт через плагины и автоматический через API.

Ручной путь — установите плагин в роде Tokens Studio for Figma или Figma Tokens. Экспортируйте в JSON:

json
{
  "colors": {
    "primary": { "value": "#6200ee" },
    "surface": { "value": "#ffffff" }
  },
  "spacing": {
    "xs": { "value": "4 px" },
    "md": { "value": "16 px" }
  }
}

Превратите JSON в DESIGN.md вручную или скриптом:

bash
# Пример конвертации через Node.js
node scripts/json-to-design-md.js tokens.json > DESIGN.md

Автоматический путь — через Figma API. Получите персональный токен доступа в настройках аккаунта, затем запросите переменные файла:

bash
curl -H "X-Figma-Token: FIGMA_PERSONAL_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/FILE_ID/variables/local"

Результат сохраните в DESIGN.md. Я предпочитаю писать конфиг руками, даже если есть GUI — так точно знаю, где лежит каждая строка, и не гадаю, почему агент подтянул не тот отступ.

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

Подробнее про использование DESIGN.md для генерации UI читайте в гиде: Использование DESIGN.md для генерации UI. Общие принципы работы с дизайн-системами описаны здесь: design-system. Ещё один разбор DESIGN.md популярных систем: Анализ DESIGN.md файлов популярных дизайн-систем.

Официальные источники: Material Design, Ant Design, Figma.

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

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

Где ИИ-агент ошибается

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

Неполное понимание семантики бренда

Модели часто путают абстрактные термины дизайн-системы с реальными визуальными требованиями. Например, при генерации кнопок ИИ может предложить стандартные оттенки, не учитывая специфические цвета из Figma-компонентов. Это приводит к тому, что интерфейс выглядит «плоским» или не соответствует ожидаемому стилю.

markdown
### Пример ошибки: кнопки без брендовых оттенков

**ИИ-вывод:**
```css
/* ИИ предлагает стандартные оттенки */
.primary-primary {
  background: #007bff;
  color: #ffffff;
}

Почему это неправильно:

  • Система DESIGN.md содержит точные цвета: brand-primary: #2563eb, brand-secondary: #7c3aed
  • ИИ не обращает внимание на файлы Figma, которые описывают точные HSL-значения
  • Результат выглядит как «общий» интерфейс, а не под бренд

Правильный подход:

bash
# Скачиваем Figma-компоненты и извлекаем точные цвета
npm install figma
figma-cli export --format=json --path="./design-system" --components

Исправленный код:

css
.brand-primary {
  background: #2563eb; /* точный цвет из DESIGN.md */
  color: #ffffff;
}

Несоответствие дизайн-системы и функциональности

ИИ-агенты генерируют UI на основе визуальных правил, но часто упускают функциональные требования. Например, при создании навигации ИИ может предложить простую сетку, не учитывая доступность (contrast ratio) и ARIA-атрибуты.

markdown
### Пример ошибки: навигация без доступности

**ИИ-вывод:**
```html
<nav class="main-nav">
  <a href="/">Главная</a>
  <a href="/about">О нас</a>
  <a href="/contact">Контакты</a>
</nav>

Проблемы:

  • Отсутствует aria-label для скрытых элементов
  • Нет семантической разметки для брендовых иконок
  • Контрастность текста ниже 4.5:1 (не соответствует WCAG AA)

Решение через конфиг:

yaml
# design-system/accessibility.yaml
navigation:
  required: true
  aria-label: "Основная навигация"
  contrast: "4.5:1"

Когда подход не работает

Слишком сложные или уникальные дизайн-системы

Если DESIGN.md содержит сотни атрибутов, сложные иерархии тем и специфичные компоненты, ИИ-агент теряет точность. Модель не способна вывести все вариации темы, состояния и адаптивных сеток за один раз.

bash
# Генерация всех темы для 50+ компонентов — ИИ может «забыть» редкие
for component in $(ls design-system/Components/*); do
  generate-ui "$component"
done

Несовпадение версий и рефакторинга

При непрерывном обновлении DESIGN.md (новые темы, изменённые оттенки) ИИ может использовать устаревшие данные, если не перезагружается контекст. Это особенно критично при автоматической генерации UI для продакшена.

Зависимости от внешних источников

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

markdown
### Практические рекомендации

1. **Мониторинг актуальности** — перед генерацией проверяйте дату последнего изменения DESIGN.md
2. **Цикл валидации** — после генерации UI проверяйте соответствие реальным компонентам
3. **Использование конфигов** — фиксируйте настройки через `design-system/` конфиги для повторяемости

Связанные материалы:

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

Как DESIGN.md влияет на предсказуемость UI при использовании coding-агентов?

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

Какие шаги нужны, чтобы подключить DESIGN.md к coding-агенту VoltAgent?

Сначала создайте файл DESIGN.md в корне репозитория и опишите в нём дизайн-токены: цвета, типографику, отступы, границы. Затем отредактируйте конфигурационный файл агента (например, .voltagent/agent.yaml) и укажите источник дизайна: source: ./DESIGN.md. После этого запускайте генерацию компонента с флагом --from-design, и агент будет использовать ваши токены. Этот процесс можно автоматизировать скриптом, который парсит Figma и записывает значения в DESIGN.md.

Как DESIGN.md помогает избежать конфликтов с CSS-фреймворком?

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

Нужно ли хранить DESIGN.md в системе контроля версий?

Да, DESIGN.md должен быть в репозитории, потому что он служит источником истины для визуальной системы. Это позволяет новым участникам команды получить дизайн-токены сразу, а CI-пайплайны могут проверять соответствие сгенерированных компонентов заданным спецификациям. Без коммита в репозиторий файл теряется при клонировании, и предсказуемость теряется. Хранение в Git также обеспечивает историю изменений и ответственность за обновления.

Поделиться:TelegramX / TwitterVK

Читайте также

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

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

22 октября 2026 г.16 мин
Средний

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

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

23 октября 2026 г.15 мин
Средний

design-system

Коллекция файлов DESIGN.md, проанализированная по системам дизайна популярных брендов. Позволяет внедрить соответствующий UI в проект с помощью VoltAgent.

2 ноября 2026 г.12 мин
Продвинутый