magicciv/.project/objectives/p2-29-guide-welcome-homepage-theme-alignment.md

id	title	priority	status	scope	owner	updated_at	evidence
p2-29	Welcome modal + HomePage lore + guide theme align to the player's chosen race/gender	p2	done	game1	tourguide	2026-04-18	public/games/age-of-dwarves/guide/src/components/welcome/WelcomeModal.tsx public/games/age-of-dwarves/guide/src/pages/HomePage.tsx public/games/age-of-dwarves/guide/src/theme/fantasy-theme.ts src/packages/guide/src/theme/RaceThemeProvider.tsx public/games/age-of-dwarves/guide/src/contexts/PreferencesContext.tsx

Summary

The guide already exposes a welcome modal that lets the player pick a race (Dwarf in Game 1 — CONCRETE_RACES = ['dwarf']) and a gender, plus a RaceThemeProvider that merges a per-race/per-gender palette into the styled-components theme. But the three surfaces don't line up:

• WelcomeModal copy reads like a settings dialog ("Settings", field labels) rather than an invitation into the story, so the player's first impression is admin-UI-shaped.
• HomePage <LoreSection> does pull the player's race + name via usePreferences(), but the surrounding <Hero> / <Tagline> / <Pitch> hardcode out-of-scope narrative ("16 asymmetric races, 5 magic schools") that is Game 2/3 territory and does NOT update when the player picks a dwarf leader.
• Theme application — the palette change from RaceThemeProvider fires on confirm, but a browser already on the HomePage may not re-derive the Hero/Pitch colors in a visually coherent way (Cinzel serif, Dwarf copper #c07040, etc.). The "align with welcome" contract is not exercised.

When the player picks Dwarf + Female in the modal and clicks Begin, all three surfaces should read as one piece: a dwarf-themed guide, referring to the named dwarf leader, in Dwarf scope language (no "5 magic schools" pitch, no generic cross-race framing).

Closure (2026-04-18)

• WelcomeModal race grid dynamic: raceOptions = ALL_ELIGIBLE_RACES.filter(r => r.episode <= activeEpisode) via useEpisode(). Game 1 shows Dwarves only; VITE_DEV_GUIDE=1 reveals Kzzkyt + Elf races.
• App.tsx filters playableRaces before passing to PreferencesProvider so resolveRace('random') cannot roll a non-episode race.
• HomePage FEATURES data-driven via homepage-features.json with min_episode gating.
• public/games/age-of-dwarves/guide/e2e/welcome.spec.ts authored (Dwarf-Female → "Brenna Ironshield" → Enter the Guide → HomePage LoreEyebrow + Dwarf prose + zero console errors + no Game 2+ strings). Spec authored only, not executed; apricot Forgejo runner owns e2e verification.

Acceptance

• Race-aware Hero / Tagline / Pitch: the top-of-HomePage block no longer hardcodes cross-race copy. For Game 1 Dwarf scope, the pitch is Dwarf-first (craft, industry, mundane tech, fortress cities). When a future episode adds a second concrete race, the prose comes from a race-keyed data source (e.g. resources/races/<race>/guide_pitch.md) — not another <RaceHighlight>{race.name}</RaceHighlight> sprinkle.
• "Your story begins" block renders race-specific lore for the chosen race + gender. Dwarf-female reads coherently ("Your band of free Dwarves have chosen you, , as their leader" in a voice consistent with the Dwarf palette). The current ley-line / magic-schools paragraphs are gated behind <EpisodeGate min={2}> (Game 2 content) so a default Game 1 bundle shows Dwarf narrative only; VITE_DEV_GUIDE=1 keeps them visible per p1-15.
• Theme alignment: after confirming Dwarf + Female in the WelcomeModal, the RaceThemeProvider palette is live — theme.colors.primary.main === '#c07040' (dwarf copper), theme.typography.fontFamily.serif === "Cinzel, …", theme.colors.background.primary === '#1a1510'. HomePage's <Eyebrow> / <LoreEyebrow> / <FeatureCard> accents derive from those tokens and visibly shift from the default palette to the Dwarf palette within one render cycle.
• WelcomeModal voice: the modal's copy is rewritten in the same voice as HomePage. Instead of "Settings", the modal frames the choice as the start of the story ("Choose your leader" / "Your band of free Dwarves choose…" etc.). BeginButton label reinforces the story beat rather than "Save".
• Smoke test: pnpm --prefix public/games/age-of-dwarves/guide test:e2e --grep welcome (new spec) walks (1) load page fresh, (2) pick Dwarf + Female + type a name, (3) click Begin, (4) assert the HomePage <LoreEyebrow> reads "Your Story Begins" with the chosen name rendered in <RaceHighlight> + the body prose uses Dwarf vocabulary (no "magic schools" / "archons" strings). Console remains zero-error.

Non-goals

• Additional races beyond Dwarf — Game 2/3 race content stays gated.
• Multi-language / i18n for the prose — copy is authored in English, matching the rest of the guide.
• In-modal preview of HomePage changes — onPreview already flashes the palette; no need for a live HomePage inset.
• A new WelcomeModal design — this is a copy + theme-alignment pass, not a visual redesign.

Why this belongs to tourguide

Closes the "clone → click Begin → first-page impression" path that the dev-guide deploy (mc.next.black.local, p1-15) is meant to showcase. Same owner that authored the tabbed Progress Report + the Markdown component + the deploy pipeline.