recap/design/DESIGN.md

# Recap — Design brief

The durable brand contract for Recap's user-facing UI. Read this and
`design/tokens.tokens.json` before building or changing any UI. This was
**extracted** from the as-built `recaps.cc` interface (no prior guidelines), then
**reconciled** with the owner on 2026-06-16 — so where the live code still
disagrees with a value here, *this file is the intent* and the code is the cleanup
backlog (see `ROADMAP.md`). Provenance: there was no design tool or export; the
source is the shipped `public/index.html`, `public/auth.html`, and the app icon.

---

## 1. Visual theme

A **dense, dark, information-first developer-tool aesthetic.** Restraint over
decoration: small type, tight radii, thin hairline borders, flat panels on a
near-black navy field, with the indigo accent used sparingly to mark what's
interactive or active. It should read like a fast, technical instrument — closer
to a code editor or an ops dashboard than a consumer media app. Calm, quiet, and
legible at high density; never glossy, never playful.

The brand mark (app icon) is a **play-triangle filled with a blue→purple gradient
over four light "transcript" lines**, on the dark navy field — the product in one
glyph: *press play on a video, get the text back.* That blue→purple gradient is
the origin of the whole accent story (§2).

Voice: precise, plain-spoken, unhyped. The UI explains tersely and trusts the
user. What it is **not**: not gradient-heavy, not glassmorphic beyond a light
overlay blur, not rounded-and-bubbly, not light-mode, not framework-flashy.

## 2. Color palette

Built almost entirely on the **Tailwind Slate + Indigo** ramps over a custom
near-black navy base. Canonical roles below; full values in
`tokens.tokens.json`.

**Surface ladder (warm/cool split — the agreed system).**
| Role | Value | Where |
|---|---|---|
| Base | `#0a0e1a` | page, body, sticky top bars, full-height side panels (history sidebar, log drawer). Also the PWA `theme_color`. |
| Card | `#111827` (warm gray-900) | raised cards, modals, popovers, toasts, icon-buttons, pipeline steps, skeletons. |
| Inset | `#0f172a` (cool slate-900) | recessed fields & list rows: settings/key inputs, queue items, subscription items, model buttons, expanded-chunk bg. |
| Raised field | `#1e293b` | the **primary URL input only** — deliberately lighter than the inset so the hero field pops. |

> Legacy darks **`#0a0e17`, `#0b1120`, `#020617`** are near-duplicates that
> leaked in; fold them into the nearest rung (`#0a0e17`/`#0b1120` → Base,
> `#020617` → Inset). Don't add new background darks.

**Accent — indigo (THE single interactive accent).**
- `#818cf8` (indigo-400) — **the accent.** Fills (submit button, active tab/icon,
  processing badge) and marks (links, focus ring, active state, timestamps,
  expanded-chunk arrow).
- `#a5b4fc` (indigo-300) — accent hover (lighter), active-line emphasis.
- Indigo tints `rgba(129,140,248, .06–.20)` — hover washes, active backgrounds,
  the `0 0 0 3px …/.15` focus ring, the `0 4px 24px …/.3` submit glow.
- **Demoted:** `#6366f1` (indigo-500) and its hovers `#4f46e5`/`#4338ca` are
  legacy dups — migrate them to `#818cf8`; do not introduce new ones.

**Premium — purple (RESERVED for paid/upgrade only).**
- `#a855f7` (purple-500) — upgrade button, highlighted tier, buy badge, primary
  buy CTA. `#c084fc` hover; `#9333ea` deep.
- `#c4b5fd`/`#d8b4fe` (purple-300/200) — tier-badge & Pro text.
- Purple appears **nowhere** in non-premium UI.

**Text ramp (slate).**
`#e2e8f0` primary · `#f1f5f9` strong/headings (canonical near-white — fold the
stray `#f5f9ff` into this) · `#cbd5e1` running body copy · `#94a3b8` muted/
secondary · `#64748b` labels & placeholders · `#475569` faint meta/timestamps ·
`#334155` dimmest (doubles as the hover-border). `#fff` only on filled
accent/premium buttons.

**Borders.** `#1e293b` (slate-800) default hairline → `#334155` (slate-700) on
hover/active → `#475569` (slate-600) strongest hover. Borders, not shadows, are
the primary way surfaces are separated.

