# RULES.md — design laws

> **Scope**: this file documents the **editorial deck variant**. For dashboards, admin tools and internal SaaS that reuse the same token system but with utilitarian density, read `PRODUCT-UI.md` (added in v1.0.2). The Color, Typography, Spacing, Radii, Shadows and Focus sections below apply to both variants.

## Register

This file is for **editorial brand decks**. Maximalism is controlled, not minimalism. Italic serif headlines carry meaning; sans-serif handles structure.

## Color

### Ink scale (tinted neutrals, never #000/#fff directly)

| Token | Hex | Use |
|---|---|---|
| `--paper` | `#ffffff` | base white surface |
| `--ink-50` | `#f7f8fa` | tone surface |
| `--ink-100` | `#eef0f3` | dividers / subtle bg |
| `--ink-200` | `#e1e4ea` | borders |
| `--ink-300` | `#c7ccd4` | quiet borders |
| `--ink-400` | `#97a0ad` | de-emphasized text |
| `--ink-500` | `#6b7480` | captions / eyebrows |
| `--ink-600` | `#4a525e` | secondary text |
| `--ink-700` | `#2e343d` | body text |
| `--ink-800` | `#181b21` | strong body |
| `--ink-900` | `#0a0b0d` | headings / dark slide bg |

All tinted slightly toward cool. Hue chroma ~0.005. Never substitute raw black/white.

### Accent (single)

| Token | Hex | Use |
|---|---|---|
| `--accent-50` | `#fffae6` | highlight underlay |
| `--accent-100` | `#fef3cb` | tints |
| `--accent-200` | `#fde791` | tints |
| `--accent-400` | `#fbd64a` | hover for solid pill |
| `--accent-500` | `#facc0d` | **primary accent** |
| `--accent-600` | `#c7a007` | focus-visible outline |
| `--accent-700` | `#8a6f04` | dark on light bg labels |
| `--accent-900` | `#4a3d02` | rarely used |

Rule: **one accent only**. No second saturated hue on the same slide.

### Semantic (data viz only)

`--success-{100,500,700}` green · `--warning-{100,500,700}` ochre · `--error-{100,500,700}` red · `--info-{100,500,700}` blue. Only inside charts.

### Series 2 (chart B)

`--series-2: #1b5566` with `--series-2-bg: #e4ecef`. Teal-ink for comparison series in dual-axis charts.

## Typography

### Families

- **Display**: DM Serif Text, italic for hero phrasing, regular for secondary headings. Color `--accent-500` on dark slides, `--ink-900` on light.
- **Sans**: Nunito Sans, weights 300–800. Body and structural text.
- **Data**: DM Serif Text for KPI figures, `tabular-nums lining-nums`.
- **Mono**: aliased to sans (no separate monospace font); use `tabular-nums` for numerical alignment in chrome/footer.

### Scale (fluid, clamp-based)

```
--fs-eyebrow:  clamp(11px, 0.85vw, 14px)   letter-spacing 0.14em UPPERCASE
--fs-caption:  clamp(12px, 0.95vw, 15px)
--fs-body:     clamp(15px, 1.15vw, 18px)
--fs-body-lg:  clamp(17px, 1.30vw, 20px)
--fs-h3:       clamp(20px, 1.70vw, 26px)   sans bold
--fs-h2:       clamp(28px, 2.40vw, 38px)   serif regular
--fs-h1:       clamp(36px, 3.60vw, 56px)   serif regular
--fs-display:  clamp(48px, 6.00vw, 96px)   serif italic
--fs-data-sm:  clamp(24px, 2.40vw, 36px)
--fs-data-md:  clamp(40px, 4.80vw, 72px)
--fs-data-lg:  clamp(64px, 8.00vw, 128px)
--fs-data-xl:  clamp(96px,12.00vw, 184px)
```

Ratio between steps ≥ 1.25.

### Headlines patterns

- Hero: `font-display italic`, `font-size: clamp(36px, 5.6vw, 88px)`, `line-height: 1.08`, `letter-spacing: -0.015em`, `max-width: ~1500px`.
- Section h2: `font-display`, `font-size: clamp(28px, 3.8vw, 56px)`, line-height 1.1.
- Sans h3 (structural): bold 700, color `--ink-800`.

### Body

`font-size: var(--fs-body)`, `line-height: 1.55`, `color: var(--ink-700)`. Max 65–75ch per line.

## Layout

### Slide skeleton

```
min-h-screen
flex
overflow-hidden
px-[clamp(24px,6vw,128px)]
py-[clamp(56px,8vh,96px)]
inner: mx-auto w-full max-w-[1664px]
```

Three variants:

- `slide-paper` — `--paper` bg, `--ink-800` text.
- `slide-tone` — `--ink-50` bg.
- `slide-feature` — `--ink-900` bg, titles `--accent-500` italic.

Three alignments: `start` (top, padded), `center` (default), `end` (bottom).

### Rhythm

Alternate variants between slides — never three of the same variant in a row. Vary `align` to break verticality.

### Spacing

```
--space-1: 4   --space-2: 8   --space-3: 12  --space-4: 16
--space-5: 24  --space-6: 32  --space-7: 48  --space-8: 64
--space-9: 96  --space-10: 128
```

Use `gap-*` Tailwind utilities or inline `gap` with these values.

### Radii

```
--radius-xs: 2   --radius-sm: 4   --radius-md: 6   --radius-lg: 10   --radius-pill: 999
```

Default: 6 px. Never round large surfaces beyond 10 px; we are not building chat bubbles.

## Shadows

Flat ground + 1 px outlines, not Material elevation.

```
--shadow-flat:  0 1px 0 rgba(10,11,13,.04)
--shadow-rest:  0 1px 2px rgba(10,11,13,.06), 0 0 0 1px rgba(10,11,13,.04)
--shadow-hover: 0 4px 12px rgba(10,11,13,.08), 0 0 0 1px rgba(10,11,13,.06)
```

## Highlight (signature element)

`.hl { background: var(--accent-500); color: var(--ink-900); padding: 2px 14px; border-radius: 2px; box-decoration-break: clone; }`

Use inside a headline to underline one phrase. Animated via `<Highlight>` component (yellow fill from transparent + text from accent → ink-900).

## Eyebrow

UPPERCASE, letter-spacing 0.14em (or 0.16–0.18 on dark), ink-500 on light or rgba(255,255,255,0.6) on dark. Two flavors:

- `.eyebrow` — plain text.
- `.eyebrow-mark` — adds 32 px horizontal rule before the text.

## Chrome

Bottom strip on every slide: left = logo strip, right = paginator `01 / NN` in tabular-nums sans. Top barre = scroll progress bar in accent (3 px tall). Right side = block indicator dots (block break labels A/B/C/…).

## Grain texture

Optional. Two utilities (`.grain-light`, `.grain-dark`) render a fine radial-gradient dot grid for paper-like surface. Subtle. Apply to slide-level wrapper if desired.

## Focus

`*:focus-visible { outline: 2px solid var(--accent-600); outline-offset: 2px; }`

## Cursor

Native cursor. **Do not** install a custom cursor in this branch of the system.

## Reduced motion

Respect `prefers-reduced-motion: reduce`. The system already disables transforms in core primitives; new components must do the same.