# Design Book `marketing-light-5` — Tokens

Префикс CSS: `--ml5-*`
Тип: editorial AI-frontier-lab corporate (dual-voice serif+sans, warm earth palette)
Файл: [`tokens.css`](tokens.css)

## Философия

5 принципов, из которых выведена вся токен-система:

1. **Warm earth palette** — все нейтралы в узком hue-диапазоне 40-60°. Ни один neutral не уходит на синюю ось. Cream paper surface (`#faf9f5`), не `#fff`.
2. **Dual-voice typography** — serif для editorial body, sans для display/UI, пропорция ~50/50 на home. Инверсия привычного паттерна (где sans для body, serif для headlines).
3. **Whisper-shadow monodiscipline** — одна тень на весь сайт (triple-layer 0.01/0.02/0.04), триггер только на hover `.card:hover`. Никакой shadow-шкалы.
4. **Fluid clamp everywhere ≥2rem** — никаких media queries для font-size или section-padding. Дыхание растёт с viewport, не скачет на breakpoints.
5. **Binary-biased radius** — `0` (609× в home) и `pill 100vw` — два полюса, role-contrast. Средние 4/8/16 редки, 6/10/12/14/20 запрещены (нет в оригинале).

---

## Colors

### Hue-map нейтралов (HSL)

| Token | Hex | Hue | Sat | Lightness |
|---|---|---|---|---|
| `--ml5-color-ivory-light` | `#faf9f5` | 49° | 38% | 97% |
| `--ml5-color-ivory-medium` | `#f0eee6` | 45° | 20% | 92% |
| `--ml5-color-ivory-dark` | `#e8e6dc` | 47° | 22% | 88% |
| `--ml5-color-slate-dark` | `#141413` | 60° | 3% | 8% |
| `--ml5-color-slate-medium` | `#3d3d3a` | 60° | 3% | 23% |
| `--ml5-color-slate-light` | `#5e5d59` | 48° | 4% | 36% |
| `--ml5-color-cloud-medium` | `#b0aea5` | 51° | 6% | 67% |

`slate-dark` (`#141413`) — не чёрный и не холодный серый, а **тёплый deep brown-black**. На dark-inversion блоках читается как «ночной холст», а не как `#000`.

### Accent clay — единственный warm accent

`--ml5-color-clay: #d97757` — hue ~15° orange-red, saturation 62% (глиняно-терракотовый, НЕ яркий digital orange).

**Правило:** 1-2 появления на viewport максимум. Используется на:
- signature CTAs в навигации (`btn.is-nav:hover → clay bg`)
- акцентный underline у dropdown-ссылок
- редкие декоративные элементы в illustrations

Всё остальное CTA-пространство — `slate-dark` → `slate-medium` (hover). Намеренный дефицит clay: редкость делает его заметным без крика.

### Swatch art collection (illustration reserve)

9 swatches (olive, cactus, sky, heather, fig, coral, manilla, kraft, oat) объявлены, но не используются в UI. Живут в SVG-иллюстрациях, тегах, декоративных элементах.

**Guardrail:** не использовать swatch-art для UI-ролей (кнопки, текст, фон секций). Все 9 swatches desaturated (S < 45%) — painter's-muted настроение сохраняется даже при максимальной цветовой нагрузке.

### Semantic aliases

Role-based proxies поверх core tokens. Компоненты обращаются к semantic, а не к core — позволяет менять палитру без правки компонентов.

`success/warning/danger` намеренно проксированы на swatch-art (`olive/kraft/fig`), не на классические красный/жёлтый/зелёный. Marketing-база сайта не использует классические UI error-states.

### WCAG notes

| Комбинация | Contrast | AA |
|---|---|---|
| slate-dark on ivory-light | 18.4:1 | ✅ |
| slate-light on ivory-light | 6.3:1 | ✅ |
| cloud-medium on ivory-light | 2.3:1 | ⚠️ ≥18pt only (large text/decorative) |
| ivory-light on slate-dark | 18.4:1 | ✅ |
| clay on ivory-light | 3.7:1 | ⚠️ ≥14pt bold only |
| clay on slate-dark | 4.9:1 | ✅ |

---

## Typography

### Families — dual-voice с mono-акцентом

| Role | Token | Stack | Substitute |
|---|---|---|---|
| Serif editorial | `--ml5-font-serif` | `"Fraunces", Georgia, serif` | **Fraunces** (Google Fonts, SIL OFL) |
| Sans display/UI | `--ml5-font-sans`  | `"Inter", Arial, sans-serif` | **Inter** (Google Fonts, SIL OFL) |
| Mono metadata | `--ml5-font-mono` | `"JetBrains Mono", monospace` | **JetBrains Mono** (Apache 2.0) |

