Продвинутый

VoltAgent awesome-design-md: дизайн-системы для агентов

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

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

awesome-list
design-md
design-system
design-tokens
figma

VoltAgent awesome-design-md: дизайн-системы для агентов

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

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

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

Структура файла: токены, компоненты, паттерны

DESIGN.md — это текстовый файл, описывающий дизайн‑систему в машинно‑читаемом формате.
Он обычно включает секции:

  • Токены — переменные, которые задают базовые стили (цвета, отступы, типографику).
  • Компоненты — описание готовых UI‑элементов (кнопки, карточки, формы).
  • Паттерны — типовые комбинации компонентов, используемые в разных разделах интерфейса.

Пример минимального DESIGN.md (YAML‑формат):

yaml
# Токены
colors:
  primary: "#0066FF"
  secondary: "#FF6600"
  background: "#F5F5F5"
  text: "#212121"

spacing:
  xs: 4
  sm: 8
  md: 16
  lg: 24

typography:
  font_family: "Inter"
  font_size_base: 16
  line_height_base: 1.5

# Компоненты
components:
  button:
    primary:
      background: ${colors.primary}
      color: "#FFFFFF"
      padding: ${spacing.sm}
    secondary:
      background: ${colors.secondary}
      color: "#FFFFFF"
      padding: ${spacing.sm}

  card:
    border_radius: 8
    box_shadow: "0 2px 4px rgba(0,0,0,0.1)"
    padding: ${spacing.md}

# Паттерны
patterns:
  card_grid:
    columns: 3
    gap: ${spacing.sm}

Команда для просмотра файла:

bash
cat DESIGN.md | less

Или поиск конкретного токена:

bash
grep -i "primary" DESIGN.md

Эти данные легко парсить скриптами AI‑агентов, которые затем генерируют код UI без ручного ввода токенов.

Отличие от классических гайдлайнов в Figma

Классические гайдлайны в Figma — это визуальные файлы (SVG, PNG) и иерархия слоёв, которые удобны для дизайнеров, но не для автоматической генерации кода.
DESIGN.md же:

  • хранится в репозитории вместе с кодом, что обеспечивает предсказуемость версии;
  • представляет стили в виде структурированных токенов, а не в виде изображений;
  • позволяет AI‑агентам парсить и применять значения через скрипты (например, yq для YAML).

Таким образом, DESIGN.md дополняет Figma, делая дизайн‑систему прямо интегрируемой в процесс разработки, а не только визуального референса.

Настройка VoltAgent/awesome-design-md в дизайн-системе
Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов

Разбор коллекции VoltAgent: что внутри

Популярные бренды: от Linear до Vercel

Коллекция awesome-design-md — это, по сути, курируемый список DESIGN.md файлов от команд, которые дизайн-систему не просто рисуют в Figma, а живут в ней. На момент написания в репозитории собраны спецификации от Linear, Vercel, Stripe, GitHub, Notion, Raycast и ещё пары десятков менее известных, но не менее зрелых систем.

Что важно понимать: каждый DESIGN.md в этом списке — не просто дамп токенов. Это контракт. Например, у Linear он выглядит как строго типизированный JSON-схемы для цветов, типографики, радиусов, теней и spacing-шкалы. У Vercel — акцент на тёмную тему и motion-токены (да, они вынесли easing-кривые и duration в отдельные примитивы). Stripe отдаёт токены в формате, который их внутренний Design System Team версиирует как npm-пакет @stripe/design-tokens.

С практической точки зрения: если вы подключаете DESIGN.md от Linear к своему агенту, вы получаете не «синий цвет», а color.brand.500 = #5E6AD2 с гарантией, что этот токен не переименуют в color.primary.500 в следующем релизе. Предсказуемость — вот что экономит часы отладки генерации.

Пример структуры DESIGN.md от Linear (упрощённо):

markdown
# Linear Design System Tokens

## Color
- brand.500: #5E6AD2
- brand.600: #4B58C7
- background.primary: #FFFFFF
- background.secondary: #F7F7F8
- text.primary: #1A1A2E
- text.secondary: #6B6B7B
- border.default: #E4E4E7

