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:
@@ -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
|
||||
Reference in New Issue
Block a user