# 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.