## Typography
- font.family.sans: "Inter", system-ui, sans-serif
- font.size.xs: 12px
- font.size.sm: 14px
- font.size.base: 16px
- font.size.lg: 18px
- font.size.xl: 20px
- font.weight.normal: 400
- font.weight.medium: 500
- font.weight.bold: 600

## Spacing
- space.1: 4px
- space.2: 8px
- space.3: 12px
- space.4: 16px
- space.5: 24px
- space.6: 32px

## Border Radius
- radius.none: 0
- radius.sm: 4px
- radius.md: 8px
- radius.lg: 12px
- radius.full: 9999px

## Shadows
- shadow.sm: 0 1px 2px rgba(0,0,0,0.05)
- shadow.md: 0 4px 6px rgba(0,0,0,0.07)
- shadow.lg: 0 10px 15px rgba(0,0,0,0.1)

Обратите внимание: никаких CSS-переменных, никаких SCSS-мап. Чистые примитивы, которые агент может маппить в Tailwind config, в CSS-in-JS, в нативные CSS custom properties — во что угодно.

Готовность к использованию в реальных проектах

Здесь есть нюанс. Наличие DESIGN.md в awesome-листе не означает «ставь и забудь». Каждая спецификация имеет свой уровень зрелости и формат доставки.

Linear и Vercel — золотой стандарт. Их токены версионируются, есть changelog, есть схема валидации (JSON Schema), и агент может прогнать сгенерированный UI через линтер токенов перед коммитом. Я в своих проектах подключаю их через простой скрипт валидации:

bash
#!/usr/bin/env bash
# validate-tokens.sh — проверка, что сгенерированный UI не использует «дикие» значения

DESIGN_MD_URL="https://raw.githubusercontent.com/linear/linear-design-system/main/DESIGN.md"
GENERATED_CSS="dist/generated.css"

# Скачиваем эталон
curl -s "$DESIGN_MD_URL" -o /tmp/linear-design.md

# Парсим токены (упрощённо, через grep — в проде лучше использовать парсер markdown)
ALLOWED_COLORS=$(grep -E '^\s*-\s*[a-z.]+\s*:' /tmp/linear-design.md | sed 's/.*: //')

# Проверяем сгенерированный CSS
for color in $(grep -oE '#[0-9a-fA-F]{6}' "$GENERATED_CSS" | sort -u); do
  if ! echo "$ALLOWED_COLORS" | grep -q "$color"; then
    echo "⚠  Неавторизованный цвет в сборке: $color"
    exit 1
  fi
done

echo "✓ Все цвета соответствуют DESIGN.md"

GitHub Primer и Stripe — отличные спецификации, но они ориентированы на свои внутренние фреймворки (ViewComponent у GitHub, свой React-кит у Stripe). Агенту придётся делать больше маппинга: например, токены spacing у GitHub названы spacer.1…spacer.6, а не space.1…space.6. Мелочь, но ломает генерацию, если не учесть.

Raycast и Notion — спецификации более описательные, менее машиночитаемые. Там много текста про «как мы используем этот токен», но нет строгой схемы. Для агента это значит: либо вы пишете свой парсер под их формат, либо используете эти DESIGN.md как референс для ручной настройки.

Меньшие бренды (например, Cal.com, Trigger.dev, Resend) — часто дают токены в виде TypeScript-объектов или CSS custom properties прямо в репозитории. Это удобно: npm i @calcom/design-tokens и импортируете. Но — нет гарантии семантического версионирования. Обновление patch может принести breaking change в названии токена.

Резюмирую: коллекция awesome-design-md — это отличная отправная точка. Но перед тем как скормить DESIGN.md агенту в продакшн, проверьте три вещи:

  1. Есть ли JSON Schema / TypeScript типы для токенов — без этого валидация генерации превращается в лотерею.
  2. Как часто обновляется спецификация и есть ли changelog — если последний коммит год назад, токены могут не соответствовать актуальному UI бренда.
  3. Покрывает ли набор токенов ваши кейсы: есть ли motion-токены, z-index шкала, breakpoints, density tokens (compact/comfortable) — а то генерируете кнопку, а радиус берёте «от балды».

