---
title: DESIGN.md
description: "Универсальный контракт дизайна для AI-ассистентов: структура DESIGN.md, design tokens, quality gates и адаптация под WordPress, JAM Stack и другие стеки."
---

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

DESIGN.md - это текстовая спецификация дизайн-контракта для AI-ассистентов и команды: токены (цвета, типографика, отступы, радиусы), правила применения (Do/Don't), поведение компонентов и ограничения адаптива.

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

- DESIGN.md = source of truth для дизайн-решений и UI-правил.
- Платформенный конфиг = слой исполнения (например, `theme.json`, CSS variables, Tailwind theme, UI-kit токены).
- Компонентный слой = конкретная реализация (блоки WordPress, React/Vue-компоненты, Laravel/Filament интерфейсы).

Такой подход снижает риск, когда ассистент генерирует визуально аккуратные, но несогласованные между собой экраны.

## Где DESIGN.md полезен

- **WordPress/WooCommerce** - связка с `theme.json`, block themes, шаблонами и паттернами.
- **JAM Stack** - синхронизация с Tailwind CSS variables и компонентными библиотеками.
- **Laravel/TALL и сервисные интерфейсы** - единые токены и правила для кабинетных UI.
- **Гибридные стеки** - единый контракт для нескольких фронтендов и дизайн-команд.

## Design as Code как upstream-слой

Design as Code — это подход, где дизайн-решения хранятся как версионируемые артефакты (обычно JSON tokens), а затем автоматически преобразуются в платформенные форматы: CSS variables, Swift/Kotlin токены, документацию и тестовые артефакты.

Короткая цепочка:

1. Дизайн-решение фиксируется в токенах.
2. Токены валидируются в CI.
3. Трансформер собирает артефакты под платформы.
4. Команды используют единый source of truth.

### Три слоя design tokens

1. Option tokens (primitive) — базовые значения без бизнес-семантики.
2. Decision tokens (semantic) — смысловой слой применения.
3. Component tokens — токены конкретных компонентов.

Пример слоев и ссылок между токенами:

```json
{
  "color": {
    "options": {
      "blue-900": "#0D47A1",
      "gray-900": "#1F2937"
    },
    "decisions": {
      "accent": "{color.options.blue-900}",
      "text-primary": "{color.options.gray-900}"
    }
  },
  "button": {
    "primary": {
      "background": "{color.decisions.accent}",
      "text": "#FFFFFF",
      "radius": "10px"
    }
  }
}
```

### Public и private токены

- Для продуктовой команды обычно публикуют semantic-слой (`decisions`).
- Primitive-слой можно держать внутренним, чтобы менять implementation details без массовых правок консьюмеров.

### Минимальный token-pipeline

1. Дизайнер задает токены в Figma/дизайн-инструменте.
2. Токены синхронизируются с Git.
3. CI валидирует схему и ссылки токенов.
4. Трансформер (например, Style Dictionary) генерирует web/mobile артефакты.
5. Артефакты попадают в тему, приложения и документацию.

### Когда полный pipeline оправдан

Подход обычно окупается, когда одновременно есть:

- несколько платформ (web/mobile/admin);
- несколько тем (light/dark/white-label);
- несколько продуктовых команд;
- высокая частота визуальных изменений.

Для одного лендинга на одной платформе полный token-pipeline может быть избыточным.

## Минимальная структура DESIGN.md

Практически полезный файл обычно содержит:

1. YAML front matter с токенами.
2. Секции с правилами применения: цвета, типографика, компоненты, layout, ограничения.

### Двухслойная модель: "что" и "почему"

- `YAML front matter` — машинный слой: точные токены (цвета, размеры, типографика, ссылки между токенами).
- `Markdown body` — контекстный слой: правила применения, Do/Don't, состояния компонентов, ограничения и анти-паттерны.

Такое разделение снижает вариативность AI-генерации: значения фиксируются в токенах, а суждения ограничиваются явными правилами.

Ниже в markdown-части добавляйте:

- правила использования primary/accent (где можно и где нельзя);
- требования контраста (WCAG 2.2 AA);
- ограничения для отступов/радиусов (не использовать произвольные значения);
- явные антипаттерны (например, не более одной primary-кнопки в одном hero-блоке).

Пример минимального DESIGN.md:

```md
---
name: Product Design Contract - DESIGN.md
description: Creates implementation-ready design-system guidance with tokens, component behavior, and accessibility standards.
colors:
	primary: "#2563EB"
	secondary: "#14B8A6"
	surface: "#FFFFFF"
	background: "#F8FAFC"
	text: "#0F172A"
	success: "#16A34A"
	warning: "#D97706"
	error: "#DC2626"
spacing:
	xs: 4px
	sm: 8px
	md: 16px
	lg: 24px
rounded:
	sm: 6px
	md: 10px
typography:
	h1:
    fontFamily: Manrope
		fontSize: 2.25rem
		fontWeight: 700
	body:
    fontFamily: Manrope
		fontSize: 1rem
		fontWeight: 400
---

# Product Design Contract - DESIGN.md

## Mission

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

## Brand

- Product/brand: Example Product
- Audience: продуктовые команды, маркетинг и разработка
- Product surface: marketing site + app + docs

## Style Foundations

- Visual style: clean, editorial, calm contrast
- Typography scale: h1/body из front matter
- Color palette: semantic tokens из colors (primary/surface/text/success/warning/error)
- Spacing scale: xs/sm/md/lg
- Radius/shadow/motion tokens: rounded.sm, rounded.md

## Accessibility

- Target: WCAG 2.2 AA
- Keyboard-first interactions required
- Focus-visible rules required
- Contrast constraints required

## Writing Tone

concise, confident, implementation-focused

## Rules: Do

- Use semantic tokens, not raw hex values in component guidance.
- Define all required states: default, hover, focus-visible, active, disabled, loading, error.
- Specify responsive behavior and edge-case handling.

## Rules: Don't

- Do not allow low-contrast text or hidden focus indicators.
- Do not introduce one-off spacing or typography exceptions.
- Do not use ambiguous labels or non-descriptive actions.

## Guideline Authoring Workflow

1. Restate design intent in one sentence.
2. Define foundations and tokens.
3. Define component anatomy, variants, and interactions.
4. Add accessibility acceptance criteria.
5. Add anti-patterns and migration notes.
6. End with QA checklist.

## Required Output Structure

- Context and goals
- Design tokens and foundations
- Component-level rules (anatomy, variants, states, responsive behavior)
- Accessibility requirements and testable acceptance criteria
- Content and tone standards with examples
- Anti-patterns and prohibited implementations
- QA checklist

## Component Rule Expectations

- Include keyboard, pointer, and touch behavior.
- Include spacing and typography token requirements.
- Include long-content, overflow, and empty-state handling.

## Quality Gates

- Every non-negotiable rule uses "must".
- Every recommendation uses "should".
- Every accessibility rule is testable in implementation.
- Prefer system consistency over local visual exceptions.
```

## Маппинг DESIGN.md в платформенные слои

Одна и та же семантика должна сохраняться при переносе в разные платформы:

| Семантика       | DESIGN.md        | WordPress (`theme.json`)               | JAM Stack (`Tailwind/CSS vars`) | Laravel/TALL (`UI tokens`)    |
| --------------- | ---------------- | -------------------------------------- | ------------------------------- | ----------------------------- |
| Основной цвет   | `colors.primary` | `settings.color.palette.primary`       | `@theme --color-primary`        | `primaryColor` / css variable |
| Цвет текста     | `colors.text`    | `styles.color.text`                    | `--color-base-content`          | `textColor`                   |
| Фон поверхности | `colors.surface` | `styles.color.background`              | `--color-surface`               | `surfaceColor`                |
| Радиусы         | `rounded.*`      | `styles.elements.button.border.radius` | `--radius-*`                    | `radius` scale                |
| Отступы         | `spacing.*`      | `settings.spacing.spacingSizes`        | `--spacing-*`                   | spacing scale                 |

Ключевая идея: semantic first. Не используйте технические имена вроде `blue-500` как бизнес-смысл; храните роли (`primary`, `surface`, `success`, `error`).

## Пример адаптера для WordPress (`theme.json`)

```json
{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "name": "Primary", "color": "#2563EB" },
        { "slug": "surface", "name": "Surface", "color": "#FFFFFF" },
        { "slug": "contrast", "name": "Contrast", "color": "#0F172A" },
        { "slug": "success", "name": "Success", "color": "#16A34A" },
        { "slug": "warning", "name": "Warning", "color": "#D97706" },
        { "slug": "error", "name": "Error", "color": "#DC2626" }
      ]
    },
    "spacing": {
      "spacingSizes": [
        { "slug": "xs", "name": "XS", "size": "4px" },
        { "slug": "sm", "name": "SM", "size": "8px" },
        { "slug": "md", "name": "MD", "size": "16px" },
        { "slug": "lg", "name": "LG", "size": "24px" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--surface)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "elements": {
      "button": {
        "border": { "radius": "10px" },
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "#FFFFFF"
        }
      }
    }
  }
}
```

## Пример адаптера для JAM Stack (`Tailwind` + `daisyUI`)

```css
@import "tailwindcss" source(none);
@source "./templates/**/*.{html,php}";
@source "./parts/**/*.{html,php}";
@source "./blocks/**/*.{php,html}";

@theme {
  --color-primary: #2563eb;
  --color-success: #16a34a;
  --color-warning: #d97706;
  --color-error: #dc2626;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --radius-md: 10px;
}

@plugin "daisyui" {
  themes: corporate --default;
}

@plugin "daisyui/theme" {
  name: "corporate";
  default: true;
  --color-primary: #2563eb;
  --color-success: #16a34a;
  --color-warning: #d97706;
  --color-error: #dc2626;
  --radius-selector: 0.625rem;
  --radius-field: 0.625rem;
  --radius-box: 0.75rem;
}
```

## Пример подключения стилей в WordPress-теме

```php
add_action('wp_enqueue_scripts', function () {
		wp_enqueue_style(
				'theme-tw',
				get_theme_file_uri('tw.css'),
				[],
				filemtime(get_theme_file_path('tw.css'))
		);
});
```

Этот вариант гарантирует cache busting по времени изменения файла и одинаковые стили после деплоя.

## Практический workflow для команды

1. Обновляете DESIGN.md (токены + правила).
2. Экспортируете/синхронизируете токены в платформенные конфиги (`theme.json`, CSS vars, Tailwind theme, UI-kit config).
3. Обновляете компонентные слои (блоки, React/Vue-компоненты, админ-интерфейсы).
4. Проверяете соответствие контракту: контраст, состояния, адаптив, фокус, пустые/ошибочные состояния.
5. Коммитите контракт и реализацию одним набором, чтобы исключить рассинхрон.

## CLI-проверки и экспорт

Если в проекте используется экосистема `@google/design.md`, полезно встроить в pipeline проверки и экспорт:

```bash
# Линт токенов/ссылок и базовых правил качества
npx @google/design.md lint DESIGN.md

# Сравнение двух версий спецификации
npx @google/design.md diff DESIGN-v1.md DESIGN-v2.md

# Экспорт токенов в Tailwind-формат
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

# Экспорт в DTCG-совместимый формат
npx @google/design.md export --format dtcg DESIGN.md
```

Для любого стека это удобно как pre-build шаг: сначала проверка `DESIGN.md`, затем обновление платформенных конфигов и компонентов.

## Минимальный старт внедрения

1. Положите `DESIGN.md` в корень репозитория рядом с `AGENTS.md`/`CLAUDE.md`.
2. Добавьте в агентные инструкции правило: использовать `DESIGN.md` для всех style-решений.
3. Перенесите ключевые токены в `theme.json` и Tailwind theme variables.
4. На ревью проверяйте не только визуал, но и соответствие токенам/Do-Don't правилам.

## Где DESIGN.md не заменяет платформенные механизмы

- DESIGN.md не заменяет `theme.json`, Tailwind config, локальные UI-kit и runtime-настройки, а дополняет их.
- Design as Code (token-pipeline) обычно лежит уровнем выше: DESIGN.md выступает AI-ориентированным слоем поверх токенов и правил.
- DESIGN.md не решает платформенно-специфичные задачи: например, WP-шаблоны и template parts, Next.js routing, Filament resources.
- Для строгого контроля нужны тесты и линтинг, а не только текстовая спецификация.
- DESIGN.md не равен полной дизайн-системе: это рабочий subset, ориентированный на воспроизводимую генерацию интерфейсов.


## Поддержка формата и примеры

В экосистеме, описанной источником, Google Stitch и Claude Design могут создавать или экспортировать дизайн-описания, а Claude Code, Cursor и Windsurf — читать файл из проекта. Поддержка конкретных функций зависит от продукта и меняется со временем, поэтому перед внедрением сверяйтесь с документацией поставщика.

Для отправной точки можно изучить коллекцию [awesome-design-md](https://github.com/VoltAgent/awesome-design-md), каталог [designmd.ai](https://designmd.ai) и готовые дизайн-скиллы [TypeUI](https://typeui.sh/). Примеры стоит адаптировать под аудиторию, бренд, стек и требования доступности проекта.

## Связанные страницы

- [AGENTS.md и контекст-файлы для AI](https://wpcraft.ru/kb/ai/agents/agent-teams.md)
- [Tailwind CSS и daisyUI в блочной теме WordPress](https://wpcraft.ru/kb/stacks/wordpress/themes/practices/tailwind-daisyui-wordpress.md)
- [Impeccable: AI-дизайн для WordPress](https://wpcraft.ru/kb/design/ai/impeccable.md) — open-source навык для AI-ассистентов, умеет генерировать DESIGN.md через `/impeccable document`.
- [Дизайн-системы в WordPress](https://wpcraft.ru/kb/stacks/wordpress/themes/design-systems.md)
- [theme.json — основа дизайн-системы WordPress и WooCommerce](https://wpcraft.ru/kb/stacks/wordpress/themes/practices/theme-json.md)
- [Figma → WordPress: мост через Design Tokens](https://wpcraft.ru/kb/stacks/wordpress/themes/practices/figma-to-wordpress.md)
- [Настройки темы: цвета, шрифты, типографика, макет](https://wpcraft.ru/kb/stacks/wordpress/themes/practices/theme-settings.md)
- [Кастомный CSS в WordPress](https://wpcraft.ru/kb/stacks/wordpress/faq/custom-css.md)

## Материалы и источники

- [google-labs-code/design.md](https://github.com/google-labs-code/design.md)
- [Google Stitch: DESIGN.md overview](https://stitch.withgoogle.com/docs/design-md/overview)
- [DESIGN.md — формат дизайн-систем для AI-агентов](https://ddpa.ru/kb/ai/design/design-md/)
- [Design as Code — дизайн-токены и архитектура](https://ddpa.ru/kb/ai/design/design-as-code/)
- [Tailwind CSS theme variables](https://tailwindcss.com/docs/theme)
- [daisyUI themes](https://daisyui.com/docs/themes/)
- [WordPress: Introduction to theme.json](https://developer.wordpress.org/themes/global-settings-and-styles/introduction-to-theme-json/)
- [WordPress: theme.json settings](https://developer.wordpress.org/themes/global-settings-and-styles/settings/)
- [WordPress: theme.json styles](https://developer.wordpress.org/themes/global-settings-and-styles/styles/)
- [WordPress: custom templates, template parts, patterns, style variations](https://developer.wordpress.org/themes/global-settings-and-styles/custom-templates/)