**Semantic status (consistent, intentional — keep).**
- Success/green: `#22c55e` base · `#4ade80` text · `#86efac` soft · `#16a34a` deep.
- Error/red: `#ef4444` base · `#f87171` text · `#fca5a5` soft · `#dc2626` deep.
- Warning/amber: `#fbbf24` base/dot · `#fcd34d` · `#fde68a` · `#f59e0b` (update btn).
- Info/blue: `#3b82f6` base · `#60a5fa` · `#93c5fd`. **Blue is status/info only**
  (and the legacy auth-screen accent, which should migrate to indigo) — never a
  primary interactive color in-app.

**Speaker chips (8-hue categorical set — intentional, keep as-is).** A→H:
red/blue/green/amber/purple/sky/pink/slate, each as the *tinted triplet*
(background α≈.18, light-shade text, border α≈.35).

## 3. Typography

- **Sans (everything):** `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
  sans-serif`. System stack — **no web fonts.**
- **Mono (timestamps, license keys, URLs, code):** `ui-monospace, "SF Mono",
  Menlo, Consolas, monospace`. One canonical stack — snap the near-variants to it.
- **Scale (px):** `10 · 11 · 12 · 13 · 14 · 16 · 18 · 20 · 22 · 28`.
  - 10–11 — micro labels, badges, meta, section labels, pills, hints.
  - 12 — secondary UI default (buttons, labels, stats, list titles).
  - 13 — body default (descriptions, list items, transcript-adjacent).
  - 14 — emphasis / larger body, drawer & settings headers.
  - 16 — input text, modal `h2`, section heads.
  - 18 — sub-headers, logo wordmark, large numerals.
  - 20–22 — headings, modal/activation titles, tier names.
  - 28 — display (price). Snap strays `15→16`, `24→22`, fractionals
    `12.5/11.5→12`, `10.5/9→10`.
- **Weights:** 400 normal · 500 medium · **600 semibold (the UI default)** · 700
  bold (headings, badges) · 800 extrabold (tier badge, big numerals). Snap
  `650→600`, `680→700`.
- **Line-height:** 1.5 body · 1.55 denser reading blocks · 1.3–1.4 titles · 1.25
  large titles · 1 single-line badges.
- **Letter-spacing:** 0 default. Uppercase micro-labels track `0.05em`; badges
  `0.04em`; tier/section labels `0.06–0.08em`; one display title tightens
  `-0.01em`.

## 4. Component styling

- **Buttons.** *Primary:* filled `#818cf8`, white text, radius 8–10px, weight
  600, hover lifts `translateY(-1px)` + indigo glow; disabled → `#1e293b` bg /
  `#475569` text. *Secondary:* `#1e293b` fill, `#334155` border, `#94a3b8`→
  `#cbd5e1` text. *Icon/ghost:* `#111827` (or transparent), `#1e293b` border,
  muted glyph; hover lightens bg + border; `.active` → accent fill. *Premium:*
  filled `#a855f7`.
- **Inputs.** Inset `#0f172a` (or `#1e293b` for the hero URL input), `#334155`/
  `#1e293b` border; focus → accent border + `0 0 0 3px rgba(129,140,248,.15)`
  ring. Mono font for keys/codes; placeholders `#64748b`/`#475569`.
- **Cards.** `#111827` bg, `#1e293b` border, radius 10–14px; border lightens on
  hover; expanded/active → accent border + faint `0 2px 16px …/.06` accent glow.
- **Pills / badges / chips — the "tinted triplet".** Background at α≈.1,
  text in the light shade, border at α≈.2–.45 of the same hue. Status pills,
  tier badges, `queue-from` tags, clip badges, and speaker chips all follow this
  one rule.
- **Modals.** `#111827` (settings) / `#0f172a` (buy) bg, radius 16px, sticky
  header with `1px #1e293b` bottom border, `slideUp` entrance, scrim
  `rgba(0,0,0,.6)` + `backdrop-filter: blur(4px)`.
- **Toasts.** Top-right stack, `#1e293b` bg, `#334155` border, slide-in from
  right, auto-fade.
- **Spinner.** 3px ring, `#1e293b` track, `#818cf8` top, `spin 0.8s linear`.
- **Pipeline / tracker.** Stepped pills: idle neutral, `.active` → accent
  tint+border, `.done` → green tint+border.

## 5. Layout

- **Single fluid column.** `.container` `max-width:100%`, padding `36px 24px`
  (landing) tightening to `16px 24px` (results) and down on mobile.
- **Results = split screen.** `.results-left` 58% (video/player, sticky top) +
  `.results-right` (scrolling chunk list), 16px gap; stacks vertically <900px.
