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>
196 lines
10 KiB
Markdown
196 lines
10 KiB
Markdown
# 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.
|