Примечания для передачи дизайна в разработку — В первую очередь для ИИ, понятно человеку

# Примечания для передачи дизайна в разработку — В первую очередь для ИИ, понятно человеку

### Структурированный документ для передачи в разработку, оптимизированный для ИИ-агентов реализации (Claude Code, Cursor, Copilot) и при этом понятный разработчикам-людям

---

## Об этом промпте

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

**Основная философия:** Если ИИ читает этот документ и вынужден о чём-то догадываться, документ не выполнил свою задачу.

**Когда использовать:** После завершения дизайна, до начала реализации. Это заменяет передачу через Figma, PDF со спецификациями дизайна и обсуждения в духе «просто сделай как на макете».

**Кто это читает:**
- В первую очередь: ИИ-агенты программирования (Claude Code, Cursor, Copilot и т. д.)
- Во вторую очередь: разработчики-люди, проверяющие или отлаживающие результат работы ИИ
- В третью очередь: ты (дизайнер), когда проверяешь соответствие реализации замыслу

**Связь с CLAUDE.md:** Этот документ предполагает, что файл дизайн-системы CLAUDE.md уже существует в корне проекта. Примечания для передачи в разработку ссылаются на токены из CLAUDE.md, но не определяют их заново. Если CLAUDE.md отсутствует, сначала запусти промпты извлечения дизайн-системы.

---

## Промпт

```
Ты — инженер по дизайн-системам, пишущий спецификации для реализации.
Твой результат будут читать прежде всего ИИ-агенты программирования (Claude Code, Cursor),
а во вторую очередь — разработчики-люди.

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

Каждое значение должно быть задано явно. Каждое состояние должно быть определено. Для каждого пограничного случая
должно быть правило. Никаких «по ситуации», «примерно» или «похоже на».

## Контекст проекта
- **Проект:** ${name}
- **Фреймворк:** [Next.js 14+ / React / и т. д.]
- **Стилизация:** [Tailwind 3.x / CSS Modules / и т. д.]
- **Библиотека компонентов:** [shadcn/ui / собственная / и т. д.]
- **Расположение CLAUDE.md:** [путь — или «ещё не создан»]
- **Источник дизайна:** [загруженный код / рабочий URL / скриншоты]
- **Страницы для спецификации:** [все / конкретные страницы]

## Правила формата вывода

Прежде чем писать какие-либо спецификации, точно соблюдай эти правила оформления:

1. **Значения всегда готовы к использованию в коде.**
   НЕПРАВИЛЬНО: «средний отступ»
   ПРАВИЛЬНО: `p-6` (24px)

2. **Цвета всегда задаются ссылками на токены + резервным значением hex.**
   НЕПРАВИЛЬНО: «фирменный синий»
   ПРАВИЛЬНО: `text-brand-500` (#2563EB) — из токенов CLAUDE.md

3. **Размеры всегда задаются в системе единиц проекта.**
   Для Tailwind: основными делай классы Tailwind, а px указывай в пояснении
   Для CSS: основной единицей делай rem, а px указывай в пояснении
   НЕПРАВИЛЬНО: «сделай крупнее на настольных компьютерах»
   ПРАВИЛЬНО: `text-lg` (18px) при ≥768px, `text-base` (16px) при меньшей ширине

4. **Условия используют явное if/else, а не «по необходимости».**
   НЕПРАВИЛЬНО: «показывай состояние загрузки, когда уместно»
   ПРАВИЛЬНО: «если получение данных занимает >300ms, показывай скелетон. Если запрос завершился неудачно, показывай состояние ошибки. Если данные вернулись пустым массивом, показывай пустое состояние».

5. **Пути к файлам указываются явно.**
   НЕПРАВИЛЬНО: «создай компонент кнопки»
   ПРАВИЛЬНО: «создай `src/components/ui/Button.tsx`»

6. **Каждое визуальное свойство указывается явно, а не считается унаследованным по умолчанию.**
   Даже если оно «очевидно» — укажи его. У ИИ-агентов нет визуального контекста.

---

## Структура документа

Сформируй документ передачи в разработку со следующими разделами:

### РАЗДЕЛ 1: КАРТА РЕАЛИЗАЦИИ

Таблица всего, что нужно создать, в порядке приоритета.
ИИ-агенты должны выполнять реализацию в этом порядке, чтобы корректно разрешать зависимости.

| Порядок | Компонент/секция | Путь к файлу | Зависимости | Сложность | Примечания |
|-------|------------------|-----------|-------------|-----------|-------|
| 1 | Настройка дизайн-токенов | `tailwind.config.ts` | Нет | Низкая | Обязательно сначала — все остальные компоненты ссылаются на них |
| 2 | Типографические компоненты | `src/components/ui/Text.tsx` | Токены | Низкая | Варианты Heading, Body, Caption, Label |
| 3 | Button | `src/components/ui/Button.tsx` | Токены, типографика | Средняя | 3 варианта × 3 размера × 6 состояний |
| ... | ... | ... | ... | ... | ... |

Правила:
- Ничто не может ссылаться на компонент, который расположен в таблице позже
- Сложность = количество вариантов × состояний компонента
- Примечания = всё неочевидное в реализации

---

### РАЗДЕЛ 2: ГЛОБАЛЬНЫЕ СПЕЦИФИКАЦИИ

Они действуют везде. ИИ-агент должен настроить их ДО создания любых компонентов.

#### 2.1 Контрольные точки
Определи точные границы поведения:

```
BREAKPOINTS {
  mobile:  0px    — 767px
  tablet:  768px  — 1023px
  desktop: 1024px — 1279px
  wide:    1280px — ∞
}
```

Для каждой контрольной точки укажи:
- Максимальную ширину контейнера и внутренние отступы
- Базовый размер шрифта
- Глобальный множитель отступов (если он меняется)
- Режим навигации (гамбургер / горизонтальная / и т. д.)

#### 2.2 Переходы по умолчанию
```
TRANSITIONS {
  default:    duration-200 ease-out
  slow:       duration-300 ease-in-out
  spring:     duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)
  none:       duration-0
}

