Adds AI-DLC inception docs for the front-end shell feature

Workspace detection, reverse engineering of web/, requirements with
answered verification questions, the execution plan and the open
application design questions for the frontend-shell feature.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-14 13:03:26 +02:00
co-authored by Claude Opus 5.5
parent 8f5841c6cb
commit db2fa89b90
18 changed files with 1403 additions and 0 deletions
@@ -0,0 +1,110 @@
# Application Design Plan — frontend-shell
Depth: **minimal**. Single front-end package; the design pins down component boundaries, props, shared pieces and what moves into the theme (NFR-02 reuse principle). Detailed behaviour rules follow in Functional Design.
## Plan
- [ ] 1. Answer the design questions below
- [ ] 2. Analyze answers for ambiguities (follow-up questions if needed)
- [ ] 3. Generate `components.md` — component definitions and responsibilities
- [ ] 4. Generate `component-methods.md` — props/signatures of components, hooks and helpers
- [ ] 5. Generate `services.md` — router configuration, head management, content provisioning
- [ ] 6. Generate `component-dependency.md` — dependency matrix, data flow
- [ ] 7. Generate `application-design.md` — consolidated design
- [ ] 8. Validate completeness and consistency (requirements FR-01…FR-11, NFR-01…NFR-05, Security/PBT applicability)
## Already decided (no question needed)
These follow directly from the requirements and the reuse principle (NFR-02):
- **Skip link**: use Chakra's built-in `SkipNavLink` + `SkipNavContent` (`id="main"`, rendered `as="main"`). Restyle via the theme's `skipNavLink` recipe so it matches the design (ink background, white text).
- **Back-to-top visibility**: reuse the existing `useScrolledPast` hook, with a module-level threshold function (60% of the viewport height).
- **Icons**: `@iconify/react/offline` with the bundled `up-outlined` from `@iconify-icons/ant-design`.
- **404 / error buttons**: the existing `LinkButton` (`linkButton` recipe).
- **Footer column headings**: the existing `eyebrow` text style.
---
## Questions
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**.
### Vraag 1: Mappenstructuur van de shell-componenten
Nu staat `AppShell.tsx` los in `components/`, met `NavigationBar/` en `Hero/` als eigen mappen.
A) Per component een eigen map, zoals nu: `components/Footer/`, `components/BackToTop/`, `components/StatusPage/`… `AppShell.tsx` blijft waar het is. **(aanbevolen)** Dit sluit aan bij het bestaande patroon.
B) Eén map `components/Shell/` met `AppShell`, `Footer/`, `BackToTop`, `NavigationBar/` erin (NavigationBar verhuist)
C) Een aparte map `layout/` naast `components/` voor alles wat shell is
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 2: Waar komt de content-module te staan, en verhuist `heroContent` mee?
A) Nieuwe map `src/content/` met `siteContent.ts` en de types. `heroContent.ts` en de types in `Hero/types.ts` verhuizen mee, zodat alle "straks-uit-de-API"-data op één plek staat. **(aanbevolen)**
B) Nieuwe map `src/content/` alleen voor `siteContent`. `heroContent` blijft bij de Hero.
C) `src/siteContent.ts` los naast `seo.ts`
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 3: Hoe krijgen Footer en Hero de site-content binnen?
A) Via props: `AppShell` geeft `siteContent` door aan `Footer`, en de home-route geeft de socials door aan `Hero`. Dat is hetzelfde patroon als de Hero nu met `content` werkt, en makkelijk te testen. Als de API er is, wordt alleen de bron vervangen (bv. een route-loader). **(aanbevolen)**
B) Componenten importeren `siteContent` direct. Dat is het simpelst, maar later moet elk component aangepast worden.
C) Een React-context (`SiteContentProvider` + `useSiteContent()`) rond de app, klaar om later met data uit de API gevuld te worden
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 4: Waar staan de menu-items voor het footermenu?
De items van het hoofdmenu (`navItems`) zijn routes, en routes zijn code: het CMS kan geen pagina's toevoegen. In de requirements (FR-04) stond het footermenu in `siteContent`.
A) Het footermenu staat naast `navItems` in de navigatiecode (bijvoorbeeld `navigation.ts` met `mainNav` en `footerNav`), getypeerd op bestaande routes. `siteContent` bevat alleen echte content (tekst, socials, e-mail). Ik pas FR-04 hierop aan. **(aanbevolen)**
B) Het footermenu staat in `siteContent`, zoals in FR-04. De `to`-waarden zijn gewone strings, dus de router controleert de types minder streng.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 5: Opbouw van de placeholder-pagina's
Vijf routes krijgen voorlopig placeholder-inhoud: portfolio, soorten-fotoshoots, contact, privacyverklaring en over-mij.
A) Een herbruikbaar `PageIntro`-component: ruimte onder de header, `Container`, eyebrow en `h1`. De placeholders gebruiken het nu, en de echte pagina's straks als bovenste blok (het "Intro"-blok uit LAYOUT.md). **(aanbevolen)**
B) Een apart `PagePlaceholder`-component, alleen voor de placeholders, dat later weer verdwijnt
C) Per route inline, zonder gedeeld component
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 6: 404- en foutpagina
A) Eén gedeeld `StatusPage`-component (titel, tekst, knop naar home). `NotFound` en `ErrorPage` zijn er dunne wrappers omheen. **(aanbevolen)**
B) Twee losse componenten
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 7: Stijl van de footerlinks
Footerlinks (socials, e-mail, footermenu) delen één stijl: zachte kleur, accent bij hover, en een zichtbare focusring. Die stijl komt op meer dan twee plekken voor, dus centraliseren is zinvol.
A) Chakra's ingebouwde `Link`-recipe uitbreiden met een variant `subtle` in het thema. Footerlinks worden `<Link variant="subtle">`, en voor router-links gebruiken we `<Link asChild><RouterLink …/></Link>`. Zo benutten we Chakra zelf. **(aanbevolen)**
B) Een eigen nieuwe recipe `subtleLink`, naast `linkButton`
C) Een klein `FooterLink`-component met style props, zonder thema-uitbreiding
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 8: Gedeelde router-link en bestaande code
`chakra(Link)` wordt nu in drie bestanden apart gedefinieerd: `NavLink`, `MobileNav` en `LinkButton`.
A) Eén gedeelde `RouterLink` (in `components/RouterLink.tsx`) en de drie bestaande bestanden daarop omzetten. Dat is een kleine, veilige refactor. **(aanbevolen)**
B) Alleen de nieuwe code gebruikt de gedeelde `RouterLink`. Bestaande bestanden blijven zoals ze zijn.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
### Vraag 9: Het "volledig zichtbaar bij hover"-patroon
`HeroArrows` en `HeroSocials` herhalen allebei hetzelfde patroon: opacity 0.6, bij hover of focus naar 1, met de transitie-tokens. De terug-naar-boven-knop gebruikt dat patroon niet (die heeft een rand en kleur zoals in het design).
A) Centraliseren in het thema, als recipe of als gedeelde style-set, en de twee Hero-componenten erop omzetten. Dat is een kleine, veilige refactor.
B) Laten zoals het is. Het komt maar op twee plekken voor, beide in de Hero, en de shell gebruikt het niet. **(aanbevolen)** Hier doen we "niet forceren".
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]:
@@ -0,0 +1,182 @@
# Execution Plan — frontend-shell
## Detailed Analysis Summary
### Transformation Scope (Brownfield)
- **Transformation Type**: Single package (`web/`), application-level changes only — no architectural or infrastructure transformation
- **Primary Changes**: Complete the application shell: footer, back-to-top, skip link + main landmark, 404 and error pages, logo link, full navigation with placeholder routes, scroll restoration, shared site content module, theme additions for reused styling, test toolchain, security headers on dev/preview server, tech-debt clean-up
- **Related Components**: `AppShell`, `NavigationBar` (+ `navItems`), `Footer`, `Hero` (socials source), `theme.ts`, `main.tsx` (router options), `routes/*`, `vite.config.js`, `package.json`
### Change Impact Assessment
- **User-facing changes**: Yes — new footer, to-top button, skip link, 404/error pages, extra menu items and placeholder pages, footer contrast deviates from design (AA)
- **Structural changes**: Yes (minor) — new shell components, shared `siteContent` module, shared router-link primitive; shell stays Header / main / Footer
- **Data model changes**: Yes (minor) — new typed `SiteContent` shape; `HeroContent.socials` moves to it
- **API changes**: No external API. Internal: Hero's content props change (socials no longer in `heroContent`)
- **NFR impact**: Yes — accessibility (WCAG 2.1 AA), new test toolchain incl. PBT, security headers / CSP, supply-chain hygiene
### Component Relationships
```mermaid
graph TD
Root["routes/__root.tsx"] --> AppShell["AppShell"]
Root --> NotFound["NotFound page (new)"]
Root --> ErrorPage["Error page (new)"]
AppShell --> SkipLink["SkipLink (new)"]
AppShell --> Nav["NavigationBar (changed)"]
AppShell --> Main["main#main + Outlet (new)"]
AppShell --> Footer["Footer (rebuilt)"]
AppShell --> ToTop["BackToTop (new)"]
Nav --> NavItems["navItems (changed)"]
Footer --> SiteContent["siteContent (new)"]
Hero["Hero (changed)"] --> SiteContent
Footer --> Theme["theme.ts (changed)"]
ToTop --> Theme
Main --> Pages["placeholder routes (new)"]
classDef existing fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef changed fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef added fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
class Root,AppShell existing;
class Nav,NavItems,Hero,Theme,Footer changed;
class NotFound,ErrorPage,SkipLink,Main,ToTop,SiteContent,Pages added;
```
Text alternative: the root route renders AppShell plus new NotFound/Error pages; AppShell gains SkipLink, a main landmark, a rebuilt Footer and a new BackToTop; Footer and Hero both read the new siteContent module; theme.ts is extended (blue = unchanged, yellow = changed, green = new).
- **Primary Component**: `web/` (React SPA) — Change Type: Minor (additive), Priority: Critical
- **Infrastructure Components**: none (only `vite.config.js` dev/preview headers — Configuration-only)
- **Shared Components**: `theme.ts`, `siteContent`, shared router-link primitive — Minor
- **Dependent Components**: `Hero` (socials source) — Minor
- **Supporting Components**: new test setup (Vitest config, test utils, generators) — Minor
### Risk Assessment
- **Risk Level**: Low — isolated front-end, not deployed yet, every change reversible via git
- **Rollback Complexity**: Easy
- **Testing Complexity**: Moderate — new toolchain (Vitest + RTL + fast-check) and jsdom limits around scrolling/media queries
## Workflow Visualization
```mermaid
flowchart TD
Start(["User Request"])
subgraph INCEPTION["🔵 INCEPTION PHASE"]
WD["Workspace Detection<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>COMPLETED</b>"]
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
US["User Stories<br/><b>SKIP</b>"]
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
AD["Application Design<br/><b>EXECUTE</b>"]
UG["Units Generation<br/><b>SKIP</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
FD["Functional Design<br/><b>EXECUTE</b>"]
NFRA["NFR Requirements<br/><b>EXECUTE</b>"]
NFRD["NFR Design<br/><b>SKIP</b>"]
ID["Infrastructure Design<br/><b>SKIP</b>"]
CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
Start --> WD
WD --> RE
RE --> RA
RA -.-> US
RA --> WP
WP --> AD
AD -.-> UG
AD --> FD
FD --> NFRA
NFRA -.-> NFRD
NFRA -.-> ID
NFRA --> CG
CG --> BT
BT --> End(["Complete<br/>(Operations: ask again)"])
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RE fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
linkStyle default stroke:#333,stroke-width:2px
```
Text alternative: completed Inception stages (green) lead to Application Design, Functional Design and NFR Requirements (orange, execute), then Code Generation and Build and Test (green); User Stories, Units Generation, NFR Design and Infrastructure Design are skipped (grey). The Operations phase is undecided and will be asked again after Build and Test.
## Phases to Execute
### 🔵 INCEPTION PHASE
- [x] Workspace Detection (COMPLETED)
- [x] Reverse Engineering (COMPLETED)
- [x] Requirements Analysis (COMPLETED)
- [x] User Stories (SKIPPED)
- **Rationale**: One persona (site visitor), requirements already concrete per shell element with clear acceptance; stories would restate FR-01…FR-11
- [x] Execution Plan (IN PROGRESS)
- [ ] Application Design - EXECUTE (minimal depth)
- **Rationale**: Several new components (Footer, BackToTop, SkipLink, NotFound, ErrorPage, placeholder page layout) and new shared pieces (`siteContent`, shared router-link primitive, theme additions such as a subtle-link style). Their boundaries, props and what gets centralised in the theme (NFR-02 reuse principle) should be decided once, before code
- [ ] Units Generation - SKIP
- **Rationale**: One package, one cohesive unit ("frontend-shell"); no parallel streams or deployment boundaries to split on
### 🟢 CONSTRUCTION PHASE
- [ ] Functional Design - EXECUTE (minimal depth)
- **Rationale**: Required by PBT-01 — identify testable properties of the shell's logic (to-top visibility threshold, footer/nav item derivation, current-year copyright, content shape). Also pins down the `SiteContent` data model and to-top / skip-link behaviour rules
- [ ] NFR Requirements - EXECUTE (minimal depth)
- **Rationale**: Tech stack decisions for the new test toolchain (Vitest, RTL, jsdom, fast-check — PBT-09), accessibility acceptance criteria, exact security header set and CSP (SECURITY-04), supply-chain checks (SECURITY-10)
- [ ] NFR Design - SKIP
- **Rationale**: The NFR patterns are small and concrete (one header config in `vite.config.js`, one Vitest setup, one generators file); they are specified directly in NFR Requirements and the code generation plan without a separate design document
- [ ] Infrastructure Design - SKIP
- **Rationale**: No infrastructure; hosting is out of scope (Operations undecided). Production header requirements are documented, not provisioned
- [ ] Code Generation - EXECUTE (ALWAYS)
- **Rationale**: Implementation planning and code generation needed
- [ ] Build and Test - EXECUTE (ALWAYS)
- **Rationale**: Build, test (incl. PBT with seed logging) and verification needed
### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - UNDECIDED
- **Rationale**: Operations Configuration = Undecided (Q14 = C); asked again at Build and Test
## Package Change Sequence
Single package (`web/`). Suggested order inside the unit (detailed in the code generation plan):
1. Test toolchain + tech-debt clean-up (safe base, `pnpm build` green)
2. Theme additions + shared primitives (`siteContent`, shared router link)
3. Routes + `navItems` (placeholder pages, privacy page)
4. Shell components (SkipLink + main, Footer, BackToTop, logo link)
5. 404 + error pages, scroll restoration
6. Security headers on dev/preview server
7. Tests (example-based + property-based) per step, final full run
## Estimated Timeline
- **Total Stages Remaining**: 5 (Application Design, Functional Design, NFR Requirements, Code Generation, Build and Test)
- **Estimated Duration**: a few working sessions; each design stage is short (minimal depth), Code Generation is the bulk
## Success Criteria
- **Primary Goal**: Every page renders inside a complete shell matching LAYOUT.md and the static design (minus the side area and mobile e-mail), with the agreed accessibility and contrast adjustments
- **Key Deliverables**:
- Footer, BackToTop, SkipLink + main landmark, logo link, full navigation
- Placeholder routes `/portfolio`, `/soorten-fotoshoots`, `/contact`, `/privacyverklaring`
- 404 and generic error pages inside the shell; scroll restoration
- `siteContent` module used by Hero and Footer; reused/centralised styling per NFR-02
- Vitest + RTL + fast-check setup with example-based and property-based tests
- Security headers on dev/preview server + documented production header set
- Tech-debt items from FR-11 resolved
- **Quality Gates**:
- `pnpm build` succeeds (type-check + bundle)
- `pnpm test` passes, PBT seed logged on failure
- `pnpm audit` reviewed, no unaddressed high/critical issues
- Security Baseline and PBT compliance summaries have no blocking findings
- Manual keyboard/screen check of the shell (skip link, focus styles, to-top, menus)
- **Integration Testing**: Shell + routes together (navigation, 404, error boundary, scroll restoration)
- **Operational Readiness**: Out of scope unless Operations is chosen at Build and Test