DESIGN.md

Что такое 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 токены, документацию и тестовые артефакты.

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

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

Три слоя design tokens

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

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

{
  "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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример минимального DESIGN.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`)

{
  "$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`)

@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-теме

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 для команды

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

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

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

# Линт токенов/ссылок и базовых правил качества
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, затем обновление платформенных конфигов и компонентов.

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

Положите DESIGN.md в корень репозитория рядом с AGENTS.md/CLAUDE.md.
Добавьте в агентные инструкции правило: использовать DESIGN.md для всех style-решений.
Перенесите ключевые токены в theme.json и Tailwind theme variables.
На ревью проверяйте не только визуал, но и соответствие токенам/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, ориентированный на воспроизводимую генерацию интерфейсов.

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

AGENTS.md и контекст-файлы для AI
Tailwind CSS и daisyUI в блочной теме WordPress
Impeccable: AI-дизайн для WordPress — open-source навык для AI-ассистентов, умеет генерировать DESIGN.md через /impeccable document.
Дизайн-системы в WordPress
theme.json — основа дизайн-системы WordPress и WooCommerce
Figma → WordPress: мост через Design Tokens
Настройки темы: цвета, шрифты, типографика, макет
Кастомный CSS в WordPress