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