AI-DLC: inception en ontwerp voor redesign B/E met contactformulier
Requirements, application design (incl. concept-API-contract voor het contactformulier), units en functional design voor U1. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
+45
@@ -0,0 +1,45 @@
|
||||
# Business Logic Model — theme-foundation (U1)
|
||||
|
||||
## Startup
|
||||
1. `/theme-init.js` (blocking, same origin) reads the stored mode (guarded), falls back to `prefers-color-scheme`, and sets `data-variant="b"` and `data-mode` on `<html>`.
|
||||
2. `ThemeProvider` initializes its state with the same function (`resolveInitialMode`) so React and the script always agree; it removes the legacy key `slp-software-theme`.
|
||||
3. `ThemeProvider` subscribes to the `prefers-color-scheme` media query; while `modeSource = 'system'` the mode follows it.
|
||||
|
||||
## Mode toggle
|
||||
`toggleMode()`: `mode = (mode === 'light') ? 'dark' : 'light'`, `modeSource = 'user'`, persist (guarded), update `<html data-mode>`.
|
||||
|
||||
## Variant switch (sequence)
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(99,179,237,0.4) Browser UI
|
||||
participant U as Visitor
|
||||
participant VT as VariantToggle
|
||||
participant TP as ThemeProvider
|
||||
participant TO as TransitionOverlay
|
||||
end
|
||||
box rgba(154,230,180,0.4) App
|
||||
participant VR as VariantRenderer
|
||||
end
|
||||
U->>VT: click
|
||||
VT->>TP: toggleVariant
|
||||
TP->>TO: start cover
|
||||
TO-->>TP: cover done
|
||||
TP->>VR: set variant, load E chunk if needed
|
||||
VR-->>TP: ready or failed
|
||||
TP->>TP: scroll to top and move focus
|
||||
TP->>TO: reveal
|
||||
TP-->>U: announce result in live region
|
||||
```
|
||||
|
||||
Text alternative: the click asks the theme provider to switch; the overlay covers the page; the renderer loads and swaps the variant; the provider scrolls, moves focus, reveals and announces.
|
||||
|
||||
## Time-travel transition (effect)
|
||||
- **cover**: a full-viewport overlay with a pixel-dither pattern (CSS `steps()` animation over a checker mask, accent-coloured) fades in over ~300 ms; pointer events are blocked and `aria-hidden` is set.
|
||||
- **swap**: variant changes, `data-variant` updated, scroll to top, focus to `main`.
|
||||
- **reveal**: the dither clears over ~300 ms. Total about 600 ms plus E chunk load time on first visit.
|
||||
- Reduced motion: none of this renders.
|
||||
|
||||
## Error handling
|
||||
- Storage unavailable: mode works for the session only.
|
||||
- E chunk fails to load: stay in B, show the alert, offer retry; the overlay is removed.
|
||||
- Media query unsupported: treat as light.
|
||||
+60
@@ -0,0 +1,60 @@
|
||||
# Business Rules — theme-foundation (U1)
|
||||
|
||||
| Id | Rule |
|
||||
|---|---|
|
||||
| BR-U1-1 | The variant is `'b'` on every page load. It is never read from or written to storage or the URL. |
|
||||
| BR-U1-2 | Initial mode: a valid stored mode wins; otherwise `dark` if `prefers-color-scheme: dark`, else `light`. |
|
||||
| BR-U1-3 | While `modeSource = 'system'`, the mode follows live changes of the system preference. After the user clicks the mode button, `modeSource = 'user'` and system changes are ignored. |
|
||||
| BR-U1-4 | The mode button toggles light and dark (two states), sets `modeSource = 'user'` and persists the new mode. Storage errors never break the toggle (state still changes for the session). |
|
||||
| BR-U1-5 | The initial `data-variant` and `data-mode` are set before first paint by a small same-origin script (`/theme-init.js`, no inline script, CSP-friendly) so there is no flash of the wrong theme; React then takes over the same values. |
|
||||
| BR-U1-6 | The variant button switches between B and E using the time-travel transition (cover → swap → reveal). After the swap the page scrolls to the top and focus moves to the start of the new page (skip target / `main`). |
|
||||
| BR-U1-7 | A live region announces the change in Dutch ("Tijdreis-weergave geladen." / "Terug naar de moderne weergave."). |
|
||||
| BR-U1-8 | E is loaded lazily. While it loads, the transition stays in `cover`. If loading fails, the variant stays `'b'`, the cover is removed and an alert says "De tijdreis kon niet worden geladen." with a retry; B stays usable. |
|
||||
| BR-U1-9 | Under `prefers-reduced-motion: reduce` there is no transition, no dither, no fade: the swap is immediate (all other rules still apply). |
|
||||
| BR-U1-10 | The mode is shared by both variants; switching variant keeps the mode. |
|
||||
| BR-U1-11 | The old red/purple themes and their classes (`theme-red`, `theme-purple`) are removed; the old storage key is ignored and removed. |
|
||||
| BR-U1-12 | Both buttons are real `<button>`s with accessible names, visible focus and at least 44×44 px touch targets on mobile; the mode button exposes `aria-pressed` (dark), the variant button has a label that changes with the current variant. |
|
||||
|
||||
## Decision flow: initial mode
|
||||
```mermaid
|
||||
graph TD
|
||||
S([Page load]) --> A{Stored mode valid}
|
||||
A -->|"yes"| B[Use stored mode and source user]
|
||||
A -->|"no"| C{System prefers dark}
|
||||
C -->|"yes"| D[Mode dark and source system]
|
||||
C -->|"no"| E[Mode light and source system]
|
||||
classDef start fill:#CE93D8,stroke:#6A1B9A,color:#000;
|
||||
classDef decision fill:#FFF59D,stroke:#F57F17,color:#000;
|
||||
classDef result fill:#9ae6b4,stroke:#2f855a,color:#000;
|
||||
class S start;
|
||||
class A,C decision;
|
||||
class B,D,E result;
|
||||
```
|
||||
|
||||
Text alternative: a valid stored mode is used; otherwise the system preference decides, and the source is system.
|
||||
|
||||
## Decision flow: variant switch
|
||||
```mermaid
|
||||
graph TD
|
||||
K([Variant button]) --> R{Reduced motion}
|
||||
R -->|"yes"| W[Swap immediately]
|
||||
R -->|"no"| CV[Cover with dither]
|
||||
CV --> L{Target is E}
|
||||
L -->|"yes"| LD[Load E chunk]
|
||||
L -->|"no"| W
|
||||
LD --> OK{Loaded}
|
||||
OK -->|"yes"| W
|
||||
OK -->|"no"| ER[Stay in B and show alert]
|
||||
W --> SC[Scroll to top and move focus]
|
||||
SC --> RV[Reveal and announce]
|
||||
classDef start fill:#CE93D8,stroke:#6A1B9A,color:#000;
|
||||
classDef decision fill:#FFF59D,stroke:#F57F17,color:#000;
|
||||
classDef step fill:#63b3ed,stroke:#2b6cb0,color:#000;
|
||||
classDef bad fill:#ffab91,stroke:#bf360c,color:#000;
|
||||
class K start;
|
||||
class R,L,OK decision;
|
||||
class W,CV,LD,SC,RV step;
|
||||
class ER bad;
|
||||
```
|
||||
|
||||
Text alternative: the variant button covers the page with the dither (unless reduced motion), loads E when needed, swaps, scrolls to the top, reveals and announces; a loading failure keeps B and shows an alert.
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
# Domain Entities — theme-foundation (U1)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
TS[ThemeState] -->|"variant"| V[Variant b or e]
|
||||
TS -->|"mode"| M[Mode light or dark]
|
||||
TS -->|"modeSource"| MS[ModeSource system or user]
|
||||
M -->|"persisted as"| SM[StoredMode in localStorage]
|
||||
TS -->|"drives"| DA[html data-variant and data-mode]
|
||||
DA -->|"selects"| TK[Token set]
|
||||
TR[TransitionState] -->|"target"| V
|
||||
TR -->|"phase"| PH[idle cover swap reveal]
|
||||
classDef state fill:#63b3ed,stroke:#2b6cb0,color:#000;
|
||||
classDef value fill:#9ae6b4,stroke:#2f855a,color:#000;
|
||||
classDef out fill:#f6e05e,stroke:#c05621,color:#000;
|
||||
class TS,TR state;
|
||||
class V,M,MS,PH value;
|
||||
class SM,DA,TK out;
|
||||
```
|
||||
|
||||
Text alternative: the theme state holds variant, mode and where the mode came from; mode is persisted, the state is written to the html element, which selects the token set; a separate transition state tracks the switch animation toward a target variant.
|
||||
|
||||
## ThemeState
|
||||
| Field | Type | Rule |
|
||||
|---|---|---|
|
||||
| `variant` | `'b' \| 'e'` | initial always `'b'`; never persisted |
|
||||
| `mode` | `'light' \| 'dark'` | initial from stored value, else system preference |
|
||||
| `modeSource` | `'system' \| 'user'` | `'system'` until the user clicks the mode button |
|
||||
|
||||
## StoredMode
|
||||
- localStorage key `slp-software-mode`, value `'light'` or `'dark'` only; anything else counts as "nothing stored". Reads and writes are guarded (private mode, blocked storage).
|
||||
- The old key `slp-software-theme` (red/purple) is ignored and removed once on startup.
|
||||
|
||||
## TransitionState
|
||||
| Field | Type | Rule |
|
||||
|---|---|---|
|
||||
| `phase` | `'idle' \| 'cover' \| 'swap' \| 'reveal'` | `idle` when reduced motion is on or no switch is running |
|
||||
| `target` | `Variant \| null` | variant being switched to |
|
||||
|
||||
## Token sets (CSS custom properties)
|
||||
Selected by `html[data-variant][data-mode]`: B light, B dark, E light, E dark. Semantic names stay (`--color-bg`, `--color-surface`, `--color-surface-2`, `--color-line`, `--color-text`, `--color-muted`, `--color-accent`, `--color-accent-soft`, `--color-accent-line`, `--color-accent-hover`, `--color-accent-contrast`) so existing Tailwind color names keep working. Accents: B `#7A1414`, E `#AC0000`. B dark values follow the canvas (page `#0F0E0E`, ink `#F3F0EC`, muted `#B3ADA7`, alt `#181615`, card `#232020`, line `#3A3532`, marks `#E5524A`); E dark values per era are defined in U5; U1 provides the E base tokens as placeholders.
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
# Frontend Components — theme-foundation (U1)
|
||||
|
||||
## Component hierarchy
|
||||
```mermaid
|
||||
graph TD
|
||||
root[__root route] --> eb[ErrorBoundary]
|
||||
eb --> tp[ThemeProvider]
|
||||
tp --> qc[QueryClientProvider]
|
||||
qc --> rl[RootLayout]
|
||||
rl --> ua[UmamiAnalytics]
|
||||
rl --> vr[VariantRenderer]
|
||||
rl --> to[TransitionOverlay]
|
||||
rl --> lr[LiveRegion]
|
||||
vr --> lb[LandingB eager]
|
||||
vr --> ee[EBoundary]
|
||||
ee --> le[LandingE lazy]
|
||||
lb --> mt[ModeToggle]
|
||||
lb --> vt[VariantToggle]
|
||||
le --> mt2[ModeToggle]
|
||||
le --> vt2[VariantToggle]
|
||||
tp -.provides.-> hooks[useTheme]
|
||||
hooks --> mt
|
||||
hooks --> vt
|
||||
classDef layout fill:#4CAF50,stroke:#2e7d32,color:#000;
|
||||
classDef guard fill:#FF9800,stroke:#e65100,color:#000;
|
||||
classDef ui fill:#2196F3,stroke:#0d47a1,color:#000;
|
||||
classDef hook fill:#9C27B0,stroke:#4a148c,color:#000;
|
||||
class root,rl,tp,qc layout;
|
||||
class eb,ee guard;
|
||||
class vr,lb,le,mt,vt,mt2,vt2,to,lr,ua ui;
|
||||
class hooks hook;
|
||||
```
|
||||
|
||||
Text alternative: the root route wraps the app in an error boundary, theme provider and query provider; the layout renders the variant renderer (eager B, lazy E behind its own boundary), the transition overlay and a live region; both landings contain the two toggle buttons that use the theme hook.
|
||||
|
||||
## Components
|
||||
| Component | Props | State / behaviour |
|
||||
|---|---|---|
|
||||
| `ThemeProvider` | `children` | holds `ThemeState` and `TransitionState`; exposes `{ variant, mode, toggleMode, toggleVariant, transition, announce }` via `useTheme()`; implements BR-U1-1..11 |
|
||||
| `ModeToggle` | none | button, `aria-pressed = (mode==='dark')`, label "Donkere weergave", icon sun/moon; calls `toggleMode` |
|
||||
| `VariantToggle` | none | icon-only button (clock/rewind), label "Tijdreis: bekijk de site zoals vroeger" in B and "Terug naar nu" in E, tooltip equal to the label; calls `toggleVariant` |
|
||||
| `VariantRenderer` | none | renders `LandingB` or `React.lazy(LandingE)` inside `Suspense`; fallback is the cover overlay |
|
||||
| `EBoundary` | `children` | error boundary for the lazy chunk; on error resets variant to `'b'` and shows the alert with a retry button (BR-U1-8) |
|
||||
| `TransitionOverlay` | none | reads `transition.phase`; renders the dither overlay only for `cover` and `reveal`; `aria-hidden`, blocks pointer events; nothing under reduced motion |
|
||||
| `LiveRegion` | none | polite `aria-live` region for the announcements in BR-U1-7 |
|
||||
| `usePrefersReducedMotion` / `usePrefersDark` | none | subscribe to the media queries (SSR-safe defaults) |
|
||||
|
||||
## User interaction flows
|
||||
- Mode button: click → mode flips immediately, persisted, `aria-pressed` updates.
|
||||
- Variant button: click → transition (or immediate under reduced motion) → new variant at top of page, focus on `main`, announcement.
|
||||
- Keyboard: both buttons reachable in the nav in DOM order (mode, variant), Enter/Space activate; Escape does not interfere with the mobile menu.
|
||||
|
||||
## Form validation rules
|
||||
None in this unit.
|
||||
|
||||
## API integration points
|
||||
None (client-only). The existing Sentry and Umami integration is untouched.
|
||||
|
||||
## Acceptance tests (Vitest + Testing Library)
|
||||
1. `resolveInitialMode`: stored valid wins; invalid/absent falls back to system; table-driven.
|
||||
2. First render: `data-variant="b"`, `data-mode` from system; legacy key removed.
|
||||
3. System preference change flips the mode while source is system, not after a user click.
|
||||
4. Mode click persists to `slp-software-mode`; storage that throws does not break the toggle.
|
||||
5. Variant is `'b'` after a fresh mount even if E was active before (not persisted).
|
||||
6. `toggleVariant`: scrolls to top and moves focus; announces; under reduced motion no overlay phases occur.
|
||||
7. Lazy chunk failure: variant stays `'b'`, alert shown, retry works.
|
||||
8. Accessibility: accessible names, `aria-pressed`, 44×44 px class, focus-visible styles.
|
||||
Reference in New Issue
Block a user