DESIGN.md в 2026: как описать дизайн‑систему для AI‑агентов

Актуально на 21 августа 2026 года. В апреле 2026 Google Labs опубликовала открытую спецификацию DESIGN.md для описания визуальной системы coding agents. Текущая версия CLI — 0.4.0 от 27 июля 2026, а сам формат всё ещё имеет статус alpha. Это формальная спецификация, но не W3C Standard и не универсально загружаемый файл инструкций.

Проблема не в «памяти», а в источниках

Фраза «каждая AI-сессия начинается с нуля» уже неточна. Claude Code умеет загружать CLAUDE.md и вести auto memory; Cursor применяет project rules и AGENTS.md. Но память и инструкции остаются контекстом, а не enforced-конфигурацией.

Главная проблема другая: агенту часто дают макет и репозиторий, но не объясняют, что является источником правды. Тогда он выбирает правдоподобный HEX, создаёт новый компонент вместо существующего или копирует значение из устаревшей документации.

Задача agent-facing документации — не переписать всю дизайн-систему в Markdown, а дать короткую карту:

• где лежат токены и как они собираются;
• какие компоненты разрешено использовать;
• где смотреть API, примеры и состояния;
• что нельзя хардкодить;
• какие проверки подтверждают результат.

Что такое DESIGN.md в 2026 году

Google Labs DESIGN.md объединяет два слоя:

• YAML frontmatter с нормативными machine-readable tokens;
• Markdown с объяснением визуального намерения, правил применения и допустимых исключений.

---
version: alpha
name: Product UI
colors:
  text: "#212223"
  background: "#fdfdfc"
spacing:
  sm: 8px
  md: 16px
---

## Overview
Спокойный продуктовый интерфейс с высокой плотностью данных.

## Do's and Don'ts
- Используй semantic colors
- Не добавляй декоративные gradients в рабочих сценариях

CLI @google/design.md умеет валидировать структуру, сравнивать версии, выводить спецификацию и экспортировать tokens, в том числе в DTCG и Tailwind-форматы. Поскольку schema и CLI активно развиваются, фиксируйте версию пакета и ожидайте breaking changes.

Само наличие DESIGN.md не означает, что Cursor, Claude Code или другой агент автоматически его прочитает. Добавьте явную ссылку в поддерживаемый entrypoint: AGENTS.md, CLAUDE.md или .cursor/rules/*.mdc.

Четыре слоя вместо одного большого файла

1. Машиночитаемый источник правды

Токены должны жить в структурированном формате, из которого генерируются платформенные артефакты. В октябре 2025 года Design Tokens Community Group выпустила первую стабильную спецификацию DTCG 2025.10. Она описывает exchange format, типы значений, aliases, groups и resolver.

Это стабильный Community Group Report, пригодный для production, но не W3C Standard и не часть Standards Track. Поддержка конкретным инструментом всё равно требует проверки.

{
  "color": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.13, 0.13, 0.14],
          "alpha": 1
        }
      }
    }
  }
}

Markdown не должен дублировать все значения из этого файла. Иначе появляются два источника правды, которые неизбежно расходятся.

2. DESIGN.md с визуальным намерением

Используйте DESIGN.md для нормативных visual tokens и короткого rationale: характер продукта, принципы композиции, типографики, цвета и ключевые do's and don'ts. Не превращайте его в копию всей component documentation.

3. Документация компонентов и паттернов

Названия токенов не объясняют намерение. Нужны правила использования: когда применять semantic token, какие состояния обязательны, когда выбрать Dialog вместо inline message, как ведёт себя компонент на узком экране.

Эта документация может жить в Storybook, документационном сайте, комментариях к компонентам или отдельных Markdown-файлах. Важно, чтобы agent entrypoint ссылался на актуальные разделы, а не копировал их целиком.

4. Инструкции конкретного агента

Для Cursor используйте:

• AGENTS.md — простой plain-Markdown в корне или поддиректориях;
• .cursor/rules/*.mdc — правила с description, globs и режимом применения.

Обычный файл .cursor/rules/design-system.md игнорируется rules-системой: нужен .mdc. Для Claude Code project instructions живут в ./CLAUDE.md или ./.claude/CLAUDE.md. Cursor CLI также читает корневые AGENTS.md и CLAUDE.md, но не стоит полагаться на случайное пересечение форматов — документируйте основной путь команды.

Минимальный AGENTS.md для UI

# Design system

## Sources of truth
- Tokens: packages/tokens/src/tokens.json
- Components: packages/ui/src
- Examples: apps/storybook
- Accessibility tests: packages/ui/tests/a11y

## Rules
- Reuse an existing component before creating a new one
- Use semantic tokens; do not add raw colors or spacing values
- Preserve keyboard navigation, focus states and ARIA semantics
- Do not copy generated CSS from Figma into production

## Validation
- pnpm lint
- pnpm test
- pnpm test:a11y
- pnpm build

Это карта репозитория и чёткие ограничения. Список из сотен HEX, размеров и вариантов здесь только ухудшит сигнал.

Когда нужны Cursor Project Rules

Если разные части monorepo используют разные системы, правило лучше ограничить glob-паттерном:

---
description: UI implementation rules for the web app
globs:
  - "apps/web/src/**/*.{ts,tsx,css}"
