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>
10 KiB
10 KiB
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 toweb/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: FR-01…FR-13, NFR-01…NFR-06
- application design
- functional design:
- NFR:
- nfr-requirements.md (NFR-P/A/S/SEC/R/M/B)
- 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-testidon interactive shell elements, named{component}-{element-role}.
- Tests sit next to the code as
- Traceability: User Stories were skipped. Each step references FR/NFR/BR/TD IDs instead.
Steps
Part A — Tooling and configuration
- Step 1: Dependencies (TD dependency table, FR-11, Q2)
- Remove
next-themes. - Move
@vitejs/plugin-reactand@tanstack/react-router-devtoolstodevDependencies. - 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
- testing:
- Remove
- Step 2: Scripts in
package.json(TD-07):test,test:watch,lint,format:check,audit:deps,lighthouse,check. - Step 3: Security headers — create
config/securityHeaders.ts, withsecurityHeaders(mode: 'production' | 'development')(TD-05, NFR-SEC-01…03). - Step 4: Sitemap plugin — create
config/sitemapPlugin.ts. The Vite plugin emitssitemap.xmlviasitemapXml(sitePages, siteUrl)(TD-06, BR-SEO-06). - Step 5: Vite config —
vite.config.js→vite.config.ts(TD-06). It holds:- the existing plugins plus the sitemap plugin
server.headersandpreview.headersfromsecurityHeaders- the Vitest
testsection:jsdom, setup file, coverage with 100% per-file thresholds for the pure functions (NFR-M-02) tsconfig.jsonincludesconfigandvite.config.ts
- Step 6: Linting and formatting config
eslint.config.js, flat config (TD-03).prettierignoregetsrouteTree.gen.ts,.lighthouseci,coverage.gitignoregets.lighthouseci,coverage
- Step 7: Lighthouse CI config —
lighthouserc.cjs(TD-04):- starts
pnpm preview - URLs: every
sitePagespath plus/bestaat-niet(404) - presets: mobile and desktop
- assertions per NFR-P-01, NFR-A-01, NFR-S-01/02
- starts
- Step 8: Test setup —
src/test/setup.tswith jest-dom and vitest-axe matchers, plussrc/test/renderWithProviders.tsx, which renders inside the Chakra system and a memory-history router (TD-02).
Part B — Theme (BR-THEME-01…07)
- 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 theContainerrecipe override - spacing
pageTop - z-index tokens
header,mobileNav,menuToggle,backToTop
- semantic colour
- Text style
pageTitle. - Global
:focus-visiblering (BR-THEME-02), with[tabindex="-1"]:focusshowing no ring (BR-A11Y-06).
- Remove
- Step 10: Recipes
linkvariantsubtle(BR-FOOT-04)skipNavLinkoverride (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)
- Step 11: Content module (
src/content/) (AD D2, domain-entities)types.ts:SiteContent,SocialLink,EmailAddress, the Hero typessiteContent.ts: newfooterIntrotext, socials,email: { user, domain }- move
heroContent.tsandsocialPlatforms.tshere; removesocialsfromHeroContent - delete the old files in
components/Hero/
- Step 12: Navigation —
src/navigation.tswithmainNavandfooterNav(FR-02, FR-05, BR-NAV-*). DeleteNavigationBar/navItems.ts. - 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)
- Step 14: SEO module
src/seo.tsgets:siteUrl,siteName,defaultOgImagecanonicalUrl(BR-SEO-02)pageHead(path)(BR-SEO-01…04)siteHeadjsonLdScript(BR-SEO-05)professionalService(content)
src/sitePages.ts: the registry (domain-entities)src/sitemap.ts:sitemapXml(BR-SEO-06)
- 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).
securityHeaderstest: the production CSP has nounsafe-eval, no'unsafe-inline'inscript-srcand nows:.- Domain generators are shared in
src/test/arbitraries.ts.
Part D — Shared primitives and hooks
- Step 16: RouterLink — create
components/RouterLink.tsx(AD D8). RefactorLinkButton,NavLinkandMobileNavonto it. - 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)
- Step 18: PageIntro —
components/PageIntro/PageIntro.tsx+ test (FR-01, BR-THEME-03/06) - 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.erroris called once- retry calls
resetandinvalidate - title and
noindexare set
- Step 20: Footer + FooterColumn —
components/Footer/+ tests (FR-05, BR-FOOT-, BR-SOC-, BR-EMAIL-03, BR-A11Y-03, BR-SEO-09). Delete the oldcomponents/Footer.tsx. Tests cover:- columns are omitted when empty
- the mailto link
- the new-tab text
aria-current- the
h2headings - the year
- 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
- 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).
- Step 23: Hero
- Separate
socialsprop. HeroSocialsusesvisibleSocials, theiconControlrecipe and the new-tabaria-label.HeroArrowsusesiconControl.- Type rename
HeroSocial→SocialLink+ test.
- Separate
- Step 24: AppShell
SkipNavLink+SkipNavContent as="main" id="main"Footer content={siteContent}BackToTopuseRouteFocus- Test (landmarks, skip link target).
Part F — Routes, app entry and static files
- Step 25: Root route —
routes/__root.tsx:- head =
siteHead+ JSON-LD notFoundComponent: NotFoundanderrorComponent: ErrorPage- devtools lazy and only in DEV (NFR-P-04)
- head =
- Step 26: Page routes
index.tsx:pageHead('/'), Hero withsocials.over-mij.tsx: rewritten as aPageIntroplaceholder in the Prettier style.- New:
portfolio.tsx,soorten-fotoshoots.tsx,contact.tsx,privacyverklaring.tsxwith the copy from frontend-components.md (FR-01, Q8). - Regenerate
routeTree.gen.tsvia the router plugin.
- Step 27: App entry —
main.tsx:- remove
ThemeProvider createRouter({ routeTree, scrollRestoration: true, defaultErrorComponent: ErrorPage })(FR-08, FR-10)
- remove
- 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.pngfor JSON-LD.index.htmlfallback getsog:image, canonical andtwitter:card.- Delete
assets/hero.png,assets/typescript.svg,assets/vite.svgafter checking they are unreferenced (FR-11).
- 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
sitePagesregistry equals the route tree (BR-SEO-07) - axe on every page
Part G — Documentation and verification
- 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.
- Step 31: Unit verification (Step 13.5): run
pnpm lint,pnpm format:check,pnpm testandpnpm build, fixing failures until green. Then:- check that
dist/sitemap.xmlexists - 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.
- check that
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.