# Change Request CR-005 — UI Overhaul

**Project:** Deadhead: Space Freight Tycoon
**Applies to:** a build with Phases 1–10, CR-001, CR-002, CR-003 and CR-004 complete
**Do this:** as **Phase 10E**, after Phase 10D and before Phase 11
**Related docs:** `implementation-plan.md`, `CR-003-map-art.md`, `DECISIONS.md`

---

## 1. Why

Every screen except the map is plain slate cards with small text, and navigation is a row of seven small text links at the bottom of the screen. It works, but it doesn't look or feel like a game. The map art from CR-003 is the only place the game's look shows up.

This change gives the whole client one visual identity, a "freight terminal HUD": deep-space backgrounds, glowing amber and cyan accents, a techy display font for headings and numbers, big icon navigation, and the existing planet and ship art used on the screens, not just the map.

It is **presentation only**. No game rules, API calls, copy or accessible names change, so the existing client tests are the regression suite for this phase.

## 2. Visual direction

| Element | Direction |
|---|---|
| Background | The map's `bg.webp` behind every screen, dimmed under a navy gradient, so all screens are "in space". |
| Surfaces | Translucent navy panels with a thin cool border, a soft inner highlight and corner brackets on feature panels. |
| Accents | Amber = primary actions and the player's selection. Cyan = in flight and info. Emerald = money in and success. Rose = errors and blocks. Fuchsia = scripted story jobs. |
| Type | **Chakra Petch** (display: headings, numbers, tab labels, buttons, uppercase eyebrow labels) and **Barlow** (body). Self-hosted with `@fontsource`, so it works offline (Phase 11 PWA). |
| Numbers | Credits, payouts and countdowns use the display font with tabular figures; key numbers are large. |
| Navigation | Icon and label tabs. Phone: a bottom bar with 24 px icons and a glowing active indicator. Desktop (≥ 768 px): a left rail. Small badges call attention to things waiting for the player. |
| Art | The map's sprites (`public/assets/map-gen`): ship art on Fleet, Market and the dispatch sheet; planet art on Locations, the contract cards' route, the map panels and HQ. |
| Motion | Screens fade and rise in; buttons press down; claimable goals and ready badges pulse gently. All motion is off under `prefers-reduced-motion`. |

## 3. Rules for this change

- All rules in `implementation-plan.md` §0.1 apply: steps in order, one commit per step, each step's test must pass, and `progress.md` is updated after every step.
- **No behavior changes.** Visible copy, roles and accessible names stay as they are, except where a step says otherwise. Existing tests must keep passing without edits to their assertions (a test may change only to follow a renamed or moved element that a step names).
- **Styling goes through the UI kit and theme tokens** (Step 10E.1–10E.2). Screens should not hard-code the old `slate-*` palette.
- No new art. Screens reuse the generated map sprites; the map's style config (`map/style.ts`) stays the map's own.
- Visual quality is a manual check: steps marked "manual check" end with desktop and phone screenshots in `docs/screenshots/`, named in `progress.md`. Stop for the user's review at the end of Phase 10E.

## 4. Decisions

Record these in `DECISIONS.md` (as plan §0.5.47–0.5.51).

- **0.5.47 Visual identity.** One "freight terminal HUD" look for the whole client (§2): space background, translucent panels, amber/cyan/emerald/rose/fuchsia accent roles, Chakra Petch + Barlow, self-hosted.
- **0.5.48 Tokens and kit.** Colors, fonts, radii, shadows and motion are Tailwind theme tokens in `apps/web/src/index.css`. Shared components (buttons, panels, sheets, stat tiles, meters, pills, screen headers, art) live in `apps/web/src/ui/`. Screens compose these.
- **0.5.49 Navigation.** Icon tabs, bottom bar on phones and a left rail from 768 px wide. Tab order and labels are unchanged. Attention badges are decorative (`aria-hidden`), so each tab's accessible name stays its label; the same information is on the screens.
- **0.5.50 Art on screens.** Ships and locations show their content `sprite` from the generated map art, as plain `<img>` with empty `alt` (the name is always in text next to it). A missing image hides itself, matching decision 0.5.41.
- **0.5.51 Presentation only.** The overhaul changes no game rules, API calls, copy or accessible names (§3).

## 5. Steps — Phase 10E

