Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/construction/plans/frontend-shell-code-generation-plan.md
T
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

10 KiB
Raw Blame History

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:
  • 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

  • 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
  • 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, with securityHeaders(mode: 'production' | 'development') (TD-05, NFR-SEC-01…03).
  • Step 4: Sitemap plugin — create config/sitemapPlugin.ts. The Vite plugin emits sitemap.xml via sitemapXml(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.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
  • Step 6: Linting and formatting config
    • eslint.config.js, flat config (TD-03)
    • .prettierignore gets routeTree.gen.ts, .lighthouseci, coverage
    • .gitignore gets .lighthouseci, coverage
  • 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
  • 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)

  • 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).
  • 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)

  • 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/
  • Step 12: Navigation — src/navigation.ts with mainNav and footerNav (FR-02, FR-05, BR-NAV-*). Delete NavigationBar/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.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)
  • 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

  • Step 16: RouterLink — create components/RouterLink.tsx (AD D8). Refactor LinkButton, NavLink and MobileNav onto 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.error is called once
    • retry calls reset and invalidate
    • title and noindex are 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 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
  • 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 socials prop.
    • HeroSocials uses visibleSocials, the iconControl recipe and the new-tab aria-label.
    • HeroArrows uses iconControl.
    • Type rename HeroSocial → SocialLink + test.
  • 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

  • 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)
  • 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.
  • Step 27: App entry — main.tsx:
    • remove ThemeProvider
    • createRouter({ routeTree, scrollRestoration: true, defaultErrorComponent: ErrorPage }) (FR-08, FR-10)
  • 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).
  • 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

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