awesome-design-md: DESIGN.md для дизайн-систем
Коллекция DESIGN.md от популярных брендовых дизайн-систем. Подключите файл к проекту — код-агенты сгенерируют подходящий UI.
Что такое awesome-design-md
Что такое awesome-design-md
awesome-design-md — это открытая коллекция DESIGN.md файлов от популярных брендовых дизайн-систем. Идея простая: подключаешь файл к проекту, и код-агенты генерируют подходящий UI. Для меня, как для инженера, который ещё в 2012 году настраивал LAMP-стеки на shared-хостинге, это выглядит как логическое продолжение инфраструктуры как кода — только для интерфейса.
Раньше описание дизайн-системы жило в Figma, в отдельном вики или в голове у ведущего дизайнера. Разработчик открывал макет, смотрел на цвета и отступы, и переводил их в CSS «на глаз». Результат зависел от внимательности конкретного человека. awesome-design-md переносит это описание в репозиторий проекта в формате, который понимает не только человек, но и ИИ-агент.
DESIGN.md как техническое задание для ИИ
ТЗ для человека и ТЗ для ИИ — разные вещи. Человеку нужно объяснить контекст, показать примеры и обсудить нюансы. ИИ нужны жёсткие границы: дизайн-токены, список компонентов, правила их использования. DESIGN.md как раз даёт эту структуру.
Вот как может выглядеть упрощённый DESIGN.md:
markdown# Design System
## Tokens
colors:
primary: #0066ff
background: #ffffff
spacing:
xs: 4px
sm: 8px
md: 16px
## Components
Button:
variants:
- primary
- secondary
- ghost
sizes:
- sm
- md
- lg
Подключить файл к проекту можно вручную или через конфиг агента. Пример с curl:
bashcurl -sO https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/designs/example/DESIGN.md
Или через конфигурационный файл код-агента:
json{
"designSystem": "./DESIGN.md",
"output": "./src/components",
"framework": "react"
}
С практической точки зрения, DESIGN.md даёт предсказуемость. Когда я описываю инфраструктуру в Ansible или Terraform, я знаю, какой сервер поднимется на выходе. С DESIGN.md для ИИ то же самое: файл задаёт границы, в которых агент генерирует компоненты, и результат не «плывёт» от сессии к сессии.
Подробнее о том, как использовать DESIGN.md для генерации интерфейса, написано в отдельном гайде.
Какие бренды представлены в коллекции
В коллекции собраны DESIGN.md от популярных брендовых дизайн-систем. Точный список меняется, но суть в том, что там представлены разные подходы: кто-то делает акцент на токенах, кто-то на правилах использования компонентов, кто-то на связке с Figma.
Если хотите сравнить, как разные бренды описывают свои системы, загляните в анализ DESIGN.md файлов популярных дизайн-систем или в разбор VoltAgent/awesome-design-md. Там же есть ссылки на исходные файлы, которые можно скопировать в свой проект.
awesome-design-md — это не просто список ссылок. Это способ привести описание дизайн-системы к виду, который понимают код-агенты. Подключаешь DESIGN.md к проекту — и получаешь предсказуемый UI, собранный по правилам бренда.
Как подключить DESIGN.md к проекту
Как подключить DESIGN.md к проекту
Куда положить файл и как на него сослаться
Размещайте DESIGN.md в корне репозитория, рядом с README.md. Coding-агенты ищут инструкции в первую очередь там, где лежит точка входа проекта. Если документация вынесена в отдельную папку, положите файл в docs/design/ и укажите путь явно — агенты не угадают вложенность.
Пример структуры:
textmy-project/ ├── DESIGN.md ├── README.md ├── docs/ │ └── architecture.md └── src/
В README.md добавьте ссылку на файл, чтобы человек и агент видели его сразу:
markdown# My Project
Дизайн-система описана в [DESIGN.md](./DESIGN.md). Все компоненты собираются по токенам из этого файла.
Если используете Cursor, добавьте правило в .cursor/rules/project.mdc (или .cursorrules для старых версий):
markdown# Project Rules
Всегда сверяйтесь с файлом DESIGN.md в корне репозитория перед генерацией UI-компонентов. Используйте токены и правила из этого файла как источник истины.
Для GitHub Copilot в рабочей области создайте .github/copilot-instructions.md:
markdown# Инструкции для Copilot
При генерации интерфейса опирайтесь на ./DESIGN.md. Не придумывайте цвета и отступы — берите их из раздела design-tokens.
С практической точки зрения, путь к файлу лучше прописывать относительным, а не абсолютным. Тогда инструкция не сломается после клонирования репозитория на другой компьютер или переноса в другую организацию.
Настройка промпта для coding-агента
Код-агент не подхватит DESIGN.md автоматически — нужно явно указать, где файл и как с ним работать. Во-первых, добавьте путь к файлу в системный промпт агента. Во-вторых, сформулируйте задачу так, чтобы агент не генерировал «по вдохновению», а следовал токенам.
Пример инструкции для Cursor (в настройках проекта или в .cursor/rules/design.mdc):
markdown# DESIGN.md integration
Перед созданием или изменением React-компонента прочтите ./DESIGN.md.
Используйте значения из раздела «Design tokens»: цвета, типографику, радиусы, отступы.
Не вводите новые токены без обновления DESIGN.md.
Если в Figma есть актуальные макросы, сверяйтесь с ними, но DESIGN.md имеет приоритет.
Пример для Cline / Aider в виде системного промпта:
Вы — фронтенд-инженер. Работаете с репозиторием, в корне которого лежит DESIGN.md.
Этот файл описывает дизайн-систему проекта: токены, правила использования компонентов, ограничения Figma.
При генерации кода всегда ссылайтесь на DESIGN.md и не отклоняйтесь от описанных там значений.
Если агент поддерживает подключение файлов по ссылке, укажите путь в конфиге. Например, для Continue.dev в config.json:
json{
"contextProviders": [
{
"name": "design-system",
"path": "./DESIGN.md"
}
]
}
Связанные материалы:
- Анализ DESIGN.md файлов популярных дизайн-систем
- Использование DESIGN.md для генерации UI
- design-system
От DESIGN.md к готовому интерфейсу
От DESIGN.md к готовому интерфейсу
Дизайн-токены
Дизайн-токены — это именованные константы, которые описывают визуальные решения системы: цвета, отступы, радиусы углов, тени и границы. В DESIGN.md они обычно вынесены в отдельный блок, чтобы разработчик не гадал, какой оттенок синего использовать для основной кнопки.
Во-первых, токены делают интерфейс предсказуемым. Если в DESIGN.md указано, что цвет акцента — #0066CC, этот же цвет будет и на кнопке, и в ссылке, и в индикаторе загрузки. Не нужно держать в голове десяток почти одинаковых оттенков.
Пример блока токенов из DESIGN.md:
yamltokens:
colors:
primary: "#0066CC"
primary-hover: "#0052A3"
background: "#FFFFFF"
surface: "#F5F7FA"
text-primary: "#1A1A1A"
text-secondary: "#666666"
border: "#E0E0E0"
spacing:
xs: "4px"
sm: "8px"
md: "16px"
lg: "24px"
xl: "32px"
border-radius:
sm: "4px"
md: "8px"
lg: "12px"
С практической точки зрения, я обычно перевожу такие токены в CSS-переменные или в конфиг Tailwind. Вот как это выглядит в CSS:
css:root {
--color-primary: #0066CC;
--color-primary-hover: #0052A3;
--color-background: #FFFFFF;
--color-surface: #F5F7FA;
--color-text-primary: #1A1A1A;
--color-text-secondary: #666666;
--color-border: #E0E0E0;
--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 16px;
--spacing-lg: 24px;
--spacing-xl: 32px;
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
}
Если проект на Tailwind, токены переносятся в tailwind.config.js:
javascript/** @type {import('tailwindcss').Config} */
module.exports = {
theme: {
extend: {
colors: {
primary: '#0066CC',
'primary-hover': '#0052A3',
surface: '#F5F7FA',
},
spacing: {
xs: '4px',
sm: '8px',
md: '16px',
lg: '24px',
xl: '32px',
},
borderRadius: {
sm: '4px',
md: '8px',
lg: '12px',
},
},
},
}
Главное правило — не изобретать значения на месте. Если в DESIGN.md есть токен --spacing-md, используйте его, а не пишите padding: 20px «на глаз». Так интерфейс остаётся предсказуемым, и при редизайне достаточно поменять значение в одном месте.
Подробнее о том, как выглядят токены у популярных брендов, можно посмотреть в Анализе DESIGN.md файлов популярных дизайн-систем и в коллекции VoltAgent/awesome-design-md.
Типографика и компоненты
Типографика в DESIGN.md описывает не только семейство шрифтов, но и размер, начертание, межстрочный интервал и интервал между буквами. Компоненты — это уже готовые паттерны: кнопка, поле ввода, модальное окно, карточка.
Я привык писать конфиги вручную, даже если в дизайн-системе есть графический интерфейс. GUI для тех, кто не знает, где лежит конфиг. Вот пример описания типографики и компонентов в DESIGN.md:
yamltypography:
font-family:
primary: "Inter, sans-serif"
mono: "JetBrains Mono, monospace"
scale:
h1: { size: "32px", lineHeight: "40px", weight: 700 }
h2: { size: "24px", lineHeight: "32px", weight: 600 }
body: { size: "16px", lineHeight: "24px", weight: 400 }
caption: { size: "14px", lineHeight: "20px", weight: 400 }
components:
button:
variants:
primary:
background: "#0066CC"
color: "#FFFFFF"
padding: "8px 16px"
border-radius: "8px"
secondary:
background: "transparent"
color: "#0066CC"
border: "1px solid #0066CC"
padding: "8px 16px"
border-radius: "8px"
input:
height: "40px"
padding: "8px 12px"
border: "1px solid #E0E0E0"
border-radius: "8px"
focus-border: "#0066CC"
Перевожу это в CSS-модули или Styled Components. Пример для React:
css/* Button.module.css */
.button {
display: inline-flex;
align-items: center;
justify-content: center;
font-family: "Inter", sans-serif;
font-size: 16px;
line-height: 24px;
font-weight: 400;
border: none;
cursor: pointer;
transition: background 0.2s;
}
.buttonPrimary {
background-color: #0066CC;
color: #FFFFFF;
padding: 8px 16px;
border-radius: 8px;
}
.buttonPrimary:hover {
background-color: #0052A3;
}
.buttonSecondary {
background-color: transparent;
color: #0066CC;
border: 1px solid #0066CC;
padding: 8px 16px;
border-radius: 8px;
}
Если мы посмотрим на структуру компонентов в DESIGN.md, становится понятно, что описание варианта primary кнопки — это не просто цвет, а полный набор свойств: фон, текст, отступы, радиус. Это позволяет генерировать компонент автоматически, а не писать его с нуля каждый раз.
О том, как DESIGN.md используется для генерации UI, написано в отдельном руководстве: Использование DESIGN.md для генерации UI. Общие принципы работы с дизайн-системами описаны в материале design-system.
Пример генерации карточки товара
Теперь соберём всё вместе. Возьмём DESIGN.md с токенами, типографикой и компонентами, и сгенерируем React-компонент карточки товара. Это типичный кейс для интернет-магазина: изображение, название, цена, кнопка «В корзину».
Сначала подключим файл к проекту. В репозитории awesome-design-md файлы лежат в корне или в папке .design/:
bashmkdir -p .design
curl -o .design/DESIGN.md https://raw.githubusercontent.com/voltagent/awesome-design-md/main/examples/shop/DESIGN.md
Затем используем код-агент или скрипт генерации. Ниже пример готового компонента, который получится после обработки DESIGN.md:
tsx// components/ProductCard.tsx
import Image from 'next/image';
interface ProductCardProps {
title: string;
price: number;
image: string;
onAddToCart: () => void;
}
export function ProductCard({ title, price, image, onAddToCart }: ProductCardProps) {
return (
<article className="card">
<Image src={image} alt={title} width={300} height={300} className="cardImage" />
<div className="cardContent">
<h3 className="cardTitle">{title}</h3>
<div className="cardPrice">{price} ₽</div>
<button className="button buttonPrimary" onClick={onAddToCart}>
В корзину
</button>
</div>
</article>
);
}
Стили берутся напрямую из токенов DESIGN.md:
css/* ProductCard.module.css */
.card {
display: flex;
flex-direction: column;
background-color: #FFFFFF;
border: 1px solid #E0E0E0;
border-radius: 8px;
overflow: hidden;
font-family: "Inter", sans-serif;
}
.cardImage {
width: 100%;
height: 200px;
object-fit: cover;
}
.cardContent {
padding: 16px;
display: flex;
flex-direction: column;
gap: 8px;
}
.cardTitle {
font-size: 16px;
line-height: 24px;
font-weight: 600;
color: #1A1A1A;
margin: 0;
}
.cardPrice {
font-size: 16px;
line-height: 24px;
font-weight: 700;
color: #0066CC;
}
.buttonPrimary {
margin-top: auto;
background-color: #0066CC;
color: #FFFFFF;
padding: 8px 16px;
border-radius: 8px;
border: none;
cursor: pointer;
font-size: 16px;
line-height: 24px;
font-weight: 400;
}
.buttonPrimary:hover {
background-color: #0052A3;
}
С практической точки зрения, генерация из DESIGN.md экономит время на согласовании с дизайнером. Не нужно спрашивать в Slack, какой оттенок синего использовать для цены — он уже описан в токене colors.primary. Если дизайнер обновит DESIGN.md, достаточно перегенерировать компоненты, и интерфейс подтянет новые значения автоматически.
Вот и весь путь: от текстового файла с токенами до готового интерфейса, который выглядит одинаково на всех страницах и не ломается при обновлении дизайн-системы.
Ещё один разбор DESIGN.md от других авторов: Анализ DESIGN.md файлов популярных дизайн-систем.
Ограничения подхода
Когда DESIGN.md недостаточно
DESIGN.md — это отличное начало для любого проекта, но у этого подхода есть явные ограничения, которые проявляются, когда система растёт или становится сложнее. Вот когда становится понятно, что одной лишь DESIGN.md не хватает.
Динамические темы и CSS-переменные
DESIGN.md отлично справляется с хранением базовых цветов, шрифтов и отступов, но не учитывает динамическую смену темы или CSS-переменные, которые зависят от контекста. Если пользователю нужно переключать тему в реальном времени или адаптировать UI под разные режимы энергосбережения, DESIGN.md просто не сможет отразить эту логику.
yaml# design-tokens.yml — пример, чего НЕ хватает DESIGN.md
theme: light
colors:
primary: "#0066CC"
background: "#FFFFFF"
# Нужны динамические переопределения, которых нет в DESIGN.md
dark:
background: "#121212"
primary: "#4A90E2"
Компонентное поведение и интерактивность
DESIGN.md — это статический файл, поэтому он не может описать, как компонент ведёт себя при наведении, фокусе, клике или анимации переходов. Когда вам нужно, чтобы кнопка меняла цвет при наведении и показывала состояние загрузки, DESIGN.md не сможет передать эту интерактивность.
json// Пример кода, который нельзя выразить в DESIGN.md
{
"components": {
"button": {
"states": {
"hover": {"backgroundColor": "#0055AA"},
"loading": {"cursor": "wait", "spinner": true}
}
}
}
}
Доступность и ARIA-атрибуты
DESIGN.md отлично подходит для визуального дизайна, но не может описать иерархию семантики, ARIA-атрибуты или логику фокуса, которые необходимы для скринридеров. Когда проект должен соответствовать WCAG 2.1 AA, вам нужно больше, чем просто цвета и отступы.
markdown<!-- DESIGN.md показывает только внешний вид, но не --> <!-- Какое роль у кнопки, какой текст у aria-label --> <!-- Какой порядок фокуса у модального окна -->
Контекстно-чувствующий дизайн
В реальных приложениях UI меняется в зависимости от роли пользователя, устройства или контекста приложения. DESIGN.md не может описать, почему определённые токены меняются для администратора по сравнению с гостем, или почему мобильная версия использует другие отступы из-за безопасной области iPhone.
yaml# DESIGN.md не может выразить это правило
breakpoints:
mobile: 320px
tablet: 768px
desktop: 1024px
# А это правило, которое нужно где-то хранить
tokens:
mobile:
spacing: 8px
desktop:
spacing: 16px
Масштабируемость для крупных систем
Когда дизайн-система обслуживает десятки компонентов, десятки токенов и несколько тем, DESIGN.md становится трудночитаемым. Поддержание однородности и отслеживание зависимостей между токенами вручную — это адская задача, которую лучше решать с помощью кода.
bash# DESIGN.md не может помочь с линтером
# что-то вроде:
design-md-lint --check-tokens --no-duplicates --validate-deps
Интеграция с инструментами разработки
Современные рабочие процессы требуют, чтобы DESIGN.md интегрировался с Storybook, Chromatic или системами генерации тем. Без скриптов для парсинга DESIGN.md вам придётся дублировать данные или писать пользовательские скрипты для извлечения информации.
json// DESIGN.md не может быть использован напрямую
{
"scripts": {
"storybook:sync": "node scripts/sync-designmd.js"
}
}
Недостаток документации по реализации
DESIGN.md — это отличное справочное руководство, но оно не содержит информации о реализации. Когда инженер спрашивает, почему используется конкретный отступ или как токен подключается к CSS-переменной, DESIGN.md не может дать технический ответ.
css/* DESIGN.md показывает значение, но не показывает */
:root {
--primary: #0066CC; /* почему именно этот цвет */
}
/* Как он подключается к компоненту */
.button {
background-color: var(--primary);
}
Заключение
DESIGN.md — это отличное место для хранения основ дизайн-системы, но оно не может заменить полную документацию по реализации, динамические темы, поведение компонентов или интеграцию с современными инструментами. Когда ваш проект выходит за рамки простого набора токенов, вам нужно перейти от статического markdown-файла к более комплексному подходу, который включает код, скрипты и полную документацию по реализации.
Для проектов, которые сталкиваются с любыми из этих ограничений, лучше сразу использовать более продвинутый стек для дизайн-систем — например, Figma + Figma REST API + CSS-переменные + документацию по компонентам, которая генерируется из кода. DESIGN.md может быть полезен как справочное руководство, но он не должен быть единственным источником истины для чего-то большего.
Часто задаваемые вопросы
Подключение DESIGN.md к проекту
Чтобы подключить DESIGN.md к проекту, можно использовать curl-команду для скачивания файла напрямую из репозитория. Пример: curl -sO https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/designs/example/DESIGN.md. Также файл можно подать через конфигурационный JSON-файл, где указывается путь к дизайн-системе, выходной каталог и фреймворк. Такая подача позволяет кодировщикам и ИИ-агентам автоматически извлечь структуру и компоненты без ручного редактирования.
Поддержка различных фреймворков
DESIGN.md поддерживает работу с различными фронтенд-фреймворками, включая React, Vue, Angular и другие. В конфигурационном файле указывается именно выбранный фреймворк, что позволяет агенту генерировать соответствующий код. Это делает коллекцию универсальной и не привязанной к конкретной технологии, сохраняя при этом привязку к дизайн-токенам и компонентам.
Преимущества перед Figma и другими инструментами
Главное преимущество DESIGN.md — это предсказуемость и воспроизводимость. В отличие от Figma, где макеты зависят от внимательности конкретного дизайнера, здесь описание хранится в коде и понимается и человеком, и ИИ. Это устраняет разрыв между визуальным дизайном и технической реализацией, обеспечивая единообразие интерфейсов в разных проектах.
Обеспечение единообразия дизайна
Для обеспечения единообразия используйте одинаковые DESIGN.md файлы во всех проектах и строго следуйте описанным токенам и правилам компонентов. Когда все команды работают с одним и тем же набором цветов, шрифтов и иконок, вероятность согласованности возрастает. Это особенно важно при интеграции подсистем в единую архитектуру, где важна стабильность визуального языка.