RULE: Каждый интерактивный элемент использует `default`, если
      этот документ не предписывает иное.
RULE: Переходы применяются к: background-color, color, border-color,
      opacity, transform, box-shadow. Никогда к: width, height, padding,
      margin (они вызывают пересчёт компоновки).
```

#### 2.3 Шкала z-index
```
Z-INDEX {
  base:       0
  dropdown:   10
  sticky:     20
  overlay:    30
  modal:      40
  toast:      50
  tooltip:    60
}

RULE: Никаких значений z-index за пределами этой шкалы. Никогда.
```

#### 2.4 Стиль фокуса
```
FOCUS {
  style:      ring-2 ring-offset-2 ring-brand-500
  applies-to: каждый интерактивный элемент (кнопки, ссылки, поля ввода, списки выбора, флажки)
  visible:    только при навигации с клавиатуры (используй focus-visible, а не focus)
}
```

---

### РАЗДЕЛ 3: СПЕЦИФИКАЦИИ СТРАНИЦ

Для каждой страницы предоставь полную спецификацию реализации.

#### Страница: ${page_name}
**Маршрут:** `/exact-route-path`
**Макет:** ${which_layout_wrapper_to_use}
**Требования к данным:** [какие данные нужны странице и откуда]

##### Структура страницы (сверху вниз)

```
СТРУКТУРА СТРАНИЦЫ: ${page_name}
├── Секция: Hero
│   ├── Компонент: Heading (h1)
│   ├── Компонент: Subheading (p)
│   ├── Компонент: CTA Button (primary, lg)
│   └── Компонент: HeroImage
├── Секция: Features
│   ├── Компонент: SectionHeading (h2)
│   └── Компонент: FeatureCard × 3 (сетка)
├── Секция: Testimonials
│   └── Компонент: TestimonialSlider
└── Секция: CTA
    ├── Компонент: Heading (h2)
    └── Компонент: CTA Button (primary, lg)
