# ADR-100 Visual Design via shared/theme-v2.css Token Presets, Outside Ponytail's Scope

## Status

Accepted, 2026-07-02.

## Status History

```yaml
status_history:
  - date: 2026-07-02
    status: Proposed
    changed_by: hkl
    reason: All PWAs converged on one look (navy/orange Recce template or flat black); visual design was being stripped as "unrequested complexity" by always-on ponytail
    changed_via: adr-kit (360lm)
  - date: 2026-07-02
    status: Accepted
    changed_by: hkl
    reason: theme-v2.css shipped with 5 presets; Hub pilot (ember-v2) executed with screenshot-critique loop (VCC Phase 5)
    changed_via: adr-kit (360lm)
```

## Context

Every new PWA inherited the same hard-coded palette from the style guide (navy `#0f172a` +
orange `#f97316`, or Hub's flat black), producing a uniform "template" look. Two forces made
this worse: (1) the pre-split style guide prescribed exact hex values per §2, so scaffolding
copied them verbatim; (2) always-on ponytail (CLAUDE.md) treats unrequested additions as waste,
and visual polish was routinely classified as such. PWAs already consume CSS custom properties
(`--bg/--card/--accent/--radius/--font` …) consistently, so a token layer can restyle without
structural rewrites. Affects: all PWAs, the /new-pwa scaffolding flow, and shared/ (ADR-079).

## Decision

- Visual identity comes from **`/shared/theme-v2.css`**: named presets selected per app via
  `<html data-theme="…">`, linked AFTER the app's inline `<style>`. Launch presets:
  `navy-classic` (Recce-standard light), `ember-v2` (Hub refined dark), `forest`, `ivory`, `slate`.
- Presets override only look-and-feel tokens (palette, gradients, radius scale, shadows, fonts,
  focus ring, motion durations) — never structural tokens (z-index ladder, `--bnav-h`, safe-bottom).
- New looks are added as **new presets in theme-v2.css** (developed with the `frontend-design`
  skill), never as forked token values inside a PWA.
- The `/new-pwa` skill asks for a design direction after Q0.1 and mandates a screenshot-critique
  pass (390×844) before UI is called done.
- **Ponytail scope boundary** (recorded in CLAUDE.md): ponytail governs logic/architecture/code
  volume; typography, color, spacing, and motion are design decisions and are not subject to the
  YAGNI ladder.
- Adoption is opt-in per PWA; a PWA that does not link the file is unaffected. Existing PWAs
  migrate opportunistically when next touched.

## Alternatives Considered

1. **Per-PWA bespoke CSS with no shared layer.** Rejected: that is the status quo that produced
   lookalike apps and unreviewable drift; also violates shared-helper governance (ADR-079) in spirit.
2. **A CSS framework (Tailwind/Pico/etc.).** Rejected: conflicts with ADR-013 single-file
   no-framework architecture, adds build tooling, and bloats offline caches.
3. **One global restyle of all PWAs at once.** Rejected: big-bang visual change confuses field
   users mid-campaign; opportunistic per-PWA adoption with SW cache-version bumps (ADR-005) is safer.

## Consequences

- Hub (pilot) runs `ember-v2`: gradient display typography (Sora/Manrope via Google Fonts,
  `font-display:swap`, SW runtime-cached), layered card gradients, elevation scale, focus rings.
  Hub SW bumped to v36 with theme-v2.css in the precache shell.
- Fonts introduce a first-load network fetch; offline falls back to system stack — acceptable.
- Each adopting PWA must bump its SW cache version (ADR-005) and note the preset in its
  `dbt_<pwa>.md`.
- Style-guide §2 (identity-and-design-system.md) remains the reference for the classic look;
  a preset row table there points to theme-v2.
