Коллекция DESIGN.md для дизайн-систем и AI-агентов

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

awesome-design-md: что внутри подборки

Отбор и анализ DESIGN.md

Когда я начинал собирать коллекцию, первое, с чем столкнулся — отсутствие единого стандарта. Один бренд называет файл DESIGN.md, другой — design-tokens.md, третий вообще хранит гайдлайн в Notion и не выкладывает в открытый доступ. Я отбирал репозитории по трём критериям.

Во-первых, файл должен лежать в корне репозитория или в хорошо видном месте вроде .github/ или docs/. Если дизайн-система спрятана в недрах вики, к ней не подключишь coding-агента без лишних телодвижений.

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

С практической точки зрения, я проверял, можно ли из файла вытащить дизайн-токены в машинночитаемом виде. JSON, YAML, даже простой блок кода с переменными — подойдёт. Если токены описаны только словами «основной цвет — синий», агент не поймёт, какой именно оттенок использовать.

Вот пример того, что я считаю минимально приемлемым DESIGN.md:

markdown
# DESIGN.md

## Colors
- primary: #0066cc
- secondary: #6c757d
- success: #28a745
- danger: #dc3545

## Typography
- font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif
- font-size-base: 16px
- line-height-base: 1.5

## Components
### Button
- padding: 8px 16px
- border-radius: 4px
- font-weight: 600
- states: default, hover, active, disabled

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

Анализ каждого файла занимал от получаса до пары часов. Я не просто копировал ссылки — прогонял DESIGN.md через локальный LLM, проверял, сгенерирует ли он адекватный React-компонент. Если нет — файл не попадал в подборку.

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

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

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

Формат файла для coding-агента

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

С практической точки зрения, структура должна быть плоской. Я пишу конфиги руками, даже если есть GUI, потому что знаю, где лежит конфиг. Для DESIGN.md правило то же: лучше простой markdown, чем глубокая вложенность, которую агент прочитает неправильно.

Пример минимального файла:

markdown
---
name: "Acme Design System"
version: "1.2.0"
---

# Acme Design System

## Цвета

- primary: `#0066cc`
- secondary: `#666666`
- background: `#ffffff`

## Типографика

- font-family: `Inter, sans-serif`
- h1: `32px / 40px, 600`
- body: `16px / 24px, 400`

## Компоненты

### Button

- padding: `8px 16px`
- border-radius: `6px`
- font-size: `14px`

Если токены уже вынесены в JSON, не дублируйте их в markdown. Ссылнитесь на файл:

markdown
## Токены

Полный список: `./tokens/design.tokens.json`

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

Работа с Claude Code и другими агентами

Claude Code ищет инструкции проекта в CLAUDE.md в корне репозитория. Чтобы агент учитывал DESIGN.md, добавьте ссылку на него туда:

markdown
# CLAUDE.md

## Контекст

Дизайн-система описана в `DESIGN.md`. При генерации или изменении UI следуйте токенам и спецификации компонентов из этого файла. Не придумывайте цвета и отступы самостоятельно.

Для Cursor используйте .cursorrules, для GitHub Copilot — copilot-instructions.md. Суть не меняется: агент должен знать, где лежит источник истины по дизайну.

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

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

Ограничения метода и границы применимости

Когда DESIGN.md недостаточно

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

Сложные состояния и мультипликативность

DESIGN.md описывает базовые состояния элементов, но не всегда покрывает комбинации. Например, когда один элемент взаимодействует с несколькими компонентами одновременно (modal + dropdown + tooltip), описание в файле может не отражать все возможные комбинации. Это приводит к дублированию логики и ошибкам при изменении одного паттерна.

yaml
# Пример сложного состояния, не описанного в DESIGN.md
- id: "modal-overlay-with-tooltip"
  type: "combined-state"
  interactions:
    - "close modal"
    - "toggle dropdown inside modal"
    - "show tooltip on hover"
  priority: "high"

Интерактивность и микро-анимации

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

json
{
  "animation": "slide-in",
  "duration": "250ms",
  "easing": "cubic-bezier(0.4, 0, 0.2, 1)",
  "trigger": "hover",
  "target": "card",
  "states": ["idle", "active", "error"]
}

Международность и локализация

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

