DESIGN.md — один файл, который решает главную проблему вайбкодинга: «AI beige»

Если вы хоть раз генерировали интерфейс через Cursor, Claude Code или Lovable — наверняка узнаете этот результат. Всё работает. Всё выглядит как... ничего конкретного. Серовато-белый фон, синяя кнопка по умолчанию, шрифт Inter, отступы по 16px. Технически корректно, визуально — никак.

Это явление получило название «AI beige» — визуальный «средний по больнице» результат, который выдаёт модель, когда у неё нет никакого представления о вашем бренде. Промпт «сделай дашборд» без дополнительного контекста почти всегда возвращает один и тот же набор паттернов, потому что модель опирается на статистически наиболее частые решения из обучающих данных.

В марте 2026 года Google представил формат, который решает эту проблему системно — DESIGN.md.

## Что такое DESIGN.md

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

Формат впервые появился в марте 2026 года как часть крупного обновления Google Stitch — AI-инструмента для дизайна интерфейсов, в которое также вошли бесконечный canvas, дизайн-агент с памятью проекта и мгновенный прототайпинг. В апреле 2026 Google открыл спецификацию как отдельный проект под лицензией Apache 2.0.

Сама идея не нова — DESIGN.md концептуально продолжает линию файлов вроде README.md и AGENTS.md: положить рядом с кодом файл, который читают не только люди, но и агенты, и зафиксировать в нём контекст один раз, а не повторять в каждом промпте.

Сегодня формат понимают основные AI-среды для разработки: Cursor, Claude Code, v0, Bolt, Codex, Aider и сам Stitch. Если в корне репозитория лежит DESIGN.md, агент использует его как источник истины при генерации любого UI-кода.

## Из чего состоит файл: два слоя в одном документе

Официальная спецификация описывает DESIGN.md как файл из двух частей: YAML front matter с токенами дизайна и тело в Markdown с обоснованием этих решений.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Архитектурный минимализм встречается с журналистской весомостью.
Интерфейс должен выглядеть как премиальная матовая поверхность —
дорогая газета или современная галерея.

## Colors

