deadhead-space-freight-tycoon/memory-bank/change-requests/CR-005-ui-overhaul.md

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.
• Amended by CR-020: The HQ dashboard became the Dashboard ("Bridge"), led by the player pilot's ship and an Alerts panel; "Next arrival" became "Ships on jobs" (every flight); owned HQs moved to their own tab (Phase 20).

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.1 (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.