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

Functional design, NFR requirements, code generation plan and summary,
and build-and-test instructions with results.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-18 17:05:03 +02:00
co-authored by Claude Opus 5.5
parent 4d6408b607
commit 069c7cb7eb
27 changed files with 2343 additions and 16 deletions
@@ -0,0 +1,195 @@
# Code Generation Plan — frontend-shell
**This plan is the single source of truth for Code Generation.** Steps are executed in order; each is checked off as soon as it is done.
## Unit Context
- **Unit**: frontend-shell (single unit, brownfield)
- **Application code**: `web/` (paths below are relative to `web/` unless stated otherwise)
- **Documentation**: `aidlc-docs/features/frontend-shell/construction/frontend-shell/code/` (markdown summaries only)
- **Dependencies on other units**: none. No back-end exists, and content is static and shaped like the future CMS API.
- **Inputs**:
- [requirements.md](../../inception/requirements/requirements.md): FR-01…FR-13, NFR-01…NFR-06
- [application design](../../inception/application-design/application-design.md)
- functional design:
- [business-rules.md](../frontend-shell/functional-design/business-rules.md) (BR-*)
- [frontend-components.md](../frontend-shell/functional-design/frontend-components.md)
- [domain-entities.md](../frontend-shell/functional-design/domain-entities.md)
- NFR:
- [nfr-requirements.md](../frontend-shell/nfr-requirements/nfr-requirements.md) (NFR-P/A/S/SEC/R/M/B)
- [tech-stack-decisions.md](../frontend-shell/nfr-requirements/tech-stack-decisions.md) (TD-*)
- **Conventions** (NFR-02a):
- Code comments in Dutch.
- Prettier style: 4 spaces, single quotes.
- One folder per component.
- Chakra tokens/recipes, no hard-coded values (BR-THEME-01).
- **Test conventions**:
- Tests sit next to the code as `*.test.ts(x)`.
- Queries by role/label first (Testing Library).
- Stable `data-testid` on interactive shell elements, named `{component}-{element-role}`.
- **Traceability**: User Stories were skipped. Each step references FR/NFR/BR/TD IDs instead.
## Steps
### Part A — Tooling and configuration
- [x] **Step 1: Dependencies** (TD dependency table, FR-11, Q2)
- Remove `next-themes`.
- Move `@vitejs/plugin-react` and `@tanstack/react-router-devtools` to `devDependencies`.
- Add dev dependencies with pnpm:
- testing: `vitest`, `@vitest/coverage-v8`, `jsdom`, `@testing-library/react`, `@testing-library/user-event`, `@testing-library/jest-dom`, `fast-check`, `vitest-axe`
- linting: `eslint`, `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`, `globals`
- Lighthouse: `@lhci/cli`
- [x] **Step 2: Scripts** in `package.json` (TD-07): `test`, `test:watch`, `lint`, `format:check`, `audit:deps`, `lighthouse`, `check`.
- [x] **Step 3: Security headers** — create `config/securityHeaders.ts`, with `securityHeaders(mode: 'production' | 'development')` (TD-05, NFR-SEC-01…03).
- [x] **Step 4: Sitemap plugin** — create `config/sitemapPlugin.ts`. The Vite plugin emits `sitemap.xml` via `sitemapXml(sitePages, siteUrl)` (TD-06, BR-SEO-06).
- [x] **Step 5: Vite config** — `vite.config.js` → `vite.config.ts` (TD-06). It holds:
- the existing plugins plus the sitemap plugin
- `server.headers` and `preview.headers` from `securityHeaders`
- the Vitest `test` section: `jsdom`, setup file, coverage with 100% per-file thresholds for the pure functions (NFR-M-02)
- `tsconfig.json` includes `config` and `vite.config.ts`
- [x] **Step 6: Linting and formatting config**
- `eslint.config.js`, flat config (TD-03)
- `.prettierignore` gets `routeTree.gen.ts`, `.lighthouseci`, `coverage`
- `.gitignore` gets `.lighthouseci`, `coverage`
- [x] **Step 7: Lighthouse CI config** — `lighthouserc.cjs` (TD-04):
- starts `pnpm preview`
- URLs: every `sitePages` path plus `/bestaat-niet` (404)
- presets: mobile and desktop
- assertions per NFR-P-01, NFR-A-01, NFR-S-01/02
- [x] **Step 8: Test setup** — `src/test/setup.ts` with jest-dom and vitest-axe matchers, plus `src/test/renderWithProviders.tsx`, which renders inside the Chakra system and a memory-history router (TD-02).
### Part B — Theme (BR-THEME-01…07)
- [x] **Step 9: Tokens and global styles** in `src/theme.ts`
- Remove `body.height: 250vh` (FR-11).
- New tokens:
- semantic colour `focusRing` (`accent.deep`)
- size `content`, used by the `Container` recipe override
- spacing `pageTop`
- z-index tokens `header`, `mobileNav`, `menuToggle`, `backToTop`
- Text style `pageTitle`.
- Global `:focus-visible` ring (BR-THEME-02), with `[tabindex="-1"]:focus` showing no ring (BR-A11Y-06).
- [x] **Step 10: Recipes**
- `link` variant `subtle` (BR-FOOT-04)
- `skipNavLink` override (FR-07)
- new `recipes/iconControl.ts` (AD D9, BR-THEME-02 ring colour on photos)
- register them in `theme.ts`
- run `pnpm typegen`
### Part C — Content, configuration and pure logic (with unit + property tests)
- [x] **Step 11: Content module** (`src/content/`) (AD D2, domain-entities)
- `types.ts`: `SiteContent`, `SocialLink`, `EmailAddress`, the Hero types
- `siteContent.ts`: new `footerIntro` text, socials, `email: { user, domain }`
- move `heroContent.ts` and `socialPlatforms.ts` here; remove `socials` from `HeroContent`
- delete the old files in `components/Hero/`
- [x] **Step 12: Navigation** — `src/navigation.ts` with `mainNav` and `footerNav` (FR-02, FR-05, BR-NAV-*). Delete `NavigationBar/navItems.ts`.
- [x] **Step 13: Pure helpers** (`src/lib/`)
- `backToTopThreshold.ts` (BR-TOP-01)
- `visibleSocials.ts` (BR-SOC-01/02)
- `emailAddress.ts` (BR-EMAIL-01/02)
- `copyrightLine.ts` (BR-FOOT-02)
- [x] **Step 14: SEO module**
- `src/seo.ts` gets:
- `siteUrl`, `siteName`, `defaultOgImage`
- `canonicalUrl` (BR-SEO-02)
- `pageHead(path)` (BR-SEO-01…04)
- `siteHead`
- `jsonLdScript` (BR-SEO-05)
- `professionalService(content)`
- `src/sitePages.ts`: the registry (domain-entities)
- `src/sitemap.ts`: `sitemapXml` (BR-SEO-06)
- [x] **Step 15: Tests for Part C** (PBT-02…08, NFR-M-01/02)
- Property tests (fast-check) for every row in "Testable Properties": threshold, socials, e-mail, copyright, canonicalUrl, sitemapXml, jsonLdScript.
- Example tests for edge cases and the menu invariants (BR-NAV-01/02).
- `securityHeaders` test: the production CSP has no `unsafe-eval`, no `'unsafe-inline'` in `script-src` and no `ws:`.
- Domain generators are shared in `src/test/arbitraries.ts`.
### Part D — Shared primitives and hooks
- [x] **Step 16: RouterLink** — create `components/RouterLink.tsx` (AD D8). Refactor `LinkButton`, `NavLink` and `MobileNav` onto it.
- [x] **Step 17: useRouteFocus** — create `hooks/useRouteFocus.ts` (BR-A11Y-01), plus a test (focus moves on a pathname change, not on first load).
### Part E — Components (with component tests incl. axe)
- [x] **Step 18: PageIntro** — `components/PageIntro/PageIntro.tsx` + test (FR-01, BR-THEME-03/06)
- [x] **Step 19: StatusPage, NotFound, ErrorPage** in `components/StatusPage/` + tests (FR-09, FR-10, BR-404-*, BR-ERR-*). Tests cover:
- no error details are rendered
- `console.error` is called once
- retry calls `reset` and `invalidate`
- title and `noindex` are set
- [x] **Step 20: Footer + FooterColumn** — `components/Footer/` + tests (FR-05, BR-FOOT-*, BR-SOC-*, BR-EMAIL-03, BR-A11Y-03, BR-SEO-09). Delete the old `components/Footer.tsx`. Tests cover:
- columns are omitted when empty
- the mailto link
- the new-tab text
- `aria-current`
- the `h2` headings
- the year
- [x] **Step 21: BackToTop** — `components/BackToTop/BackToTop.tsx` + tests (FR-06, BR-TOP-*). Tests cover:
- hidden/visible around the threshold
- not focusable while hidden
- smooth vs instant scrolling under reduced motion
- focus moves to `main`
- [x] **Step 22: NavigationBar**
- Logo becomes a link home (FR-03).
- Menu from `mainNav`.
- `let` → `const`.
- z-index tokens (BR-THEME-05) + test (menu order, logo link name).
- [x] **Step 23: Hero**
- Separate `socials` prop.
- `HeroSocials` uses `visibleSocials`, the `iconControl` recipe and the new-tab `aria-label`.
- `HeroArrows` uses `iconControl`.
- Type rename `HeroSocial` → `SocialLink` + test.
- [x] **Step 24: AppShell**
- `SkipNavLink` + `SkipNavContent as="main" id="main"`
- `Footer content={siteContent}`
- `BackToTop`
- `useRouteFocus`
- Test (landmarks, skip link target).
### Part F — Routes, app entry and static files
- [x] **Step 25: Root route** — `routes/__root.tsx`:
- head = `siteHead` + JSON-LD
- `notFoundComponent: NotFound` and `errorComponent: ErrorPage`
- devtools lazy and only in DEV (NFR-P-04)
- [x] **Step 26: Page routes**
- `index.tsx`: `pageHead('/')`, Hero with `socials`.
- `over-mij.tsx`: rewritten as a `PageIntro` placeholder in the Prettier style.
- New: `portfolio.tsx`, `soorten-fotoshoots.tsx`, `contact.tsx`, `privacyverklaring.tsx` with the copy from frontend-components.md (FR-01, Q8).
- Regenerate `routeTree.gen.ts` via the router plugin.
- [x] **Step 27: App entry** — `main.tsx`:
- remove `ThemeProvider`
- `createRouter({ routeTree, scrollRestoration: true, defaultErrorComponent: ErrorPage })` (FR-08, FR-10)
- [x] **Step 28: Static files**
- `public/robots.txt` (BR-SEO-08).
- `public/og-image.jpg`: a 1200×630 crop of a hero photo (BR-SEO-04). If no image tool is available locally, I'll ask you to supply the crop.
- `public/logo.png` for JSON-LD.
- `index.html` fallback gets `og:image`, canonical and `twitter:card`.
- Delete `assets/hero.png`, `assets/typescript.svg`, `assets/vite.svg` after checking they are unreferenced (FR-11).
- [x] **Step 29: Integration tests** (`src/app.test.tsx`), with the real route tree in a memory router:
- an unknown URL shows the 404 inside the shell
- a throwing route shows the error page inside the shell (NFR-R-01)
- the `sitePages` registry equals the route tree (BR-SEO-07)
- axe on every page
### Part G — Documentation and verification
- [x] **Step 30: Code summary** — `aidlc-docs/features/frontend-shell/construction/frontend-shell/code/code-summary.md`. It covers:
- files created, modified and deleted
- mapping to FR/BR IDs
- how to run the scripts
- Check LAYOUT.md. No change is expected: the shell blocks (Header / Content / Footer) stay the same.
- [x] **Step 31: Unit verification** (Step 13.5): run `pnpm lint`, `pnpm format:check`, `pnpm test` and `pnpm build`, fixing failures until green. Then:
- check that `dist/sitemap.xml` exists
- check that the bundle does not contain the joined e-mail address (NFR-SEC-07)
- run `pnpm audit:deps`
- try `pnpm lighthouse`. If Chrome is missing, report that and leave it for Build and Test.
## Scope Estimate
- **About 30 files**:
- roughly 18 new source/test files
- about 12 modified
- 7 deleted, of which 3 starter assets
- **New dev dependencies**: 15. **Removed**: 1.