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]: