WaveSpeedAI
← Блог

Что такое design.md для агентов кодирования?

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

By Dora 9 min read
Что такое design.md для агентов кодирования?

Меня зовут Дора. На прошлой неделе я попросила Claude Code добавить три новых экрана в побочный проект. К второму экрану радиус кнопок уже сместился, шрифт заголовка незаметно изменился, а «вторичный» серый стал другим оттенком серого. Та же структура промпта. Та же модель. Та же сессия. Результат просто перестал учитывать то, что было до.

Именно эту проблему design.md для агентов написания кода и призван решить. Это обычный markdown-файл, который хранит вашу дизайн-систему в формате, который AI-агент может читать каждый раз при генерации интерфейса — не как разовый промпт, а как постоянный контекст. Stitch читает его. Claude Code читает его. Cursor читает его. Любой другой инструмент, подхватывающий контекстные файлы из корня репозитория, тоже его читает.

Что такое design.md и зачем Google Labs его опубликовал

Формат файла и роль в дизайн-системе

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

Вот примерно как выглядит заголовок — взято из официальной спецификации DESIGN.md на GitHub:

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

Ниже следуют ## Overview, ## Colors, ## Typography в обычном markdown. Порядок разделов фиксирован — Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts. Разделы можно пропускать, но те, что присутствуют, должны идти именно в таком порядке. Дублирующиеся заголовки разделов — ошибка, файл не пройдёт валидацию.

Синтаксис ссылок на токены взят из W3C Design Tokens Format Module — пути в фигурных скобках вида {colors.primary}. Ссылки должны указывать на примитивные значения (не на группы), кроме раздела компонентов, где разрешены составные ссылки на токены типографики. Значения цветов — только SRGB hex в текущей спецификации. Display P3 и Oklch — оба поддерживаются стабильной спецификацией W3C DTCG 2025.10 — в DESIGN.md пока не поддерживаются; репозиторий открыто обозначает это маркером version: alpha. Стоит учитывать, если вы работаете с wide-gamut токенами.

Формат поставляется с CLI — @google/design.md на npm. npx @google/design.md lint запускает семь правил против разобранного файла. Два, с которыми я сталкиваюсь чаще всего: broken-ref (уровень ошибки) обнаруживает ссылки на токены, которые не разрешаются, а contrast-ratio (предупреждение) проверяет пары backgroundColor/textColor компонентов на соответствие минимуму WCAG AA — 4,5:1. Ещё три — missing-primary, orphaned-tokens и структурные правила — выявляют проблемы, которые большинство команд вносят в течение недели после начала редактирования файла. CLI также умеет diff (регрессии токенов между версиями) и export (Tailwind v3 config, Tailwind v4 @theme CSS или W3C DTCG JSON).

Почему постоянный визуальный контекст важен для агентов написания кода

Проблема проста. Агент, генерирующий интерфейс, ничего не знает о вашей дизайн-системе, если вы не дадите ему что-то структурированное для чтения. Вы можете описать палитру в промпте, получить кнопку в ответ, затем попросить карточку — и наблюдать, как логика отступов сбрасывается. Модель не плохо пишет код. У неё просто нет якоря.

design.md — это якорь. Stitch передаёт его как контекст при каждом запросе генерации. Claude Code и Cursor подхватывают его так же, как CLAUDE.md или AGENTS.md — файл в корне репозитория, который агент читает перед ответом. Позиция Google в анонсе с открытым исходным кодом такова: это позволяет агентам «точно знать, для чего используется тот или иной цвет», а не угадывать намерение из промпта.

Я проверила это на обоих проектах. Процедура: положить DESIGN.md в корень, регенерировать те же пять экранов, которые ранее «расплылись» (лендинг, тарифы, регистрация, дашборд, настройки), затем подсчитать нарушения токенов относительно заголовка. При наличии файла Claude Code создал 5/5 экранов с использованием точных значений hex для primary и tertiary и объявленного rounded.sm. Cursor — 4/5: дашборд продолжал заменять rounded.sm (4px) на rounded.md (8px) на карточках, что проза DESIGN.md явно не запрещала. Добавление строки в «Do’s and Don’ts» — «углы карточек используют rounded.sm, никогда rounded.md» — исправило это при следующей регенерации.

Реальная проблема, которую он решает в AI-генерации интерфейсов

Консистентность между экранами и итерациями

В предыдущей сессии сломалось не качество отдельного экрана. Каждый экран по отдельности выглядел нормально. Второй экран просто не знал, что решил первый. Каждая генерация начиналась с немного другой интерпретации «вашего бренда».

Именно этот сценарий отказа и нацелен исправить design.md. Не «сделай интерфейс красивее» — сделай его одинаковым между генерациями. Токены нормативны. Когда в заголовке написано tertiary: “#B8422E”, у агента нет пространства для интерпретации этого как «тёплый оранжевый». Это именно то hex-значение — или ошибка, и lint об этом скажет.

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

Почему проза плюс токены сильнее, чем токены в одиночку

Я чуть не пропустила этот момент. Зачем писать абзацы про «Boston Clay — единственный движущий элемент для взаимодействия», если hex-значение уже есть в YAML?

