# EMBER — Style Guide (the how)

Practical usage of the nine signatures, per pattern and per medium.
For the reasoning, read `MANIFESTO.md` first. Check any piece against this
page before shipping it.

## The ember audit

Before anything ships, count ember-colored elements:

- Exactly **one** per composition (a page, a poster, one face of a card).
- The wordmark period **EMBER.** counts as the one when present.
- A repeated ember *sequence* (flip-book frames, a marching animation) is
  one ember **event**.
- The ember glow (`--glow-ember`) is the language's only sanctioned blur;
  it may appear only on the ember element itself.
- Semantic colors (ok/warn/err) and persona colors on the job never count.
- Catalog pages (the style guide, the sticker sheet) are exempt — each
  artifact inside carries its own single ember.

## Persona colors — one job each

| Color | Token | Job | Allowed uses |
|---|---|---|---|
| Azure | `--azure` | cold data | links, coordinates, indices, data annotations |
| Sky | `--sky` | asking air | envelope and field fills, anything that requests input |
| Pink | `--pink` | the human hand | the whisper, selection highlight, reading-progress line, marginalia |

Never: persona colors as headings, borders, buttons, or decoration.
Only ember radiates heat.

## Composition — rules make the rooms

Structure comes from dividing lines, never from wrapping boxes. Four devices
carry every EMBER page:

1. **Band** — full-width field, opened by a heavy rule. One band per page
   may invert into an ink field (or burn with the conflict gradient — see
   Welcome the conflict).
2. **Ledger** — ruled rows: `index | content | annotation`. Lists, indexes,
   navigation — anything enumerable becomes a ledger.
3. **Annotation column** — content beside a mono note rail, like the margin
   notes of a technical drawing.
4. **Scale jump** — a leap up the type scale as a divider.

**The box allowance:** a bordered box is legitimate only for a genuine
*object*, and it takes a posture (below). One or two per view, maximum.

## Postures — geometry declares intent

| Posture | Intent | Geometry | Web class |
|---|---|---|---|
| GIVE | informs | sharp top corners, rounded open bottom | `.posture-give` (the rare `.card`) |
| ASK | requests | an envelope: airmail stripe, unsealed V-flap, sky fill | `.envelope` |
| SPEAK | announces | tag: rounded left (the mouth), sharp right (the point) | `.posture-speak` (`.callout`) |
| PRESS | acts | keycap: sharp cap standing on a side wall | `.btn` |

Rules:
- Choose posture from intent, not aesthetics. If you can't name what a
  surface does, it doesn't get a shape.
- The envelope always wears its airmail stripe (ember + azure dashes) —
  that conflict is sanctioned because the envelope *is* the event.

## The keycap (buttons)

- The cap sits on a side wall: `box-shadow: 0 var(--keycap-wall) 0`.
- **Press** = the cap sinks the full wall height and lands
  (`translateY` + wall collapse). Never a diagonal shadow.
- **Hover** = the motion ghost: the wall extends and a shrunken echo trails
  off the left — the key looks ready to move.
- Variants: default (raise), primary (ink), ember (the one ember — its hover
  adds the sanctioned glow), ghost (hairline cap, 4px wall).
- Optional mono key legend (`.key`, e.g. ↵) marks the primary action.

## Chips are tickets

Pills with punched holes left and right (`.chip::before/::after`). A chip
with no holes is just a rounded rectangle — not EMBER.

## Color usage ratios

- ~70% background family (`--bg`, `--raise`, `--sunk`)
- ~22% ink family (text, rules, slabs — table headers are ink slabs)
- ≤5% ember (once) · azure/sky/pink strictly on the job · semantics functional only

## Typography rules

- Display: grotesque 700, `--tracking-display`, line-height 0.92–0.95, often
  uppercase. Body: grotesque 400/500, line-height 1.6, max 68ch.
- Snap to the nearest `--text-*` step; never invent intermediate sizes.
- The whisper is Newsreader italic, **pink**, `--text-lg` or smaller, once
  per composition.

## Welcome the conflict — the rules of engagement

- One deliberate conflict per composition: one gradient event, one neon
  breath, one rough edge a tidier system would have smoothed.
- The sanctioned tools: `--conflict-gradient` (ink → ember, for exactly one
  surface — the marquee band is the canonical one) and `--glow-ember`
  (only on the ember element).
- You must be able to point at the conflict and say why it's there.
  Two conflicts are chaos; one is a signature.

## The desire to move

**On screens (real motion):**
- **Marquee**: principles march through a conflict-gradient band; pause on
  hover; `aria-hidden` + static under reduced motion.
- **Press-in**: entrances land like a stamp (`ember-press-in`, staggered by
  `.press-in-2/3/4`) — never a soft fade alone.
- **Ember pulse**: the period breathes (`--pulse-dur`, 2.8s) and quivers —
  it is alive, never quite at rest.
- **Tension**: stillness is stored energy. Headline lines strain in slow
  cycles (`--strain-dur`, 7s, `.strain-a/b`, opposite phases); the fist
  line clenches — long stillness, then a fast snap-and-settle
  (`--clench-dur`, 6s, `.clench`). Pinned elements (the grid-break chip,
  the break bar) strain against their pin. Hovering a headline line
  surfaces its echo trail — potential energy made visible.
- **The scan**: when a large plate leaves a deliberate vacancy beside it,
  turn the plate in 3D toward the void (`.face-turn`, `--scan-dur`) and
  annotate the vacancy itself in azure dashed mono (the "vacant quarter"
  note). Unbalance held on purpose becomes tension; unbalance ignored is
  a bug in the layout. The shouted variant is `.megaphone`: an upright
  ink slab behind the type, and the type fired off it — oversized,
  stretched (`--stretch`), sheared, mildly receding — dark-on-dark across
  the slab with a faint bone emboss edge, breaking toward the vacancy.
  Reserve it for one hero moment per page.
- **Progress rule**: a pink 3px line tracks reading under the header.
- Every animation respects `prefers-reduced-motion` (base.css kills them).

**On paper (printed yearning):**
- **Echo trail**: stepped text-shadows behind display type (poster, cover).
- **Speed dashes**: three dashes fading in front of a moving ember chip.
- **Flip-book**: a strip of frames with the ember cube mid-march, captioned.
- **Momentum bar**: `▓▓▓▓░░ 58% — DESIRE TO MOVE` in mono, in footers.
- **Dog-ear**: a folded-corner triangle — the page caught mid-turn.
- A repeated ember sequence counts as one ember event.

## Per-medium notes

**Web** — default mode paper; honor `prefers-color-scheme` or the toggle.
Motion is part of the contract, not garnish. Respect reduced motion.

**Poster / print** — design at true millimeters; export via Print →
Save as PDF, margins *none*, background graphics *ON*. Heavy rules are
0.8–6mm at true scale. Every print piece must carry at least one printed
motion device (echo, dashes, flip-book, momentum, dog-ear).

**Physical products** — templates give the artwork; `PRODUCTION.md` gives
stocks and processes. Warm uncoated stocks; ember as spot color (Pantone
173 C–adjacent) or foil.

**Social/other media (future)** — link `tokens/ember.css`, keep the nine
signatures, pass the ember audit.

## The anti-template checklist

Run any new piece against this list; one "yes" means rework:

1. Could it be swapped into a thousand other sites unnoticed?
2. Is every corner the same radius?
3. Does any box exist that you can't name the posture of?
4. Is there exactly one gradient — and can you point at why?
5. Does anything move (or, on paper, *want* to move)?
6. Would removing the ember period leave zero ember on the page?
7. Is the only personality the color palette?