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>
7.5 KiB
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_newcopies). Branchfeature/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), Msrc/fonts.ts, Mtailwind.config.ts(font family key) - M
src/theme/tokens.ts, Msrc/theme/ThemeProvider.tsx, Msrc/index.css - C
public/theme-init.js, Mindex.html - C
src/shared/hooks/usePrefersReducedMotion.ts, Csrc/shared/hooks/usePrefersDark.ts - C
src/components/ui/ModeToggle.tsx, Csrc/components/ui/VariantToggle.tsx, Dsrc/components/ui/ThemeToggle.tsx - C
src/components/layout/VariantRenderer.tsx, Csrc/components/layout/TransitionOverlay.tsx, Csrc/components/layout/LiveRegion.tsx, Csrc/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, Msrc/components/layout/RootLayout.tsx - Tests: M
src/theme/__tests__/ThemeProvider.test.tsx, Msrc/components/layout/__tests__/Nav.test.tsx, Csrc/theme/__tests__/tokens.test.ts, Csrc/shared/hooks/__tests__/*.test.ts(x), Csrc/components/layout/__tests__/VariantRenderer.test.tsx, Csrc/components/layout/__tests__/TransitionOverlay.test.tsx, Csrc/components/ui/__tests__/ModeToggle.test.tsx, Csrc/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 buildare 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 insrc/fonts.tsnext to the existing fonts (old fonts are removed in U2); add TailwindfontFamily.archivo. - Step 2 — Tokens (pure logic): rewrite
src/theme/tokens.ts: typesVariant,Mode,ModeSource; constantsMODE_STORAGE_KEY = 'slp-software-mode',LEGACY_THEME_STORAGE_KEY = 'slp-software-theme'; pure functionsisValidMode,resolveInitialMode(stored, systemPrefersDark)returning{ mode, source }. (BR-U1-1, 2, 11) - Step 3 — Media-query hooks:
usePrefersReducedMotion,usePrefersDark(SSR-safe, subscribe/unsubscribe, jsdom-safe whenmatchMediais missing → defaults false). (BR-U1-3, 9) - Step 4 — CSS tokens: in
src/index.cssreplace.theme-red/.theme-purplewithhtml[data-variant='b'][data-mode='light'|'dark']and E placeholders ('e', light/dark, accent#AC0000) with the semantic variables; B accent#7A1414; transitions guarded byprefers-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, setsdata-variant="b"anddata-modeon<html>, mirrorsresolveInitialMode); add<script src="/theme-init.js"></script>(blocking, in<head>) inindex.html. No inline script. (BR-U1-5) - Step 6 — ThemeProvider: rewrite with
variant,mode,modeSource,toggleMode,toggleVariant,transition,announce; follow system changes while source issystem; persist mode on user toggle (guarded); remove the legacy key once; apply data attributes in an effect;toggleVariantruns the phases cover → swap → reveal (timers, ~300 ms each), scrolls to top and moves focus to#mainafter 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-onlyVariantToggle(label "Tijdreis: bekijk de site zoals vroeger" / "Terug naar nu", tooltip = label,data-testid="variant-toggle-button"),TransitionOverlay,LiveRegion,EBoundary,VariantRenderer(B eager, E viaReact.lazy(() => import('../../variants/e/LandingE')),Suspensefallback = cover, error → B + alert + retry). DeleteThemeToggle.tsx. (FR-4, FR-6, BR-U1-6..8, 12) - Step 8 — Layout integration:
Nav.tsxshowsModeTogglethenVariantToggle(desktop and mobile bar);RootLayout.tsxwraps content in<main id="main" tabIndex={-1}>, rendersVariantRenderer(B shell = Nav + page + Footer),TransitionOverlay,LiveRegion;LandingEis a minimal placeholder ("Tijdreis — in aanbouw") with its own nav containing the two toggles so the round trip is testable.src/routes/__root.tsxcomposition order unchanged. - Step 9 — Tests: per the acceptance list in
frontend-components.md(8 items): table-drivenresolveInitialMode; 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(runstsc -b). Fix and retry until green; report real counts. Manual smoke check of both modes viapnpm buildoutput 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.jsCSP/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-Byline 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 insrc/test/setup.tsadditions (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.