Activity

What this PR delivers

The plan itself, not code. Implementation lands in subsequent per-phase PRs.

After merging this, anyone can pick up the work from a blank slate by reading docs/ux-overhaul/ — start at README.md for the status board, follow KICKOFF.md to resume in a fresh Claude session.

Why

We've been playing whack-a-mole. The May 2026 Playwright audit surfaced 21 issues across the public site spanning data freshness, mobile responsiveness, link/typography inconsistency, navigation, brand coherence and edge-state messaging. Fixing them one at a time duplicates effort and produces drift. This plan establishes a tokens foundation + structured phase sequence so the work becomes additive instead of patchwork.

Contents

docs/ux-overhaul/
├── README.md                # status board + how to use
├── 00-audit.md              # the audit findings
├── 01-tokens-spec.md        # wire-service-editorial aesthetic + tokens
├── 02-process.md            # how to brief sub-agents + review
├── KICKOFF.md               # fresh-session prompt
└── phases/
    ├── phase-1-tokens-foundation.md        # tokens.css + Tailwind v4 wiring
    ├── phase-2-datatable-primitive.md      # responsive DataTable (replaces Leaderboard)
    ├── phase-3-data-freshness.md           # timestamps + contextual empty states
    ├── phase-4-visual-language.md          # SmartLink, MetricValue, type hierarchy
    ├── phase-5-navigation-transitions.md   # Breadcrumb, Inertia progress
    ├── phase-6-content-polish.md           # /reports/index card upgrade
    ├── phase-7-color-semantics.md          # StatusBadge, 3-colour palette applied
    └── phase-8-showpiece-additions.md      # per-prediction share view + pre-warm

Each phase doc is complete — sub-agent brief, file list, acceptance criteria, verification commands. A fresh-context Claude session can execute any phase by reading the relevant doc.

What changes if this lands

• Future UX work cuts a phase-specific branch (feature/ux-phase-N-<slug>), not arbitrary ad-hoc commits to main.
• Sub-agents get a structured brief from the phase doc rather than ad-hoc conversational prompts.
• The status board in README.md is the single source of truth for progress.

Test plan

• All docs render correctly in GitHub's markdown viewer
• No code changes — existing tests unaffected
• No production impact (docs-only)

Review notes

• The audit screenshots referenced in 00-audit.md are gitignored (audit-*.png at repo root). They exist locally as evidence; happy to upload to the PR description if useful.
• Tokens spec was produced by the /frontend-design skill on 2026-05-16. It honours the existing zinc/emerald + Instrument Serif identity while adding the missing amber + rose semantic accents.
• KICKOFF.md is intentionally self-contained so a future Stu or future Claude can resume without re-reading conversation history.