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:
+75
@@ -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.
|
||||
+38
@@ -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).
|
||||
+44
@@ -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.
|
||||
+40
@@ -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`).
|
||||
+44
@@ -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) |
|
||||
+34
@@ -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`.
|
||||
Reference in New Issue
Block a user