VoltAgent/awesome-design-md: Анализ дизайн-систем для генерации UI
Анализ коллекции DESIGN.md файлов популярных дизайн-систем. Подключите один файл в проект и позволите кодировым агентам создавать соответствующий интерфейс.
Основные принципы анализа DESIGN.md
Основные принципы анализа DESIGN.md
В репозитории awesome-design-md собраны DESIGN.md файлы ведущих дизайн-систем — Material UI, Ant Design, Chakra UI и других. Идея проста: вы подключаете один такой файл к своему проекту, и кодовый агент на его основе генерирует интерфейс, который соответствует правилам исходной системы. Не нужно перерисовывать компоненты в Figma вручную и потом переносить их в код — DESIGN.md становится единственным источником истины.
Но файл сам по себе ничего не делает. Нужно понимать, что именно в нём извлекать и как это соотносится с реальной кодовой базой.
Идентификация ключевых компонентов
Во-первых, DESIGN.md описывает компоненты на уровне имен и намерений, а не реализации. В файле обычно есть раздел с перечислением компонентов, их вариантов и правил использования. Моя задача — вытащить из этого списка то, что реально попадёт в код.
Пример типичной структуры DESIGN.md:
markdown# Design System
## Components
### Button
- Variants: primary, secondary, ghost
- Sizes: sm, md, lg
- States: default, hover, active, disabled
### Input
- Types: text, email, password
- Sizes: sm, md
- Validation states: valid, invalid
Чтобы автоматизировать извлечение, достаточно пройтись по заголовкам второго и третьего уровня. Я использую ripgrep, потому что он работает предсказуемо и не требует лишних зависимостей:
bashrg '^#{2,3} ' DESIGN.md
На выходе получаю список компонентов и их вложенных сущностей. Далее сопоставляю каждый компонент с существующими реализациями в проекте. Если в DESIGN.md есть Button с вариантами primary и ghost, а в кодовой базе только один универсальный компонент — это сигнал, что нужно добавить проп variant и задокументировать допустимые значения.
С практической точки зрения, я не пытаюсь распарсить весь файл целиком. Достаточно трёх блоков:
- Список компонентов и их вариантов.
- Дизайн-токены (цвета, отступы, радиусы, тени).
- Правила использования (когда какой компонент применим).
Остальное — второстепенный шум для генерации UI.
Связь с дизайн-системами
DESIGN.md не заменяет дизайн-систему, он её формализует. В Figma у вас могут быть отдельные библиотеки компонентов, в Storybook — истории, а в коде — CSS-модули или styled-components. DESIGN.md связывает эти слои в одном документе.
Например, токен --color-primary из DESIGN.md должен совпадать с цветом в Figma и переменной в CSS:
css:root {
--color-primary: #0066ff;
--spacing-4: 1rem;
--radius-md: 0.375rem;
}
Если в DESIGN.md указано, что компонент Button использует токен --color-primary, а в Figma у кнопки другой оттенок — это расхождение, которое нужно устранить до генерации. Иначе агент создаст интерфейс, который визуально не совпадёт с макетами.
Я всегда проверяю соответствие вручную, даже если есть GUI. Конфиг пишу руками, потому что знаю, где лежит файл. Пример простого сопоставления токенов в JSON, которое можно скормить агенту:
json{
"designSystem": "awesome-design-md",
"tokens": {
"color-primary": "#0066ff",
"spacing-4": "1rem"
},
"components": [
{
"name": "Button",
"variants": ["primary", "secondary", "ghost"],
"sizes": ["sm", "md", "lg"]
},
{
"name": "Input",
"types": ["text", "email", "password"],
"sizes": ["sm", "md"]
}
]
}
Предсказуемость конфигурации здесь важнее скорости. Если агент получит неполный список вариантов, он сгенерирует компонент без состояния disabled, и это заметит только пользователь, а не разработчик.
Для дополнительного контекста по интеграции DESIGN.md с AI-агентами можно ознакомиться с руководством Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов или статьей Использование DESIGN.md для генерации UI через AI.
Интеграция с AI-агентами
Интеграция с AI-агентами
Коллекция awesome-design-md собрана из DESIGN.md файлов популярных дизайн-систем. Каждый такой файл описывает токены, компоненты и правила оформления в формате, который удобно читать не только человеку, но и языковой модели. Если подключить один такой файл к проекту, кодовый агент сможет генерировать интерфейс, соответствующий уже утверждённому дизайну, а не придумывать цвета и отступы с нуля.
Подготовка контекста для генерации
Во-первых, не нужно скормить агенту весь репозиторий дизайн-системы. Контекстное окно модели ограничено, а лишний шум только снижает точность генерации. Из DESIGN.md достаточно выделить три блока: дизайн-токены (цвета, типографика, отступы), спецификацию компонентов и ссылки на Figma-макеты.
С практической точки зрения, я обычно создаю отдельный файл контекста, который агент будет использовать в качестве справочника. Например, так:
markdown# Контекст для генерации UI
## Дизайн-токены
- Цвета: primary #0066CC, secondary #6B7280, background #FFFFFF
- Типографика: Inter, размеры 14/16/20 px, жирность 400/600
- Отступы: 4px сетка, базовый отступ 16 px
## Компоненты
- Кнопка: варианты primary/secondary, состояния default/hover/disabled
- Поле ввода: подпись, хелпер-текст, состояние ошибки
- Карточка: тень, скругление 8 px, отступы 16 px
## Источники
- Figma: https://figma.com/...
- DESIGN.md: https://github.com/...
Затем копирую выбранный DESIGN.md из коллекции в папку проекта, чтобы агент всегда брал актуальную версию:
bashcp node_modules/@org/design-system/DESIGN.md .ai-context/design-tokens.md
Если мы посмотрим на структуру awesome-design-md, там уже собраны готовые DESIGN.md из Material Design, Ant Design, Shopify Polaris и других систем. Можно взять любой из них за основу и адаптировать под свой проект, не описывая токены вручную.
Далее этот файл подключается к агенту. В Cursor или Windsurf это делается через @ или добавление файла в контекст чата. В Claude Code — через флаг --add-dir или вставку содержимого в системный промпт. Главное, чтобы агент видел актуальную версию токенов перед генерацией компонента.
Автоматическое создание UI
Когда контекст готов, агент может генерировать компоненты прямо в репозитории. Я обычно формулирую задачу так: «Создай React-компонент кнопки согласно DESIGN.md, используя токены из контекста». Агент предлагает код, который уже соответствует цветам, отступам и типографике дизайн-системы.
Пример сгенерированного компонента на React с TypeScript:
tsximport React from 'react';
interface ButtonProps {
variant?: 'primary' | 'secondary';
children: React.ReactNode;
onClick?: () => void;
disabled?: boolean;
}
export const Button: React.FC<ButtonProps> = ({
variant = 'primary',
children,
onClick,
disabled = false,
}) => {
const baseStyles =
'px-4 py-2 rounded font-inter text-sm font-medium transition-colors';
const variants = {
primary: 'bg-blue-600 text-white hover:bg-blue-700 disabled:bg-blue-400',
secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300 disabled:bg-gray-100',
};
return (
<button
className={`${baseStyles} ${variants[variant]}`}
onClick={onClick}
disabled={disabled}
>
{children}
</button>
);
};
С практической точки зрения, сгенерированный код ещё нужно проверить. Агент может ошибиться в именовании классов или пропустить состояние disabled. Я рекомендую запускать Storybook или визуальный регрессионный тест сразу после генерации, чтобы убедиться, что компонент выглядит так, как задумано в дизайн-системе.
Предсказуемость результата зависит от качества исходного DESIGN.md. Если токены описаны чётко, агент не будет изобретать свои оттенки синего и отступы в 13 пикселей. Если же в файле только общие фразы вроде «современный стиль», результат будет случайным.
Связанные материалы:
- Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов
- Использование DESIGN.md для генерации UI через AI-агентов
- Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов
- Использование DESIGN.md для генерации UI через AI
- Использование DESIGN.md для генерации UI
Практические шаги для внедрения
Практические шаги для внедрения
Выбор подходящего DESIGN.md
При выборе DESIGN.md файла для вашего проекта важно понимать, что этот файл — это не просто набор картинок из Figma, а структурированная документация, которую могут читать как люди, так и кодовые агенты.
На что обратить внимание
| Критерий | Почему важно | Как проверить |
|---|---|---|
| Структурированные токены | Токены (цвета, шрифты, отступы) должны быть описаны в читаемом виде, чтобы агентам было легко их интерпретировать. | Поищите секции colors, typography, spacing. Проверьте, что каждая запись содержит CSS-переменную и пример использования. |
| Компонентная документация | Агент должен понимать, как собирать UI из готовых компонентов, а не рисовать их с нуля. | Найдите блоки components или atoms. Убедитесь, что у каждого компонента есть описание, параметры и пример кода. |
| Версионирование и читаемость | Предсказуемость конфигурации — ключ к стабильной генерации. | Посмотрите на историю файлов, убедитесь, что имена файлов и секций соответствуют snake_case, а не camelCase. |
| Примеры использования | Реальные примеры помогают агенту понимать контекст, а не просто копировать токены. | Проверьте наличие блоков examples или demo. Они должны содержать минимальный HTML/JSX с комментарием, почему выбран такой вариант. |
Практический пример: оценка design.md
Допустим, вы клонируете репозиторий:
bashgit clone https://github.com/ VoltAgent/awesome-design-md.git
cd awesome-design-md
Откройте файл design.md в редакторе:
markdown## Токены
### Colors
- `--color-primary: #0066CC; /* основной синий */`
- `--color-secondary: #F5F5F5; /* светлый фон */`
### Typography
- `--font-family: 'Inter', sans-serif; /* современный шрифт */`
- `--font-size-base: 16px; /* базовый размер для десктопа */`
## Компоненты
### Button
- **props**: `{ size: 'small' | 'medium' | 'large', variant: 'primary' | 'secondary' }`
- **example**:
```jsx
<Button size="medium" variant="primary">Сохранить</Button>
Обратите внимание на несколько моментов:
1. **Читаемость** — каждая секция начинается с заголовка уровня 2, подпункты оформлены через `-`. Это предсказуемая структура, которую легко парсить.
2. **Комментарии** — в CSS-переменных есть комментарии, объясняющие назначение. Агенту не нужно гадать, для чего предназначен токен.
3. **Примеры** — JSX-пример компонента сопровождается русским текстом, что помогает агенту понимать контекст.
**Как подключить DESIGN.md к агенту**
```yaml
# .agent/config.yaml
design:
source: ./design.md # относительный путь к файлу
parser: markdown # используем парсер markdown
tokens:
- --color-primary
- --font-size-base
components:
- Button
- Input
examples: true # включить парсинг примеров
Ключевые моменты конфигурации:
source— относительный путь, чтобы конфигурация работала на любой машине.parser: markdown— указывает агенту, что формат файла — Markdown, а не JSON или YAML.- Списки токенов и компонентов — это явное указание, что использовать, а что игнорировать.
Настройка кодового агента
После того как DESIGN.md выбран, нужно настроить агента так, чтобы он мог создавать UI на его основе. Ниже приведён пошаговый пример для агента, написанного на Node.js (например, voltagent).
1. Установите зависимости
bashnpm init -y npm install voltagent @voltagent/node
2. Создайте файл запуска агента
agent.js:
javascript// agent.js
const { VoltAgent } = require('voltagent');
const agent = new VoltAgent({
name: 'ui-generator',
model: 'gpt-4', // или любая другая модель
systemPrompt: `
Ты — UI-агент, который генерирует интерфейс на основе DESIGN.md.
Используй токены и компоненты, указанные в DESIGN.md.
Отвечай только валидным JSX-кодом, без лишних комментариев.
Если токен не найден, используй значение по умолчанию.
`,
tools: [
{
name: 'parseDesignMd',
description: 'Парсить DESIGN.md и вернуть токены и компоненты',
parameters: {
type: 'object',
properties: {
path: { type: 'string', description: 'Путь к DESIGN.md' },
},
required: ['path'],
},
},
{
name: 'generateComponent',
description: 'Сгенерировать компонент на основе описания',
parameters: {
type: 'object',
properties: {
name: { type: 'string' },
props: { type: 'object' },
tokens: { type: 'object' },
},
required: ['name', 'props', 'tokens'],
},
},
],
});
// Загрузка DESIGN.md при старте
const designPath = './design.md';
const { tokens, components } = await agent.tools.parseDesignMd({ path: designPath });
// Автоматически регистрируем компоненты в агенте
agent.registerComponents(tokens, components);
3. Настройте конфигурационный файл агента
.agent/config.yaml (тот же файл, что и выше, но теперь он загружается автоматически):
yaml# .agent/config.yaml
design:
source: ./design.md
parser: markdown
tokens:
- --color-primary
- --font-size-base
components:
- Button
- Input
examples: true
runtime:
node_version: '18' # используем стабильный LTS
monitoring: true # включить логирование
alerts:
- event: 'agent_error'
channel: 'slack' # канал оповещений
4. Запустите агент
bashnode agent.js
Агент загрузит DESIGN.md, извлечёт токены (--color-primary, --font-size-base) и компоненты (Button, Input), а затем будет готов генерировать UI по запросу.
5. Пример запроса и ответа
Запрос: «создай кнопку с основным цветом и размером medium»
Ответ (валидный JSX):
jsx<Button size="medium" variant="primary" style={{ backgroundColor: '#0066CC', color: '#fff' }}>
Новая кнопка
</Button>
Обратите внимание на предсказуемость: цвет взят из --color-primary, размер — из --font-size-base (или из токена размера кнопки, если он определён). Агент не будет экспериментировать с «красивым синим», потому что дизайн-система жёстко фиксирует значения.
6. Мониторинг и алерты
Поскольку мы включили monitoring: true, агент будет логировать каждое действие в agent.log. Для быстрой проверки работоспособности можно использовать простой скрипт:
bash# healthcheck.sh
if grep -q "UI generation successful" agent.log; then
echo "Агент работает корректно"
else
echo "Проверьте логи агента"
fi
7. Документация для команды
Привяжите этот процесс к README, чтобы новички быстро могли подключить DESIGN.md:
markdown## Быстрое начало
1. Клонируйте репозиторий:
```bash
git clone https://github.com/VoltAgent/awesome-design-md.git
cd awesome-design-md
-
Установите зависимости:
bashnpm install -
Запустите агент:
bashnode agent.js
Агент автоматически загрузит ./design.md и будет готов генерировать UI.
**Вывод**
Следуя этим двум подразделам — выбору DESIGN.md и настройке агента — вы получите предсказуемую, документированную и мониторинговую систему генерации UI. Такой подход исключает «решений на коленке», обеспечивает читаемость как для людей, так и для агентов, и позволяет быстро масштабировать создание интерфейсов для любых домашних серверов или продуктовых приложений.
## Часто задаваемые вопросы
### Что такое DESIGN.md и зачем он нужен?
DESIGN.md — это документационный файл, описывающий компоненты дизайн-системы. Он содержит перечень компонентов, их вариантов и правил использования. Благодаря этому файлу кодовый агент может автоматически генерировать интерфейс, соответствующий правилам исходной системы, что устраняет необходимость ручного переноса элементов из Figma в код.
### Как извлекать компоненты из DESIGN.md для автоматической генерации?
Для извлечения компонентов из DESIGN.md рекомендуется использовать ripgrep с регулярным выражением. Команда `rg '^#{2,3} ' DESIGN.md` позволяет найти все заголовки второго и третьего уровня, которые обычно описывают компоненты и их свойства. Этот подход предсказуем и не требует дополнительных зависимостей для обработки текста.
### В чем разница между дизайн-системой и библиотекой компонентов?
Дизайн-система определяет правила, цвета, шрифты и поведение элементов, тогда как библиотека компонентов предоставляет готовые реализации этих элементов. Дизайн-система — это источник истины, который описывает, как элементы должны вести себя, а библиотека — это конкретная реализация, которая их воплощает в коде. Понимание этой разницы помогает правильно настраивать генерацию UI из DESIGN.md.
### Какой инструмент лучше использовать для анализа DESIGN.md файлов?
Ripgrep (rg) является оптимальным выбором для анализа DESIGN.md благодаря своей скорости и предсказуемости работы. Он позволяет быстро находить все компоненты и их вложенные сущности без установки дополнительных пакетов. Этот инструмент легко интегрируется в пайплайны автоматизации и обеспечивает точное извлечение информации для последующего использования.
### Какие преимущества даёт DESIGN.md как единственный источник истины?
Использование DESIGN.md как единственного источника истины гарантирует консистентность дизайна во всей проекте. Все компоненты и их поведение описаны в одном месте, что упрощает поддержку и отслеживание изменений. Когда дизайнеры обновляют правила в DESIGN.md, автоматический агент сразу применяет новые стандарты к генерации UI, исключая рассинхронизацию между документацией и кодом.