Потому что агент использует прозу, чтобы принимать решения, которые токены не покрывают. Токены говорят, что tertiary — это #B8422E. Проза говорит, что этот цвет используется только для взаимодействия — не для декоративных акцентов, не для заголовков. Когда промпт неоднозначен («добавь бейдж уведомления»), проза решает, получит ли бейдж цвет взаимодействия или нейтральный. В моём прогоне в Cursor именно отсутствие прозового ограничения было причиной дрейфа дашборда.

Та же логика применима к Do’s and Don’ts — явным ограждениям вроде «никогда не используй тени на карточках» или «всегда используй sentence case для подписей кнопок». Негативные ограничения несут вес, который чистые токены не могут выразить. Это спецификация дизайна для агентов, а не CSS-файл.

Формат не привязан к Stitch. Спецификация под лицензией Apache 2.0, CLI на npm, экспорт DTCG означает, что токены попадают в любой инструмент, читающий стандарт W3C, а сообщество уже движется вперёд. Коллекция awesome-design-md от VoltAgent с DESIGN.md-файлами, вдохновлёнными реальными брендами, набрала 71 000 звёзд на GitHub за несколько недель после запуска, а топик design-md на GitHub теперь содержит инструменты для извлечения, Chrome-расширения и реестры companion SKILL.md — всё от людей за пределами Google. Принятие — это то, что говорит вам, что формат реален.

Кому важно разобраться с design.md

Скажу честно об ограничениях, потому что design.md подходит не всем.

Он оправдывает себя, если:

  • Вы генерируете интерфейс с помощью агентов написания кода хотя бы раз в неделю, на более чем одном экране
  • У вас есть дизайн-система — пусть даже минималистичная — которую вы хотите сохранять между генерациями
  • Вы работаете с более чем одним агентом или инструментом и хотите одинаковый брендовый контекст во всех из них
  • Вам надоело вставлять «помни, наша палитра — X, Y, Z» в каждый промпт

Он не оправдывает себя, если:

  • Вы генерируете разовые макеты и выбрасываете их
  • Ваша «дизайн-система» — это то, что агент сгенерирует на этот раз
  • Вы работаете в Figma-ориентированном процессе со зрелым DTCG-конвейером через Style Dictionary или подобное — design.md легче того, что у вас есть, и это будет шагом назад
  • Вам уже сейчас нужны wide-gamut цвета (Display P3, Oklch) — текущая alpha-спецификация поддерживает только SRGB

Для AI-native продуктовых команд, использующих design.md наряду с другими файлами AI-рабочего процесса (CLAUDE.md, AGENTS.md), он встраивается органично. Один markdown-файл на каждую зону ответственности. Без шага сборки. Без борьбы со схемой JSON. Цена попытки — один файл в корне репозитория и команда lint.

Для платформ, создающих поверхности агентной генерации — включая унифицированные слои AI-генерации, маршрутизирующие запросы между несколькими моделями и нуждающиеся в сохранении брендового контекста при каждом вызове — design.md ближе всего к портативному контракту между брендом и агентом, который есть в экосистеме. Согласно объявлению Google Labs, формат создавался именно для того, чтобы быть экспортируемым и импортируемым между инструментами. Переносимость — это и есть суть.

FAQ

Для чего используется design.md?

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

Он только для рабочих процессов в Google Stitch?

Нет. Формат появился в Stitch, но Google опубликовал спецификацию под лицензией Apache 2.0. Любой AI-инструмент, читающий контекстные файлы — Claude Code, Cursor, GitHub Copilot, Antigravity, Gemini CLI — может его использовать. CLI экспортирует в Tailwind config, CSS-переменные или W3C DTCG JSON, поэтому токены попадают и в инструменты не на основе агентов.

Зачем AI-генерируемому интерфейсу нужен файл дизайн-системы?

Потому что у моделей нет памяти о вашем бренде между генерациями. Без структурированного файла ai design system каждый промпт заново интерпретирует ваш дизайн-язык с нуля. С ним токены выступают жёсткими ограничениями, а проза покрывает суждения. Разница становится особенно заметна в масштабе — пять экранов, сгенерированных с design.md, сохраняют стиль; пять экранов без него — расплываются.

Каким командам стоит попробовать его первыми?

Командам, уже регулярно генерирующим интерфейс с помощью агентов написания кода. Разработчики-одиночки и небольшие продуктовые команды, работающие с Claude Code или Cursor, получают наиболее быструю отдачу — положите файл, регенерируйте, убедитесь в консистентности. Крупным организациям со зрелыми конвейерами Figma + Style Dictionary стоит рассматривать design.md как дополнение, а не замену: используйте его, чтобы дать агентам перевариваемое подмножество существующей системы.

Заключение

design.md — не революционный формат файлов. Это markdown-файл с YAML наверху. В этом и суть — формат, который LLM читают лучше всего, это тот, на котором они обучались больше всего, а это обычный текст.

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

Я использую его в двух проектах уже неделю. Он работает. В долгосрочной перспективе — будут ли команды поддерживать эти файлы с той же строгостью, что и настоящую дизайн-систему, или они устареют так же, как устаревают README — это ещё предстоит проверить. Запустите его на своём проекте. Это расскажет вам больше, чем всё, что я могу сказать.

Предыдущие посты：

Поделиться