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:
2026-10-18 17:05:03 +02:00
co-authored by Claude Opus 5.5
parent 4d6408b607
commit 069c7cb7eb
27 changed files with 2343 additions and 16 deletions
@@ -0,0 +1,75 @@
# Build and Test Summary — frontend-shell
Run on 2026-10-18, on a clean install (`node_modules` removed, `pnpm install --frozen-lockfile`), with the full `pnpm check`: **exit 0, 225 s**.
## Build Status
- **Build tool**: pnpm 12 + Vite 8 (`tsc && vite build`)
- **Build status**: ✅ Success
- **Clean install**: ✅ `postinstall` generated the Chakra types automatically
- **Artifacts**: `dist/` with `index.html`, hashed assets, one chunk per route, plus:
- `sitemap.xml` (home only)
- `robots.txt`
- `og-image.jpg`
- `logo.png`
- **Accepted warning**: main chunk > 500 kB (≈170 kB gzip), mostly Chakra; see performance
## Test Execution Summary
### Unit tests
- **Total**: 82 tests in 18 files. **Passed**: 82. **Failed**: 0.
- **Property-based**: 18 properties over 8 pure functions. The seed is logged on every run (e.g. `1344216500`).
- **Coverage**: 100% on all pure functions (enforced); ≈80% of lines overall (reported).
- **Status**: ✅ Pass
### Integration tests
- **Scenarios**: 7 automated (`src/app.test.tsx`) + 5 build-level checks. **Passed**: all.
- **Status**: ✅ Pass
### Performance (Lighthouse)
| Measure | Result | Target |
|---|---|---|
| Home, mobile | 82 | ≥ 80 (temporary) |
| Home, desktop | 99 | ≥ 90 |
| Other pages | 94–95 mobile, 100 desktop | ≥ 90 |
| Accessibility / Best Practices | 100 everywhere | 100 |
| SEO | 100 on indexed pages | 100 indexed |
**Status**: ✅ Pass (with the agreed exception for home mobile)
### Additional tests
- **Security**: ✅ Pass
- `audit:deps` clean.
- All 5 security headers present on `preview`.
- CSP test, e-mail and devtools absent from the build, only the own origin loaded.
- `audit:dev` reports 8 dev-tool advisories, non-blocking by decision.
- **Accessibility (automated)**: ✅ Pass. axe on every page and component; Lighthouse 100.
- **Manual keyboard / screen reader** ([manual-test-instructions.md](manual-test-instructions.md)), run by the owner:
- K3–K6, K9, screen reader and responsive: ✅ good.
- K7–K8: ✅ on mobile with a screen reader; desktop not testable yet (too little content).
- **K1 (skip link invisible): fixed.** Chakra's skip link has no z-index and sat under the fixed header; it now uses `zIndex: skipNav` and `margin: 0`. ✅ Retested by the owner.
- **K2 (Tab after the skip link went into the menu): resolved with K1.** ✅ Retested by the owner: focus moves to the content.
- **"SOCIALS" spelled out by a mobile screen reader**: CSS uppercase is read as an abbreviation. Footer headings now carry an `aria-label` in normal casing (owner choice A). ✅ Mobile: read correctly. Windows desktop screen reader: still spelled out; **accepted by the owner** (visual "SOCIALS" preferred over "Social media"). Option B remains available if this ever needs to change.
- **Contract tests**: N/A, no API yet.
- **E2E**: covered by integration tests in jsdom and by Lighthouse in a real browser. No separate E2E framework.
## Extension Compliance (Build and Test)
- **PBT-08**: ✅ Compliant.
- Shrinking is on.
- Seed logged on every run and replayable with `FC_SEED`.
- Property tests are part of `pnpm check`, the future CI step.
- **SECURITY-04 / 10 / 13 / 15**: ✅ Compliant, see [security-test-instructions.md](security-test-instructions.md).
- **Other rules**: N/A at this stage.
## Overall Status
- **Build**: ✅ Success
- **All automated tests**: ✅ Pass
- **Open**: none (one accepted known issue, see manual tests)
- **Ready for Operations**: Yes, if chosen.
## Follow-ups (carried forward)
1. **CI/CD**: run `pnpm check` on every push.
2. **Production host**: send the same security headers.
3. **Responsive images**: from the API/CMS.
4. **Prerendering**: restores home mobile to ≥ 90 and correct link previews per page.
5. **Contact form and spam filter**: with the .NET API.
6. **Wider browser support**: once visitor statistics exist.
@@ -0,0 +1,54 @@
# Build Instructions — frontend-shell
## Prerequisites
- **Node.js** 24 (tested with v24.16.0)
- **pnpm** 12 (tested with 12.11.2)
- **Google Chrome**, only for `pnpm lighthouse` / `pnpm check`
- **Environment variables**: none required. `FC_SEED` is optional (see unit-test-instructions.md).
- **OS**: tested on Windows 11; nothing OS-specific in the build
## Build Steps
All commands run in `web/`.
### 1. Install dependencies
```bash
pnpm install --frozen-lockfile
```
- `--frozen-lockfile` installs exactly what `pnpm-lock.yaml` pins (SECURITY-10).
- `postinstall` runs `chakra typegen`, which generates the theme types (recipe variants such as `link` `subtle`) into `node_modules`. Without it, `tsc` fails on custom variants.
### 2. Build
```bash
pnpm build
```
This runs `tsc` (type check) and then `vite build`.
### 3. Verify the build
- **Expected output**: `✓ built in …`, no TypeScript errors.
- **Artifacts in `dist/`**:
- `index.html` with the fallback head (title, description, Open Graph, canonical)
- `assets/` with hashed JS, CSS, fonts and images; one chunk per route
- `sitemap.xml`, generated from `src/sitePages.ts`, indexed pages only
- `robots.txt`, `og-image.jpg`, `logo.png`, `favicon.png` (copied from `public/`)
- **Accepted warning**: "Some chunks are larger than 500 kB". The main chunk is ~580 kB (≈170 kB gzip), mostly Chakra UI. It is tracked under performance (NFR-P-01 exception).
### 4. Run the built site locally
```bash
pnpm preview # http://localhost:4173, with the production security headers
```
Measure performance against this, not against `pnpm dev`: the dev server is unbundled, unminified and loads devtools (measured 0.47 vs 0.82 on mobile).
## Troubleshooting
### `tsc`: `Type '"subtle"' is not assignable to …`
- **Cause**: the Chakra typegen output in `node_modules` is missing (for example after a manual reinstall with scripts disabled).
- **Fix**: `pnpm typegen`, then build again.
### `pnpm install` warns about the store location
- **Cause**: the global pnpm store is on another drive than the project, so pnpm cannot hard-link from it.
- **Fix**: none needed; pnpm uses a store on the project drive. Optionally set `storeDir`.
### Vite warns about imports without a file extension in the config
- **Cause**: Vite 8's native config loader requires extensions. The config import chain uses `.ts` extensions for that reason.
- **Fix**: keep the `.ts` extensions in `vite.config.ts`, `config/*` and the modules they import.
@@ -0,0 +1,38 @@
# Integration Test Instructions — frontend-shell
## Purpose
This feature is a single unit, so there are no cross-unit or cross-service calls. Integration here means **the real app wired together**:
- the generated route tree
- router options as in `main.tsx` (scroll restoration, default error component)
- the Chakra theme
- the shell around every page
- the head management per route
- the build-time sitemap
## Automated scenarios (`src/app.test.tsx`, part of `pnpm test`)
| # | Scenario | Expected |
|---|---|---|
| 1 | Every route in `sitePages` renders | Inside the shell (banner + contentinfo), exactly one `h1`, no axe violations |
| 2 | `/portfolio` head | Title "Portfolio \| Andrea Slop Fotografie", canonical `https://andreaslop.nl/portfolio`, `robots: noindex` |
| 3 | Structured data | Exactly one `application/ld+json` block of type `ProfessionalService` |
| 4 | Unknown URL `/bestaat-niet` | "Pagina niet gevonden" inside the shell, no axe violations |
| 5 | A page throws while rendering | "Er ging iets mis" inside the shell; error text not shown |
| 6 | Page registry vs route tree | Same set of paths (BR-SEO-07) |
| 7 | Page registry vs Lighthouse URLs | `lighthouserc.cjs` lists the same indexed / noindex pages |
Also in `pnpm test`: `useRouteFocus` (focus moves to `main` after a page change) and `NavigationBar`/`Footer` with a real router (`aria-current`, link targets).
## Build-level checks (run after `pnpm build` + `pnpm preview`)
| Check | How | Expected |
|---|---|---|
| Deep link served | `curl -s -o /dev/null -w "%{http_code}" http://localhost:4173/portfolio` | `200` (SPA fallback) |
| Sitemap | `curl http://localhost:4173/sitemap.xml` | `200`, `text/xml`, only `https://andreaslop.nl/` |
| Robots | `curl http://localhost:4173/robots.txt` | `200`, points to the sitemap |
| E-mail address not in build | `grep -rl "info@andreaslop" dist` | No result (BR-EMAIL-01) |
| No devtools in build | `ls dist/assets \| grep -i devtool` | No result (NFR-P-04) |
## Setup and cleanup
- **Setup**: no services. The automated tests use an in-memory router history and jsdom.
- **Cleanup**: stop `pnpm preview` (Ctrl+C).
@@ -0,0 +1,44 @@
# Manual Test Instructions — frontend-shell
The automated tests cover structure, roles and labels (Testing Library + axe) and Lighthouse covers contrast. What they cannot judge is how the site **feels** with a keyboard and a real screen reader (NFR-A-04). Run this checklist on the built site.
## Setup
```bash
pnpm build && pnpm preview # http://localhost:4173
```
- **Screen reader**: NVDA (Windows, free) with Chrome, or VoiceOver (macOS/iOS) with Safari.
- **Phone**: open `http://<your-PC-IP>:4173`. For that, run `pnpm preview --host`.
## Keyboard (no mouse)
| # | Step | Expected |
|---|---|---|
| K1 | Load `/`, press Tab once | "Direct naar de inhoud" appears top left |
| K2 | Press Enter | Focus jumps to the content; the next Tab goes to the first link in the page |
| K3 | Tab through the header | Logo, then the menu items, each with a clearly visible focus ring |
| K4 | Below 1024 px: Tab to the menu button, Enter, Escape | Menu opens; Escape closes it; the page does not scroll behind it |
| K5 | Open a page from the menu | Page starts at the top; focus is in the content (next Tab = first link in the page) |
| K6 | Browser back | Previous page at the previous scroll position |
| K7 | Scroll down, Tab to "Terug naar boven", Enter | Page scrolls up; the button disappears; focus is in the content |
| K8 | At the top of the page, Tab | "Terug naar boven" is skipped while invisible |
| K9 | Footer links | Visible focus; Facebook/Instagram open in a new tab |
## Screen reader
| # | Step | Expected |
|---|---|---|
| S1 | List landmarks (NVDA: D / VoiceOver: rotor) | Banner, "Hoofdmenu" navigation, main, content info, "Footermenu" navigation |
| S2 | List headings (NVDA: H) | One heading level 1 per page; "Socials" and "Contact" at level 2 |
| S3 | Footer social link | "Facebook, opent in nieuw tabblad, link" (wording differs per reader) |
| S4 | Follow a menu link | The new page is read from the start of the content |
| S5 | Unknown URL `/bestaat-niet` | "Pagina niet gevonden" is read; header and footer present |
| S6 | Hero arrows and social icons | "Vorige foto", "Volgende foto", "Instagram, opent in nieuw tabblad" |
## Visual / responsive
| # | Step | Expected |
|---|---|---|
| V1 | Widths 320, 390, 820, 1440 and ultrawide (DevTools device toolbar) | No horizontal scrolling, nothing cut off |
| V2 | Footer brand column | Mobile: logo and tagline centred, stacked. Tablet and desktop: logo with the tagline beside it |
| V3 | 32:9 screen | "Terug naar boven" aligns with the content edge, not the screen corner |
| V4 | Browser zoom 200% | Everything readable, nothing overlaps |
| V5 | OS "reduce motion" on | No smooth scrolling or slide/fade animations on the to-top button |
Record findings with page, step and browser/reader, and report them as a bug (Bug Fix lane) or a change request.
@@ -0,0 +1,40 @@
# Performance Test Instructions — frontend-shell
## Purpose
This is a static front-end without a server, so load, stress and throughput testing do not apply (NFR scalability: N/A). Performance here means **page-load quality as a visitor experiences it**, measured with Lighthouse.
## Requirements (NFR-P-01)
- **Performance**: ≥ 90 on every page, mobile and desktop.
- **Temporary exception**: home page on mobile ≥ 80, until responsive images come from the API/CMS and prerendering exists.
- **Accessibility, Best Practices**: 100 on every page.
- **SEO**: 100 on indexed pages. On `noindex` pages only the "is crawlable" audit may fail.
## Run
```bash
pnpm build
pnpm lighthouse # mobile (lighthouserc.cjs), then desktop (lighthouserc.desktop.cjs)
```
- Lighthouse CI starts `pnpm preview` itself (port 4173, real security headers).
- It measures all six routes plus `/bestaat-niet` (404) once per form factor.
- It fails if any assertion fails.
- Reports are written to `.lighthouseci/` (git-ignored). Open the `.html` files for details.
- Requires a local Chrome.
Manual measurement in a browser: `pnpm build && pnpm preview`, then open `http://localhost:4173` in a **private window** (extensions and Brave Shields skew results) and run Lighthouse from DevTools.
## Results (2026-10-18, clean install)
| Page | Mobile Perf | Desktop Perf | A11y | Best Pr. | SEO |
|---|---|---|---|---|---|
| `/` | **82** (target 80) | 99 | 100 | 100 | 100 |
| `/over-mij`, `/portfolio`, `/soorten-fotoshoots`, `/contact`, `/privacyverklaring` | 94 | 100 | 100 | 100 | 69 (noindex, accepted) |
| `/bestaat-niet` (404) | 95 | 100 | 100 | 100 | 58 (noindex, no description; accepted) |
Home page mobile: LCP ≈ 4.3 s (simulated slow 4G), total download ≈ 1.2 MB, CLS ≈ 0.
## Known bottlenecks and follow-ups
- **Responsive images**: the first hero photo is 2560 px wide (≈325 KB), also on a phone. The fix is image variants per width from the API/CMS or an image service, used via `srcset`.
- **Render after JavaScript**: the hero title appears only after the JS bundle (≈170 kB gzip, mostly Chakra) has loaded. Prerendering (planned with hosting) fixes this.
- **Already done in this feature**:
- Hero slides load just-in-time (active, next, previous), so the download went from 2.6 MB to 1.2 MB.
- The logo is sized correctly (`htmlWidth`/`htmlHeight`).
@@ -0,0 +1,44 @@
# Security Test Instructions — frontend-shell
## Dependency scan (SECURITY-10, NFR-SEC-05)
```bash
pnpm audit:deps # blocking: packages that ship with the site
pnpm audit:dev # report only: all packages incl. dev tools
```
- **`audit:deps`**: expected "No known vulnerabilities found".
- **`audit:dev`**: reports advisories in dev-only tools and never blocks. Status on 2026-10-18: 5 high, 2 moderate, 1 low.
- 7 of them via `@lhci/cli`, 1 via `@chakra-ui/cli`.
- None of these packages end up in `dist/`.
- Review this list periodically, and when you update those tools.
- **`source-map-js`**: held at ≥ 1.2.2 through an override in `pnpm-workspace.yaml` (GHSA-68fv-2mgg-jv7q).
## HTTP security headers (SECURITY-04)
Automated: `config/securityHeaders.test.ts` checks that the production CSP has:
- no `unsafe-eval`
- no `unsafe-inline` for scripts
- no `ws:`
- `frame-ancestors 'none'`
Against the built site:
```bash
pnpm build && pnpm preview
curl -sI http://localhost:4173/
```
Expected:
- `Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`
- `Strict-Transport-Security: max-age=31536000; includeSubDomains` (browsers only honour it over HTTPS)
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `Referrer-Policy: strict-origin-when-cross-origin`
The production host must send the same set; that is a follow-up for Operations.
## Other checks
| Check | Covered by |
|---|---|
| External links use `rel="noopener noreferrer"` and only `https:` | Footer and Hero tests, `visibleSocials` property tests |
| JSON-LD cannot close its `<script>` element | `jsonLdScript` property test (no `<` or `>` in output) |
| Error page shows no internals | ErrorPage test and integration scenario 5 |
| E-mail address not literally in the build | `grep -rl "info@andreaslop" dist` → no result |
| No third-party resources loaded | Lighthouse network log: only the own origin |
| No inline scripts besides the non-executed JSON-LD data block | `next-themes` removed; CSP `script-src 'self'` with no console violations (Best Practices 100) |
@@ -0,0 +1,34 @@
# Unit Test Execution — frontend-shell
## Run the tests
```bash
pnpm test # once, with coverage
pnpm test:watch # while developing
```
## Expected results
- **18 test files, 82 tests, 0 failures.** That includes:
- **Property-based tests** (fast-check) for every row in "Testable Properties" of business-rules.md: `backToTopThreshold`, `visibleSocials`, `emailAddress`, `copyrightLine`, `canonicalUrl`, `sitemapXml`, `jsonLdScript`, `slidesToLoad`.
- **Example-based component tests** with React Testing Library.
- **axe-core accessibility checks** in the component and integration tests (colour contrast excluded in jsdom; Lighthouse covers it).
- **Coverage**: the run fails if any pure function in `src/lib/**`, `src/seo.ts` or `src/sitemap.ts` drops below 100% (statements, branches, functions, lines). For everything else coverage is reported only (overall ≈80% of lines).
- **Report**: in the terminal; an HTML report is written to `coverage/` (git-ignored).
## Property-based testing (PBT-08)
- **Seed**: every run prints one line, for example:
```
fast-check seed: 1344216500 (opnieuw: FC_SEED=1344216500 pnpm test)
```
The seed comes from `config/testSeed.ts` and applies to all property tests in that run.
- **Replay** a run exactly, failing or not:
```bash
FC_SEED=1344216500 pnpm test
```
- **On a failure** fast-check also reports the shrunk minimal counterexample and its `path`. Shrinking is on and never disabled.
- **Flaky failures** are not retried away. Replay with the seed, find the cause, fix it.
## Fixing failing tests
1. Read the failing test name and message in the terminal output.
2. For a property test: replay with `FC_SEED`, then turn the shrunk counterexample into an example test.
3. Fix the code, or the property if it was stated too broadly. An example from this feature: monotonicity of `backToTopThreshold` holds only for finite input, because BR-TOP-01 maps non-finite input to 0.
4. Rerun `pnpm test`.