- **Primary (#1A1C1E):** глубокий чернильный — для заголовков и основного текста
- **Tertiary (#B8422E):** "Boston Clay" — единственный цвет для интерактивных элементов

Логика простая: токены — это конкретные значения (#1A1C1E, 16px, Public Sans). Без них агент угадывает цвета. Прозаическая часть — это качественные описания и обоснования («минималистично, как Linear», «тёплое, как Airbnb»). Без неё агент знает цвета, но не понимает характер — и может расставить их неправильно.

Система токенов опирается на спецификацию W3C Design Tokens, включая синтаксис ссылок между токенами вида {colors.primary} — то есть один токен может ссылаться на другой, и при изменении базового значения все связанные обновятся автоматически.

## Структура файла: 8 секций по спецификации

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

1. Overview (он же Brand & Style). Целостное описание характера продукта: личность бренда, целевая аудитория, эмоция, которую должен вызывать интерфейс. Это базовый контекст для любых решений, не покрытых конкретными правилами ниже — своего рода fallback для агента.

2. Colors. Палитра с семантическими ролями: primary, secondary, tertiary, neutral. Для каждого цвета — hex-значение, описательное имя и правило использования. Без семантического имени модель может, например, по ошибке использовать цвет ошибки как акцентный.

3. Typography. Уровни типографики (обычно 9–15: заголовки разных уровней, тело текста, подписи, лейблы). Токены включают fontFamily, fontSize, fontWeight, lineHeight, letterSpacing. Модели нужны конкретные числа — формулировка «крупный шрифт» бесполезна как инструкция.

4. Layout (он же Layout & Spacing). Стратегия сетки и отступов: на основе grid, поля, безопасные зоны. Токены отступов задают шкалу (sm, md, lg, xl).

5. Elevation & Depth. Как передаётся визуальная иерархия. Если используются тени — задаются их параметры (spread, blur, цвет). Для плоского дизайна описываются альтернативные приёмы: границы, контраст цвета.

6. Shapes. Язык форм: радиусы скругления для кнопок, карточек и других прямоугольных элементов через токены rounded (sm, md, lg, full).

7. Components. Токены на уровне компонентов — каждый компонент мапится на группу свойств: backgroundColor, textColor, typography, rounded, padding, size. Состояния (hover, active, pressed) описываются отдельными записями со связанным именем:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

8. Do's and Don'ts. Явные ограничения и запреты. Модели хорошо реагируют на негативные инструкции — то, чего делать нельзя, так же важно, как и то, что нужно делать:

## Do's and Don'ts
- Используй primary только для одного, самого важного действия на экране
- Не смешивай скруглённые и острые углы в одном представлении
- Соблюдай контраст WCAG AA (минимум 4.5:1 для обычного текста)
- Не используй больше двух начертаний шрифта на одном экране

## Как это работает на практике

Стандартная структура проекта:

your-project/
├── DESIGN.md       ← описание дизайн-системы
├── AGENTS.md       ← ссылка на DESIGN.md для агентов
├── package.json
└── src/

В AGENTS.md достаточно одной строки в секции про UI:

## UI & Design System
Follow ./DESIGN.md for all visual decisions.

После этого любой промпт к агенту автоматически учитывает дизайн-систему проекта. Вместо «сделай кнопку» агент делает кнопку в заданном стиле — с нужными токенами, радиусом и состоянием hover, описанными в файле.

Разница между «до» и «после» хорошо документирована: один и тот же промпт «Build a modern dashboard» без DESIGN.md выдаёт усреднённый интерфейс — тот самый AI beige. С файлом — интерфейс с конкретным характером, соответствующий описанной системе.

## Официальный CLI: lint, diff, export, spec

У формата есть официальный пакет @google/design.md с четырьмя командами.

lint — проверяет файл на ошибки: битые ссылки между токенами, контраст по WCAG AA, токены-сироты, порядок секций, отсутствующую типографику.

npx @google/design.md lint DESIGN.md

diff — сравнивает две версии файла на уровне токенов, показывает изменения. Возвращает код выхода 1, если обнаружены регрессии — удобно для CI.

npx @google/design.md diff DESIGN.md DESIGN-v2.md

export — конвертирует токены в конфиг темы Tailwind или в tokens.json формата DTCG (W3C Design Tokens Format).

npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

spec — выводит полную спецификацию формата. Полезно когда нужно вставить контекст спецификации прямо в промпт агенту.

npx @google/design.md spec
npx @google/design.md spec --rules --format json

## Где взять готовый файл

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

Stitch (stitch.withgoogle.com) — можно сгенерировать DESIGN.md бесплатно прямо в официальном инструменте Google: задаёте цвета бренда и шрифты, получаете файл на выходе.

getdesign.md — библиотека готовых файлов под реальные бренды: Stripe, Linear, Vercel, Notion, Airbnb и другие. Скачиваете подходящий по духу файл, кладёте в репозиторий — и агент начинает строить интерфейс «в стиле Linear» без дополнительных объяснений.

designmd.app — более крупная библиотека шаблонов с разными эстетическими направлениями, от Y2K и brutalism до enterprise-систем вроде IBM Carbon. Также содержит подробную документацию по спецификации и гайды.

При выборе готового файла стоит помнить: спецификация официально находится в статусе alpha. Формат развивается, и в будущих версиях возможны изменения структуры — стоит периодически проверять файлы через lint после обновления зависимостей или CLI.

## Связь с AGENTS.md и почему это особенно важно для команд

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

Для команд эффект особенно заметен. Раньше два разработчика, параллельно работающие в Cursor и Claude Code над одним проектом, неизбежно создавали визуальный дрейф — каждый агент по-своему интерпретировал «современный минималистичный дизайн» в отсутствие конкретики. DESIGN.md в корне репозитория действует как единый источник истины для всех агентов одновременно, независимо от того, кто и в каком инструменте генерирует код.

## Ограничения формата

DESIGN.md — это не замена полноценной дизайн-системе. Он не управляет состояниями приложения, не проверяет анимации, не валидирует доступность на уровне готовых компонентов (хотя линтер проверяет контраст цветов на уровне токенов). Это контекст для агента, а не production-ready пайплайн дизайн-токенов.

Для серьёзного продукта DESIGN.md логичнее рассматривать как стартовую точку или как прослойку между Figma и кодом — но не как замену обоим.

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

И ещё момент: формат в alpha-статусе. Это означает, что спецификация может меняться, а синтаксис в более старых готовых файлах из библиотек может со временем разойтись с актуальной версией CLI. Запуск lint после обновлений — не лишняя предосторожность.

## Итог

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

Формат сочетает точные токены в YAML (для конкретных значений) и текстовые объяснения в Markdown (для намерения и контекста) — именно эта комбинация отличает его от обычных файлов токенов вроде tokens.json, которые модель может прочитать, но не может интерпретировать.

Для одиночного вайбкодера это означает конец AI beige без лишних усилий. Для команды — визуальную согласованность между параллельно работающими агентами. Попробовать проще всего через готовую библиотеку: возьмите файл под близкий по духу бренд из getdesign.md или designmd.app, положите в проект и сравните результат генерации UI до и после.