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
+1 -1
View File
@@ -2,4 +2,4 @@
| Type | Name | Status | Branch | Affected Components | Session Start | | Type | Name | Status | Branch | Affected Components | Session Start |
|------|------|--------|--------|---------------------|---------------| |------|------|--------|--------|---------------------|---------------|
| Feature | frontend-shell | 🔵 Inception | feature/frontend-shell | web/src (AppShell, NavigationBar, Footer, Hero socials, new BackToTop/SkipLink/404/error pages, routes, theme.ts, main.tsx), web/vite.config.js, web/package.json | 2026-10-14 | | Feature | frontend-shell | 🟢 Construction | feature/frontend-shell | web/src (AppShell, NavigationBar, Footer, Hero socials, new BackToTop/SkipLink/404/error pages, routes, theme.ts, main.tsx), web/vite.config.js, web/package.json | 2026-10-14 |
@@ -5,7 +5,7 @@
- **Feature Slug**: frontend-shell - **Feature Slug**: frontend-shell
- **Project Type**: Brownfield - **Project Type**: Brownfield
- **Start Date**: 2026-10-14T09:46:02Z - **Start Date**: 2026-10-14T09:46:02Z
- **Current Stage**: INCEPTION - Application Design (awaiting approval) - **Current Stage**: CONSTRUCTION - Build and Test (complete, awaiting Operations decision)
- **Branch**: feature/frontend-shell - **Branch**: feature/frontend-shell
## Workspace State ## Workspace State
@@ -53,24 +53,24 @@
- [x] Requirements Analysis - [x] Requirements Analysis
- [x] User Stories - SKIP - [x] User Stories - SKIP
- [x] Workflow Planning - [x] Workflow Planning
- [~] Application Design - EXECUTE (artifacts generated, awaiting approval) - [x] Application Design - EXECUTE (approved)
- [ ] Units Generation - SKIP - [x] Units Generation - SKIP
### 🟢 CONSTRUCTION PHASE ### 🟢 CONSTRUCTION PHASE
- [ ] Functional Design - EXECUTE - [x] Functional Design - EXECUTE (approved)
- [ ] NFR Requirements - EXECUTE - [x] NFR Requirements - EXECUTE (approved)
- [ ] NFR Design - SKIP - [x] NFR Design - SKIP
- [ ] Infrastructure Design - SKIP - [x] Infrastructure Design - SKIP
- [ ] Code Generation - EXECUTE - [x] Code Generation - EXECUTE (approved)
- [ ] Build and Test - EXECUTE - [x] Build and Test - EXECUTE (complete; Operations decision pending)
### 🟡 OPERATIONS PHASE ### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - UNDECIDED - [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - UNDECIDED
## Current Status ## Current Status
- **Lifecycle Phase**: INCEPTION - **Lifecycle Phase**: CONSTRUCTION
- **Current Stage**: Application Design - **Current Stage**: Build and Test
- **Next Stage**: Functional Design - **Next Stage**: Operations (undecided)
## Reverse Engineering Status ## Reverse Engineering Status
- [x] Reverse Engineering - Artifacts generated on 2026-10-14T09:58:04Z (approved 2026-10-14T10:05:21Z) - [x] Reverse Engineering - Artifacts generated on 2026-10-14T09:58:04Z (approved 2026-10-14T10:05:21Z)
+300
View File
@@ -174,3 +174,303 @@
**Context**: INCEPTION - Application Design; artifacts generated, awaiting approval **Context**: INCEPTION - Application Design; artifacts generated, awaiting approval
--- ---
## Session Resume
**Timestamp**: 2026-10-18T09:04:08Z
**User Input**: "kan je met aidlc verdergaan met de openstaande feature?"
**AI Response**: "Resumed feature frontend-shell (only active item, treated as option A). active-features.md (Inception) consistent with aidlc-state.md (Application Design awaiting approval). Loaded application-design.md and audit history. Re-presented the Application Design completion message; awaiting explicit approval before starting Functional Design."
**Context**: INCEPTION - Application Design; awaiting approval
---
## Application Design - Approval
**Timestamp**: 2026-10-18T09:08:25Z
**User Input**: "ga verder naar het volgende onderdeel"
**AI Response**: "Application Design approved. Marked complete in aidlc-state.md; Units Generation skipped (single unit 'frontend-shell'). Started CONSTRUCTION - Functional Design for unit frontend-shell."
**Context**: INCEPTION - Application Design complete; CONSTRUCTION - Functional Design started
---
## Functional Design - Plan and Questions
**Timestamp**: 2026-10-18T09:08:25Z
**User Input**: "(none — stage start)"
**AI Response**: "Created construction/plans/frontend-shell-functional-design-plan.md and construction/plans/frontend-shell-fd-questions.md (12 questions): 404 head mechanism, BackToTop focus after click, BackToTop hide/show animation, BackToTop hover colour, social href validation, empty-content behaviour, footer active state, placeholder copy, 404 copy, error page actions, error logging, footer e-mail display."
**Context**: CONSTRUCTION - Functional Design; awaiting answers
---
## Functional Design - Answers and Clarification
**Timestamp**: 2026-10-18T09:34:55Z
**User Input**: "ik heb de vragen beantwoord"
**AI Response**: "Read frontend-shell-fd-questions.md. Answers: Q1 A, Q2 A, Q3 A, Q4 'A, al vind ik de knop en z'n kleuren nu sowieso niet heel erg duidelijk en vraga me af of die niet wegvalt. Daarbij komt dat op een 32:9 scherm de knop nog steeds helemaal rechtsonderin getoond wordt terwijl de content een max width heeft.', Q5 A, Q6 'A, verder wil ik kijken hoe we het e-mailadres zo veilig mogelijk kunnen plaatsen om te beschermen tegen spam. Dat is nu namelijk ook al een probleem.', Q7 B, Q8 A, Q9 A, Q10 B, Q11 A, Q12 'x, bij vraag 6 heb ik ook al een opmerking geplaatst. Wat is de veiligste manier om het e-mailadres te tonen? Geef mij aanbevelingen'. Created frontend-shell-fd-clarification-questions.md with 4 questions: to-top appearance, to-top position on ultrawide screens, e-mail anti-spam display technique (with comparison of techniques and recommendation), recording out-of-scope follow-ups."
**Context**: CONSTRUCTION - Functional Design; awaiting clarification answers
---
## Functional Design - Clarifications and Artifacts
**Timestamp**: 2026-10-18T09:48:15Z
**User Input**: "ik heb de vragen beantwoord"
**AI Response**: "Read frontend-shell-fd-clarification-questions.md. Answers: CQ1 A, CQ2 A, CQ3 'A, verder ter info: techniek 4 is al toegepast met dit specifieke e-mailadres.', CQ4 'A, maar techniek 4 is al (deels) toegepast. info@andreaslop.nl is al een mailadres specifiek voor de website.' No remaining ambiguities. Generated construction/frontend-shell/functional-design/domain-entities.md, business-rules.md (incl. Testable Properties for PBT-01), business-logic-model.md (incl. recommendations outside this feature), frontend-components.md. Refinements: SiteContent.email becomes { user, domain } (FR-04 updated), StatusPage action prop becomes actions ReactNode, to-top styling/position deviates from design (FR-06 updated), ErrorPage also gets own title + noindex."
**Context**: CONSTRUCTION - Functional Design; artifacts generated, awaiting approval
---
## Functional Design - Change Request
**Timestamp**: 2026-10-18T10:16:26Z
**User Input**: "De footerIntro tekst mag worden `Lifestyle fotograaf uit Huizen. Ik leg jouw mooiste momenten vast.`
Ik zie niks staan over SEo-optimalisatie en screenreader-optimalisatie of Responsive design. Ik wil dat daar meteen rekening me egehouden wordt zodat we dat niet achteraf nog moeten toevoegen.
Denk ook aan het gebruik van chakra en het thema om redundatie zoveel mogelijk te voorkomen."
**AI Response**: "Request Changes. Updated footerIntro in domain-entities.md and requirements.md (FR-05). Created construction/plans/frontend-shell-fd-change-questions.md: listed SEO/screen-reader/responsive/reuse items that will be designed without a question, plus 6 questions with trade-offs: prerendering for link previews, canonical domain, og:image, JSON-LD structured data, robots.txt/sitemap.xml, route-change announcement for screen readers."
**Context**: CONSTRUCTION - Functional Design; change request, awaiting answers
---
## Functional Design - Change Answers and Revised Artifacts
**Timestamp**: 2026-10-18T10:32:08Z
**User Input**: "ik heb de vragen beantwoord"
**AI Response**: "Read frontend-shell-fd-change-questions.md. Answers: Q1 A, Q2 A, Q3 A, Q4 A, Q5 'B is het makkelijkste. Hoeveel meerwerk is het en hoe wordt het automatisch opgebouwd? Hoe betrouwbaar is het? Bij teveel gedoe of onzekerheden is A het beste. Anders B, met eventueel de test uit optie A', Q6 A. Assessed Q5: verified TanStack Router head supports links and scripts; chose B via a single sitePages registry + small Vite plugin + sync test (low effort, no extra dependency, reliable). Updated functional design: domain-entities.md (site config, sitePages registry, JSON-LD), business-rules.md (BR-SEO-01..11, BR-A11Y-01..07, BR-RWD-01..05, BR-THEME-01..07, extra testable properties for canonicalUrl, sitemapXml, jsonLdScript), business-logic-model.md (flows 5 focus on page change, 6 build-time SEO files; recommendations prerendering and responsive images), frontend-components.md (useRouteFocus, root head, route heads, responsive table checked against design CSS, theme usage table). Footer headings set to h2 (corrects the note in the change-question file). requirements.md: FR-12, FR-13, NFR-06 added."
**Context**: CONSTRUCTION - Functional Design; revised artifacts, awaiting approval
---
## Functional Design - Approval
**Timestamp**: 2026-10-18T10:40:10Z
**User Input**: "goedgekeurd, ga verder"
**AI Response**: "Functional Design approved. Marked complete in aidlc-state.md. Started CONSTRUCTION - NFR Requirements for unit frontend-shell."
**Context**: CONSTRUCTION - Functional Design complete; NFR Requirements started
---
## NFR Requirements - Plan and Questions
**Timestamp**: 2026-10-18T10:40:51Z
**User Input**: "(none — stage start)"
**AI Response**: "Created construction/plans/frontend-shell-nfr-requirements-plan.md with pre-decided items (test stack per PBT-09, security headers, production CSP, devtools dev-only, sitemap plugin in vite.config.ts) and 8 questions: CSP in dev, next-themes removal (verified it injects an inline script), Lighthouse targets, axe testing, ESLint, browser support, coverage, dependency audit script."
**Context**: CONSTRUCTION - NFR Requirements; awaiting answers
---
## NFR Requirements - Answers and Clarification
**Timestamp**: 2026-10-18T10:51:59Z
**User Input**: "ik heb de vragen beantwoord"
**AI Response**: "Read frontend-shell-nfr-requirements-plan.md. Answers: Q1 A, Q2 A, Q3 B, Q4 A, Q5 A, Q6 'Begin met optie A. B zou later nog kunnen met name voor de mobiele versies.', Q7 A, Q8 A. Q6 interpreted as A now, B recorded as possible follow-up. Q3 B ambiguous on when Lighthouse CI runs (every build vs pre-release check); created frontend-shell-nfr-clarification-questions.md with 1 question, noting SEO 100 target applies to indexed pages only."
**Context**: CONSTRUCTION - NFR Requirements; awaiting clarification
---
## NFR Requirements - Clarification Answer and Artifacts
**Timestamp**: 2026-10-18T10:58:52Z
**User Input**: "ik heb de vraag beantwoord"
**AI Response**: "Read clarification answer: 'A, er vanuitgaand dat ik lokaal de check kan draaien zodat ik tussendoor ook een check kan doen. Ik vraag me alleen wel af of een automatische check vlak voor release niet te laat is. Stel ik doe onderhoud en vergeet dat ik die check moet doen. Dan zie ik dat pas vlak voor release. Als het standaard in CI/CD workflow wordt meegenomen als bijvoorbeeld de laatste stap, dan hoeft het niks in de weg te zitten.' Resolved: pnpm lighthouse + pnpm check runnable locally at any time; CI/CD running pnpm check as final step on every push recorded as follow-up for Deployment Setup. Generated nfr-requirements/nfr-requirements.md and nfr-requirements/tech-stack-decisions.md."
**Context**: CONSTRUCTION - NFR Requirements; artifacts generated, awaiting approval
---
## NFR Requirements - Approval
**Timestamp**: 2026-10-18T10:59:54Z
**User Input**: "Goedgekeurd, ga verder"
**AI Response**: "NFR Requirements approved. NFR Design and Infrastructure Design skipped per execution plan. Started CONSTRUCTION - Code Generation Part 1 (Planning) for unit frontend-shell."
**Context**: CONSTRUCTION - NFR Requirements complete; Code Generation planning started
---
## Code Generation - Plan Approval Prompt
**Timestamp**: 2026-10-18T11:00:58Z
**User Input**: "(none — plan created)"
**AI Response**: "Created construction/plans/frontend-shell-code-generation-plan.md: 31 steps in 7 parts (A tooling/config, B theme, C content + pure logic + PBT, D shared primitives/hooks, E components + tests incl. axe, F routes/entry/static files, G docs + unit verification). Asked for plan approval (Request Changes / Approve Plan)."
**Context**: CONSTRUCTION - Code Generation Part 1; awaiting plan approval
---
## Code Generation - Plan Approval
**Timestamp**: 2026-10-18T11:07:51Z
**User Input**: "heb je voor de preofessionalservice nog content nodig? Of is dat iets wat ik later handmatig moet in- of aanvullen?
Ziet er verder goed uit. Dus als je niks nodig hebt mag je verder."
**AI Response**: "Answered: no extra content needed for ProfessionalService (name, url, logo, image, locality/country, areaServed, sameAs, description from home meta description all available); optional later additions: telephone, priceRange, openingHours, full address (advised to omit when working from home). Plan approved; starting Code Generation Part 2."
**Context**: CONSTRUCTION - Code Generation; plan approved, generation started
---
## Code Generation - Generation Complete
**Timestamp**: 2026-10-18T11:48:36Z
**User Input**: "(none — generation)"
**AI Response**: "Executed all 31 plan steps. Verification: lint 0 issues (72 files), Prettier clean, 77 tests in 17 files pass incl. PBT and axe, 100% coverage thresholds on pure functions met, build OK, sitemap.xml generated, e-mail address absent from dist, devtools absent from dist, pnpm audit --prod clean. Fixed during verification: Chakra Image width/height were style props (logo rendered 500px high) -> htmlWidth/htmlHeight; typegen output lost on reinstall -> postinstall typegen; footer accessible name lost a space; hero loaded all 6 slides at once -> others load after first photo painted (mobile LCP 19.7s -> 4.2s); source-map-js override. Unresolved, needs user decision: (1) mobile Lighthouse performance on / is 0.81 vs target 0.9 (all other pages and all desktop pass); (2) pnpm audit:deps fails on 5 high dev-only advisories (4 via @lhci/cli, 1 via pre-existing @chakra-ui/cli), no fix available for most. Presented completion message."
**Context**: CONSTRUCTION - Code Generation; awaiting approval and 2 decisions
---
## Code Generation - Change Request (hero images, audit)
**Timestamp**: 2026-10-18T12:06:47Z
**User Input**: "1. Ik heb hero-5.jpg vervangen voor een webversie die een stuk kleiner is.
2. Ik snap niet zo goe dhoe developer tools de productiescore beinvloeden.
Verder heb ik 2 afbeeldingen toegevoegd aan de hero. Dat zijn er nu totaal 8. Maakt dat uit? Is er een max die je aan zou raden vanuit performance-oogpunt?"
**AI Response**: "Rebuilt and re-measured: home mobile performance 0.82 (unchanged; deferred slides load after LCP), total download 2.6 MB. Explained dev tools never ship; audit:deps fails because it scans all packages incl. dev-only tools; prod audit clean. Advised just-in-time slide loading instead of a maximum; 5-8 slides fine, 150-250 KB per photo. Created construction/plans/frontend-shell-code-change-questions.md with 3 questions (mobile performance approach, audit gate scope, hero slide loading)."
**Context**: CONSTRUCTION - Code Generation; change request, awaiting answers
---
## Code Generation - Change Answers Applied
**Timestamp**: 2026-10-18T12:17:47Z
**User Input**: "ik heb de vragen beantwoord"
**AI Response**: "Answers: Q1 'B, omdat de data later uit een API komt weet ik niet of responseive foto's met een vite-plugin toevoegen verstandig is voor een tijdelijke situatie. Prerendering pakken we sowieso later op.', Q2 A, Q3 'A, maar je kan vanaf de eerste foto ook terug-klikken naar de laatste foto, dus de actieve foto + de volgende en vorige (of laatste in geval van eerste foto) wil je laden.' Applied: lighthouserc.cjs home mobile >= 0.8, new lighthouserc.desktop.cjs keeps 0.9; audit:deps --prod (blocking) + audit:dev (report only); lib/slidesToLoad (active, next, previous wrapping) with PBT, Hero uses it after first paint. Updated NFR-P-01, NFR-SEC-05, follow-up responsive images via API/CMS, BR-HERO-01, code-summary. Full pnpm check exit 0: lint, format, 82 tests in 18 files, build, audit, Lighthouse mobile+desktop. Home mobile 0.81, download 2.6 MB -> 1.2 MB."
**Context**: CONSTRUCTION - Code Generation; changes applied, awaiting approval
---
## Code Generation - Footer Brand Column Review
**Timestamp**: 2026-10-18T14:04:37Z
**User Input**: "De eerste kolom van de footer ziet er gek uit met die tekst onder de afbeelding. De 2 zinnetjes onder elkaar zetten of mnisschien de afbeelding in het midden uitlijnen zal het beter maken gok ik. heb je een suggestie?" / "Ik kan nog geen echte keuze maken, want de varianten op de tablet geven een error-afbeelding dus ik weet niet hoe dat er op een tabelt uit ziet. Zelfde voor mobile schermen. Die heb je helemaal niet gemaakt met de varianten" / "Ik heb even gekeken. ik vind optie C het mooiste, behalve voor mobiel. Daar is B het beste. Dus Optie C voor table en desktop en optie B voor mobiel"
**AI Response**: "First variant renders were broken (compile error overlay; tablet shown as error, mobile missing) - acknowledged. Re-rendered current/A/B/C (+ D) with puppeteer-core device emulation at 390/820/1440 px; no horizontal overflow at any width. Implemented user choice: mobile centred stacked (B), tablet/desktop logo 110px beside text (C); footerIntro split into two lines in content with whiteSpace pre-line. Noted remaining tablet issues (orphan word, Contact alone on second row) and offered full-width brand block on tablet. Lint, format, 82 tests, build pass. Docs updated."
**Context**: CONSTRUCTION - Code Generation; footer change applied, awaiting approval
---
## Code Generation - Approval
**Timestamp**: 2026-10-18T14:22:30Z
**User Input**: "dat ziet er goed uit. ga verder"
**AI Response**: "Code Generation approved (tablet full-width brand option not requested; footer stays as chosen). Marked complete. Started CONSTRUCTION - Build and Test."
**Context**: CONSTRUCTION - Code Generation complete; Build and Test started
---
## Build and Test Stage
**Timestamp**: 2026-10-18T14:33:42Z
**Build Status**: Success (clean install with --frozen-lockfile; postinstall typegen verified)
**Test Status**: Pass. pnpm check exit 0 in 225 s: lint, format, 82 tests in 18 files (18 property tests, seed logged), build, audit:deps clean, Lighthouse mobile+desktop pass. Home mobile 82 (target 80), other pages 94-95 mobile / 100 desktop. Security headers verified on preview with curl; e-mail and devtools absent from dist. Added PBT-08 seed logging on every run (config/testSeed.ts, FC_SEED replay). Manual keyboard/screen-reader check handed to owner.
**Files Generated**:
- build-instructions.md
- unit-test-instructions.md
- integration-test-instructions.md
- performance-test-instructions.md
- security-test-instructions.md
- manual-test-instructions.md
- build-and-test-summary.md
**Operations Phase Decision**: Undecided (asked now, Variant C)
---
## Build and Test - Manual Test Results
**Timestamp**: 2026-10-18T14:52:32Z
**User Input**: "K1: De knop wordt wel gefocust, maar ik zie niet in beeld komen "Direct naar inhoud"
K2: Ik weet niet wat er zou moeten gebeuren, we hebben nog geen inhoud, maar de volgende tab gaat eerst door de navigation menu heen en niet naar de inhoud of nu dan de footer, klopt dat?
K3-6: Dat ziet er goed uit
K7-8: Te weinig content en kan ik nog niet testen op desktop. Op mobiel met de screenreader deed deze het wel zoals verwacht.
K9: Gaat ide goed doorheen
Screen reader ziet er goed uit, behalve de kopjes in de footer. SOCIALS wordt opgelezen als loss eletters. Waarshcijnlijk omdat het alleen hoofdletters zijn. CONTACT doet die wel goed. Responsiveness ziet er ook goed uit"
**AI Response**: "Reproduced K1 with puppeteer keyboard input: skip link focused and positioned but covered by the fixed header (Chakra skipNavLink recipe sets no z-index). Fixed in recipes/skipNavLink.ts (zIndex skipNav, margin 0); verified not covered, rect 0,0. K2 not reproducible: after Enter focus is on main, next Tab goes to first focusable after main (footer on placeholders, 'Lees meer' on home); only deviation when URL already has #main (browser sets focus start point). Asked user to retest K1/K2 without #main. SOCIALS spelled out: CSS uppercase read as acronym by mobile screen readers; created construction/plans/frontend-shell-bt-questions.md (aria-label / 'Social media' / 'Volg mij')."
**Context**: CONSTRUCTION - Build and Test; fixing manual test findings
---
## Build and Test - Retest and Socials Fix
**Timestamp**: 2026-10-18T14:56:51Z
**User Input**: "k2 skipped nu het menu en hij zet de focus bij de eerstvolgende tab in de Hero. dus dat is nu wel goed. K1 is ook gefixed.
Verder heb ik de vraag ook beantwoord"
**AI Response**: "K1/K2 confirmed fixed by owner. Question 1 answered A: added aria-label={title} to FooterColumn h2 headings; Footer test asserts the labels. Lint, format, 82 tests, build pass. Updated build-and-test-summary.md with manual test results. Asked owner to retest 'Socials' on mobile screen reader and for the Operations decision."
**Context**: CONSTRUCTION - Build and Test; awaiting retest and Operations decision
---
## Build and Test - Socials Retest
**Timestamp**: 2026-10-18T15:02:17Z
**User Input**: "Hij spreekt Socials op mijn device wel goed uit nu. Op de desktop (Windows) leest hij nog steeds de losse letters, maar de tekst SOCIALS is visueel wel mooier dan Social Media. dus dat mag zo blijven. Die ene tekst in de footer is niet zo;n ramp"
**AI Response**: "Recorded: mobile reads 'Socials' correctly; Windows desktop still spells it out; accepted known issue by owner. Summary updated (no open items). Operations decision still pending; re-asked."
**Context**: CONSTRUCTION - Build and Test; awaiting Operations decision
---
@@ -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`.
@@ -0,0 +1,90 @@
# Code Summary — frontend-shell
All application code is in `web/`. Plan: [frontend-shell-code-generation-plan.md](../../plans/frontend-shell-code-generation-plan.md).
## Structure
```mermaid
graph TD
Root["routes/__root.tsx"] --> Shell["AppShell"]
Root --> Head["siteHead + JSON-LD"]
Shell --> Skip["SkipNavLink"]
Shell --> Nav["NavigationBar"]
Shell --> Main["main#35;main + Outlet"]
Shell --> Foot["Footer"]
Shell --> Top["BackToTop"]
Main --> Pages["Route pages via PageIntro / Hero"]
Main --> Status["NotFound / ErrorPage via StatusPage"]
Pages --> Registry["sitePages + pageHead"]
Registry --> Sitemap["sitemap.xml at build"]
classDef layout fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef data fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
class Root,Shell,Main layout;
class Skip,Nav,Foot,Top,Pages,Status ui;
class Head,Registry,Sitemap data;
```
Text alternative: the root route renders the shell and site-wide head data; the shell holds the skip link, navigation, main content, footer and back-to-top button; pages take their head data from the page registry, which also generates the sitemap.
## Files
### Created
| Area | Files | Covers |
|---|---|---|
| Config | `vite.config.ts` (replaces `.js`), `config/securityHeaders.ts`, `config/sitemapPlugin.ts`, `eslint.config.js`, `lighthouserc.cjs` + `.d.cts` | TD-03…07, NFR-SEC-01…03, BR-SEO-06 |
| Theme | `recipes/container.ts`, `link.ts`, `skipNavLink.ts`, `iconControl.ts` | BR-THEME-02…07 |
| Content | `content/siteContent.ts` | FR-04, BR-EMAIL-01 |
| Logic | `lib/slidesToLoad.ts`, `lib/backToTopThreshold.ts`, `visibleSocials.ts`, `emailAddress.ts`, `copyrightLine.ts`, `navigation.ts`, `sitePages.ts`, `sitemap.ts` | BR-TOP-01, BR-SOC-*, BR-EMAIL-*, BR-FOOT-02, BR-NAV-*, BR-SEO-* |
| Components | `RouterLink`, `PageIntro/`, `StatusPage/` (`StatusPage`, `NotFound`, `ErrorPage`), `Footer/` (`Footer`, `FooterColumn`, `FooterLink`), `BackToTop/` | FR-01, FR-05…FR-10 |
| Hooks | `hooks/useRouteFocus.ts` | BR-A11Y-01 |
| Routes | `portfolio.tsx`, `soorten-fotoshoots.tsx`, `contact.tsx`, `privacyverklaring.tsx` | FR-01 |
| Static | `public/robots.txt`, `public/og-image.jpg` (1200×630 crop of `hero-1.jpg`), `public/logo.png` | BR-SEO-04/05/08 |
| Tests | 17 test files, incl. `src/test/` (setup, axe matcher, arbitraries, `renderWithProviders`) and `src/app.test.tsx` (integration) | NFR-M-01, NFR-A-02 |
### Modified
- `theme.ts`: removed `250vh`; added focus ring, `content`/`pageTop`/z-index tokens, `pageTitle`, recipe registration.
- `seo.ts`: `pageHead(path)` from the registry, canonical, Open Graph image, `siteHead`, JSON-LD.
- `main.tsx`: `next-themes` removed, `scrollRestoration`, `defaultErrorComponent`.
- `routes/__root.tsx`, `index.tsx`, `over-mij.tsx`.
- `AppShell`, `NavigationBar` (logo link, `mainNav`, 44px menu button, z-index tokens), `MobileNav`, `NavLink`, `LinkButton` (onto `RouterLink`).
- `Hero`: socials prop; first only the active photo, after it is painted also the next and previous (BR-HERO-01). `HeroArrows` and `HeroSocials` use `iconControl`.
- `index.html`: fallback head with `og:image`, canonical, `twitter:card`.
- `package.json`: scripts, dependencies, `postinstall` typegen. `pnpm-workspace.yaml`: `source-map-js` override.
- `tsconfig.json`, `.gitignore`, `.prettierignore`.
- Formatting only: Prettier over all of `web/`, which also touched existing files such as `useHeroSlider.ts` and line endings.
### Moved / deleted
- Moved: `components/Hero/{heroContent,socialPlatforms,types}.ts` → `content/`.
- Deleted: `components/Footer.tsx`, `NavigationBar/navItems.ts`, `assets/hero.png`, `assets/typescript.svg`, `assets/vite.svg`.
## Deviations From the Plan
| Planned | Done instead | Why |
|---|---|---|
| `vitest-axe` | Own `toHaveNoViolations` on `axe-core` (TD-02 fallback) | `vitest-axe` 0.1.0 types target the old Vitest `Vi` namespace |
| ESLint 10 | ESLint 9 | `eslint-plugin-jsx-a11y` supports up to ESLint 9 |
| — | `inert` on the hidden to-top button | Makes BR-TOP-03 hold without CSS and testable in jsdom |
| — | Hero loads the active slide first, then only its neighbours | Stacked slides defeat `loading="lazy"`; mobile LCP 19.7s → 4.3s, home download 2.6 MB → 1.2 MB |
| Footer brand column: logo above text, left-aligned | Mobile centred and stacked; tablet/desktop logo 110px beside the text; tagline split into two lines in the content | User choice after reviewing renders at 390/820/1440px |
| Home mobile Performance ≥ 0.9 | ≥ 0.8 for now (`lighthouserc.cjs`); desktop stays 0.9 (`lighthouserc.desktop.cjs`) | User choice; responsive images come with the API/CMS |
| `audit:deps` on all packages | `audit:deps` on production packages; `audit:dev` reports dev tools without blocking | User choice; dev tools never ship |
| — | `.ts` extensions in the config import chain | Vite 8 warns these become required for its native config loader |
| — | `postinstall: chakra typegen` | Typegen output lives in `node_modules` and was lost on reinstall |
## Scripts
| Command | Does |
|---|---|
| `pnpm test` / `pnpm test:watch` | Vitest with coverage (100% threshold on pure functions) |
| `pnpm lint`, `pnpm format:check` | ESLint, Prettier |
| `pnpm build` | Type check + Vite build, including `sitemap.xml` |
| `pnpm audit:deps` | `pnpm audit --prod --audit-level high` (blocks) |
| `pnpm audit:dev` | `pnpm audit`, report only |
| `pnpm lighthouse` | Lighthouse CI, mobile (`lighthouserc.cjs`) then desktop (`lighthouserc.desktop.cjs`); needs local Chrome |
| `pnpm check` | All of the above in order |
## LAYOUT.md
No change. The shell blocks (Header / Content / Footer) are unchanged. Skip link and back-to-top are not page sections.
@@ -0,0 +1,175 @@
# Business Logic Model — frontend-shell
The shell has four flows: content provisioning, page navigation, not-found/error rendering and the back-to-top interaction. Rules are referenced by ID from [business-rules.md](business-rules.md).
## 1. Content provisioning
```mermaid
graph TD
Site["content/siteContent"] --> Shell["AppShell"]
Hero_c["content/heroContent"] --> Home["Home route"]
Site --> Home
Shell -->|"content prop"| Footer["Footer"]
Home -->|"content + socials props"| Hero["Hero"]
Footer --> VS1["visibleSocials"]
Footer --> EA["emailAddress"]
Hero --> VS2["visibleSocials"]
classDef data fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
classDef provider fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef fn fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
class Site,Hero_c data;
class Shell,Home provider;
class Footer,Hero ui;
class VS1,VS2,EA fn;
```
Text alternative: static content modules are imported only by AppShell and the home route, which pass them as props to Footer and Hero; both use the pure helpers to decide what to show.
- Components never import content (AD D3). Later the two import points become route loaders or API calls.
- The e-mail address is joined in `Footer` at render (BR-EMAIL-01).
## 2. Page navigation and scroll position
```mermaid
sequenceDiagram
box rgba(246,224,94,0.4) Visitor
participant V as Visitor
end
box rgba(99,179,237,0.4) App
participant R as Router
participant S as AppShell
participant P as Page
end
V->>R: Click menu link
R->>S: Render matched route in main
S->>P: Render page with its head
R-->>V: Scroll to top of new page
V->>R: Browser back
R-->>V: Restore previous scroll position
```
Text alternative: a menu click renders the new page inside the shell and starts at the top; browser back restores the earlier scroll position (FR-08, router scroll restoration).
## 3. Not-found and error rendering
```mermaid
graph TD
Url["URL requested"] --> Match{"Route matches?"}
Match -->|"no"| NF["NotFound in main, shell stays"]
NF --> NFHead["Own title + noindex"]
Match -->|"yes"| Render{"Error while rendering?"}
Render -->|"no"| Page["Page in main"]
Render -->|"in a page"| ErrIn["ErrorPage in main, shell stays"]
Render -->|"in the shell"| ErrOut["ErrorPage without shell"]
ErrIn --> Log["console.error once"]
ErrOut --> Log
ErrIn --> Retry{"Opnieuw proberen?"}
Retry -->|"yes"| Reset["Reset boundary + invalidate router"]
Reset --> Render
Retry -->|"Terug naar home"| HomeR["Navigate to /"]
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef fail fill:#F44336,stroke:#b71c1c,stroke-width:1px,color:#000;
classDef action fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
class Match,Render,Retry decision;
class Page,HomeR ok;
class NF,ErrIn,ErrOut fail;
class Url,NFHead,Log,Reset action;
```
Text alternative: an unknown URL shows NotFound inside the shell; a page error shows ErrorPage inside the shell and a shell error shows it without the shell; errors are logged once, and the visitor can retry (re-render) or go home.
## 4. Back-to-top interaction
```mermaid
sequenceDiagram
box rgba(246,224,94,0.4) Visitor
participant V as Visitor
end
box rgba(154,230,180,0.4) Shell
participant H as useScrolledPast
participant B as BackToTop
participant M as main
end
V->>H: Scroll down
H->>B: scrollY above threshold so visible
V->>B: Click or Enter
B->>V: Scroll to top, smooth or instant
B->>M: Move focus with preventScroll
H->>B: scrollY below threshold so hidden
```
Text alternative: scrolling past the threshold makes the button visible; activating it scrolls to the top (instant under reduced motion), moves focus to main and the button hides again (BR-TOP-02, -05, -06).
## 5. Focus on page change (BR-A11Y-01)
```mermaid
sequenceDiagram
box rgba(246,224,94,0.4) Visitor
participant V as Visitor
end
box rgba(154,230,180,0.4) App
participant R as Router
participant F as useRouteFocus
participant M as main
end
V->>R: Follow a link or use back and forward
R->>R: Render new page and restore scroll
R->>F: Resolved with a new pathname
alt First load
F->>F: Do nothing
else Pathname changed
F->>M: Focus with preventScroll
end
M-->>V: Screen reader reads from start of content
```
Text alternative: after the router has rendered a page with a new pathname (not on first load), focus moves to main without scrolling, so a screen reader starts reading the new content.
## 6. Build-time SEO files (BR-SEO-06 to -08)
```mermaid
graph LR
Pages["sitePages registry"] --> Plugin["Vite sitemap plugin"]
Url["siteUrl"] --> Plugin
Plugin -->|"indexed pages only"| Xml["dist/sitemap.xml"]
Robots["public/robots.txt"] --> Dist["dist/robots.txt"]
Pages --> Test{"Test: registry equals route tree?"}
Tree["Generated route tree"] --> Test
Test -->|"no"| Fail["Test fails"]
classDef code fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef out fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
classDef check fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef fail fill:#F44336,stroke:#b71c1c,stroke-width:1px,color:#000;
class Pages,Url,Tree,Robots code;
class Plugin build;
class Xml,Dist out;
class Test check;
class Fail fail;
```
Text alternative: during the build a small Vite plugin turns the indexed entries of the page registry into sitemap.xml and robots.txt is copied as a static file; a test fails when the registry and the route tree list different pages.
**Effort and reliability of the generated sitemap (CH Q5)**:
- The plugin is about 30 lines. The XML is built by the pure, property-tested function `sitemapXml`.
- It needs no route crawling and no extra dependency. It reads the same `sitePages` module the route heads use, so a page can never be indexed in the sitemap and `noindex` in its head at the same time.
- The only manual step is adding a new page to `sitePages`. BR-SEO-07 makes the tests fail when that is forgotten.
## Recommendations Outside This Feature (CQ4 = A)
Recorded so they come back with the Contact page and the .NET API:
1. **Contact form** as the main contact channel (technique 3). The address then appears nowhere on the site. Needs the back-end: server-side sending, a honeypot field and rate limiting, and possibly a CAPTCHA.
2. **Dedicated address + spam filter** (technique 4). Already partly in place: `info@andreaslop.nl` is used only for the website. Remaining step: a strict spam filter on that mailbox.
3. **CMS content**: the e-mail address keeps the `{ user, domain }` shape in the API (BR-EMAIL-01).
4. **Old static site**: as long as it is online, it exposes the address literally in its HTML. Replacing it with this site removes that source.
5. **Prerendering** (CH Q1 = A): generate static HTML per route at build time once the real pages exist, so link previews (WhatsApp, Facebook, LinkedIn) show the right title and image per page. BR-SEO-11 keeps this possible without rework. Belongs with hosting/Operations.
6. **Responsive images**: serve smaller variants of the hero and portfolio photos per screen width (`srcset`). Comes with the portfolio feature, where most photos are.
@@ -0,0 +1,182 @@
# Business Rules — frontend-shell
Rule IDs are referenced by the code generation plan and the tests. "Q" = [frontend-shell-fd-questions.md](../../plans/frontend-shell-fd-questions.md), "CQ" = [frontend-shell-fd-clarification-questions.md](../../plans/frontend-shell-fd-clarification-questions.md).
## Back-to-top button
| ID | Rule | Source |
|---|---|---|
| BR-TOP-01 | Threshold = `backToTopThreshold(viewportHeight)` = `0.6 × max(0, viewportHeight)`. Non-finite input counts as 0. | FR-06 |
| BR-TOP-02 | Visible when `scrollY > threshold` (strictly greater), otherwise hidden. Evaluated on mount and on every (passive) scroll event via `useScrolledPast`. | FR-06 |
| BR-TOP-03 | Hidden means `visibility: hidden`: not focusable, not in the accessibility tree, not clickable. | FR-06 |
| BR-TOP-04 | Show/hide animation: fade + 8px upward slide with the `interaction` duration and `smooth` easing. Under `prefers-reduced-motion: reduce`: instant, no transition. | Q3 = A |
| BR-TOP-05 | Click: scroll to the top, `smooth`, or `instant` under reduced motion. | FR-06 |
| BR-TOP-06 | After the click, focus moves to `main#main` with `preventScroll`, so the smooth scroll is not interrupted. `main` shows no focus ring for programmatic focus. | Q2 = A |
| BR-TOP-07 | Appearance: `ink` background, white `up-outlined` icon, no border, square, 46×46px. Hover/focus-visible: background `accent.deep`. Focus-visible also shows a focus ring. | CQ1 = A, Q4 = A |
| BR-TOP-08 | Position: fixed at the bottom right. The right offset is the design offset (`clamp(1rem, 3vw, 2rem)`), but on viewports wider than the `Container` max width it aligns with the container's right edge instead of the screen corner. | CQ2 = A |
| BR-TOP-09 | Stacking: below the header and the mobile menu. | FR-06 |
## Hero slides
| ID | Rule | Source |
|---|---|---|
| BR-HERO-01 | Only the active slide loads first. Once it has loaded and been painted, `slidesToLoad(active, count)` decides which slides are mounted: the active one, the next and the previous, wrapping around (from the first slide the previous is the last). Slides further away load when the slider gets near them. | Code change Q3 = A |
## Social links
| ID | Rule | Source |
|---|---|---|
| BR-SOC-01 | `visibleSocials(socials)` keeps a link only when `href` parses as a URL with protocol `https:`. Empty, `http:`, `javascript:`, relative or unparseable values are dropped. | Q5 = A |
| BR-SOC-02 | Order is preserved; no entries are added or changed. | — |
| BR-SOC-03 | Hero and Footer both use `visibleSocials`; the Hero shows icons, the Footer shows platform names. | FR-04, AD D11 |
| BR-SOC-04 | External links open in a new tab with `rel="noopener noreferrer"`. | NFR-04 |
## E-mail address
| ID | Rule | Source |
|---|---|---|
| BR-EMAIL-01 | The address is stored as `{ user, domain }` and joined in the browser by `emailAddress(parts)` at render time. The complete address is never a literal in source, bundle or content data. | CQ3 = A |
| BR-EMAIL-02 | `emailAddress` returns `null` when the parts are invalid: either part empty, containing whitespace or `@`, or a domain without a `.`. Otherwise it returns `user@domain`. | CQ3 = A |
| BR-EMAIL-03 | The Footer shows the joined address as link text with `href="mailto:<address>"`, as in the design. | CQ3 = A |
## Footer
| ID | Rule | Source |
|---|---|---|
| BR-FOOT-01 | A column with nothing to show is omitted entirely (heading included): Socials when `visibleSocials` is empty, Contact when `emailAddress` is `null`. The grid closes up. | Q6 = A |
| BR-FOOT-02 | Copyright: `copyrightLine(year)` = `"© {year} Andrea Slop Fotografie"`, with `year = new Date().getFullYear()` at render. | FR-05 |
| BR-FOOT-03 | Footer menu links get `aria-current="page"` when active (router default), with **no** visual difference. | Q7 = B |
| BR-FOOT-04 | Link colours: `ink.soft`, hover/focus `accent.deep` (`link` variant `subtle`). Column headings and bottom bar use `ink.soft`. | NFR-01 |
## Navigation
| ID | Rule | Source |
|---|---|---|
| BR-NAV-01 | `mainNav` and `footerNav` each contain no duplicate `to`. | — |
| BR-NAV-02 | `mainNav` starts with Home `/` and does not contain `/privacyverklaring`. | FR-02 |
| BR-NAV-03 | Every `to` in both menus is a registered route (type-checked). | AD D4 |
## Not-found page
| ID | Rule | Source |
|---|---|---|
| BR-404-01 | Any URL without a matching route renders `NotFound` inside the shell (root `notFoundComponent`). | FR-09 |
| BR-404-02 | `NotFound` renders its own `<title>` "Pagina niet gevonden \| Andrea Slop Fotografie" and `<meta name="robots" content="noindex">`. React 19 hoists both into `<head>` and removes them on navigation. Only the root route matches, and it sets no title, so there is no duplicate `<title>`. | Q1 = A |
## Error page
| ID | Rule | Source |
|---|---|---|
| BR-ERR-01 | Render and route errors render `ErrorPage`: inside the shell for page errors, without the shell for errors in the shell itself. | FR-10, AD services |
| BR-ERR-02 | `ErrorPage` never renders the error message, stack or any error property. | SECURITY-09/15 |
| BR-ERR-03 | `ErrorPage` logs the error once with `console.error(error)`, in every environment. | Q11 = A |
| BR-ERR-04 | Actions: "Opnieuw proberen" (resets the error boundary and invalidates the router, so the route loads again) and "Terug naar home". | Q10 = B |
| BR-ERR-05 | `ErrorPage` sets `<title>` "Er ging iets mis \| Andrea Slop Fotografie" and `robots: noindex`, the same way as BR-404-02. | Derived from BR-404-02 |
## SEO (change request)
"CH" = [frontend-shell-fd-change-questions.md](../../plans/frontend-shell-fd-change-questions.md).
| ID | Rule | Source |
|---|---|---|
| BR-SEO-01 | Every route takes its title, description and `indexed` flag from the `sitePages` registry via `pageHead(path)`. Title = `"{title} \| Andrea Slop Fotografie"`. Home keeps its full keyword title. | FR-01, CH |
| BR-SEO-02 | Every page sets `<link rel="canonical">` and `og:url` to `canonicalUrl(path)` = `siteUrl` + path. No trailing slash (the root is `siteUrl/`), no query, no hash. | CH Q2 = A |
| BR-SEO-03 | Pages with `indexed: false`, the 404 page and the error page set `robots: noindex`. Indexed pages set no robots tag. | CH |
| BR-SEO-04 | Every page has `og:image` (absolute URL), `og:image:alt`, `og:image:width`/`height` and `twitter:card = summary_large_image`. The default is `defaultOgImage`; a page may override it. The fallback head in `index.html` has the same tags for the home page. | CH Q3 = A |
| BR-SEO-05 | The root head renders one `ProfessionalService` JSON-LD block. It sits where `HeadContent` renders (in the body of this SPA); Google reads JSON-LD anywhere in the page. `jsonLdScript` serialises it with `<`, `>` and `&` escaped as `<`, `>`, `&`, so content can never close the `<script>` element. | CH Q4 = A, security |
| BR-SEO-06 | At build time a small Vite plugin generates `sitemap.xml` from `sitePages`: one `<url><loc>` per indexed page, as an absolute, XML-escaped URL. No `lastmod`, because Google ignores unreliable values. | CH Q5 = B |
| BR-SEO-07 | A test fails when a route has no `sitePages` entry, or an entry has no route. | CH Q5 (check from A) |
| BR-SEO-08 | `public/robots.txt` allows everything and points to `https://andreaslop.nl/sitemap.xml`. | CH Q5 |
| BR-SEO-09 | Exactly one `h1` per page, and no skipped heading levels. Footer column headings are `h2` (styled as `eyebrow`), because they are top-level sections of the page. | CH |
| BR-SEO-10 | Internal navigation uses real `<a href>` links (router `Link`). Images: <ul><li>a meaningful `alt`, or `alt=""` when decorative</li><li>`width`/`height` against layout shift</li><li>`loading="lazy"` below the fold</li><li>the first hero slide loads eagerly with `fetchpriority="high"`</li></ul> | CH |
| BR-SEO-11 | No `window` or `document` access during render, only in effects and handlers. All head data goes through route `head`. This keeps prerendering possible later without rework. | CH Q1 = A |
## Screen readers and keyboard (change request)
| ID | Rule | Source |
|---|---|---|
| BR-A11Y-01 | After every client-side page change, focus moves to `main#main` with `preventScroll`. A page change means the pathname changes; the first load does not count. The router's scroll restoration keeps handling the scroll position. Same mechanism as the skip link and BR-TOP-06. | CH Q6 = A |
| BR-A11Y-02 | Landmarks: <ul><li>one `header`</li><li>`nav aria-label="Hoofdmenu"` and `nav aria-label="Mobiel menu"`</li><li>one `main#main`</li><li>one `footer` with `nav aria-label="Footermenu"`</li></ul> | NFR-01 |
| BR-A11Y-03 | Links that open a new tab announce it. Text links get the visually hidden text " (opent in nieuw tabblad)". Icon-only links get it in their `aria-label`, e.g. "Instagram (opent in nieuw tabblad)". | CH |
| BR-A11Y-04 | Icons are `aria-hidden`; icon-only controls have an `aria-label`. | NFR-01 |
| BR-A11Y-05 | The whole site has one focus style, from the theme (BR-THEME-02). Components do not define their own outline; they may only switch the ring colour on photos. | CH |
| BR-A11Y-06 | `main` and other programmatic focus targets (`tabIndex=-1`) show no focus ring. | BR-TOP-06 |
| BR-A11Y-07 | All animations and smooth scrolling are off under `prefers-reduced-motion: reduce`. | NFR-01 |
## Responsive (change request)
| ID | Rule | Source |
|---|---|---|
| BR-RWD-01 | Mobile-first, with Chakra's default breakpoints: `sm` 480, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536. Per-component behaviour is in [frontend-components.md](frontend-components.md). | CH |
| BR-RWD-02 | No horizontal scrolling from 320px wide up to 32:9 (WCAG 1.4.10 Reflow). | CH |
| BR-RWD-03 | Text sizes are in `rem`. At 200% browser zoom no content is clipped or overlaps (WCAG 1.4.4). | CH |
| BR-RWD-04 | Below `lg`, touch targets are at least 44×44px: menu items, footer links, to-top, hamburger and hero controls. Footer links reach this with vertical padding, not with bigger text. | CH |
| BR-RWD-05 | Page content never exceeds the shared content width (BR-THEME-04). On ultrawide screens it is centred, and fixed elements align with it (BR-TOP-08). | CH, CQ2 |
## Reuse via Chakra and the theme (change request)
| ID | Rule | Source |
|---|---|---|
| BR-THEME-01 | A value that exists as a token is never hard-coded. That covers colours, spacing (`gutter`, `header`), durations, easings, letter spacing and z-index. | NFR-02 |
| BR-THEME-02 | Focus ring: one global `:focus-visible` style in `globalCss` (2px outline, 2px offset). Its colour comes from the semantic token `focusRing` (`accent.deep`). On photos, the `iconControl` recipe switches it to white. | CH |
| BR-THEME-03 | A new text style `pageTitle` is used for every page `h1` (PageIntro, StatusPage). `eyebrow` stays the one label style. | NFR-02 |
| BR-THEME-04 | A new size token `content` holds the `Container` max width. `Container` and BackToTop's alignment both use it, so there is only one width. | CQ2, NFR-02 |
| BR-THEME-05 | New z-index tokens `header`, `mobileNav`, `menuToggle` and `backToTop` replace the current `docked`, `calc(docked - 1)` and `modal` values. They make the stacking order (BR-TOP-09) explicit in one place. | CH |
| BR-THEME-06 | A new spacing token `pageTop` holds the header height plus standard spacing. PageIntro and StatusPage use it instead of each computing their own offset. | NFR-02 |
| BR-THEME-07 | Shared component styles are recipes (`linkButton`, `link` variant `subtle`, `iconControl`, `skipNavLink`), not repeated style props. A one-off style stays local; it gets no recipe. | NFR-02 |
## Decision Logic
```mermaid
graph TD
Start["Render footer"] --> Soc{"visibleSocials non-empty?"}
Soc -->|"yes"| ShowSoc["Show Socials column"]
Soc -->|"no"| HideSoc["Omit Socials column"]
ShowSoc --> Mail{"emailAddress valid?"}
HideSoc --> Mail
Mail -->|"yes"| ShowMail["Show Contact column with mailto link"]
Mail -->|"no"| HideMail["Omit Contact column"]
Scroll["Scroll event"] --> Past{"scrollY greater than 0.6 x viewport?"}
Past -->|"yes"| Visible["To-top visible"]
Past -->|"no"| Hidden["To-top hidden, not focusable"]
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef show fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef hide fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000;
classDef start fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
class Soc,Mail,Past decision;
class ShowSoc,ShowMail,Visible show;
class HideSoc,HideMail,Hidden hide;
class Start,Scroll start;
```
Text alternative: the footer shows the Socials column only when at least one valid social link remains and the Contact column only when the e-mail parts are valid; the to-top button is visible only when scrolled past 60% of the viewport height.
## Testable Properties (PBT-01)
| Function / component | Property | Category |
|---|---|---|
| `backToTopThreshold` | For any finite `h ≥ 0`: `0 ≤ t(h) ≤ h` | Invariant |
| `backToTopThreshold` | For finite `h1 ≤ h2`: `t(h1) ≤ t(h2)` (monotonic; non-finite input is 0 by BR-TOP-01) | Invariant |
| `backToTopThreshold` | Equals the model `0.6 × max(0, h)`; non-finite or negative input gives 0 | Oracle |
| `visibleSocials` | `visibleSocials(visibleSocials(x)) = visibleSocials(x)` | Idempotence |
| `visibleSocials` | Output is an order-preserving subsequence of the input | Invariant |
| `visibleSocials` | Every output `href` has protocol `https:`; every input with an `https:` URL is kept | Easy verification / Oracle |
| `emailAddress` | For valid parts: splitting the result at `@` returns the original `{ user, domain }` | Round-trip |
| `emailAddress` | Result is `null` or contains exactly one `@` and no whitespace | Invariant |
| `copyrightLine` | For any integer year: extracting the number from the line returns the year | Round-trip |
| `copyrightLine` | Always starts with `©` and ends with "Andrea Slop Fotografie" | Invariant |
| `canonicalUrl` | Idempotent: canonicalising the path of a canonical URL yields the same URL. Always starts with `siteUrl`; never ends with `/` except the root; never contains `?` or `#` | Idempotence / Invariant |
| `sitemapXml` | For any page list, the set of `<loc>` values equals the set of canonical URLs of the indexed pages, each exactly once | Oracle / Invariant |
| `sitemapXml` | Output is well-formed XML even for paths with `&`, `<`, `'` or `"`; parsing it back yields the original URLs | Round-trip |
| `jsonLdScript` | `JSON.parse(jsonLdScript(x))` deep-equals `x` for any JSON value with arbitrary strings | Round-trip |
| `jsonLdScript` | Output never contains `<`, so `</script` cannot occur | Invariant |
| `slidesToLoad` | Unique valid indexes, `min(count, 3)` of them, the active one first | Invariant |
| `slidesToLoad` | Every returned slide is at most one step away from the active one, wrapping around | Oracle |
| `sitePages` vs route tree | Same set of paths (BR-SEO-07; static data, example-based) | — |
| `mainNav`, `footerNav` | BR-NAV-01/02 (static data; example-based tests, no generator needed) | — |
**No PBT properties identified** (example-based tests only):
- `AppShell`, `NavigationBar`, `PageIntro`, `StatusPage`, `NotFound`, `ErrorPage`, `Footer`, `BackToTop` components: rendering and interaction with fixed inputs. Their logic lives in the pure functions above.
- Theme recipes: static style data.
@@ -0,0 +1,163 @@
# Domain Entities — frontend-shell
The shell has no back-end data. Its "domain" is the site-wide content that will later come from the CMS API, plus the menus, which are code. Every content type is plain data (strings, objects, arrays), so it can later be replaced 1-on-1 by an API response.
Decisions: [frontend-shell-fd-questions.md](../../plans/frontend-shell-fd-questions.md), [frontend-shell-fd-clarification-questions.md](../../plans/frontend-shell-fd-clarification-questions.md).
## Entity Relationships
```mermaid
graph TD
SiteContent["SiteContent"]
SocialLink["SocialLink"]
EmailAddress["EmailAddress"]
SocialPlatform["SocialPlatform registry"]
HeroContent["HeroContent"]
HeroSlide["HeroSlide"]
HeroCta["HeroCta"]
NavItem["NavItem"]
Routes["Registered routes"]
SiteContent -->|"has 0..n"| SocialLink
SiteContent -->|"has 1"| EmailAddress
SocialLink -->|"refers to"| SocialPlatform
HeroContent -->|"has 1..n"| HeroSlide
HeroContent -->|"has 1"| HeroCta
HeroCta -->|"points to"| Routes
NavItem -->|"points to"| Routes
classDef content fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef value fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
classDef code fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
class SiteContent,HeroContent content;
class SocialLink,EmailAddress,HeroSlide,HeroCta value;
class SocialPlatform,NavItem,Routes code;
```
Text alternative: SiteContent holds social links (each referring to a platform in the registry) and one e-mail address; HeroContent holds slides and a CTA pointing to a route; nav items point to routes (blue = CMS content, orange = value objects, green = code).
## Content (later from the CMS) — `content/types.ts`
### SiteContent
| Field | Type | Required | Description |
|---|---|---|---|
| `footerIntro` | `string` | yes | Intro text under the footer logo |
| `socials` | `SocialLink[]` | yes (may be empty) | Social profiles; shown in Hero (icons) and Footer (names) |
| `email` | `EmailAddress` | yes | Contact address, **stored in parts** (anti-spam, clarification Q3 = A) |
Static value until the API exists:
- `footerIntro`: "Lifestyle fotograaf uit Huizen.
Ik leg jouw mooiste momenten vast." (each sentence on its own line; line breaks in the content are kept, so the CMS can use a plain text area)
- `socials`: Facebook and Instagram (the current links from `heroContent.ts`)
- `email`: `{ user: 'info', domain: 'andreaslop.nl' }`
### EmailAddress (new value object)
| Field | Type | Required | Description |
|---|---|---|---|
| `user` | `string` | yes | Part before the `@` |
| `domain` | `string` | yes | Part after the `@` |
**Why parts**: the complete address then appears in neither the HTML nor the JavaScript bundle nor (later) the API response. It is joined only in the browser at render time (BR-EMAIL-01). This **refines FR-04 and the Application Design**, where `email` was a `string`.
### SocialLink (renamed from `HeroSocial`)
| Field | Type | Required | Description |
|---|---|---|---|
| `platform` | `SocialPlatform` | yes | Key into the platform registry |
| `href` | `string` | yes | Profile URL; only shown when it is a valid `https://` URL (BR-SOC-01) |
### HeroContent, HeroSlide, HeroCta (moved from `Hero/types.ts`)
Unchanged, except that `HeroContent.socials` is removed. The Hero receives `SiteContent.socials` as a separate prop.
| Entity | Fields |
|---|---|
| `HeroContent` | `title`, `tagline`, `cta: HeroCta`, `slides: HeroSlide[]` |
| `HeroSlide` | `id`, `src`, `alt` |
| `HeroCta` | `label`, `to` |
## Code (not content)
### SocialPlatform registry — `content/socialPlatforms.ts`
A fixed set of supported platforms: `facebook` and `instagram`, each with a display `name` and bundled `icon`. The CMS supplies only links. A platform outside the registry is a type error.
### NavItem — `navigation.ts`
| Field | Type | Description |
|---|---|---|
| `to` | registered route path | A typo is a type error |
| `label` | `string` | Menu text |
| Menu | Items, in order |
|---|---|
| `mainNav` | Home `/`, Over mij `/over-mij`, Portfolio `/portfolio`, Soorten fotoshoots `/soorten-fotoshoots`, Contact `/contact` |
| `footerNav` | Portfolio, Soorten fotoshoots, Contact, Privacyverklaring `/privacyverklaring` |
### Page copy (code until the real pages exist)
Placeholder, 404 and error page texts are fixed strings in their components. See [frontend-components.md](frontend-components.md).
## SEO entities (change request)
Decisions: [frontend-shell-fd-change-questions.md](../../plans/frontend-shell-fd-change-questions.md) ("CH").
```mermaid
graph TD
SiteConfig["siteUrl and site defaults"]
SitePage["SitePage registry"]
Route["Route file"]
Head["Page head"]
Sitemap["sitemap.xml"]
JsonLd["ProfessionalService JSON-LD"]
Socials["SiteContent.socials"]
Route -->|"looks up its"| SitePage
SitePage -->|"feeds"| Head
SiteConfig -->|"base URL for"| Head
SitePage -->|"indexed pages generate"| Sitemap
SiteConfig -->|"base URL for"| Sitemap
SiteConfig -->|"name, url, logo"| JsonLd
Socials -->|"sameAs"| JsonLd
classDef code fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef output fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef content fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
class SiteConfig,SitePage,Route code;
class Head,Sitemap,JsonLd output;
class Socials content;
```
Text alternative: the page registry is the single source for each route's head and for the generated sitemap; the site configuration supplies the base URL, and the JSON-LD block combines site data with the social links (green = code, blue = generated output, dark blue = content).
### Site configuration — `seo.ts`
| Constant | Value | Use |
|---|---|---|
| `siteUrl` | `https://andreaslop.nl` (no `www`, no trailing slash) | Canonical URLs, `og:url`, `og:image`, sitemap, JSON-LD (CH Q2 = A) |
| `siteName` | `Andrea Slop Fotografie` | `og:site_name`, title suffix, JSON-LD |
| `defaultOgImage` | `/og-image.jpg`, 1200×630, a crop of a hero photo, with alt text | Site-wide preview image; a page may override it (CH Q3 = A) |
### SitePage registry — `sitePages.ts` (new)
The single list of pages. Route heads and the sitemap both read it, so they cannot drift apart.
| Field | Type | Description |
|---|---|---|
| `path` | registered route path | Type-checked against the route tree |
| `title` | `string` | Page title without the site suffix (≤ ~60 chars including suffix) |
| `description` | `string` | Meta description (≤ ~155 chars) |
| `indexed` | `boolean` | `true`: in the sitemap, no robots tag. `false`: `noindex`, not in the sitemap |
| `ogImage?` | `string` | Optional page-specific preview image |
Initial values:
- `/` is indexed.
- `/over-mij`, `/portfolio`, `/soorten-fotoshoots`, `/contact` and `/privacyverklaring` are **not** indexed while they are placeholders.
- Putting a real page live means flipping `indexed` to `true`.
The 404 and error pages are not in the registry. They are not routes, and always set `noindex` themselves.
### Structured data — ProfessionalService (CH Q4 = A)
| Property | Value |
|---|---|
| `@type` | `ProfessionalService` |
| `name`, `url`, `logo`, `image` | `siteName`, `siteUrl`, absolute logo URL, `defaultOgImage` |
| `address` | `PostalAddress` with `addressLocality` Huizen, `addressCountry` NL |
| `areaServed` | `Place` "Huizen" |
| `sameAs` | hrefs of `visibleSocials(siteContent.socials)` |
| e-mail | **Deliberately absent** (BR-EMAIL-01) |
@@ -0,0 +1,188 @@
# Frontend Components — frontend-shell
Paths relative to `web/src/`. Builds on [components.md](../../../inception/application-design/components.md); this file adds behaviour, state and final copy. Rule IDs refer to [business-rules.md](business-rules.md).
## Component Hierarchy
```mermaid
graph TD
root["__root.tsx RootLayout"]
head["HeadContent"]
shell["AppShell"]
skip["SkipNavLink"]
nav["NavigationBar"]
navlink["NavLink"]
mobile["MobileNav"]
main["SkipNavContent as main"]
outlet["Outlet"]
pages["Route pages"]
intro["PageIntro"]
hero["Hero"]
notfound["NotFound"]
errorp["ErrorPage"]
status["StatusPage"]
footer["Footer"]
col["FooterColumn"]
top["BackToTop"]
rlink["RouterLink"]
lbtn["LinkButton"]
scrolled["useScrolledPast"]
root --> head
root --> shell
shell --> skip
shell --> nav
shell --> main
shell --> footer
shell --> top
nav --> navlink
nav --> mobile
main --> outlet
outlet --> pages
outlet --> notfound
outlet --> errorp
pages --> intro
pages --> hero
notfound --> status
errorp --> status
status --> lbtn
footer --> col
navlink --> rlink
mobile --> rlink
lbtn --> rlink
footer --> rlink
nav --> scrolled
top --> scrolled
classDef layout fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef hook fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
classDef chakra fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
class root,shell,main,outlet layout;
class nav,navlink,mobile,pages,intro,hero,notfound,errorp,status,footer,col,top,lbtn ui;
class rlink,scrolled hook;
class head,skip chakra;
```
Text alternative: the root layout renders HeadContent and AppShell; AppShell holds the skip link, NavigationBar, main (with the routed page, NotFound or ErrorPage), Footer and BackToTop; NotFound and ErrorPage share StatusPage; all router links go through RouterLink and both NavigationBar and BackToTop use useScrolledPast (green = layout, blue = UI, purple = shared primitive/hook, orange = built-in).
## Components
### AppShell
- **Props / state**: none
- **Renders**: `SkipNavLink` "Direct naar de inhoud" → `NavigationBar` → `SkipNavContent as="main" id="main"` with `<Outlet />` → `Footer content={siteContent}` → `BackToTop`
- **Hook**: `useRouteFocus()` (new, `hooks/`) subscribes to the router's resolved event and moves focus to `main#main` when the pathname changes, skipping the first load (BR-A11Y-01)
### RootLayout (`__root.tsx`)
- Root `head`: `siteHead` (site-wide Open Graph and `twitter:card` tags, default `og:image`) plus the JSON-LD script from `jsonLdScript(professionalService(siteContent))` (BR-SEO-04, -05)
### Route heads
- Each route calls `pageHead('/portfolio')` etc. `pageHead` looks up the `sitePages` entry and returns title, description, canonical link, `og:url`, `og:title`, `og:description`, `og:image` and, for `indexed: false`, `robots: noindex` (BR-SEO-01 to -04)
### Footer (+ local FooterColumn)
- **Props**: `content: SiteContent`. **State**: none.
- **Derived**: `socials = visibleSocials(content.socials)`, `email = emailAddress(content.email)`, `year = new Date().getFullYear()`
- **Top section** (`SimpleGrid`, 1 / 2 / 3 columns):
- Brand: `logo-dark.png` (alt "Andrea Slop Fotografie") + `footerIntro` with its line breaks kept. Mobile: logo 150px and text centred, stacked. Tablet and desktop: logo 110px with the text beside it, vertically centred (footer review)
- "Socials": text links with the platform name plus visually hidden " (opent in nieuw tabblad)"; omitted when empty (BR-FOOT-01, BR-A11Y-03)
- "Contact": `mailto:` link with the address as text; omitted when `email` is `null`
- Column headings are `h2` with `textStyle="eyebrow"` (BR-SEO-09); the logo has `width`/`height` and `loading="lazy"` (BR-SEO-10)
- **Bottom bar**: `copyrightLine(year)` + `nav aria-label="Footermenu"` with `footerNav`. Stacked and centred on mobile.
- **Links**: `Link variant="subtle"`; internal via `asChild` + `RouterLink` (`aria-current` without visual change, BR-FOOT-03)
### BackToTop
- **Props**: none. **State**: `visible` from `useScrolledPast(threshold)`; `threshold` is a module-level function `() => backToTopThreshold(window.innerHeight)`.
- **Renders**: `chakra.button` with `aria-label="Terug naar boven"` and the `up-outlined` icon (`aria-hidden`)
- **Behaviour**: BR-TOP-01…09. Click handler:
1. `reduced = matchMedia('(prefers-reduced-motion: reduce)').matches`
2. `window.scrollTo({ top: 0, behavior: reduced ? 'instant' : 'smooth' })`
3. `document.getElementById('main')?.focus({ preventScroll: true })`
### PageIntro
- **Props**: `title`, `eyebrow?`, `children?`
- **Renders**: `pt="pageTop"`, `Container`, eyebrow (`textStyle="eyebrow"`), one `h1` (`textStyle="pageTitle"`), children
### StatusPage
- **Props**: `title`, `children` (message), `actions?: ReactNode`. Defaults to one `LinkButton to="/"` "Terug naar home".
- **Refinement of the Application Design**: `action?: { label, to }` becomes `actions?: ReactNode`, because the error page needs a `button` next to a link (BR-ERR-04).
- **Renders**: `pt="pageTop"`, centred `Container`, one `h1` (`textStyle="pageTitle"`), text, action row
### NotFound
- Renders `<title>` + `<meta name="robots" content="noindex">` (BR-404-02) and `StatusPage`
### ErrorPage
- **Props**: `ErrorComponentProps` (`error`, `reset`). `error` is used only for logging.
- `useEffect(() => console.error(error), [error])` (BR-ERR-03)
- Renders `<title>` + `noindex` (BR-ERR-05) and `StatusPage` with two actions:
- "Opnieuw proberen": `chakra.button` with the `linkButton` recipe, variant `accent`. On click: `reset()` and `router.invalidate()`
- "Terug naar home": `LinkButton variant="outline"`
### NavigationBar, NavLink, MobileNav
- Menu from `mainNav`. Logo wrapped in `RouterLink to="/"` with `aria-label="Andrea Slop Fotografie, naar de homepage"`. Otherwise unchanged.
### Hero, HeroSocials, HeroArrows
- `Hero` props `content: HeroContent` and `socials: SocialLink[]`. `HeroSocials` renders `visibleSocials(socials)` with `aria-label` "{name} (opent in nieuw tabblad)". Both icon controls use the `iconControl` recipe, which also turns the focus ring white on photos.
- The first slide loads eagerly with `fetchpriority="high"`, the others lazily (BR-SEO-10).
## Responsive Behaviour (BR-RWD-01 to -05)
| Component | base (< 768) | md (768–1023) | lg (≥ 1024) | Ultrawide |
|---|---|---|---|---|
| NavigationBar | 66px, hamburger + mobile menu, always solid | same as base | 92px → 68px after scrolling, inline menu, transparent over the hero | content width centred |
| Footer top | 1 column | 2 equal columns; the third wraps to a new row | 3 columns, `1.2fr 1fr 1fr` | content width centred |
| Footer bottom bar | stacked, centred | one row: © left, menu right | same as md | content width centred |
| PageIntro / StatusPage | `gutter` side margin, title size `pageTitle` base | larger `pageTitle` | largest `pageTitle` | content width centred |
| BackToTop | 46px, design offset, 44px+ target | same | same | aligned to the content edge (BR-TOP-08) |
| Hero | full-screen photo, controls 44px+ | same | same | photo fills the width, text in the content width |
Every column: no horizontal scroll from 320px; works at 200% zoom.
## Theme Usage (BR-THEME-01 to -07)
| Shared piece | Kind | Status | Used by |
|---|---|---|---|
| `paper`, `ink`, `ink.soft`, `line`, `accent.deep` | colour tokens | existing | all |
| `focusRing` | semantic colour token + global `:focus-visible` | new | every focusable element |
| `gutter`, `header` | spacing tokens | existing | NavigationBar, Footer, PageIntro, StatusPage |
| `pageTop` | spacing token | new | PageIntro, StatusPage |
| `content` | size token | new | `Container` recipe, BackToTop |
| `header`, `mobileNav`, `menuToggle`, `backToTop` | z-index tokens | new | NavigationBar, MobileNav, BackToTop |
| `interaction`, `smooth` | duration/easing | existing | all transitions |
| `eyebrow` | text style | existing | footer headings, PageIntro eyebrow, buttons |
| `pageTitle` | text style | new | PageIntro, StatusPage |
| `linkButton` | recipe | existing | LinkButton, ErrorPage retry button |
| `link` variant `subtle` | recipe variant | new | Footer |
| `iconControl` | recipe | new | HeroArrows, HeroSocials |
| `skipNavLink` | recipe override | new | SkipNavLink |
| `RouterLink` | shared primitive | new | NavLink, MobileNav, LinkButton, logo, Footer |
## Copy
### Placeholder pages (Q8 = A)
Every placeholder uses `PageIntro` with the line **"Deze pagina is nog in de maak. Kom snel terug!"**
| Route | Eyebrow | `h1` |
|---|---|---|
| `/over-mij` | Andrea Slop Fotografie | Over mij |
| `/portfolio` | Werk | Portfolio |
| `/soorten-fotoshoots` | Mogelijkheden | Soorten fotoshoots |
| `/contact` | Neem contact op | Contact |
| `/privacyverklaring` | Privacy | Privacyverklaring |
### Status pages
| Page | `h1` | Text | Actions |
|---|---|---|---|
| 404 (Q9 = A) | Pagina niet gevonden | Deze pagina bestaat niet (meer). Misschien is de link verouderd of zit er een typfout in het adres. | Terug naar home |
| Error (Q10 = B) | Er ging iets mis | Door een fout kan deze pagina nu niet worden getoond. Probeer het opnieuw of ga terug naar de homepage. | Opnieuw proberen, Terug naar home |
## User Interaction Flows
- **Keyboard, first Tab**: skip link appears → Enter → focus in `main#main`
- **Back to top**: scroll down → button appears → click/Enter → page scrolls up, focus in `main`, button hides
- **Page change**: click a menu link → new page at the top, focus in `main`, screen reader reads the new content
- **Unknown URL**: shell + 404 → "Terug naar home"
- **Page error**: shell + error page → "Opnieuw proberen" re-renders the route, or "Terug naar home"
## Forms and API Integration
- **Forms**: none in the shell. The contact form is a later feature (see business-logic-model.md, Recommendations).
- **API**: none yet. `siteContent` and `heroContent` are static modules shaped like the future CMS responses.
@@ -0,0 +1,107 @@
# NFR Requirements — frontend-shell
Refines requirements NFR-01…NFR-06 into measurable criteria. Decisions: [frontend-shell-nfr-requirements-plan.md](../../plans/frontend-shell-nfr-requirements-plan.md) ("Q"), [frontend-shell-nfr-clarification-questions.md](../../plans/frontend-shell-nfr-clarification-questions.md) ("CQ"). Business rules (BR-*) are in [business-rules.md](../functional-design/business-rules.md).
## Quality Gates Overview
```mermaid
graph LR
Code["Code change"] --> Lint["pnpm lint"]
Lint --> Test["pnpm test incl. PBT, axe, coverage"]
Test --> Build["pnpm build incl. type check and sitemap"]
Build --> Audit["pnpm audit:deps"]
Audit --> LH["pnpm lighthouse on preview"]
LH --> Ready["Release ready"]
Check["pnpm check runs all steps"] -.-> Lint
classDef step fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef gate fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef done fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
class Code done;
class Lint,Test,Build,Audit,LH step;
class Check gate;
class Ready done;
```
Text alternative: `pnpm check` runs lint, tests (including property-based and accessibility tests), build, dependency audit and Lighthouse in that order; every step must pass before a release.
## NFR-P Performance
| ID | Requirement | Measure | Source |
|---|---|---|---|
| NFR-P-01 | Lighthouse Performance ≥ 90, mobile and desktop, on every route. **Exception (temporary): home page on mobile ≥ 80**, until responsive images come from the API/CMS and prerendering exists (measured 0.81–0.82). | `pnpm lighthouse` against `pnpm preview` | Q3 = B; code change Q1 = B |
| NFR-P-02 | No layout shift from shell elements: images have `width`/`height`, fonts are self-hosted | Lighthouse CLS ≤ 0.1 | BR-SEO-10 |
| NFR-P-03 | The shell adds no network requests beyond bundled assets | No third-party origins in the network log | NFR-05 |
| NFR-P-04 | Router devtools are not in the production bundle | Build output does not contain the devtools chunk | SECURITY-09 |
| NFR-P-05 | Scroll handling is passive, and NavigationBar and BackToTop share `useScrolledPast` | Code review | NFR-05 |
## NFR-A Accessibility
| ID | Requirement | Measure | Source |
|---|---|---|---|
| NFR-A-01 | Lighthouse Accessibility = 100, mobile and desktop, on every route | `pnpm lighthouse` | Q3 = B |
| NFR-A-02 | No axe-core violations in the component tests of the shell, placeholder, 404 and error pages | `pnpm test` (`vitest-axe`) | Q4 = A |
| NFR-A-03 | `jsx-a11y` lint rules pass | `pnpm lint` | Q5 = A |
| NFR-A-04 | Keyboard and screen-reader behaviour per BR-A11Y-01…07 and BR-TOP-03/06 | Example-based tests + manual check with NVDA or VoiceOver at Build and Test | NFR-01 |
| NFR-A-05 | Colour contrast per NFR-01. axe in `jsdom` cannot measure contrast, so Lighthouse covers it | NFR-A-01 | Q4 note |
## NFR-S SEO
| ID | Requirement | Measure | Source |
|---|---|---|---|
| NFR-S-01 | Lighthouse SEO = 100 on indexed pages (currently `/`) | `pnpm lighthouse` | CQ1 |
| NFR-S-02 | Non-indexed pages are `noindex` on purpose. Lighthouse's "blocked from indexing" audit is the only allowed SEO failure there | Lighthouse assertion per URL | CQ1 |
| NFR-S-03 | `sitemap.xml` contains exactly the indexed pages; registry and route tree are in sync | `pnpm test` (BR-SEO-07, PBT) + build output | BR-SEO-06/07 |
## NFR-SEC Security
| ID | Requirement | Measure | Source |
|---|---|---|---|
| NFR-SEC-01 | Headers on `preview`: <ul><li>CSP (below)</li><li>HSTS `max-age=31536000; includeSubDomains`</li><li>`nosniff`</li><li>`X-Frame-Options: DENY`</li><li>`Referrer-Policy: strict-origin-when-cross-origin`</li></ul> | Test on the header config + response check at Build and Test | SECURITY-04 |
| NFR-SEC-02 | Production CSP: `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'`. `style-src 'unsafe-inline'` is justified: Chakra/Emotion inject runtime styles. | Lighthouse Best Practices: no CSP violations in the console | SECURITY-04 |
| NFR-SEC-03 | The dev server uses the same headers. Its CSP adds only Vite's needs: `'unsafe-inline'` in `script-src` for the React Refresh preamble, and `ws:` in `connect-src` for HMR. These dev exceptions never reach `preview` or production. | Header config test | Q1 = A |
| NFR-SEC-04 | The production CSP has no inline scripts. `next-themes` is removed (Q2 = A); JSON-LD is a non-executed data block. | NFR-SEC-02 | Q2 = A |
| NFR-SEC-05 | `pnpm audit:deps` (`--prod --audit-level high`) passes: no high or critical advisories in packages that ship with the site. Advisories in dev-only tools are reported by `pnpm audit:dev` but do not block. | `pnpm check` | Q8 = A, SECURITY-10; code change Q2 = A |
| NFR-SEC-06 | Dependencies are pinned by `pnpm-lock.yaml`; no unused dependencies; build tools in `devDependencies` | Code review | SECURITY-10 |
| NFR-SEC-07 | No secrets in front-end code; the e-mail address is never a literal (BR-EMAIL-01) | Test: bundle does not contain the joined address | NFR-04, BR-EMAIL-01 |
| NFR-SEC-08 | Error and 404 pages expose no internals (BR-ERR-02) | Example-based test | SECURITY-09/15 |
## NFR-R Reliability
| ID | Requirement | Measure | Source |
|---|---|---|---|
| NFR-R-01 | A render error in a page never blanks the site: the shell stays and ErrorPage shows | Test with a throwing route | FR-10 |
| NFR-R-02 | Errors are logged with `console.error` in every environment (BR-ERR-03). Central logging is out of scope (SECURITY-03 N/A until there is a back-end). | Test | Q11 (FD) |
## NFR-M Maintainability and Testing
| ID | Requirement | Measure | Source |
|---|---|---|---|
| NFR-M-01 | Every testable property in business-rules.md has a fast-check property test. Failures print the seed and shrink. | `pnpm test` | PBT-02…08 |
| NFR-M-02 | 100% statement and branch coverage of the pure functions: `backToTopThreshold`, `visibleSocials`, `emailAddress`, `copyrightLine`, `canonicalUrl`, `sitemapXml`, `jsonLdScript`. No global threshold; coverage is reported. | Vitest coverage with per-file thresholds | Q7 = A |
| NFR-M-03 | ESLint (TypeScript, React Hooks, jsx-a11y) and Prettier pass | `pnpm lint`, `pnpm format:check` | Q5 = A |
| NFR-M-04 | `pnpm check` runs lint, format check, tests, build, audit and Lighthouse, in that order, and fails on the first failing step. It runs locally at any time. | Script | Q8 = A, CQ1 = A |
| NFR-M-05 | No duplicate styling: theme usage per BR-THEME-01…07 | Code review | NFR-02 |
## NFR-B Browser Support
| ID | Requirement | Source |
|---|---|---|
| NFR-B-01 | Supported: the last 2 versions of Chrome, Edge, Firefox and Safari, and Safari on iOS 16+. Older browsers get the site without guarantees. | Q6 = A |
| NFR-B-02 | Features used must work in that set: `color-mix()`, `:focus-visible`, `fetchpriority`, `prefers-reduced-motion`, `scrollTo` behaviour `instant`. `fetchpriority` degrades gracefully. | Q6 = A |
## Not Applicable
| Category | Rationale |
|---|---|
| Scalability | Static site without a server; load is the host's concern |
| Availability / DR | Depends on the future host (Operations phase) |
| Data protection / compliance | No personal data processed by the shell; privacy statement is a placeholder page |
## Follow-ups Outside This Unit
1. **CI/CD**: run `pnpm check` (including Lighthouse) automatically as the final step on every push or pull request, so a forgotten local check is caught early (CQ1). Hand-over to Deployment Setup in the Operations phase.
2. **Wider browser support** (Q6 note): reconsider support for older mobile browsers (e.g. iOS 14/15) once real visitor statistics exist.
3. **Responsive images** (code change Q1): the hero (and later portfolio) images should come in several widths from the API/CMS or an image service, used via `srcset`. Restores NFR-P-01 to 0.9 for the home page together with prerendering.
4. **Production headers**: configure the same header set (NFR-SEC-01/02) on the production host (Operations).
@@ -0,0 +1,104 @@
# Tech Stack Decisions — frontend-shell
Existing stack (unchanged): React 19, TypeScript, Vite, TanStack Router, Chakra UI v3, pnpm. See [technology-stack.md](../../../../../_shared/reverse-engineering/technology-stack.md).
All new packages are installed with pnpm at their latest stable version and pinned by `pnpm-lock.yaml` (SECURITY-10).
## Dependency Changes
| Package | Change | Kind | Why |
|---|---|---|---|
| `vitest` | add | dev | Test runner, native to Vite (NFR-03) |
| `@vitest/coverage-v8` | add | dev | Coverage with per-file thresholds (NFR-M-02) |
| `jsdom` | add | dev | DOM environment for component tests |
| `@testing-library/react`, `@testing-library/user-event`, `@testing-library/jest-dom` | add | dev | Component tests from the user's perspective |
| `fast-check` | add | dev | Property-based testing (PBT-09) |
| `vitest-axe` (on `axe-core`) | add | dev | Accessibility assertions in component tests (Q4 = A) |
| `eslint`, `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`, `globals` | add | dev | Linting (Q5 = A) |
| `@lhci/cli` | add | dev | Lighthouse CI with assertions (Q3 = B) |
| `next-themes` | **remove** | — | The site is fixed to light; it only added an inline script (Q2 = A) |
| `@vitejs/plugin-react` | move to dev | dev | Build tool (FR-11) |
| `@tanstack/react-router-devtools` | move to dev | dev | Loaded only in development (NFR-P-04) |
## Decisions
### TD-01 Property-based testing: fast-check (PBT-09)
- **Generators**: fast-check provides custom arbitraries for the domain types (`SocialLink`, `EmailAddress`, `SitePage`, paths, JSON values).
- **Shrinking and replay**: shrinking is on by default. On failure, fast-check reports the seed and path, and `fc.assert(..., { seed, path })` replays the exact case.
- **Test runner**: runs as normal Vitest tests, so no separate runner is needed.
- **Default runs**: 100 per property. Raise it per property only when needed.
- **Considered**: `@fast-check/vitest` (adds `test.prop`). Not needed: plain `fc.assert` inside `it` is enough and is one dependency less.
### TD-02 Test environment: Vitest + jsdom
- The Vitest config lives in `vite.config.ts` (`test` section), so tests use the same aliases and plugins as the app.
- Setup file: `@testing-library/jest-dom` matchers + `vitest-axe` matchers.
- Router-dependent components are tested inside a memory-history router.
- **Fallback**: if `vitest-axe` turns out to be incompatible with the installed Vitest version, a ~10-line custom `toHaveNoViolations` matcher on `axe-core` replaces it. Same assertion, one dependency less.
### TD-03 Linting: ESLint flat config
- Rule sets: `@eslint/js` recommended, `typescript-eslint` recommended, `react-hooks` recommended, `jsx-a11y` recommended.
- Prettier remains the formatter. No stylistic ESLint rules, to avoid conflicts.
- Excluded: `routeTree.gen.ts` and `dist`.
### TD-04 Lighthouse CI
- **Server**: `@lhci/cli` starts `pnpm preview`, so the real production headers and the SPA fallback apply. It measures every route in `sitePages` plus one unknown URL (the 404), on both mobile and desktop.
- **Assertions**:
- Performance ≥ 0.9
- Accessibility = 1
- Best Practices = 1
- SEO = 1 on indexed URLs. On `noindex` URLs only the `is-crawlable` audit is allowed to fail (NFR-S-02).
- **Requirements**: a local Chrome/Chromium.
- **Results**: written to `.lighthouseci/`, which is git-ignored. No upload to a public server.
- **Scripts**:
- `pnpm lighthouse` runs it on its own.
- It is part of `pnpm check` (CQ1 = A).
### TD-05 Security headers in Vite
- **One source**: `securityHeaders(mode)` in a small config module, used by `server.headers` (dev) and `preview.headers`.
- Production mode returns the strict set (NFR-SEC-01/02).
- Dev mode adds only the Vite exceptions (NFR-SEC-03).
- **Testing**: the function is pure, so a test can check that the production CSP never contains `unsafe-eval`, never contains `unsafe-inline` in `script-src`, and never contains `ws:`.
- **Production**: the same production set is the required configuration for the future host.
### TD-06 Vite config in TypeScript
- `vite.config.js` becomes `vite.config.ts`. It contains:
- the existing plugins
- the local `sitemap` plugin (BR-SEO-06), which reads `sitePages`
- the security headers (TD-05)
- the Vitest `test` section
- **Plugin**: about 30 lines, using Rollup's `generateBundle` hook to emit `sitemap.xml`. The XML itself comes from the pure, tested `sitemapXml`.
### TD-07 Scripts in `package.json`
| Script | Runs |
|---|---|
| `test` | `vitest run --coverage` |
| `test:watch` | `vitest` |
| `lint` | `eslint .` |
| `format:check` | `prettier --check .` |
| `audit:deps` | `pnpm audit --audit-level high` |
| `lighthouse` | `lhci autorun` |
| `check` | lint → format:check → test → build → audit:deps → lighthouse, stopping at the first failure |
### TD-08 Colour mode
- **Without `next-themes`**: the light theme is the default. The `_dark` semantic token values stay in the theme, so a dark mode can be added later without rework.
- **Considered**: keeping `next-themes` and allowing its script via a CSP hash. Rejected: the hash breaks on every library update, and the script has no use while the site is light-only.
## Security Baseline Compliance (NFR Requirements)
| Rule | Status | Rationale |
|---|---|---|
| SECURITY-04 | Compliant | Header set + CSP defined, `unsafe-inline` only for styles with documented justification (NFR-SEC-01…04) |
| SECURITY-09 | Compliant | Devtools dev-only, starter assets removed, generic error pages |
| SECURITY-10 | Compliant | Lock file, `audit:deps` in `check`, unused `next-themes` removed, build tools in dev |
| SECURITY-13 | Compliant | No CDN resources; Lighthouse CI uploads nothing externally |
| SECURITY-15 | Compliant | Root error boundary (NFR-R-01) |
| SECURITY-03, -14 | N/A | No server component; revisit with the .NET API |
| Others | N/A | As in requirements.md |
## PBT Compliance (NFR Requirements)
| Rule | Status | Rationale |
|---|---|---|
| PBT-09 | Compliant | fast-check: custom arbitraries, shrinking, seed replay, runs in Vitest (TD-01) |
| Others | N/A at this stage | Applied in Code Generation |
@@ -0,0 +1,12 @@
# Build and Test Questions — frontend-shell
## Vraag 1: "SOCIALS" wordt door de schermlezer gespeld
De koptekst is in de code "Socials"; het thema maakt hem met CSS hoofdletters. Schermlezers op mobiel (VoiceOver, TalkBack) lezen de tekst zoals hij in beeld staat, zien "SOCIALS" en behandelen het als een afkorting. "CONTACT" herkennen ze wel als woord. Ik kan mobiele schermlezers hier niet zelf testen, dus na de aanpassing vraag ik je het opnieuw te proberen.
A) De kop een `aria-label` geven met het woord in gewone schrijfwijze ("Socials"). In beeld verandert niets. Moderne schermlezers lezen dan het label in plaats van de hoofdletters, maar niet elke combinatie van schermlezer en browser doet dat even goed.
B) De kop veranderen in "Social media". In beeld staat dan "SOCIAL MEDIA"; twee gewone woorden worden vrijwel altijd als woorden voorgelezen. **(aanbevolen)** Het meest betrouwbaar, en ook voor bezoekers duidelijker.
C) De kop veranderen in "Volg mij", passend bij de Nederlandse toon van de site
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -0,0 +1,34 @@
# Code Generation Change Questions — frontend-shell
Meting na je nieuwe afbeeldingen: homepage mobiel **0,82** (doel 0,9), totale download **2,6 MB**. Vul per vraag de letter in na `[Answer]:`. Waar ik een voorkeur heb staat **(aanbevolen)**.
## Vraag 1: Hoe halen we de homepage op mobiel naar 0,9?
Wat nu nog vertraagt: de eerste foto (2560 px breed, ook op een telefoon), de JavaScript-bundel (169 KB gzip, vooral Chakra) en de titel die pas verschijnt als de JavaScript binnen is.
A) Nu responsive afbeeldingen toevoegen: bij het bouwen worden van elke hero-foto kleinere varianten gemaakt (bv. 640, 1280 en 2560 px), en de browser kiest de passende (`srcset`). Telefoons downloaden dan een foto van ±50–80 KB in plaats van 325 KB. Kost één extra dev-afhankelijkheid (`vite-imagetools`). Waarschijnlijk genoeg voor 0,9, maar dat meet ik na. **(aanbevolen)**
B) Het doel voor de homepage op mobiel voorlopig op 0,8 zetten. Responsive afbeeldingen en prerendering pakken we op bij de portfolio-feature.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B, omdat de data later uit een API komt weet ik niet of responseive foto's met een vite-plugin toevoegen verstandig is voor een tijdelijke situatie. Prerendering pakken we sowieso later op.
## Vraag 2: Wanneer moet de controle op kwetsbare pakketten falen?
De gebouwde site heeft geen kwetsbaarheden (`pnpm audit --prod` is schoon). De 5 meldingen zitten in ontwikkeltools die alleen op jouw computer draaien. Voor de meeste bestaat nog geen oplossing.
A) De check faalt alleen op kwetsbaarheden in pakketten die in de site terechtkomen. Meldingen in ontwikkeltools worden wel getoond, maar blokkeren niet. **(aanbevolen)**
B) Zoals A, en daarnaast Lighthouse CI niet meer als vaste ontwikkeltool installeren, maar bij elke run met een vaste versie ophalen (`pnpm dlx @lhci/cli@0.15.1`). Er staan dan minder pakketten in het project; de meldingen blijven bestaan, maar buiten het project.
C) Zoals vastgelegd: de check faalt op elke hoge melding, ook in ontwikkeltools. Dan faalt `pnpm check` tot de makers van die tools een oplossing uitbrengen.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 3: Hoe laden de hero-foto's?
Nu laadt de homepage na de eerste foto direct alle andere foto's (8 stuks, ±2,4 MB), ook als de bezoeker na 10 seconden doorklikt.
A) Alleen de huidige en de volgende foto laden. Elke keer dat de slider doorschuift, wordt de foto daarna opgehaald; met de pijlen terug blijft de vorige ook beschikbaar. Het aantal foto's maakt dan voor de snelheid nauwelijks uit. **(aanbevolen)**
B) Zoals nu: na de eerste foto alles laden
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, maar je kan vanaf de eerste foto ook terug-klikken naar de laatste foto, dus de actieve foto + de volgende en vorige (of laatste in geval van eerste foto) wil je laden.
@@ -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.
@@ -0,0 +1,95 @@
# Functional Design Change Questions — SEO, schermlezers, responsive, hergebruik
Je vroeg om SEO, schermlezers, responsive design en hergebruik via Chakra/thema meteen mee te nemen. Het grootste deel kan ik op vaste uitgangspunten uitwerken (zie "Wordt uitgewerkt zonder vraag"). Hieronder staan alleen de punten waar een echte keuze in zit. Vul per vraag de letter in na `[Answer]:`. Waar ik een voorkeur heb staat **(aanbevolen)**.
## Wordt uitgewerkt zonder vraag
**SEO**
- Per pagina een unieke titel en beschrijving (bestaat al via `pageHead`). Placeholderpagina's en 404/fout krijgen `noindex`, zodat een lege "in de maak"-pagina niet in Google komt. Zodra de echte inhoud er staat, gaat `noindex` eraf.
- Eén `h1` per pagina, koppen in logische volgorde (geen niveaus overslaan). Footerkoppen zijn `h2`, opgemaakt als eyebrow: het zijn hoofdsecties van de pagina (gecorrigeerd bij het uitwerken, zie BR-SEO-09).
- Interne links zijn echte `<a href>`-links (geen klik-handlers op `div`s), zodat zoekmachines ze kunnen volgen.
- Alle afbeeldingen hebben een betekenisvolle `alt`, decoratieve krijgen `alt=""`.
**Schermlezers**
- `lang="nl"` (staat al), landmarks `header`/`nav`/`main`/`footer` met Nederlandse labels.
- Skip link, zichtbare focusstijl op alles wat focus kan krijgen, en die focusstijl komt **op één plek uit het thema** in plaats van per component.
- Iconen zijn `aria-hidden`; knoppen met alleen een icoon hebben een `aria-label`.
- Externe links die in een nieuw tabblad openen, melden dat aan schermlezers ("opent in nieuw tabblad", visueel verborgen).
- Respecteren van `prefers-reduced-motion`.
**Responsive**
- Mobile-first, met de standaard Chakra-breakpoints (`sm` 480, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536). Per component een tabel met wat er per breakpoint verandert.
- Werkt van 320px breed tot 32:9 zonder horizontaal scrollen; tekst kan 200% vergroot worden zonder dat er iets wegvalt.
- Klikdoelen minimaal 44×44px op touch (menu, footerlinks, to-top).
**Hergebruik via Chakra en het thema**
- Een overzicht per component van welke tokens, text styles en recipes het gebruikt, en welke nieuwe gedeelde stukken erbij komen (bv. één `pageTitle`-text style voor de `h1` van PageIntro en StatusPage, één `focusRing` voor de hele site, z-index-tokens voor header/menu/to-top in plaats van losse getallen).
- Geen waarden die al als token bestaan, opnieuw hard in een component.
---
## Questions
### Vraag 1: Link-previews en crawlers die geen JavaScript uitvoeren
De site wordt in de browser opgebouwd. Google voert JavaScript uit en ziet dus de juiste titel per pagina. **WhatsApp, Facebook en LinkedIn doen dat niet**: die zien bij elke pagina alleen de vaste fallback uit `index.html` (de homepage-titel). Dat los je alleen op door de pagina's bij het bouwen al als HTML te genereren ("prerendering").
A) Nu nog niet prerenderen, maar alles zo bouwen dat het later zonder ombouw kan: alle head-data via de route-`head`, geen `window`/`document` tijdens het renderen, content via props. Prerendering wordt een vervolgpunt bij hosting/Operations. **(aanbevolen)** Prerendering is pas zinvol als er echte pagina-inhoud is; nu zijn het placeholders.
B) Nu al prerendering toevoegen in deze feature (een build-stap die per route statische HTML maakt). Grotere scope en een extra afhankelijkheid.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 2: Domein voor canonical-URL's en `og:url`
Voor canonical-URL's (voorkomt dubbele pagina's in Google) en voor link-previews is het definitieve adres nodig.
A) `https://andreaslop.nl` (zonder www) **(aanbevolen)** Komt overeen met het e-maildomein; `www` stuurt de host dan door.
B) `https://www.andreaslop.nl`
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 3: Afbeelding voor link-previews (`og:image`)
Zonder `og:image` tonen WhatsApp en Facebook een preview zonder plaatje.
A) Eén vaste site-brede afbeelding (een uitsnede van een hero-foto, 1200×630), die een pagina later kan overschrijven met een eigen beeld **(aanbevolen)**
B) Het logo als preview-afbeelding
C) Nog geen `og:image`
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 4: Gestructureerde data voor Google (JSON-LD)
Met gestructureerde data begrijpt Google dat dit een lokale fotograaf is (naam, plaats, socials). Dat helpt bij lokaal zoeken ("fotograaf Huizen").
A) Ja, site-breed één `ProfessionalService`-blok met naam, website, regio Huizen, logo en de social-links. **Zonder e-mailadres**, anders staat het adres alsnog leesbaar in de pagina. **(aanbevolen)**
B) Nog niet, later met de echte pagina's
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 5: `robots.txt` en `sitemap.xml`
A) Beide als statisch bestand in `public/`. De sitemap bevat alleen de geïndexeerde pagina's (nu: home) en wordt bijgewerkt zodra er een pagina live gaat. Een test controleert dat de sitemap en de routes niet uit elkaar lopen. **(aanbevolen)**
B) De sitemap wordt bij elke build automatisch gemaakt uit de routes. Meer werk nu, maar niets handmatig bij te houden.
C) Later, bij hosting/Operations
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B is het makkelijkste. Hoeveel meerwerk is het en hoe wordt het automatisch opgebouwd? Hoe betrouwbaar is het? Bij teveel gedoe of onzekerheden is A het beste. Anders B, met eventueel de test uit optie A
### Vraag 6: Paginawissel aankondigen aan schermlezers
Bij een gewone website leest een schermlezer na een klik de nieuwe pagina voor. In een app als deze gebeurt dat niet vanzelf: de inhoud wisselt, maar de schermlezer merkt het niet.
A) Na elke paginawissel (niet bij de eerste keer laden) gaat de focus naar `main#main`, net als bij de skip link en de to-top-knop. De schermlezer leest dan de nieuwe inhoud vanaf het begin. **(aanbevolen)** Eén consistent gedrag.
B) De focus blijft staan en een onzichtbaar meldingsgebied leest de nieuwe paginatitel voor ("Portfolio, pagina geladen")
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -0,0 +1,70 @@
# Functional Design Clarification Questions — frontend-shell
Je antwoorden op vraag 4, 6 en 12 bevatten aanvullende wensen. Die werk ik hieronder uit met aanbevelingen. Vul per vraag de letter in na `[Answer]:`.
---
## Ambiguity 1: Zichtbaarheid en positie van de to-top-knop (vraag 4)
Je koos `accent.deep` als hoverkleur, maar vindt de knop in het design niet duidelijk genoeg en hij staat op een 32:9-scherm ver van de content af.
Wat het design nu doet: lichte achtergrond (`paper`), dunne lijn (`line`) als rand en een donkere pijl. Over een lichte pagina valt die knop bijna weg. De rand zelf haalt geen 3:1 contrast, dus alleen de pijl is echt zichtbaar.
### Clarification Question 1: Uiterlijk van de knop
A) Omgekeerd: donkere achtergrond (`ink`) met witte pijl, zonder rand. Hover: achtergrond `accent.deep`. Valt goed op op lichte en op donkere vlakken, en is dezelfde stijl als de skip link. **(aanbevolen)**
B) Licht zoals het design, maar met een duidelijke rand in `ink.soft` en een lichte schaduw. Hover: rand en pijl `accent.deep`. Dichter bij het design, minder opvallend.
C) Precies zoals het design, alleen de hoverkleur `accent.deep`
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Clarification Question 2: Positie op hele brede schermen
A) De knop lijnt uit met de rechterkant van de content (de maximale breedte van `Container`). Op normale schermen verandert er niets, want daar is de content even breed als het scherm. Op een ultrawide staat hij naast de content in plaats van in de hoek van het scherm. **(aanbevolen)**
B) Altijd rechtsonder in de hoek van het scherm, zoals het design
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
---
## Ambiguity 2: E-mailadres beschermen tegen spam (vraag 6 en 12)
Eerst de eerlijke basis: **een adres dat een bezoeker kan lezen, kan een bot uiteindelijk ook lezen.** Je kunt het oogsten alleen duur en lastig maken. De meeste spambots zijn eenvoudig: ze lezen de HTML en zoeken naar `iets@iets.nl` of `mailto:`. Daar valt het meeste te winnen.
Hoe het nu zit:
- **De huidige statische site**: het adres staat drie keer letterlijk in de HTML. Dat is precies wat bots oogsten, en verklaart waarschijnlijk de spam die je nu krijgt.
- **De nieuwe React-site**: de pagina wordt in de browser opgebouwd, dus in de HTML staat het adres al niet meer. Wel staat `info@andreaslop.nl` letterlijk in het JavaScript-bestand. Sommige bots doorzoeken dat ook.
De gangbare technieken op een rij:
| Techniek | Bescherming | Nadeel |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 1. Adres in delen opslaan (`info` + `andreaslop.nl`), pas in de browser samenvoegen | Goed tegen bots die HTML of JS-bestanden doorzoeken | Bots die de pagina echt uitvoeren (headless browser) zien het nog wel; dat zijn er weinig |
| 2. Pas tonen na een klik ("Toon e-mailadres") | Nog beter: zelfs een uitgevoerde pagina bevat het adres pas na een klik | Eén extra klik voor de bezoeker |
| 3. Contactformulier in plaats van een adres | Het sterkst: het adres staat nergens op de site | Heeft een backend nodig (de .NET API, later); hoort bij de Contact-pagina, buiten deze feature |
| 4. Apart adres voor de site (bv. `contact@`) met een goed spamfilter | Beperkt de schade als het toch uitlekt | Is een mailbox-instelling, geen code |
| Afgeraden: adres als afbeelding, of met CSS-trucs achterstevoren | Werkt | Onbruikbaar voor schermlezers, niet te kopiëren of aan te klikken; botst met NFR-01 |
Mijn aanbeveling: **1 nu in de shell**, en 3 en 4 voor later. Optie 2 is de moeite waard als je meer zekerheid wilt en de extra klik acceptabel vindt.
### Clarification Question 3: Hoe toont de footer het e-mailadres?
A) Techniek 1: het adres wordt in delen opgeslagen (ook straks in de CMS-data) en pas in de browser samengevoegd. Daarna staat het als gewone, aanklikbare `mailto:`-link met het adres als tekst, zoals in het design. Toegankelijk en zonder extra klik. **(aanbevolen)**
B) Techniek 1 + 2: de footer toont eerst een knop "Toon e-mailadres". Pas na de klik wordt het adres samengevoegd en verschijnt de `mailto:`-link.
C) Geen e-mailadres in de footer, alleen een link "Neem contact op" naar de Contact-pagina. Daar komt later het contactformulier (techniek 3).
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, verder ter info: techniek 4 is al toegepast met dit specifieke e-mailadres.
### Clarification Question 4: Vastleggen van de vervolgstappen buiten deze feature
Techniek 3 (contactformulier) en 4 (apart adres + spamfilter) vallen buiten de shell.
A) Opnemen als aanbeveling in de functional design, zodat ze bij de Contact-pagina en de .NET API weer opduiken **(aanbevolen)**
B) Niet vastleggen
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, maar techniek 4 is al (deels) toegepast. info@andreaslop.nl is al een mailadres specifiek voor de website.
@@ -0,0 +1,127 @@
# Functional Design Questions — frontend-shell
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**.
## Already decided (no question needed)
- **Drempel to-top**: zichtbaar zodra `scrollY > 0,6 × viewporthoogte` (strikt groter dan, zoals `useScrolledPast` nu werkt voor de header).
- **Jaartal**: `new Date().getFullYear()` op het moment van renderen.
- **Externe links**: altijd `target="_blank"` + `rel="noopener noreferrer"` (NFR-04).
- **Volgorde menu's**: exact zoals FR-02 en FR-05; geen dubbele routes binnen één menu.
---
## Questions
### Vraag 1: Hoe krijgt de 404-pagina haar titel en `noindex`?
Een onbekende URL heeft geen eigen route, dus ook geen eigen `head`. Ik heb React 19 en TanStack Router naast elkaar bekeken.
A) `NotFound` rendert zelf `<title>` en `<meta name="robots" content="noindex">`. React 19 zet die automatisch in `<head>` en haalt ze weg zodra je de pagina verlaat. Bij een not-found matcht alleen de root-route, en die zet geen titel, dus er komt geen dubbele `<title>`. **(aanbevolen)** Simpel en lokaal bij de pagina.
B) De root-route `head` kijkt of de huidige match "not found" is en zet dan titel + `noindex`. Alles loopt via `HeadContent`, maar de root krijgt kennis van de 404-pagina.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 2: Waar gaat de toetsenbordfocus heen na een klik op "Terug naar boven"?
Bovenaan verdwijnt de knop, dus als de focus erop blijft, staat hij op een onzichtbaar element.
A) Naar `main#main` (hetzelfde doel als de skip link). Een toetsenbordgebruiker kan daarna direct verder vanaf de inhoud. **(aanbevolen)**
B) Naar het begin van de pagina (`body`), zodat de volgende Tab weer bij de skip link begint
C) Focus niet verplaatsen
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 3: Animatie van de to-top-knop bij verschijnen en verdwijnen
A) Zoals het design: infaden en 8px omhoog schuiven, met de bestaande tokens voor duur en easing. Bij `prefers-reduced-motion` alleen direct tonen/verbergen, zonder beweging. **(aanbevolen)**
B) Alleen infaden, geen beweging
C) Geen animatie
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 4: Hoverkleur van de to-top-knop
Het design kleurt rand en pijl bij hover naar `accent` (#7f8b76). Dat haalt op de lichte achtergrond net 3:1, de grens voor iconen. Voor tekstlinks gebruiken we al `accent.deep` (NFR-01).
A) `accent.deep`, gelijk aan de linkhover in de footer. Ruim voldoende contrast en één consistente hoverkleur. **(aanbevolen)**
B) `accent`, precies zoals het design
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, al vind ik de knop en z'n kleuren nu sowieso niet heel erg duidelijk en vraga me af of die niet wegvalt. Daarbij komt dat op een 32:9 scherm de knop nog steeds helemaal rechtsonderin getoond wordt terwijl de content een max width heeft.
### Vraag 5: Welke social-links worden getoond?
Nu filtert `HeroSocials` alleen lege `href`s weg. Straks komen de links uit het CMS, dus ze zijn invoer van buiten de code.
A) Alleen links met een geldige `https://`-URL tonen. Leeg, `http://`, `javascript:` of iets anders onleesbaars wordt overgeslagen. **(aanbevolen)** Dit voorkomt dat een fout in het CMS een onveilige link oplevert.
B) Alleen lege links overslaan, zoals nu
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 6: Wat als een footerkolom niets te tonen heeft?
Bijvoorbeeld geen enkele geldige social-link, of een leeg e-mailadres.
A) De kolom (kop + inhoud) helemaal weglaten. Het grid schuift gewoon door. **(aanbevolen)**
B) De kop wel tonen met een lege kolom, zodat de layout altijd drie kolommen heeft
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, verder wil ik kijken hoe we het e-mailadres zo veilig mogelijk kunnen plaatsen om te beschermen tegen spam. Dat is nu namelijk ook al een probleem.
### Vraag 7: Actieve pagina in het footermenu
In het hoofdmenu krijgt de actieve pagina een streep (`aria-current="page"`).
A) Ook in de footer `aria-current="page"` zetten (gratis via de router) en de actieve link in `accent.deep` tonen
B) Wel `aria-current="page"` voor schermlezers, maar geen visueel verschil **(aanbevolen)** Het design toont geen actieve status in de footer.
C) Geen actieve status in de footer
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
### Vraag 8: Tekst op de placeholderpagina's (Portfolio, Soorten fotoshoots, Contact, Privacyverklaring, Over mij)
A) Eyebrow en `h1` uit de `page-head` van het design (Portfolio: "Werk" / "Portfolio", Soorten fotoshoots: "Mogelijkheden" / "Soorten fotoshoots", Contact: "Neem contact op" / "Contact", Over mij: "Andrea Slop Fotografie" / "Over mij"; Privacyverklaring heeft geen design en wordt "Privacy" / "Privacyverklaring"), plus de regel "Deze pagina is nog in de maak. Kom snel terug!" **(aanbevolen)**
B) Alleen de paginanaam als `h1`, zonder eyebrow, met de regel "Deze pagina is nog in de maak."
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 9: Tekst op de 404-pagina
A) Kop "Pagina niet gevonden", tekst "Deze pagina bestaat niet (meer). Misschien is de link verouderd of zit er een typfout in het adres.", knop "Terug naar home". **(aanbevolen)**
B) Kop "Oeps, hier is niets te zien", tekst "Deze pagina kon ik niet vinden.", knop "Terug naar home"
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 10: Welke acties biedt de foutpagina?
A) Alleen "Terug naar home"
B) "Opnieuw proberen" (laadt de pagina opnieuw via de router) én "Terug naar home" **(aanbevolen)** Een tijdelijke fout is dan met één klik op te lossen.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
### Vraag 11: Loggen van fouten in de browserconsole
Er is (nog) geen centrale logging. Bezoekers zien nooit details, maar de console is voor iedereen te openen.
A) Altijd `console.error(error)`, ook in productie. Handig bij het debuggen van meldingen, en een frontend-fout bevat geen geheimen. **(aanbevolen)**
B) Alleen in development (`import.meta.env.DEV`)
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 12: Hoe staat het e-mailadres in de Contact-kolom?
A) Het adres zelf als linktekst (`info@…` → `mailto:`), zoals het design **(aanbevolen)**
B) Een vaste tekst, bv. "Stuur me een mail", met het adres alleen in de link
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: x, bij vraag 6 heb ik ook al een opmerking geplaatst. Wat is de veiligste manier om het e-mailadres te tonen? Geef mij aanbevelingen
@@ -0,0 +1,21 @@
# Functional Design Plan — frontend-shell
Unit: **frontend-shell** (single unit; Units Generation skipped). Builds on the approved Application Design in `inception/application-design/`.
Questions for this stage are in [frontend-shell-fd-questions.md](frontend-shell-fd-questions.md).
## Plan
- [x] 1. Answer the functional design questions
- [x] 2. Analyze answers for ambiguities (follow-up questions if needed)
- [x] 3. Generate `domain-entities.md` — content and navigation data model (`SiteContent`, `SocialLink`, `SocialPlatform`, `NavItem`, `HeroContent`) with relationships and field rules
- [x] 4. Generate `business-rules.md` — behaviour rules and decision logic:
- back-to-top visibility, scroll and focus rules
- social link filtering/validation and empty-content rules
- copyright line, nav invariants
- 404 head (title + `noindex`) mechanism
- error page behaviour and logging
- [x] 5. Generate `business-logic-model.md` — flows: page navigation and scroll restoration, not-found and error rendering inside/outside the shell, back-to-top interaction, content provisioning
- [x] 6. Generate `frontend-components.md` — component hierarchy, props/state per component, interaction flows, final Dutch copy for placeholders, 404 and error page
- [x] 7. Add the "Testable Properties" section (PBT-01) covering `backToTopThreshold`, `visibleSocials`, `copyrightLine`, `mainNav`/`footerNav`, and explicitly mark components without properties
- [x] 8. Validate against FR-01…FR-11, NFR-01…NFR-05, Security Baseline and PBT-01; validate Mermaid diagrams
@@ -0,0 +1,18 @@
# NFR Requirements Clarification Questions — frontend-shell
## Ambiguity 1: Wanneer draait Lighthouse CI? (vraag 3 = B)
Je koos voor automatisch meten met Lighthouse CI. Een run bouwt de site, start een browser (Chrome moet geïnstalleerd zijn) en meet elke pagina een paar keer. Dat kost al snel 30–60 seconden. "Bij elke build" kan twee dingen betekenen.
Twee dingen gelden ongeacht je keuze:
- Lighthouse meet de pagina's mobiel én desktop.
- De placeholderpagina's staan bewust op `noindex`, en Lighthouse rekent dat af in de SEO-score. Het doel "SEO 100" geldt daarom alleen voor geïndexeerde pagina's (nu: home). Voor de andere pagina's geldt alleen de controle dat `noindex` er bewust staat.
### Clarification Question 1
A) Een apart script `pnpm lighthouse`, en het draait mee in `pnpm check` (de controle vóór elke release, zie vraag 8). `pnpm build` blijft snel. Haalt een pagina de doelen niet, dan faalt `check`. **(aanbevolen)**
B) Echt bij elke `pnpm build`. Elke build duurt dan 30–60 seconden langer en faalt als een doel niet gehaald wordt.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, er vanuitgaand dat ik lokaal de check kan draaien zodat ik tussendoor ook een check kan doen. Ik vraag me alleen wel af of een automatische check vlak voor release niet te laat is. Stel ik doe onderhoud en vergeet dat ik die check moet doen. Dan zie ik dat pas vlak voor release. Als het standaard in CI/CD workflow wordt meegenomen als bijvoorbeeld de laatste stap, dan hoeft het niks in de weg te zitten.
@@ -0,0 +1,99 @@
# NFR Requirements Plan — frontend-shell
Unit: **frontend-shell**. Builds on requirements NFR-01…NFR-06 and the approved functional design. NFR Design is skipped (execution plan); the patterns are small and go straight into this document and the code generation plan.
## Plan
- [x] 1. Answer the questions below
- [x] 2. Analyze answers for ambiguities (follow-up questions if needed)
- [x] 3. Generate `nfr-requirements.md` — measurable NFRs per category: performance, accessibility, SEO, security, reliability, maintainability/testing, browser support; scalability/availability marked N/A with rationale
- [x] 4. Generate `tech-stack-decisions.md` — test stack (PBT-09), linting, security headers/CSP, build plugins, dependency changes with rationale
- [x] 5. Validate against Security Baseline (SECURITY-04, -09, -10, -13, -15) and PBT-09
## Already decided (no question needed)
- **Scalability and availability**: N/A for the shell. It is a static site without a server; availability depends on the future host (Operations).
- **Test stack** (NFR-03, PBT-09): Vitest + React Testing Library + `@testing-library/user-event` + `jsdom` + fast-check. fast-check covers custom generators, shrinking and seed-based replay, and runs inside Vitest. The seed is printed on failure and can be passed back to replay a run.
- **Security headers** (NFR-04): `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` and HSTS `max-age=31536000; includeSubDomains`. Browsers ignore HSTS over plain `http://localhost`, so locally it has no effect; it matters on the production host.
- **CSP content for the production build**: `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'`.
- `style-src 'unsafe-inline'` is needed because Chakra/Emotion inject `<style>` tags at runtime (justified).
- The JSON-LD block is a data block (`application/ld+json`). It is not executed and needs no CSP exception.
- **Router devtools**: only loaded in development (`import.meta.env.DEV`), so they are not in the production bundle (SECURITY-09 hardening). `@tanstack/react-router-devtools` moves to `devDependencies`.
- **Sitemap plugin**: a local plugin in the Vite config; no extra dependency. `vite.config.js` becomes `vite.config.ts`, so it can import the typed `sitePages` registry and get type checking.
---
## Questions
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**.
### Vraag 1: Content-Security-Policy tijdens het ontwikkelen
De strenge CSP hierboven werkt op de gebouwde site (`pnpm preview`). De dev-server (`pnpm dev`) heeft voor hot reload een inline script en een websocket nodig. Een strenge CSP breekt daar het herladen.
A) Strenge CSP op `preview` (en als voorschrift voor productie). In `dev` dezelfde CSP, maar met alleen de uitzonderingen die Vite nodig heeft (inline script voor React Refresh, websocket voor HMR). De overige headers zijn in beide gelijk. **(aanbevolen)** Je ziet CSP-problemen dan al tijdens het ontwikkelen, behalve die van Vite zelf.
B) Alleen op `preview` een CSP; `dev` zonder CSP
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 2: `next-themes` (wisselen tussen licht en donker)
De site staat vast op licht (`defaultTheme="light"`, `enableSystem={false}`). `next-themes` doet nu dus niets nuttigs. Wel zet het een inline script in de pagina, en dat botst met een strenge CSP (`script-src 'self'`).
A) `next-themes` verwijderen en de site vast op licht zetten. Het thema houdt zijn `_dark`-waarden, zodat een donkere modus later weer kan. **(aanbevolen)** Eén afhankelijkheid minder, en geen CSP-uitzondering nodig.
B) Houden voor een mogelijke donkere modus later, en het script via een hash in de CSP toestaan
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 3: Meetbare doelen voor kwaliteit
A) Lighthouse (mobiel) ≥ 90 voor Performance en 100 voor Accessibility, Best Practices en SEO, op de gebouwde site (`pnpm preview`). Handmatig gemeten bij Build and Test. **(aanbevolen)**
B) Hetzelfde, maar automatisch bij elke build (Lighthouse CI). Meer opzetwerk, en zonder CI-server draait het alleen lokaal.
C) Geen harde doelen, alleen de regels uit het functional design
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
### Vraag 4: Automatisch testen op toegankelijkheid
A) `axe-core` in de componenttests (via `vitest-axe`): elke shell-, placeholder-, 404- en foutpagina-test controleert ook op toegankelijkheidsfouten. Contrast controleert axe in `jsdom` niet; dat dekt Lighthouse (vraag 3) af. **(aanbevolen)**
B) Geen automatische controle, alleen handmatig met Lighthouse en een schermlezer
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 5: Linting
Er is nu alleen Prettier (opmaak), geen linter die fouten in code vindt.
A) ESLint toevoegen met de aanbevolen regels voor TypeScript, React Hooks en `jsx-a11y` (toegankelijkheid in JSX), plus een `lint`-script **(aanbevolen)** Vangt bv. vergeten `alt`-teksten en fouten met hooks al tijdens het schrijven.
B) Geen linter in deze feature
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 6: Welke browsers ondersteunen we?
A) De laatste 2 versies van Chrome, Edge, Firefox en Safari, plus Safari op iOS 16 en nieuwer. Dat dekt vrijwel alle bezoekers; oudere browsers krijgen de site zonder garantie. **(aanbevolen)**
B) Ruimer: ook oudere browsers (bv. iOS 14), met extra fallbacks voor nieuwere CSS
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: Begin met optie A. B zou later nog kunnen met name voor de mobiele versies.
### Vraag 7: Testdekking
A) Geen harde drempel voor de hele code, wel 100% dekking van de pure functies (`backToTopThreshold`, `visibleSocials`, `emailAddress`, `copyrightLine`, `canonicalUrl`, `sitemapXml`, `jsonLdScript`). De dekking wordt gerapporteerd bij `pnpm test`. **(aanbevolen)**
B) Een drempel voor de hele code (bv. 80% van de regels), die de tests laat falen als hij niet gehaald wordt
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 8: Controle op kwetsbare afhankelijkheden
A) Een script `pnpm audit:deps` (`pnpm audit --audit-level high`) plus een `check`-script dat lint, tests, build en audit achter elkaar draait. Dit is de controle vóór elke release, en later de basis voor CI. **(aanbevolen)**
B) Alleen documenteren dat `pnpm audit` handmatig gedraaid moet worden
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -44,7 +44,7 @@
- Introduce one API-shaped, typed content module for site-wide data (working name `siteContent`). It holds: - Introduce one API-shaped, typed content module for site-wide data (working name `siteContent`). It holds:
- the footer intro text - the footer intro text
- social links (`platform` + `href`, reusing `SocialPlatform`) - social links (`platform` + `href`, reusing `SocialPlatform`)
- the contact e-mail address - the contact e-mail address, stored as separate `user` and `domain` parts and joined only in the browser (anti-spam; revised in Functional Design, BR-EMAIL-01)
- The Hero's social links come from this module instead of `heroContent.ts`, so both Hero and Footer read one source. - The Hero's social links come from this module instead of `heroContent.ts`, so both Hero and Footer read one source.
- Plain data (strings and arrays), so it can later be replaced 1-on-1 by a CMS API response. - Plain data (strings and arrays), so it can later be replaced 1-on-1 by a CMS API response.
- **Menu items are not content.** The main menu and footer menu items are routes, which are code (the CMS cannot add pages). They live together in a typed navigation module (`mainNav`, `footerNav`), not in `siteContent`. - **Menu items are not content.** The main menu and footer menu items are routes, which are code (the CMS cannot add pages). They live together in a typed navigation module (`mainNav`, `footerNav`), not in `siteContent`.
@@ -52,7 +52,7 @@
### FR-05 Footer ### FR-05 Footer
The top section has three columns: The top section has three columns:
1. **Brand**: the monogram, reusing `web/src/assets/logo-dark.png` (~150px wide), with the intro text "Lifestyle fotograaf uit Huizen. Ik leg jouw mooiste momenten vast met mijn camera." below it. 1. **Brand**: the monogram, reusing `web/src/assets/logo-dark.png` (~150px wide), with the intro text "Lifestyle fotograaf uit Huizen. Ik leg jouw mooiste momenten vast." below it.
2. **Socials**: an eyebrow heading "Socials", then **text links** "Facebook" and "Instagram". They open in a new tab with `rel="noopener noreferrer"`. 2. **Socials**: an eyebrow heading "Socials", then **text links** "Facebook" and "Instagram". They open in a new tab with `rel="noopener noreferrer"`.
3. **Contact**: an eyebrow heading "Contact", then a `mailto:` link to the e-mail address. 3. **Contact**: an eyebrow heading "Contact", then a `mailto:` link to the e-mail address.
@@ -68,7 +68,7 @@ Layout and styling:
- *Source: Q3 = A, Q5 = C, Clarification 1 = A, Clarification 2 = A, design* - *Source: Q3 = A, Q5 = C, Clarification 1 = A, Clarification 2 = A, design*
### FR-06 Back-to-top button ### FR-06 Back-to-top button
- A fixed square button at the bottom right, styled like the design (`.to-top`), with an Ant Design `up-outlined` icon instead of the ↑ character. - A fixed square button at the bottom right, with an Ant Design `up-outlined` icon instead of the ↑ character. It deviates from the design (`.to-top`): dark `ink` background with a white icon so it stands out, and on very wide screens it aligns with the content edge (revised in Functional Design, BR-TOP-07/08).
- It becomes visible when the page is scrolled more than 60% of the viewport height, and is hidden again otherwise. - It becomes visible when the page is scrolled more than 60% of the viewport height, and is hidden again otherwise.
- **Click**: scrolls to the top, smoothly, or instantly when `prefers-reduced-motion: reduce` is set. - **Click**: scrolls to the top, smoothly, or instantly when `prefers-reduced-motion: reduce` is set.
- **Accessibility**: - **Accessibility**:
@@ -107,6 +107,18 @@ Layout and styling:
- Move `@vitejs/plugin-react` from `dependencies` to `devDependencies`. It is a build tool (SECURITY-10 hygiene). - Move `@vitejs/plugin-react` from `dependencies` to `devDependencies`. It is a build tool (SECURITY-10 hygiene).
- *Source: Q10 = A* - *Source: Q10 = A*
### FR-12 SEO foundation (added at Functional Design)
- One page registry (`sitePages`) is the single source for per-page title, description, `indexed` flag and preview image.
- Every page has a canonical URL and `og:url` on `https://andreaslop.nl`, plus `og:image` and `twitter:card`. Placeholder, 404 and error pages are `noindex`.
- Site-wide `ProfessionalService` JSON-LD, without the e-mail address.
- `sitemap.xml` is generated at build time from the registry; `robots.txt` is static. A test keeps the registry and the routes in sync.
- The code stays prerender-ready (no browser APIs during render); prerendering itself is a follow-up.
- *Source: functional design change request, [frontend-shell-fd-change-questions.md](../../construction/plans/frontend-shell-fd-change-questions.md); rules BR-SEO-01…11*
### FR-13 Page change for screen readers (added at Functional Design)
- After every client-side page change, focus moves to `main#main`, so screen readers announce the new content.
- *Source: change request Q6 = A; rule BR-A11Y-01*
--- ---
## Non-Functional Requirements ## Non-Functional Requirements
@@ -188,6 +200,12 @@ Principle: **reuse as much as possible and make good use of Chakra UI v3, where
- The shell adds no network requests beyond its bundled assets. The footer logo reuses the already-bundled `logo-dark.png`. - The shell adds no network requests beyond its bundled assets. The footer logo reuses the already-bundled `logo-dark.png`.
- Scroll listeners are passive. The to-top button and the header share the existing scroll-hook approach; no layout thrashing. - Scroll listeners are passive. The to-top button and the header share the existing scroll-hook approach; no layout thrashing.
### NFR-06 Responsive design (added at Functional Design)
- Mobile-first with Chakra's default breakpoints; works from 320px wide up to 32:9 without horizontal scrolling.
- Works at 200% zoom; touch targets at least 44×44px below `lg`.
- Content is limited to one shared content width; fixed elements align with it on ultrawide screens.
- *Source: functional design change request; rules BR-RWD-01…05*
--- ---
## Security Baseline — Applicability at Requirements Level ## Security Baseline — Applicability at Requirements Level