Files
SlpSoftware/aidlc-docs/features/redesign-modern-timetravel/construction/plans/theme-foundation-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 0854e3a096 Thema-fundament: variant (B/E) x modus (licht/donker), tijdreis-knop en overgang
Vervangt rood/paars door tokens per variant en modus, voegt ModeToggle en
icoon-knop VariantToggle toe, VariantRenderer met lazy E-chunk, dither-overgang
(uit bij minder beweging), theme-init.js tegen themaflits en tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-09 21:14:11 +01:00

49 lines
7.5 KiB
Markdown

# Code Generation Plan — theme-foundation (U1)
Single source of truth for U1 Code Generation. Inputs: `unit-of-work.md` (U1), Functional Design in `construction/theme-foundation/functional-design/`, requirements FR-3..FR-6, NFR-1, NFR-3, NFR-7.
## Unit context
- **Workspace root**: `K:\Development\SlpSoftware\Projects\SlpSoftware` (brownfield; modify in place, no `_new` copies). Branch `feature/redesign-modern-timetravel`.
- **Dependencies**: none. **Blocks**: U2..U5. **External**: none.
- **Owned entities**: `ThemeState`, `StoredMode`, `TransitionState`, token sets (see domain-entities.md).
- **Interim visual note**: U1 swaps the token values (B light/dark replace red/purple). Existing sections keep using the semantic Tailwind colors and are restyled to design B in U2. The branch is not deployed between units.
- **Story/requirement mapping**: FR-3, FR-4, FR-5, FR-6 (shell), NFR-1 (toggle a11y, reduced motion), NFR-3 (self-hosted font), NFR-7.
## Files (modify = M, create = C, delete = D)
- M `package.json`, `pnpm-lock.yaml` (add `@fontsource-variable/archivo`), M `src/fonts.ts`, M `tailwind.config.ts` (font family key)
- M `src/theme/tokens.ts`, M `src/theme/ThemeProvider.tsx`, M `src/index.css`
- C `public/theme-init.js`, M `index.html`
- C `src/shared/hooks/usePrefersReducedMotion.ts`, C `src/shared/hooks/usePrefersDark.ts`
- C `src/components/ui/ModeToggle.tsx`, C `src/components/ui/VariantToggle.tsx`, D `src/components/ui/ThemeToggle.tsx`
- C `src/components/layout/VariantRenderer.tsx`, C `src/components/layout/TransitionOverlay.tsx`, C `src/components/layout/LiveRegion.tsx`, C `src/components/layout/EBoundary.tsx`
- C `src/variants/e/LandingE.tsx` (placeholder shell for the lazy chunk; real content in U5)
- M `src/components/layout/Nav.tsx`, M `src/components/layout/RootLayout.tsx`
- Tests: M `src/theme/__tests__/ThemeProvider.test.tsx`, M `src/components/layout/__tests__/Nav.test.tsx`, C `src/theme/__tests__/tokens.test.ts`, C `src/shared/hooks/__tests__/*.test.ts(x)`, C `src/components/layout/__tests__/VariantRenderer.test.tsx`, C `src/components/layout/__tests__/TransitionOverlay.test.tsx`, C `src/components/ui/__tests__/ModeToggle.test.tsx`, C `src/components/ui/__tests__/VariantToggle.test.tsx`
- Docs: C `aidlc-docs/features/redesign-modern-timetravel/construction/theme-foundation/code/summary.md`
## Steps
- [x] **Step 0 — Preparation**: commit the AI-DLC inception/design documents separately (`aidlc-docs/`) on the branch so code commits stay clean. Verify the baseline: `pnpm test`, `pnpm lint`, `pnpm build` are green before changes (record the numbers).
- [x] **Step 1 — Dependency and fonts**: add `@fontsource-variable/archivo` (variable weight + width axis) respecting the repo's pnpm settings; if the package is blocked by the release-age policy or missing, stop and report instead of working around it. Import it in `src/fonts.ts` next to the existing fonts (old fonts are removed in U2); add Tailwind `fontFamily.archivo`.
- [x] **Step 2 — Tokens (pure logic)**: rewrite `src/theme/tokens.ts`: types `Variant`, `Mode`, `ModeSource`; constants `MODE_STORAGE_KEY = 'slp-software-mode'`, `LEGACY_THEME_STORAGE_KEY = 'slp-software-theme'`; pure functions `isValidMode`, `resolveInitialMode(stored, systemPrefersDark)` returning `{ mode, source }`. (BR-U1-1, 2, 11)
- [x] **Step 3 — Media-query hooks**: `usePrefersReducedMotion`, `usePrefersDark` (SSR-safe, subscribe/unsubscribe, jsdom-safe when `matchMedia` is missing → defaults false). (BR-U1-3, 9)
- [x] **Step 4 — CSS tokens**: in `src/index.css` replace `.theme-red/.theme-purple` with `html[data-variant='b'][data-mode='light'|'dark']` and E placeholders (`'e'`, light/dark, accent `#AC0000`) with the semantic variables; B accent `#7A1414`; transitions guarded by `prefers-reduced-motion`; add the dither overlay classes (checker mask + `steps()` keyframes, accent colored), all disabled under reduced motion. (FR-3, BR-U1-9)
- [x] **Step 5 — No-flash script**: create `public/theme-init.js` (plain ES5, guarded storage access, sets `data-variant="b"` and `data-mode` on `<html>`, mirrors `resolveInitialMode`); add `<script src="/theme-init.js"></script>` (blocking, in `<head>`) in `index.html`. No inline script. (BR-U1-5)
- [x] **Step 6 — ThemeProvider**: rewrite with `variant`, `mode`, `modeSource`, `toggleMode`, `toggleVariant`, `transition`, `announce`; follow system changes while source is `system`; persist mode on user toggle (guarded); remove the legacy key once; apply data attributes in an effect; `toggleVariant` runs the phases cover → swap → reveal (timers, ~300 ms each), scrolls to top and moves focus to `#main` after the swap, immediate under reduced motion. (BR-U1-1..10, FR-5)
- [x] **Step 7 — UI components**: `ModeToggle` (aria-pressed = dark, label "Donkere weergave", ≥44px target on mobile, `data-testid="mode-toggle-button"`), icon-only `VariantToggle` (label "Tijdreis: bekijk de site zoals vroeger" / "Terug naar nu", tooltip = label, `data-testid="variant-toggle-button"`), `TransitionOverlay`, `LiveRegion`, `EBoundary`, `VariantRenderer` (B eager, E via `React.lazy(() => import('../../variants/e/LandingE'))`, `Suspense` fallback = cover, error → B + alert + retry). Delete `ThemeToggle.tsx`. (FR-4, FR-6, BR-U1-6..8, 12)
- [x] **Step 8 — Layout integration**: `Nav.tsx` shows `ModeToggle` then `VariantToggle` (desktop and mobile bar); `RootLayout.tsx` wraps content in `<main id="main" tabIndex={-1}>`, renders `VariantRenderer` (B shell = Nav + page + Footer), `TransitionOverlay`, `LiveRegion`; `LandingE` is a minimal placeholder ("Tijdreis — in aanbouw") with its own nav containing the two toggles so the round trip is testable. `src/routes/__root.tsx` composition order unchanged.
- [x] **Step 9 — Tests**: per the acceptance list in `frontend-components.md` (8 items): table-driven `resolveInitialMode`; ThemeProvider (first render, legacy key removal, system change following, user click stops following, persistence, storage failure, variant never persisted); variant switch (scroll to top, focus on `#main`, announcement, reduced-motion path with no overlay, failure path with alert + retry); accessibility attributes of both buttons; Nav test updates. Replace obsolete red/purple assertions.
- [x] **Step 10 — Build and test (automatic, Step 13.5)**: `pnpm lint`, `pnpm test`, `pnpm build` (runs `tsc -b`). Fix and retry until green; report real counts. Manual smoke check of both modes via `pnpm build` output is not required.
- [x] **Step 11 — Docs**: write `construction/theme-foundation/code/summary.md` (files, behaviour, how to use the hooks, notes for U2..U5, the `/theme-init.js` CSP/nginx note for Operations: must be served same-origin and not cached long).
- [x] **Step 12 — Commit**: one commit for U1 code (Dutch message in the repo's style, `Co-Authored-By` line as required). No push.
## Explicitly NOT touched in U1
Section content and layout (Hero, About, Packages, Process, Contact), `content.ts`, `usePackagesQuery`, Sentry/Umami wiring, nginx configs, router. Old fonts stay until U2. The E variant's real content is U5.
## Risks
- jsdom has no `matchMedia`/`scrollTo`: mocks live in `src/test/setup.ts` additions (Step 9).
- Dependency policy (release age) could block the font package: handled in Step 1 by reporting, not bypassing.
- The interim look changes (light default for many visitors) until U2; accepted because units are not deployed separately.
## Traceability
FR-3, FR-4, FR-5, FR-6 (shell), NFR-1, NFR-3, NFR-7; Functional Design BR-U1-1..12; Security Baseline: no inline script (CSP), guarded storage access, no external font requests.