Files
SlpSoftware/aidlc-docs/features/redesign-modern-timetravel/construction/plans/theme-foundation-code-generation-plan.md
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

7.5 KiB

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

  • 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).
  • 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.
  • 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)
  • Step 3 — Media-query hooks: usePrefersReducedMotion, usePrefersDark (SSR-safe, subscribe/unsubscribe, jsdom-safe when matchMedia is missing → defaults false). (BR-U1-3, 9)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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.
  • 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.
  • 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.
  • 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).
  • 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.