```

##### Спецификации по секциям

Для каждой секции:

**${section_name}**

```
LAYOUT {
  container:    max-w-[1280px] mx-auto px-6 (mobile: px-4)
  direction:    flex-col (mobile) → flex-row (desktop)
  gap:          gap-8 (32px)
  padding:      py-16 (64px) (mobile: py-10)
  background:   bg-white
}

CONTENT {
  heading {
    text:       "${exact_heading_text_or_content_source}"
    element:    h2
    class:      text-3xl font-bold text-gray-900 (mobile: text-2xl)
    max-width:  max-w-[640px]
  }
  body {
    text:       "${exact_body_text_or_content_source}"
    class:      text-lg text-gray-600 leading-relaxed (mobile: text-base)
    max-width:  max-w-[540px]
  }
}

GRID (если применимо) {
  columns:      grid-cols-3 (tablet: grid-cols-2) (mobile: grid-cols-1)
  gap:          gap-6 (24px)
  items:        ${what_component_renders_in_each_cell}
  alignment:    items-start
}

ANIMATION (если применимо) {
  type:         fade-up при прокрутке
  trigger:      когда секция входит в область просмотра (threshold: 0.2)
  stagger:      каждый дочерний элемент задерживается на 100ms относительно предыдущего
  duration:     duration-500
  easing:       ease-out
  runs:         один раз (не запускать повторно при прокрутке вверх)
}
```

---

### РАЗДЕЛ 4: СПЕЦИФИКАЦИИ КОМПОНЕНТОВ

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

#### Компонент: ${componentname}
**Файл:** `src/components/${path}/${componentname}.tsx`
**Назначение:** [одно предложение — что делает этот компонент]

##### Интерфейс props
```typescript
interface ${componentname}Props {
  variant: 'primary' | 'secondary' | 'ghost'     // visual style
  size: 'sm' | 'md' | 'lg'                        // dimensions
  disabled?: boolean                                // default: false
  loading?: boolean                                 // default: false
  icon?: React.ReactNode                           // optional leading icon
  children: React.ReactNode                         // label content
  onClick?: () => void                              // click handler
}
```

##### Матрица вариантов × размеров
Определи точные значения для каждого сочетания:

```
VARIANT: primary
  SIZE: sm
    height:           h-8 (32px)
    padding:          px-3 (12px)
    font:             text-sm font-medium (14px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-md (6px)
    shadow:           none

  SIZE: md
    height:           h-10 (40px)
    padding:          px-4 (16px)
    font:             text-sm font-medium (14px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-lg (8px)
    shadow:           shadow-sm

  SIZE: lg
    height:           h-12 (48px)
    padding:          px-6 (24px)
    font:             text-base font-semibold (16px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-lg (8px)
    shadow:           shadow-sm

VARIANT: secondary
  [та же структура, другие значения]

VARIANT: ghost
  [та же структура, другие значения]
```

##### Спецификации состояний
Каждое состояние должно быть определено для каждого варианта:

```
STATES (применяются ко ВСЕМ вариантам, если не переопределены):

  hover {
    background:     ${token} — на одну ступень темнее значения по умолчанию
    transform:      none (никаких scale/translate при наведении)
    shadow:         ${token_or_none}
    cursor:         pointer
    transition:     default (duration-200 ease-out)
  }

  active {
    background:     ${token} — на две ступени темнее значения по умолчанию
    transform:      scale-[0.98]
    transition:     duration-75
  }

  focus-visible {
    ring:           ring-2 ring-offset-2 ring-brand-500
    all other:      как в состоянии по умолчанию
  }

  disabled {
    opacity:        opacity-50
    cursor:         not-allowed
    pointer-events: none
    ALL hover/active/focus states: не применяются
  }

  loading {
    content:        заменить children индикатором загрузки (16px, animate-spin)
    width:          сохранить ту же ширину, что и вне состояния загрузки (предотвратить сдвиг компоновки)
    pointer-events: none
    opacity:        opacity-80
  }
```

##### Поведение иконки
```
ICON RULES {
  position:       слева от текста подписи (всегда)
  size:           16px (sm), 16px (md), 20px (lg)
  gap:            gap-1.5 (sm), gap-2 (md), gap-2 (lg)
  color:          наследует цвет текста (currentColor)
  when loading:   иконка скрыта, её место занимает индикатор загрузки
  icon-only:      если children отсутствует, компонент становится квадратным (width = height)
                  добавить обязательный prop aria-label
}
```

---

### РАЗДЕЛ 5: СЦЕНАРИИ ВЗАИМОДЕЙСТВИЯ

Для каждого пользовательского сценария предоставь пошаговую реализацию:

#### Сценарий: [Название сценария, например «Пользователь регистрируется»]
```
TRIGGER:     пользователь нажимает кнопку «Зарегистрироваться» в шапке

STEP 1:      Открывается модальное окно
             animation:   fade-in (opacity 0→1, duration-200)
             backdrop:    bg-black/50, нажатие снаружи закрывает модальное окно
             focus:       удерживать фокус внутри окна, автоматически фокусировать первое поле ввода
             body:        scroll-lock (предотвратить прокрутку фона)

STEP 2:      Пользователь заполняет форму
             fields:      ${list_exact_fields_with_validation_rules}
             validation:  при blur (не при change — это уменьшает шум)
             
             field: email {
               type:       email
               required:   true
               validate:   регулярное выражение + «должно содержать @ и домен»
               error:      «Это не похоже на адрес электронной почты — проверьте опечатки»
               success:    появляется зелёная иконка галочки (fade-in, duration-150)
             }
             
             field: password {
               type:       password (с переключателем показать/скрыть)
               required:   true
               validate:   минимум 8 символов, 1 заглавная буква, 1 цифра
               error:      показывать список требований, выделять невыполненные
               strength:   показывать шкалу надёжности (слабый/средний/сильный)
             }

STEP 3:      Пользователь отправляет форму
             button:      показывает состояние загрузки (см. спецификацию компонента Button)
             request:     POST /api/auth/signup
             duration:    ожидается 1–3 секунды

STEP 4a:     Успех
             modal:       содержимое сменяется сообщением об успехе (crossfade, duration-200)
             message:     «Аккаунт создан! Проверьте почту для подтверждения».
             action:      кнопка «Понятно» закрывает модальное окно
             redirect:    после закрытия перенаправить на /dashboard
             toast:       none (модальное окно И ЕСТЬ подтверждение)

STEP 4b:     Ошибка — адрес электронной почты уже существует
             field:       поле email показывает состояние ошибки
             message:     «Для этого адреса уже есть аккаунт — хотите вместо этого войти?»
             action:      ссылка «Войти» переключает модальное окно на форму входа
             button:      возвращается в состояние по умолчанию (не загрузка)

STEP 4c:     Ошибка — сетевой сбой
             display:     баннер ошибки вверху модального окна (не всплывающее уведомление)
             message:     «С нашей стороны что-то пошло не так. Попробовать ещё раз?»
             action:      кнопка «Попробовать ещё раз» повторно отправляет форму
             button:      возвращается в состояние по умолчанию

STEP 4d:     Ошибка — ограничение частоты запросов
             display:     баннер ошибки
             message:     «Слишком много попыток. Подождите 60 секунд и попробуйте снова».
             button:      отключена на 60 секунд с видимым обратным отсчётом
```

---

### РАЗДЕЛ 6: ПРАВИЛА АДАПТИВНОГО ПОВЕДЕНИЯ

Не описывай, что меняется, — укажи точные правила:

```
ПРАВИЛА АДАПТИВНОСТИ:

Правило 1: Навигация
  ≥1024px:    горизонтальная навигация, все пункты видимы
  <1024px:    иконка гамбургера, выдвижная панель справа
              drawer-width: 80vw (max-w-[320px])
              animation: translate-x (duration-300 ease-out)
              backdrop: bg-black/50, нажатие снаружи закрывает

Правило 2: Секции с сеткой
  ≥1024px:    grid-cols-3
  768-1023px: grid-cols-2 (последний элемент занимает всю ширину при нечётном количестве)
  <768px:     grid-cols-1

Правило 3: Главная секция Hero
  ≥1024px:    две колонки (текст слева, изображение справа) — соотношение 55/45
  <1024px:    одна колонка (текст сверху, изображение снизу)
              image max-height: 400px, object-cover

Правило 4: Масштабирование типографики
  ≥1024px:    h1=text-5xl, h2=text-3xl, h3=text-xl, body=text-base
  <1024px:    h1=text-3xl, h2=text-2xl, h3=text-lg, body=text-base

Правило 5: Масштабирование отступов
  ≥1024px:    section-padding: py-16, container-padding: px-8
  768-1023px: section-padding: py-12, container-padding: px-6
  <768px:     section-padding: py-10, container-padding: px-4

Правило 6: Области касания
  <1024px:    у всех интерактивных элементов область попадания не менее 44×44px
              если визуальный размер < 44px, используй невидимые отступы, чтобы достичь 44px

Правило 7: Изображения
  all images: используй next/image с адаптивным prop sizes
  hero:       sizes="(max-width: 1024px) 100vw, 50vw"
  grid items: sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
```

---

### РАЗДЕЛ 7: ПОГРАНИЧНЫЕ СЛУЧАИ И ГРАНИЧНЫЕ УСЛОВИЯ

Этот раздел предотвращает проблемы вида «а что произойдёт, когда...»:

```
ПОГРАНИЧНЫЕ СЛУЧАИ:

Text Overflow {
  headings:     максимум 2 строки, затем обрезать с text-ellipsis (добавить атрибут title с полным текстом)
  body text:    разрешить естественный перенос, без обрезки
  button labels: только одна строка, максимум 30 символов, без обрезки (ограничение дизайна)
  nav items:    одна строка, обрезать при >16 символах на мобильных устройствах
  table cells:  обрезать с подсказкой при наведении
}

Empty States {
  lists/grids with 0 items: показывать компонент ${emptystate}
    - illustration: ${describe_or_reference_asset}
    - heading: "${exact_text}"
    - body: "${exact_text}"
    - CTA: "${exact_text}" → ${action}
  
  user avatar missing: показывать инициалы на цветном фоне
    - background: генерировать из хеша имени пользователя (детерминированно)
    - initials: первая буква имени + фамилии, в верхнем регистре
    - font: text-sm font-medium text-white
  
  image fails to load: показывать серую заглушку с иконкой изображения
    - background: bg-gray-100
    - icon: ImageOff из lucide-react, text-gray-400, 24px
}

Loading States {
  page load:      скелетон на всю страницу (не индикатор вращения)
  component load: скелетон на уровне компонента, совпадающий с итоговыми размерами
  button action:  встроенный индикатор вращения в кнопке (см. спецификацию Button)
  infinite list:  строка скелетона × 3 внизу, пока загружается следующая страница
  
  skeleton style: bg-gray-200 rounded animate-pulse
  skeleton rule:  форма скелетона должна совпадать с формой итогового содержимого
                  (прямоугольник для текста, круг для аватаров, rounded-lg для карточек)
}

Error States {
  API error (500):     показывать встроенный баннер ошибки с кнопкой повтора
  Network error:       показывать вверху баннер «Похоже, вы не в сети» (автоматически скрывать при восстановлении соединения)
  404 content:         показывать собственный компонент 404 (не стандартный Next.js)
  Permission denied:   перенаправлять на /login с параметром URL возврата
  Form validation:     непосредственно у каждого поля (см. спецификации сценариев), никогда не alert()
}

Data Extremes {
  username 1 character:   отображать обычным образом
  username 50 characters: обрезать до 20 в навигации, полностью показывать в профиле
  price $0.00:            показывать «Бесплатно»
  price $999,999.99:      убедиться, что компоновка не ломается (проверить с отформатированным числом)
  list with 1 item:       та же компоновка, что и для нескольких (без особого случая)
  list with 500 items:    разбить на страницы по 20, показывать кнопку «Загрузить ещё»
  date today:             показывать «Сегодня», а не дату
  date this year:         показывать "Mar 13", а не "Mar 13, 2026"
  date other year:        показывать "Mar 13, 2025"
}
```

---

### РАЗДЕЛ 8: ЧЕК-ЛИСТ ПРОВЕРКИ РЕАЛИЗАЦИИ

После реализации ИИ-агент (или разработчик-человек) должен проверить:

```
ПРОВЕРКА:

□ Каждый компонент точно соответствует матрице вариантов × размеров
□ Каждое состояние (hover, active, focus, disabled, loading) работает
□ Порядок перехода клавишей Tab соответствует визуальному порядку на всех страницах
□ Обводка focus-visible появляется при навигации с клавиатуры, а не при нажатии мышью
□ Все переходы используют указанную длительность и функцию изменения скорости (не значения браузера по умолчанию)
□ При загрузке страницы нет сдвигов компоновки (проверить CLS)
□ Размеры скелетонов совпадают с размерами итогового содержимого
□ Все пограничные случаи из раздела 7 обработаны
□ Области касания ≥ 44×44px на мобильных контрольных точках
□ Ни на одной контрольной точке нет горизонтальной прокрутки
□ Все изображения используют next/image с корректным prop sizes
□ Значения z-index используют только заданную шкалу
□ Состояния ошибок отображаются корректно (проверить с ограничением скорости сети)
□ Пустые состояния отображаются корректно (проверить с пустыми данными)
□ Обрезка текста работает при граничных длинах
□ Все токены тёмной темы (если применимо) сопоставлены
```

---

## Как ИИ-агент должен использовать этот документ

Включи эту инструкцию в начало создаваемого документа передачи в разработку,
чтобы реализующий ИИ знал, как с ним работать:

```
ИНСТРУКЦИИ ДЛЯ ИИ-АГЕНТА РЕАЛИЗАЦИИ:

1. Прочитай этот документ полностью, прежде чем писать какой-либо код.
2. Выполняй реализацию в порядке, указанном в РАЗДЕЛЕ 1 (Карта реализации).
3. Обращайся к CLAUDE.md за значениями токенов. Если токена, на который здесь есть ссылка,
   нет в CLAUDE.md, отметь это и используй предоставленное резервное значение.
4. Каждое значение в этом документе задано намеренно. Не заменяй его
   «достаточно близким». `gap-6` означает `gap-6`, а не `gap-5`.
5. Каждое состояние должно быть реализовано. Если состояние для
   компонента не указано, это пробел в спецификации — отметь его, не гадай.
6. После реализации каждого компонента пройди по его матрице состояний
   и проверь работоспособность всех состояний, прежде чем переходить к следующему компоненту.
7. Столкнувшись с неоднозначностью, предпочитай более явную интерпретацию.
   Если неоднозначность остаётся, добавь комментарий TODO: "// HANDOFF-AMBIGUITY: [описание]"
```
```

---

## Примечания по адаптации

**Если ты не используешь Tailwind:** Замени в промпте все ссылки на классы Tailwind эквивалентами из своей системы. Структура остаётся прежней — меняется только формат значений. Скажи Claude: «Используй пользовательские свойства CSS как основные, а значения в px — как пояснения».

**Если ты передаёшь задачу конкретному ИИ-инструменту:** Добавь примечания для этого инструмента. Например, для Cursor: «Генерируй реализацию как пошаговые изменения существующих файлов, а не полное переписывание файлов». Для Claude Code: «Создай каждый компонент целым файлом, протестируй его и затем переходи к следующему».

**Если CLAUDE.md ещё нет:** Попроси промпт сгенерировать в начале документа передачи в разработку минимальный раздел токенов, охватывающий только токены, необходимые для этой конкретной передачи. Это не будет полной дизайн-системой, но предотвратит жёстко заданные значения.

**Для многостраничных проектов:** Запускай промпт один раз для каждой страницы, но включай раздел 1 (Карта реализации) и раздел 2 (Глобальные спецификации) только при первом запуске. Последующие страницы ссылаются на те же глобальные настройки.