### Step 10E.1 — Fonts, theme tokens and backdrop
- Add `@fontsource/chakra-petch` and `@fontsource/barlow`. Define theme tokens in `index.css` (`@theme`): fonts, the panel/ink color scale, accent colors, glow shadows and keyframes (rise-in, pulse). Body uses Barlow; a global backdrop shows `bg.webp` under a dark gradient.
- Respect `prefers-reduced-motion` globally.
- **Test:** a test reads `index.css` and checks the font families, the backdrop image and the reduced-motion rule are present.

### Step 10E.2 — UI kit
- `src/ui/`: `Button` (primary, secondary, ghost, success, danger; sizes; pressed feedback), `Panel` (plain, feature with corner brackets, tone), `Sheet` (modal shell: backdrop, bottom sheet on phones, centered card from `sm`), `StatTile`, `Meter` (labelled `progressbar`), `Pill`, `ScreenHeader` (eyebrow, title as the screen's `h1`, subtitle), `Art` (sprite image), and the icon set used by navigation and screens.
- **Test:** `ui-kit.test.tsx`: buttons keep `type="button"` and forward `disabled`; `Meter` exposes progressbar values; `Sheet` is an `aria-modal` dialog labelled by its title; `ScreenHeader` renders a level-1 heading; `Art` resolves sprite URLs and hides on error.

### Step 10E.3 — App shell
- HUD header: logo mark and wordmark, credits in a glowing chip, game clock chip. The `Credits` and `Game clock` labels stay.
- Navigation per decision 0.5.49: bottom icon bar on phones, left rail from `md`. Badges: HQ = goals ready to claim; Jobs = idle crewed ships not resting; Pilots = pilots with unspent skill points. Computed by a pure `tabAttention(state)`.
- The map screen fills exactly the space left by the new header and navigation on both layouts.
- **Test:** existing `layout.test.tsx` passes; new tests for `tabAttention` and for a badge appearing without changing the tab's accessible name.

### Step 10E.4 — HQ dashboard
- Company hero (name, credits large), icon stat tiles, a "Next arrival" panel with a route strip and live progress, pilot rest, the tutorial card as a story panel, goals with reward pills, the loan with a meter.
- **Test:** existing HQ, goals, loan and rest tests pass. **Manual check.**

### Step 10E.5 — Contracts and dispatch
- Location switcher as planet chips. Contract cards: a route strip (origin art → line → destination art), cargo and mass, a large payout, requirement pills, expiry, and a prominent Dispatch button. The tutorial board gets the same card, with suggested and scripted variants. The dispatch sheet uses the `Sheet` and shows each ship with its art and the numbers as stat tiles.
- **Test:** existing contracts, tutorial board, dispatch and board refresh tests pass. **Manual check.**

### Step 10E.6 — Fleet and Market
- Ship cards with ship art, a status pill (idle, in flight), the route and a progress meter in flight, and actions as buttons. The deadhead picker uses `Sheet`. Market cards are "showroom" cards: large art, price, and stat meters for speed, capacity and range relative to the best model, plus landing class.
- **Test:** existing fleet and market tests pass. **Manual check.**

### Step 10E.7 — Pilots
- Pilot cards with an initials badge, level and XP meter, skills as pips out of their maximum with a raise button, the duty meter (amber, rose when near the limit) or rest status, and actions as buttons. The hire panel becomes a feature panel.
- **Test:** existing pilots and duty tests pass. **Manual check.**

### Step 10E.8 — Locations, map panels, start screen and dialogs
- Location cards with planet art, details as a compact spec list, the HQ status pill and the lease button. Undiscovered locations show dimmed art and a lock. The map's location and flight panels get the panel style with art. The start screen becomes a title screen over the space backdrop, with the sun and planets. The away summary and the deal use `Sheet`.
- **Test:** existing locations, map interaction, onboarding, away summary and deal tests pass. **Manual check.**

### Step 10E.9 — Regression and review
- Full suite, coverage, lint, typecheck and web build green. Screenshots of every screen at desktop and phone width (tutorial and mid-game). **Phase 10E complete — stop for review.**

## 6. Amendments to earlier steps

- **Step 8.2 (layout):** the header and bottom navigation are restyled per decision 0.5.49; desktop uses a left rail.
- **Step 11.1 (PWA):** the self-hosted font files are part of the offline asset cache.