alwaysApply: false
---

- Import components from @company/ui
- Use semantic tokens from @company/tokens
- Check responsive states at 360, 768 and 1440 px
- Run pnpm --filter web test before handoff

Правило с узкой областью действия полезнее глобального манифеста: агент получает только релевантный контекст.

Описывать компоненты через решения, а не скриншоты

Для каждого сложного компонента документируйте не весь визуальный вид, а контракт:

• Назначение: какую задачу решает компонент.
• Когда не использовать: ближайшие альтернативы.
• API: props, slots/children, controlled state.
• Состояния: loading, empty, error, disabled, focus.
• Контент: ограничения длины, локализация, формат чисел и дат.
• Accessibility: role, name, keyboard interaction, focus management.
• Responsive: что меняется, а что остаётся инвариантом.

## Dialog

Use for a short blocking decision or focused task.
Do not use for long multi-step forms; use a page or drawer.

Required:
- accessible name
- focus moves inside on open
- Escape closes when dismissal is allowed
- focus returns to the trigger

Composition:
- DialogHeader
- DialogBody
- DialogFooter

Figma и Code Connect

Figma MCP передаёт агенту структуру дизайна, переменные и компоненты. Code Connect добавляет курируемую связь с реальной реализацией. Это полезнее, чем вручную перечислять в Markdown каждый prop.

Но связь не заменяет документацию. Code Connect отвечает «какой компонент использовать и как выглядит его кодовый пример». Правила должны отвечать «когда этот компонент уместен» и «как проверить результат».

С 17 августа 2026 Figma больше не обновляет framework-specific parsers Code Connect. Для новых mappings используйте framework-agnostic template files .figma.ts; старые parser-based integrations стоит мигрировать командой npx figma connect migrate.

Проверки важнее обещаний

Инструкции помогают агенту принять правильное решение, но не гарантируют соблюдение. Проверяйте то, что можно проверить автоматически:

• линтер на запрещённые raw values и импорты;
• type-check публичного API компонентов;
• unit и interaction tests;
• accessibility checks;
• visual regression на ключевых состояниях;
• сборку token outputs из единого source-файла;
• проверку broken links и устаревших snippets в документации.

Универсального «аудит-скрипта», который автоматически подберёт правильный токен для любого hardcoded значения, нет. Такие проверки зависят от структуры токенов и правил проекта. Не приравнивайте отсутствие regex-совпадений к качеству интерфейса.

Как не создать второй источник правды

1. Храните values в структурированном token source, желательно совместимом с DTCG.
2. Генерируйте CSS, iOS, Android и другие outputs автоматически.
3. Храните component API рядом с кодом и проверяйте его тестами.
4. В agent instructions оставляйте ссылки, ограничения и команды проверки.
5. Меняйте документацию и реализацию в одном pull request.
6. Удаляйте устаревшие правила: короткий актуальный контекст лучше длинного архива.

Что считать результатом

Хорошая agent-facing спецификация не обещает одинаковый результат в каждой сессии. Она делает отклонения заметными и дешёвыми: агент находит нужный компонент, использует semantic tokens, запускает проверки и оставляет reviewable diff.

DESIGN.md — полезная открытая alpha-спецификация для visual context, но не замена DTCG, component documentation или agent-specific rules. Инфраструктура начинается там, где назначен источник правды, явно связаны форматы и работает автоматическая проверка.

Источники

• Google Labs: DESIGN.md
• Google Labs: спецификация DESIGN.md
• Cursor: Rules и AGENTS.md
• Anthropic: CLAUDE.md и auto memory
• DTCG Technical Reports 2025.10
• DTCG FAQ: статус спецификации
• Figma: Code Connect
• Figma: миграция Code Connect на template files