- **Persistent left history sidebar**, 320px, *pushes* content on desktop /
  overlays on mobile. **Right log drawer**, 440px, slides in.
- **Dense vertical rhythm.** Card margin 14px, chunk margin 6px, gaps 6–16px.
- **Spacing steps (de-facto):** `4 · 6 · 8 · 10 · 12 · 14 · 16 · 20 · 24` for
  controls/gaps, `28 · 32 · 36` for section padding. Not a strict 4/8 grid —
  dense and organic by design; prefer these steps over new in-between values.

## 6. Depth / elevation

**Flat by default — separation comes from 1px borders, not shadows.** Shadows are
reserved for things that genuinely float:
- Overlays/drawers/modals: `0 8px 24px …/.3` (toast) · `0 8px 32px …/.4` (video,
  side drawers `±8px 0 32px`) · `0 12px 32px …/.5` (menu) · `0 20px 60px …/.5`
  and `0 24px 64px …/.5–.6` (panel, settings/buy modal). All `rgba(0,0,0,α)`.
- **Accent glows** signal primary/active: submit `0 4px 24px rgba(129,140,248,.3)`;
  focus ring `0 0 0 3px rgba(129,140,248,.15)`; expanded chunk `0 2px 16px …/.06`;
  premium tier `0 12px 40px rgba(168,85,247,.25)`.
- Overlay scrims use `rgba(0,0,0,.4–.65)` + `backdrop-filter: blur(4–6px)`.
- Drag/drop affordance is an accent line: `box-shadow: 0 ±2px 0 0 #818cf8`.

## 7. Do's and don'ts

**Do**
- Use `#818cf8` as the *single* interactive accent; reserve purple `#a855f7`
  strictly for premium/upgrade.
- Separate surfaces with 1px `#1e293b` borders that lighten to `#334155` on hover;
  keep shadows for true overlays only.
- Build every status/category chip as the tinted triplet (bg α.1 / light text /
  border α.2).
- Keep type dense — 12–13px body, 10–11px meta — with 600 as the default weight.
- Follow the surface ladder: base `#0a0e1a` → card `#111827` → inset `#0f172a`.
- Use the system font stack; mono only for timestamps / keys / URLs.

**Don't**
- Don't introduce new `#6366f1`/`#4f46e5` indigos — they migrate to `#818cf8`.
- Don't put blue `#3b82f6` on primary interactive elements; blue is info/status
  (and legacy auth) only — auth should move to indigo.
- Don't add new background darks (`#0a0e17`/`#0b1120`/`#020617` are legacy dups).
- Don't use purple for non-premium UI, or the accent indigo for premium.
- Don't add fractional font sizes (12.5/11.5/10.5) or off-scale weights (650/680).
- Don't reach for a framework, web font, or heavy drop shadows — vanilla JS,
  system fonts, flat-with-borders is the intentional language.

## 8. Responsive behavior

- **Breakpoints:** `900px` (primary: split→stack, sidebar push→overlay), `880px`
  (tablet: top breadcrumb swaps to a hoisted mobile copy), `600px` (phone:
  icon-only submit, hamburger menu, desktop toolbar/pills hidden), `640px` (share
  export). Plus `≤900px landscape` → fullscreen video.
- **Mobile rules:** form inputs forced to `16px` (iOS auto-zoom guard); touch
  targets 44–48px; sticky top bar; full-width drawers/panels; hover-gated
  controls pinned visible (touch has no hover). Use `100dvh` for full-height.

## 9. Agent prompt guide

When building or changing UI in this repo:
- Read `design/tokens.tokens.json` and pull values from it — don't eyeball new hex.
- Match the **dense dark vanilla-JS** style. The frontend is one file,
  `public/index.html`, with two `<style>` blocks + ~447 inline `style=` attrs and
  a render-into-`innerHTML` loop. No framework, no bundler, no web fonts — keep it
  that way.
- Accent is `#818cf8`; purple is premium-only; follow the surface ladder; build
  chips as the tinted triplet; system font for text, mono for timestamps/keys.
- **Three surfaces stay in sync:** the main app stylesheet, the `SHARE_PAGE_CSS`
  string (the self-contained share export), and `public/auth.html`. A token change
  must be reflected in all three. Auth currently uses the legacy blue accent —
  new auth work should adopt indigo.
- Sanitize operator-internal strings at error boundaries (per `AGENTS.md`) — they
  must never reach cloud users, design surfaces included.