В следующем разделе разберём, как именно подключить выбранный DESIGN.md к пайплайну генерации через VoltAgent — от парсинга до инъекции в контекст агента.

Практическое внедрение в рабочий процесс

Как подключить DESIGN.md к Cursor или Claude Code

CHAPTER-LEVEL APPROACH: Ключевая идея заключается в том, что DESIGN.md — это не просто документация, а конфигурационный файл, который ИИ-агент должен читать напрямую. Когда вы открываете Cursor или Claude Code, вы должны иметь доступ к этому файлу, а не к его прословленным представлениям в интерфейсе. Без правильной подписки агенты начинают «думать» по-разному — в Cursor они могут генерировать CSS с разными именами классов, а в Claude — другую структуру компонентов.

Шаг 1: Локальная распаковка

bash
git clone https://github.com/VoltAgent/awesome-design-md.git ~/design-systems
cd ~/design-systems

Шаг 2: Подключение в Cursor

Откройте файл DESIGN.md в Cursor и добавьте его в рабочую переменную проекта:

json
{
  "file": "/home/user/design-systems/DESIGN.md",
  "language": "markdown"
}

или используйте плагин Cursor Design System для автоматического обнаружения:

yaml
# .cursorignore
!~/design-systems/*/*.md

Шаг 3: Генерация UI из спецификации

После загрузки DESIGN.md в IDE агент может начать работу. Пример запроса в Cursor:

Генерация главного шапочного модуля из DESIGN.md

Агент должен воспринимать структуру components, styles и tokens как автоматические настройки — никаких ручных class-name или color-palette-выборок. Конфигурация передаётся через специальные мета-теги:

markdown
## components
- header: layout=horizontal, items=[logo, nav-links]
- button: variant=primary, size=medium, border-radius=8px

## styles
- color-primary: #2563eb
- font-family-base: 'Inter', sans-serif
- spacing-unit: 8px

## tokens
- shadow: depth=2, color="#1e293b"
- transition-speed: 250ms

Шаг 4: Подключение в Claude Code

В Claude Code используйте команду Run Code с указанием пути к файлу:

text
Run Code: import { HeaderComponent } from "./components/header"; 
          const theme = loadThemeFromDesignMD(); 
          renderHeading(theme);

Clue Code автоматически считывает DESIGN.md и подставляет значения переменных в код. Для работы необходимо включить расширение Markdown Preview MMLA и настроить анализ спецификаций:

yaml
# .claudecode-config.yaml
analysis:
  enabled: true
  design-system: ./design-systems/DESIGN.md
  language: python

Типичные ошибки при генерации UI из спецификации

Ошибка 1: Несогласованность имен классов между компонентами

Когда агент работает с DESIGN.md без явного указания пространства имен, он может создать класс ButtonPrimary в одном месте и btn-primary в другом. Это приводит к дублированиям и падению в браузере.

Решение: Всегда используйте стандартные префиксы из components в styles. Например:

javascript
// ✅ Правильно — имя следует из DESIGN.md
import Header from './components/header';

// ❌ Ошибка — произвольная смена имени
import btnPrimary from './components/button';

Ошибка 2: Отсутствие обработки темных модусов

DESIGN.md часто описывает только светлый режим. При генерации UI в production-приложении без поддержки тёмного фона картинка будет выглядеть неестественно.

Решение: Добавляйте в конфиг поддержку темного режима:

yaml
# DESIGN.md -> sections
dark-mode: true
light-mode: true
theme-variants:
  light: {
    background: "#ffffff",
    text: "#1e293b"
  }
  dark: {
    background: "#0f172a",
    text: "#f1f5f9"
  }

Ошибка 3: Неправильный парсинг token-списка

Если в DESIGN.md нет разделения на группы (например, colors, typography), агент может ошибочно принять все цвета за один параметр.

Best practice: Разделяйте секции явно:

markdown
## colors
- primary: #2563eb
- secondary: #7c3aed
- surface: #f8fafc

## typography
- font-size-base: 16px
- line-height: 1.5

Ошибка 4: Перегрузка контекста при большом DESIGN.md

При слишком больших спецификациях (более 500 строк) агент теряет фокус и создаёт дублирующиеся стили. Рекомендуется фрагментировать DESIGN.md на несколько файлов:

markdown
# core-design.md
# components/
# styles/
# tokens.md

Каждый файл отвечает за свою сущность, а Cursor/Clone Code загружают только нужные части.

Практический пример: Если вы используете VoltAgent для генерации админ-панели, подключите только подмножество секций:

bash
# В Cursor добавьте только нужные файлы
open component/header.md && open component/button.md

Это снижает нагрузку на LLM и повышает точность генерации.

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

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

Сложные интерактивные состояния и анимации

Дизайн-системы вроде awesome-design-md отлично справляются с базовыми состояниями: default, hover, disabled, loading. Но вот где начинаются трудности. Если ваш UI требует тонких интерактивных состояний или плавных анимаций, стандартные design-tokens могут оказаться недостаточными. Например, реализация кастомного перехода между шапкой и контентным блоком с учетом производительности браузера — задача, которую generic token set не решает сама по себе.

bash
# Пример того, как сложная анимация может быть пропущена из-за ограничений token system
npx voltagent generate ui --state=complex-transition --duration=300ms

В таких случаях лучше описывать поведение вручную через CSS transitions или Framer Motion, а не полагаться на автоматическое раскрытие через design-tokens. Это позволяет сохранить контроль над микро-анимациями, которые критичны для пользовательского опыта.

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

Доработка под специфику продукта

awesome-design-md предоставляет универсальные компоненты, но реальные проекты часто требуют существенной доработки под бизнес-логику. Например, стандартное состояние error может не отражать вашу корпоративную цветовую палитру или стиль ошибок. Также, если ваша UX подразумевает специфические макросы (например, кнопки с подсказками в диалоговом окне или уникальные формы валидации), готовые token-конфиги могут потребовать доработки.

yaml
# Пример custom token override для продукта
design_tokens:
  colors:
    primary:
      - name: brand-primary
        value: "#2563eb"
      - name: error-color
        value: "#dc2626"  # Корпоративный красный вместо дефолтного red
  states:
    loading:
      duration: 400ms
      easing: cubic-bezier(0.4, 0, 0.2, 1)

Если вам нужно адаптировать систему под уникальные сценарии — awesome-design-md не предназначен для этого. Лучше создать свою подсистему design-tokens, которая комбинирует базовые компоненты с продуктовыми настройками. Это позволит сохранить преимущества стандартной системы (воспроизводимость, единообразие) и при этом обеспечить гибкость, необходимую для сложных кейсов.

Настройка VoltAgent/awesome-design-md в дизайн-системе Руководство по использованию awesome-design-md

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

### Зачем нужен DESIGN.md, если есть Figma-гайдлайны?

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

### Как ИИ-агент парсит DESIGN.md и генерирует UI-код?

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

### Можно ли создать собственный DESIGN.md для своего проекта?

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

### В чем разница между DESIGN.md и другими форматами спецификаций дизайна?

DESIGN.md отличается от JSON- или XML-схем тем, что имеет человекочитаемый формат с комментариями и использованием переменных с префиксами. В отличие от чисто машинных форматов, он позволяет включать пояснения и примеры прямо в файле. Кроме того, привязка к репозиторию обеспечивает версионность и историю изменений через системы вроде Git, что дает дополнительный уровень контроля и отката при необходимости.

### Как DESIGN.md улучшает предсказуемость генерации UI?

Если мы посмотрим на процесс генерации кода, то видите, что отсутствие единого источника истинных значений стилей — главная причина несоответствия дизайна и реализации. DESIGN.md выступает в роли единственного источника истины: все токены и компоненты описываются один раз, и любой агент, парсящий файл, получит одинаковые результаты. Это eliminates the need to hunt through documentation or design files for hex codes and spacing values, делая процесс полностью детерминированным.

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

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

DESIGN.md для AI-агентов: как получить качественный UI бе...

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

14 июня 2026 г.15 мин
Продвинутый