**Обоснование выбора:**
- **Fraunces** — вариативный serif с `opsz 9..144` и `wght 100..900`. Opsz адаптирует контраст штрихов под размер (display vs text) — ближайшая бесплатная замена проприетарному custom serif по editorial характеру. Альтернативы (Source Serif 4, Spectral) нейтральнее и теряют авторский характер.
- **Inter** — универсальный гротеск с `wght 100..900`. Покрывает все 4 используемых веса 400/500/600/700. x-height и апертуры близки к Söhne-подобным san-серифам.
- **JetBrains Mono** — вариативный monospace 100-800, Apache 2.0.

**Google Fonts URL** (`<head>` демо):
```html
<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,400;0,9..144,600;1,9..144,400&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
```

### Dual-voice principle (signature DNA)

Инверсия привычного паттерна: **serif для body-параграфов, sans для display/UI**. Пропорция ≈50/50 на home (serif freq 333 / sans freq 328).

**Role map:**
- **Serif body** — paragraph-m/l, editorial section-H2 (`"Latest releases"`, mission-statement paragraphs), release-card titles
- **Sans display** — hero H1 weight 700, page-headers, nav, CTA-label, eyebrow-метки, footer links

Сохранять строго как сигнатуру — без этого теряется авторский голос.

### Font-size scale

Clamp fluid начиная с 2rem (display-m). Детали ≤1.25rem — fixed.

| Token | Formula | Role |
|---|---|---|
| `display-xxxl` | `clamp(3.5rem, 2.73rem + 3.27vw, 6rem)` | editorial page-hero |
| `display-xxl` | `clamp(2.75rem, 2.21rem + 2.29vw, 4.5rem)` | hero-H1 sans 700 |
| `display-xl` | `clamp(2.5rem, 2.04rem + 1.96vw, 4rem)` | section-H2 editorial serif |
| `display-l` | `clamp(2.25rem, 2.02rem + 0.98vw, 3rem)` | subsection heading |
| `display-m` | `clamp(1.75rem, 1.67rem + 0.33vw, 2rem)` | UI-H2 sans 600 |
| `paragraph-l` | `clamp(1.375rem, 1.34rem + 0.16vw, 1.5rem)` | lede, intro |
| `paragraph-m` | `clamp(1.125rem, 1.09rem + 0.16vw, 1.25rem)` | body default (serif 400) |
| `paragraph-s` | `clamp(1rem, 0.96rem + 0.16vw, 1.125rem)` | secondary copy |
| `detail-*` | fixed 0.75-1.25rem | UI labels, nav, captions |

### Weights

Измеренная частота: **400 доминирует 88-89%**. 500/600/700 — акценты.

- `400` — body (serif) + UI-текст + nav
- `500` — eyebrow uppercase, button-label
- `600` — serif-display semibold, section-H2-UI
- `700` — **только hero-H1** и page-headers sans

### Line-heights и letter-spacings

- Display `1.05-1.1` (плотный режим)
- Body `1.4` (дефолт)
- Lede paragraph-l `1.5`
- `--ml5-ls-tight-body: -0.005em` — body 16-20px
- `--ml5-ls-tight-display: -0.02em` — display 32-96px
- `--ml5-ls-uppercase: 0.02em` — eyebrow caps

---

## Spacing — dual-mode fixed/fluid

Порог перехода — `--ml5-space-6: clamp(1.75rem → 2rem)`.
- Мелкие ≤24px — **fixed** (стабильный rhythm внутри кнопок/pill)
- Крупные ≥32px — **fluid** (дышит с viewport, не скачет на breakpoints)

**Dominant section rhythm:** `--ml5-section-main` (88-160px) — между смысловыми блоками на home.
**Hero:** `--ml5-section-lg` (112-224px).
**Above-fold:** `--ml5-section-page-top` (96-192px).

---

## Layout

**12-col grid, max-width 89.5rem (1432px).** Редкое решение — стандарт 1200-1280px. Лишние 150-230px дают воздух для editorial long-form: paragraph-m 18-20px читается комфортнее при ширине колонки 640-680px.

Edge-margin `clamp(2rem → 5rem)` (32-80px) делает контейнер floating. На 1440+ заметные поля, на mobile 320 минимальные 32px.

Column-gutter синхронизирован со `--ml5-space-6` — один ритм между колонками и карточками.

`--ml5-nav-height: 4.25rem` (68px). `--ml5-nav-banner-height: 2.75rem` (44px).

---

## Radius

### Binary-biased distribution

| Radius | Частота (home) | Роль |
|---|---|---|
| `0` | **609** (dominant) | Секции, блоки, типографика |
| `8px` | 26 | Cards, inputs |
| `16px` | 5 | Large containers |
| `24px` | 4 | Prominent tiles |
| `12px` | 4 | Rare, minor |
| `100vw` | pill | CTA buttons |

**Guardrails:**
- `0` — дефолт для любой секции/контейнера без явного основания
- `100vw` — **только** для CTA-кнопок (role-contrast с квадратными секциями)
- `8px` — cards/inputs
- `16/24px` — featured-плашки, редко
- **Запрет:** `6/10/12/14/20px` — не в оригинале, создают «SaaS-шум»

---

## Shadows — whisper monodiscipline

### Signature

