Files
SluijsensandClaude Opus 5.5 069c7cb7eb 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>
2026-10-18 17:05:03 +02:00

196 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.