Интеграция с инструментами и CI

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

Что добавить к анализу дизайн-системы

Для полноценного применения DESIGN.md необходимо расширить анализ до следующих аспектов.

Интерфейсное поведение и ошибки

Дополнительно к DESIGN.md следует включать описание состояний ошибок и граничных случаев. Базовый паттерн «ошибка загрузки» или «нет данных» не всегда описан, что приводит к непредсказуемому поведению интерфейса.

markdown
### Обработка ошибок и граничных состояний

- **Ошибка загрузки**: описание UI при отсутствии ресурсов, поведение при таймауте API
- **Пустой экран**: как выглядит система без данных, какие элементы должны появляться
- **Сбой авторизации**: шаблон ошибки, сохранение контекста сессии
- **Нет доступа**: визуальные индикаторы ограничений, альтернативные пути

Производительность и оптимизация

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

yaml
# Пример конфига оптимизации
optimization:
  image_size: "32x32"  # минимальный размер иконок
  vector_only: true
  lazy_loading: true
  bundle_size_limit: "150kb"

Тестирование и валидация

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

javascript
// Пример теста консистентности
test('design-tokens update propagates to all components', () => {
  const originalColor = getDesignToken('primary-color');
  updateDesignToken('primary-color', '#3B82F6');
  expect(getComponentColor('button', 'primary')).toBe('#3B82F6');
});

Интеграция с Figma и плагинами

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

json
{
  "figma_plugin": "design-system-export",
  "export_settings": {
    "components": "all",
    "tokens": "all",
    "variants": "size, color, state"
  },
  "ci_integration": "pre-commit hook"
}

Мониторинг и аудит

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

markdown
### Мониторинг соответствия

- **Лог отклонений**: отслеживание случаев, когда элементы не соответствуют DESIGN.md
- **Метрики использования**: частотность применения каждого паттерна
- **Частичный аудит**: ежемесячная проверка на наличие устаревших паттернов

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

Заключение

Ожидаемый результат

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

Пример интеграции

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

yaml
design-system:
  tokens:
    color:
      primary:
        - name: "primary-primary"
          value: "#1a73e8"
          usage: "акценты, кнопки"
      secondary:
        - name: "secondary-primary"
          value: "#34a853"
          usage: "успешные действия"
    typography:
      font-family: "Inter, sans-serif"
      heading: "Inter, 24px, 600"
      body: "Inter, 14px, 400"
    spacing:
      base: "4px"
      medium: "16px"
      large: "32px"
  layout:
    grid: "12-column"
    breakpoints:
      mobile: "360px"
      tablet: "768px"
      desktop: "1024px"
  components:
    button:
      variant: "primary"
      size: "medium"
      icon: "✅"
    card:
      shadow: "0 2px 8px rgba(0,0,0,0.1)"
      border-radius: "8px"

Генерация UI с помощью AI-агентов

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

Агент считывает DESIGN.md коллекцию бренда
Формирует спецификацию компонентов
Генерирует код в соответствии с дизайн-токенами
Проверяет соответствие консистентности через мониторинг

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

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

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

Несмотря на эффективность DESIGN.md для генерации UI, существуют сценарии, в которых подход не применим или требует дополнительных усилий:

Сложная вариативность бренда — если дизайн-система содержит слишком много уникальных вариаций (несколько тональностей, региональных адаптаций), автоматическая генерация может нарушить целостность. В таких случаях рекомендуется ручное согласование критических элементов.
Отсутствие единого источника истины — если DESIGN.md файлы распределены по разным репозиториям или не синхронизированы, агенты могут генерировать несовместимый UI. Необходимо поддерживать единый репозиторий с версионированием анализ DESIGN.md файлов популярных дизайн-систем.
Специфические бизнес-решения — когда UI требует нестандартных интеракций, не описанных в design-tokens, автоматическая генерация не сможет их создать. В таких случаях необходимо комбинировать AI-генерируемый базовый UI с ручными адаптациями.
Масштабирование на сотни экранов — при проектировании сложных приложений с тысячами компонентов автоматическая генерация без кастомизации может привести к ухудшению UX. Рекомендуется использовать design-system с явными правилами расширения.

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

Коллекция DESIGN.md для дизайн-систем и AI-агентов