**Одна тень на весь сайт.** Три слоя с opacity 0.01 / 0.02 / 0.04 — по отдельности почти невидимы, вместе дают мягкую дымку.

```css
--ml5-shadow-whisper:
  rgba(0,0,0,0.01) 0 2px  2px 0,
  rgba(0,0,0,0.02) 0 4px  4px 0,
  rgba(0,0,0,0.04) 0 16px 24px 0;
```

**Триггер:** только `.card:hover`. На статических состояниях — **нет тени**.

### Guardrails

- **Никогда** не добавлять `box-shadow` вне hover-state для карточек-ссылок
- **Никогда** не использовать цветные тени
- **Никогда** не добавлять новые уровни шкалы (md, xl, glow)
- `--ml5-shadow-subtle` — исключение для `/product/*` подстраниц, экономно

---

## Motion

### Budget: color / opacity / transform

Никаких rotation, skew, scale > 1.02. Движение подчёркивает смысл, не демонстрирует технику.

### Durations

| Token | Value | Use |
|---|---|---|
| `instant` | 100ms | Opacity micro-fade |
| `fast` | 200ms | Color transitions (top, 155× home) |
| `base` | 300ms | Fallback (редко) |
| `slow` | 400ms | Opacity fade, menu open/close |

### Easings

- `--ml5-ease-default: cubic-bezier(0.77, 0, 0.175, 1)` — power4 easeInOut, для menu/opacity
- `--ml5-ease-out-circ: cubic-bezier(0.165, 0.84, 0.44, 1)` — для hover transforms, Next.js-страниц

### Signature — menuOpen curtain

Navigation menu раскрывается через `clip-path: polygon` анимацию `0 0 → 100% 100%` curtain-down reveal, 400ms, easing `--ml5-ease-default`. Единственная «сложная» анимация в системе.

### Guardrails

- Не добавлять новые easings — хватает трёх
- Не превышать 400ms
- Hover transforms — только translate или scale(1.01-1.02), **никогда** rotation
- `@prefers-reduced-motion` — глобальный `@media` сбрасывает всё до 0.01ms

---

## Z-index

Плоская иерархия с явными «этажами» и зазорами ≥900:
- `1-2` — контент + sticky-section
- `1000-1200` — overlay (nav/modal/toast)
- `2000` — системный overlay

---

## Breakpoints — только layout reflow

`479 / 767 / 991 / 1249` — Webflow defaults + desktop-граница. **Не используются** для font-size или spacing (clamp). Только для collapse колонок 12→2→1 и горизонтальное меню → гамбургер.

Верхняя граница дизайна (1440+) фиксируется через `max()` в `clamp()` — отдельный `--ml5-bp-xl` не нужен.

---

## Extension — marketing-light specifics

| Token | Value | Use |
|---|---|---|
| `--ml5-hero-padding-top` | `--ml5-section-page-top` | Above-fold hero top |
| `--ml5-hero-padding-bottom` | `--ml5-section-lg` | Hero bottom before next section |
| `--ml5-article-max-width` | `40rem` (640px) | Editorial prose column |
| `--ml5-card-padding` | `--ml5-space-8` (36-48px) | Standard card padding |
| `--ml5-dark-inset-padding` | `--ml5-space-10` (48-80px) | Dark inversion block inside cream body |
| `--ml5-underline-thickness` | `0.06em` | H1 editorial underline |
| `--ml5-underline-offset` | `0.1em` | Default underline offset |
| `--ml5-underline-hover-offset` | `0.2em` | Nav/link hover offset |
| `--ml5-release-card-bg` | `--ml5-color-ivory-medium` | Release card surface |
| `--ml5-release-card-radius` | `--ml5-radius-lg` (16px) | Release card radius |

---

## Что не потерять при воспроизведении

1. **Serif в body, не в headlines.** Эта инверсия — главный signature. Если в ваш демо H1 будет Fraunces — вы нарушили DNA. H1 = `--ml5-font-sans` weight 700.
2. **Cream `#faf9f5`, не `#fff`.** Pure white ломает warm-earth настроение.
3. **Одна тень на весь сайт.** `--ml5-shadow-whisper` на hover карточек-ссылок, остальное — плоско.
4. **Единственный warm accent — clay.** НЕ добавлять голубой/зелёный/фиолетовый как secondary accent.
5. **Fluid clamp — никаких media queries для font-size.** Если в demo `@media (max-width: 768px) { h1 { font-size: 32px } }` — вы нарушили DNA.
6. **Radius binary 0 + pill.** 6/10/12/14/20px запрещены.
7. **Editorial underline в H1** — вторые подчёркнутые слова, это рукописная правка редактора, не hyperlink. `text-decoration: underline`, без `color: link`.
8. **Nav-hover → clay bg** (на is-nav variant кнопок). Это единственное место в UI, где clay выступает как background.
9. **12-col 89.5rem grid** — не 1200-1280px. Воздух для editorial long-form.
10. **Swatch art только для illustrations.** Не использовать olive/sky/fig/heather в UI-кнопках или фоне секций.