awesome-design-md: DESIGN.md создаёт UI через agents
Анализ коллекции DESIGN.md файлов дизайн-систем. Один файл в проекте заставляет coding agents генерировать современный, предсказуемый интерфейс для быстрой интеграции и поддержки без ручного кодирования.
Анализ DESIGN.md файлов
Анализ DESIGN.md файлов
Короткий файл в корне репозитория — это не просто документация. Для coding-agents DESIGN.md становится исходником интерфейса: токены, правила компонентов и ограничения бренда читаются один раз, а потом используются для автоматического создания UI.
Популярные дизайн-системы
Большая часть открытых дизайн-систем хранит гайдлайны в wiki или отдельном портале, но в последнее время команды начали выносить ключевые правила в DESIGN.md прямо в репозиторий проекта. Это удобно: файл лежит рядом с кодом, версионируется вместе с ним и доступен агенту без дополнительных настроек.
Во-первых, DESIGN.md обычно содержит design tokens — именованные значения для цветов, отступов, типографики и границ. Пример минимального файла:
markdown# DESIGN.md
## Tokens
colors:
primary: "#0066cc"
surface: "#ffffff"
text-primary: "#1a1a1a"
spacing:
xs: "4px"
sm: "8px"
md: "16px"
lg: "24px"
typography:
font-family: "Inter, system-ui, sans-serif"
font-size-base: "16px"
line-height-base: "1.5"
## Components
button:
variants: [primary, secondary, ghost]
padding: "8px 16px"
border-radius: "6px"
С практичной точки зрения, такой формат работает лучше, чем разрозненные Figma-арты, потому что агент может спарсить YAML или Markdown и сразу подставить значения в CSS-переменные или объект темы.
Популярные системы вроде Material Design 3, Ant Design или MUI имеют свои гайдлайны, но редко публикуют их как один DESIGN.md. Поэтому сообщество собирает такие файлы в отдельных коллекциях — например, в awesome-design-md: DESIGN.md для дизайн-систем или в коллекции DESIGN.md для дизайн-систем и AI-агентов. Там можно посмотреть, как другие команды описывают токены и правила компонентов, и взять за основу свой файл.
Если нужно углубиться в конкретные примеры, есть отдельный материал Анализ DESIGN.md файлов популярных дизайн-систем, где разобраны реальные репозитории и их подходы к описанию интерфейса.
Связь с генерацией UI
Генерация интерфейса по DESIGN.md работает по простой схеме: агент читает файл, извлекает токены и правила, а затем пишет компоненты на выбранном фреймворке. Главное здесь — предсказуемость. Если в DESIGN.md чётко сказано, что кнопка имеет варианты primary и secondary, агент не будет изобретать третий вариант «на коленке».
Допустим, в репозитории лежит DESIGN.md, а в конфиге агента указан путь к нему:
json{
"designSystem": "./DESIGN.md",
"outputDir": "src/components/ui",
"framework": "react"
}
После этого команда генерации может выглядеть так:
bashnpx design-md-agent generate --design-md ./DESIGN.md --output src/components/ui
На выходе получаются готовые компоненты с вшитыми токенами. Например, кнопка:
tsximport { cn } from "@/lib/utils";
interface ButtonProps {
variant?: "primary" | "secondary" | "ghost";
children: React.ReactNode;
}
export function Button({ variant = "primary", children }: ButtonProps) {
const base = "inline-flex items-center justify-center rounded-md px-4 py-2 text-sm font-medium transition-colors";
const variants = {
primary: "bg-primary text-surface",
secondary: "bg-surface text-primary border border-primary",
ghost: "text-primary hover:bg-surface/10",
};
return <button className={cn(base, variants[variant])}>{children}</button>;
}
Связь между DESIGN.md и генерацией UI описана в материалах DESIGN.md для ИИ-агентов: генерация UI по гайдлайну бренда и DESIGN.md и генерация UI с помощью ИИ-агентов. Там разобрано, как именно агенты интерпретируют токены и какие ограничения накладывают на сгенерированный код.
С точки зрения инженерии, подход оправдан, если DESIGN.md поддерживается в актуальном состоянии. Устаревший файл приведёт к тому, что агент начнёт генерировать компоненты с цветами и отступами, которых больше нет в брендбуке. Поэтому файл нужно хранить рядом с кодом, ревьюить вместе с пул-реквестами и воспринимать как часть интерфейса, а не как отдельную документацию.
Практическое применение
Практическое применение
DESIGN.md не заменяет дизайнера. Он даёт coding agentу исходные данные, которые раньше приходилось объяснять словами или показывать на скриншотах из Figma. Подборку готовых файлов можно посмотреть в Коллекция DESIGN.md для дизайн-систем и AI-агентов, а общий подход к генерации UI описан в материале DESIGN.md и генерация UI с помощью ИИ-агентов. Ниже разберём, где файл лежать должен и как агент с ним работает.
Как вставить файл в проект
Во-первых, файл должен быть доступен агенту. Я кладу его в корень репозитория или в каталог .design/ — так он не мешает исходному коду, но остаётся на виду.
Минимальный DESIGN.md выглядит так:
markdown# Design System
## Tokens
- color-primary: #0f62fe
- color-surface: #ffffff
- radius-md: 8px
- spacing-unit: 16px
## Components
- Button: primary, secondary, outline
- Input: text, password, search
Создать его можно одной командой:
bashmkdir -p .design
cat > .design/DESIGN.md <<'EOF'
# Design System
## Tokens
- color-primary: #0f62fe
- color-surface: #ffffff
- radius-md: 8px
- spacing-unit: 16px
## Components
- Button: primary, secondary, outline
- Input: text, password, search
EOF
С практической точки зрения, достаточно одного файла на проект. Если в репозитории несколько пакетов (monorepo), я дублирую DESIGN.md в каждый пакет или ссылаюсь на корневой из agent-конфига.
Далее нужно сказать агенту, где файл искать. В Cursor это правило в .cursorrules, в Claude Code — блок в CLAUDE.md, в других агентах — инструкция в системном промпте. Пример для CLAUDE.md:
markdown# Agent instructions
Before generating any UI component, read `.design/DESIGN.md`. Use only the design tokens listed there. Do not invent colours, spacing or border-radius values.
Если вы используете коллекцию готовых DESIGN.md, можно взять за основу файл из awesome-design-md: DESIGN.md для дизайн-систем и адаптировать под свои токены.
Роль coding agents
Агент не придумывает дизайн. Он читает токены из DESIGN.md и переносит их в код. Если мы посмотрим на типичный запрос, он выглядит так:
Создай компонент Card на основе .design/DESIGN.md. Используй color-surface для фона, radius-md для скругления и spacing-unit для внутренних отступов. Верни React-компонент с CSS-модулями.
Агент сгенерирует что-то вроде:
tsx// Card.tsx
import styles from './Card.module.css';
export function Card({ children }: { children: React.ReactNode }) {
return <div className={styles.card}>{children}</div>;
}
css/* Card.module.css */
.card {
background-color: #ffffff;
border-radius: 8px;
padding: 16px;
}
Предсказуемость здесь в том, что цвета и отступы берутся из одного источника. Если в DESIGN.md изменить color-primary с #0f62fe на #1a73e8, агент при следующей генерации подтянет новый оттенок автоматически. Вручную править десяток компонентов не придётся.
Роль агента — исполнитель, а не автор. Он не решит, нужна ли кнопка с иконкой или без, но точно применит правильный radius-md, если вы укажете это в задании. Подробнее о том, как агенты интерпретируют гайдлайн бренда, написано в материале DESIGN.md для ИИ-агентов: генерация UI по гайдлайну бренда.
Если нужно увидеть реальные примеры из популярных дизайн-систем, полезно заглянуть в Анализ DESIGN.md файлов популярных дизайн-систем. Там показано, какие токены чаще всего выносят в отдельный файл и как агенты с ними работают.
Конечный результат зависит от чёткости DESIGN.md. Чем точнее описаны токены и компоненты, тем меньше у агента пространства для самодеятельности — и тем предсказуемее получается интерфейс.
Рекомендации
Выбор подходящего дизайн-системы
Во-первых, DESIGN.md — это не замена дизайн-системе, а инструкция для агента. Если в репозитории нет чёткой структуры токенов, агент будет генерировать интерфейс, который выглядит по-разному на разных страницах.
С практической точки зрения, я смотрю на три вещи перед тем, как подключать коллекцию awesome-design-md к проекту.
Первая — именование токенов. Если цвета описаны как color-primary и color-secondary, агент поймёт. Если как main-color и accent-color, придётся править вручную. Вторая — наличие компонентов. DESIGN.md должен описывать не только цвета и отступы, но и кнопки, поля ввода, модальные окна. Третья — связь с Figma. Если токены в DESIGN.md не совпадают с переменными в Figma, разработчики и дизайнеры будут спорить о каждом пикселе.
Пример минимального DESIGN.md, который я считаю рабочим:
markdown# DESIGN.md
## Tokens
- color-primary: #0066cc
- color-secondary: #6c757d
- spacing-xs: 4px
- spacing-sm: 8px
- spacing-md: 16px
- spacing-lg: 24px
- radius-sm: 4px
- radius-md: 8px
## Components
### Button
- variant: primary
background: color-primary
text: #ffffff
padding: spacing-sm spacing-md
border-radius: radius-md
Если мы посмотрим на коллекцию DESIGN.md для дизайн-систем и AI-агентов, большинство файлов уже содержат такие секции. Остаётся только проверить, подходят ли они под стек проекта — React, Vue или чистый HTML.
Интеграция с CI/CD
С практической точки зрения, DESIGN.md должен проверяться автоматически. Я не доверяю ручной проверке конфигов — человек пропустит опечатку в токене, а агент сгенерирует кнопку с несуществующим цветом. Поэтому я добавляю валидацию в конвейер сборки.
Пример GitHub Actions, который проверяет DESIGN.md при каждом пуше:
yamlname: validate-design-md
on:
push:
paths:
- 'DESIGN.md'
- '.github/workflows/validate-design-md.yml'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install node
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install validator
run: npm install -g @awesome-design-md/validator
- name: Validate DESIGN.md
run: design-md validate DESIGN.md
Если валидатор находит ошибку, сборка падает. Это раздражает в первый день, но через неделю привыкаешь: предсказуемость конфига важнее скорости коммита.
Для генерации UI через агента я добавляю отдельный job. Он запускается после успешной валидации и вызывает агент с контекстом из DESIGN.md:
yaml - name: Generate UI preview
run: |
design-md agent generate \
--input DESIGN.md \
--output src/components/ui \
--framework react \
--tokens-path tokens/
Команда design-md agent generate — это пример. В реальности подставьте имя своего агента или скрипта, который оборачивает вызов LLM. Главное — фиксировать версию DESIGN.md в коммите, чтобы откат был возможен.
Если проект использует systemd для деплоя (а я всегда рекомендую systemd для сервисов на своих серверах), можно добавить юнит, который перезапускает фронтенд после обновления компонентов:
ini[Unit]
Description=Frontend UI service
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/frontend
ExecStart=/usr/bin/node server.js
Restart=always
User=frontend
[Install]
WantedBy=multi-user.target
Но это уже вне рамки DESIGN.md — просто напоминание, что сгенерированный интерфейс нужно где-то запускать.
Часто задаваемые вопросы
Можно ли использовать DESIGN.md без coding-агента?
Да, файл остаётся обычной документацией для людей. Во-первых, он лежит в репозитории и версионируется вместе с кодом, поэтому любой разработчик может открыть его и увидеть токены цвета, отступы и типографику. С практичной точки зрения, DESIGN.md работает как единый источник правды, даже если агент пока не подключён.
Нужно ли переписывать DESIGN.md при каждом изменении интерфейса?
Не обязательно при каждом, но при изменении дизайн-токенов — да. Если вы меняете основной цвет или отступы, обновите файл, иначе агент сгенерирует компоненты со старыми значениями. С точки зрения предсказуемости конфигурации, лучше править DESIGN.md один раз, чем править десять сгенерированных компонентов по отдельности.
Чем DESIGN.md отличается от описания компонентов в Storybook?
Storybook показывает, как компонент выглядит и ведёт себя, а DESIGN.md задаёт правила, по которым компонент должен быть создан. Агент читает токены и ограничения из DESIGN.md и собирает интерфейс автоматически, в то время как Storybook требует ручной поддержки каждой истории. Для быстрой интеграции нового интерфейса DESIGN.md работает быстрее, потому что не нужно описывать каждый компонент вручную.
Какие coding-агенты лучше всего работают с DESIGN.md?
Любой агент, который умеет читать файлы из репозитория и генерировать код, подойдёт. Важнее не название агента, а структура DESIGN.md: чёткие токены, варианты компонентов и ограничения бренда. Если агент поддерживает контекст из репозитория, он подхватит файл автоматически без дополнительных настроек.
Можно ли генерировать через DESIGN.md интерфейс для мобильных приложений?
Можно, если агент поддерживает целевую платформу и понимает формат токенов. DESIGN.md описывает значения — цвета, отступы, типографику — которые легко переносятся в CSS-переменные, тему SwiftUI или Jetpack Compose. С практичной точки зрения, ограничения будут не в формате файла, а в возможностях агента по генерации нативного кода.