Plans the portfolio page

Records the requirements, execution plan and application design for the
portfolio page: the ten live photos in a filterable masonry grid with an
accessible lightbox, filters per shoot type in the URL, the Instagram
block shared with the homepage, and an indexed page with image gallery
structured data. Built alongside the contact and shoot type pages, with
shared pieces split between them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-25 21:32:48 +01:00
co-authored by Claude Opus 5.5
parent 1bf28cb569
commit b35b1c2404
11 changed files with 1100 additions and 0 deletions
@@ -0,0 +1,68 @@
# Application Design — Portfolio Page
Consolidated view of [components.md](components.md), [component-methods.md](component-methods.md), [services.md](services.md) and [component-dependency.md](component-dependency.md). Decisions: [application-design-plan.md](../plans/application-design-plan.md).
## Decisions
| # | Decision |
|---|---|
| Q1 | Three independent shared pieces (`PortfolioGrid`, `Lightbox`, `FilterBar`) connected by a page-specific `PortfolioGallery` in `components/portfolio/` |
| Q2 | Filter bar = group of toggle buttons with `aria-pressed`, one tab stop per button |
| Q3 | Filter style = text links in eyebrow style, active underlined in `accent.deep` (new recipe) |
| Q4 | Filter changes replace the URL (no history entry per change) |
| Q5 | Swipe logic extracted from the hero into `useSwipe` + `lib/swipeDirection`; hero behaviour unchanged |
| Q6 + 6a | CSS-only masonry in row order (row spans from the aspect ratio, container units); no preparation for JS measuring — rebuild later if ever needed |
| Q7 | `Lightbox` loaded lazily on first open or on tile hover/focus |
| — | Names as agreed with the parallel sessions; generic APIs; generic `GalleryItem` so shared components never see shoot types |
## Component Overview
```mermaid
graph TD
Route["routes/portfolio.tsx"] --> Intro["PageIntro"]
Route --> Gallery["portfolio/PortfolioGallery"]
Route --> Insta["InstagramGrid (shared)"]
Gallery --> Section["PageSection"]
Gallery --> Filter["FilterBar"]
Gallery --> Grid["PortfolioGrid"]
Gallery --> Box["Lightbox (lazy)"]
Grid --> Deferred["DeferredImage + Reveal"]
Box --> Dialog["Chakra Dialog"]
Box --> Swipe["useSwipe"]
Hero["Hero / useHeroSlider"] --> Swipe
Home["routes/index.tsx"] --> Insta
classDef newpart fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef changed fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef existing fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
class Gallery,Filter,Grid,Box,Swipe newpart;
class Route,Insta,Hero,Home changed;
class Intro,Section,Deferred,Dialog existing;
```
Text alternative: the portfolio route renders PageIntro, the page-specific PortfolioGallery and the shared InstagramGrid; the gallery composes PageSection, FilterBar, PortfolioGrid and the lazily loaded Lightbox; the grid reuses DeferredImage and Reveal, the lightbox builds on Chakra Dialog and the new useSwipe hook, which the hero also adopts; the homepage uses the moved InstagramGrid.
## Per Unit
| Unit | New | Changed |
|---|---|---|
| 1 Shared Instagram block | `content/instagramContent.ts`, `InstagramContent` | `InstagramGrid` moved, `homeContent` (instagram removed), homepage route |
| 2 Gallery building blocks | `PortfolioGrid`, `Lightbox`, `FilterBar`, `useSwipe`, recipe `filterControl`, `GalleryItem`/`ImageSource`, `lib/{wrapIndex, swipeDirection, masonryRowSpan, neighbourIndexes}`, arbitraries, possibly a `zIndex.lightbox` token | `useHeroSlider` (uses `useSwipe` and `wrapIndex`) |
| 3 Portfolio page | `PortfolioGallery`, `portfolioContent.ts`, `PortfolioPhoto`/`PortfolioContent`, `lib/{shootTypesWithPhotos, shootFromSearch, filterPhotos, filterOptions, toGalleryItems, photoCountLabel}`, `galleryImages` in `seo.ts`, 10 photos ×2, `og-portfolio.jpg` | portfolio route, `sitePages.ts`, `lighthouserc*.cjs`, LAYOUT.md, RE lines about `/portfolio` |
## State and Data Flow (summary)
- The **URL** owns the active filter (`?shoot=`, typed and allowlisted, replace navigation); **`PortfolioGallery`** owns which photo is open; everything else is derived by pure helpers.
- Shared components get data and report events through props; none import page content.
- See [services.md](services.md) and [component-dependency.md](component-dependency.md) for the flow diagram and the peer dependencies.
## Extension Compliance — Application Design
| Rule | Status | Note |
|---|---|---|
| SECURITY-04 headers | Compliant | No CSP change; no external resources |
| SECURITY-05 input validation | Compliant | `?shoot=` allowlisted in `validateSearch` and `shootFromSearch`; never rendered |
| SECURITY-10 supply chain | Compliant | No new dependency (Chakra `Dialog` is already in `@chakra-ui/react`) |
| SECURITY-11 secure design | Compliant | Misuse case (crafted parameter) handled by allowlist + fallback |
| SECURITY-13 integrity | Compliant | Lazy chunk is our own bundle; no CDN |
| Other SECURITY rules | N/A | No data stores, auth, server or infrastructure |
| PBT-01 | Planned | Every pure helper above is listed for property identification in Functional Design (units 2 and 3) |
| PBT-06 | Planned | Open-index state in `PortfolioGallery` + `Lightbox` navigation modelled in Functional Design |
| PBT-07 | Planned | Generators for `GalleryItem`, `PortfolioPhoto`, `ShootType` in `src/test/arbitraries.ts` |
| PBT-08 / 09 | Compliant | Existing seed logging and fast-check |
| Other PBT rules | Planned at Functional Design / Code Generation | |
@@ -0,0 +1,71 @@
# Component Dependencies — Portfolio Page
## Dependency Matrix
| Component | Depends on | Used by |
|---|---|---|
| `routes/portfolio.tsx` | `PageIntro`, `PortfolioGallery`, `InstagramGrid`, `portfolioContent`, `instagramContent`, `shootTypes`*, `siteContent`, `seo.ts` (`pageHead`, `webPage`*, `galleryImages`), `lib/visibleSocials`, `lib/shootFromSearch` | router |
| `routes/index.tsx` | … + `InstagramGrid` (new path), `instagramContent` | router |
| `PortfolioGallery` | `PageSection`, `FilterBar`, `PortfolioGrid`, `Lightbox` (lazy), `lib/` (filter/gallery helpers) | portfolio route |
| `PortfolioGrid` | `DeferredImage`, `Reveal`, `lib/masonryRowSpan`, theme tokens | `PortfolioGallery` (any page later) |
| `Lightbox` | Chakra `Dialog`, `useSwipe`, `lib/wrapIndex`, `lib/neighbourIndexes`, recipes `iconControl`/`carouselControl` | `PortfolioGallery` (any page later) |
| `FilterBar` | recipe `filterControl` (new) | `PortfolioGallery` |
| `useSwipe` | `lib/swipeDirection` | `useHeroSlider`, `Lightbox` |
| `useHeroSlider` | `useSwipe`, `lib/wrapIndex` (refactor, same behaviour) | `Hero` |
| `InstagramGrid` | `PageSection`, `SectionHeading`, `Reveal`, `DeferredImage` | home and portfolio routes |
| `seo.ts` `galleryImages` | `siteUrl`, `personId`, `businessId` | portfolio route |
\* delivered by a parallel feature (see below)
## Data Flow
```mermaid
graph LR
Url["URL ?shoot="] --> Route["routes/portfolio.tsx"]
Content["portfolioContent + shootTypes"] --> Route
Route -->|"shoot, photos, shootTypes"| Gallery["PortfolioGallery"]
Gallery -->|"options, value"| Filter["FilterBar"]
Filter -->|"onChange(id)"| Gallery
Gallery -->|"onShootChange"| Route
Route -->|"navigate replace"| Url
Gallery -->|"items"| Grid["PortfolioGrid"]
Grid -->|"onOpen(index), onIntent"| Gallery
Gallery -->|"items, index"| Box["Lightbox (lazy)"]
Box -->|"onIndexChange, onClose"| Gallery
Lib["lib/ pure helpers"] -.-> Gallery
Lib -.-> Grid
Lib -.-> Box
classDef state fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef comp fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef support fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
class Url,Content state;
class Route,Gallery,Filter,Grid,Box comp;
class Lib support;
```
Text alternative: the route reads the `?shoot=` parameter and the content and passes the active filter, photos and shoot types to PortfolioGallery; the filter bar reports a choice back up to the route, which updates the URL with replace; the gallery gives the filtered items to the grid and the lightbox and keeps which item is open; pure helpers in lib support all three.
## Communication Patterns
- **Props down, callbacks up**; no context or global store. The URL is the source of truth for the filter, `PortfolioGallery` for the open item
- **Lazy boundary**: `Lightbox` behind `React.lazy` + `Suspense`; the chunk is requested on first `onIntent` or `onOpen`
- **No cross-page coupling**: `PortfolioGrid`, `Lightbox`, `FilterBar` and `useSwipe` import nothing page-specific
## Parallel-Feature Dependencies
```mermaid
graph TD
Contact["contact-page commit: webPage() + WebPageType"] --> U3["Unit 3 Portfolio page"]
Soorten["soorten-fotoshoots commit: ShootType, ShootTypeId, shootTypes.ts"] --> U3
U1["Unit 1 Shared Instagram block"] --> U3
U2["Unit 2 Gallery building blocks"] --> U3
U3 -.->|"?shoot= URL, shootTypesWithPhotos"| SoortenPage["Soorten fotoshoots links"]
classDef peer fill:#CE93D8,stroke:#6A1B9A,stroke-width:1px,color:#000;
classDef unit fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
class Contact,Soorten,SoortenPage peer;
class U1,U2,U3 unit;
```
Text alternative: units 1 and 2 have no outside dependency; unit 3 needs units 1 and 2 plus the cherry-picked commits from contact-page (webPage) and soorten-fotoshoots (shoot types); in return the portfolio offers the ?shoot= URL and a helper the Soorten fotoshoots page can link with.
- Unit 3 starts by cherry-picking both peer commits; if either is missing it stops and reports (no parallel copy)
- `useHeroSlider` is touched by unit 2 (swipe extraction); no other feature has claimed the hero
@@ -0,0 +1,120 @@
# Component Methods — Portfolio Page
Signatures only; the rules behind them (edge cases, invariants, properties) follow in Functional Design for units 2 and 3. Types are TypeScript; names are working names.
## Types
```ts
// content/types.ts (unit 2: GalleryItem lives next to ContentImage)
interface ImageSource { src: string; width: number; height: number }
// What the generic components show
interface GalleryItem {
id: string;
thumb: ContentImage; // grid size (~800 px), alt text included
full: ImageSource; // lightbox size (~1600–2000 px), same alt as thumb
caption?: string; // visible caption in the lightbox
}
// unit 3
interface PortfolioPhoto {
id: string;
shootType: ShootTypeId; // from the soorten-fotoshoots commit
thumb: ContentImage;
full: ImageSource;
}
interface PortfolioContent {
intro: { eyebrow: string; title: string; text: string };
photos: PortfolioPhoto[];
}
// unit 1
interface InstagramContent {
title: string;
handle: string;
photos: ContentImage[];
}
interface FilterOption { id: string; label: string }
```
## Components (props)
```ts
// unit 1
InstagramGrid({ content: InstagramContent; profileUrl: string })
// unit 2
PortfolioGrid({
items: readonly GalleryItem[];
eagerCount?: number; // default 3
onOpen: (index: number) => void;
onIntent?: () => void; // hover/focus: preload the lightbox code
'data-testid'?: string;
})
Lightbox({
items: readonly GalleryItem[];
index: number | null; // null = closed
onIndexChange: (index: number) => void;
onClose: () => void;
label?: string; // dialog name, default "Foto groot bekijken"
finalFocusRef?: RefObject<HTMLElement> // or a getter for the tile to return to
})
FilterBar({
options: readonly FilterOption[];
value: string;
onChange: (id: string) => void;
label: string; // group name, e.g. "Filter op soort shoot"
})
// unit 3
PortfolioGallery({
photos: readonly PortfolioPhoto[];
shootTypes: readonly ShootType[];
shoot: ShootTypeId | undefined; // active filter from the route
onShootChange: (shoot: ShootTypeId | undefined) => void;
})
```
## Hooks
```ts
// hooks/useSwipe.ts (unit 2)
useSwipe(options: { onPrev: () => void; onNext: () => void; enabled?: boolean }):
{ onTouchStart: TouchEventHandler; onTouchEnd: TouchEventHandler }
```
## Pure helpers (`lib/`, 100% coverage threshold, example + property-based tests)
```ts
// unit 2
wrapIndex(index: number, count: number): number
// position within 0..count-1, wrapping both ways (also used by useHeroSlider)
swipeDirection(start: Point, end: Point, threshold?: number): 'prev' | 'next' | null
masonryRowSpan(image: { width: number; height: number }, rowsPerColumnWidth: number): number
// number of implicit rows an item spans, from its aspect ratio
neighbourIndexes(index: number, count: number): number[]
// which large images to preload around the current one
// unit 3
shootTypesWithPhotos(shootTypes: readonly ShootType[], photos: readonly PortfolioPhoto[]): ShootType[]
// in list order; also offered to soorten-fotoshoots
shootFromSearch(value: unknown, available: readonly ShootTypeId[]): ShootTypeId | undefined
// allowlist check for ?shoot= (like packageFromSearch)
filterPhotos(photos: readonly PortfolioPhoto[], shoot: ShootTypeId | undefined): PortfolioPhoto[]
filterOptions(shootTypes: readonly ShootType[], allLabel: string): FilterOption[]
// "Alles" first, then one option per shoot type (label = name)
toGalleryItems(photos: readonly PortfolioPhoto[], shootTypes: readonly ShootType[]): GalleryItem[]
// caption = shootLabel
photoCountLabel(count: number): string // "1 foto" / "4 foto's"
```
## SEO (`seo.ts`, unit 3)
```ts
galleryImages(photos: readonly PortfolioPhoto[], base?: string): ImageObject[]
// contentUrl/thumbnailUrl absolute https, description = alt, creator → personId, copyrightHolder → businessId
// head: structuredDataScript(webPage('ImageGallery', '/portfolio', { associatedMedia: galleryImages(...) }))
```
@@ -0,0 +1,74 @@
# Components — Portfolio Page
New and changed components, grouped by unit. Shared building blocks live in their own folder directly under `web/src/components/`; page-specific parts under `components/portfolio/` (same pattern as `components/home/` and `components/about/`). *Source: plan Q1 = A*
## Unit 1 — Shared Instagram block
### InstagramGrid (moved)
- **From → to**: `components/home/InstagramGrid/` → `components/InstagramGrid/`
- **Purpose**: the Instagram section (design `.instagram`): heading with the handle as link, full-width row of square tiles linking to the profile
- **Change**: props type `HomeContent['instagram']` → `InstagramContent` (own content module). Markup, styling, test ids and behaviour unchanged
- **Used by**: homepage route, portfolio route
## Unit 2 — Gallery building blocks (generic, no shoot types)
### PortfolioGrid (new, shared)
- **Purpose**: masonry grid of photos in row order (design `.portfolio-grid` / `.portfolio-item`); every photo is a link to its large image that asks the page to open the lightbox instead
- **Responsibilities**:
- list semantics (`ul`/`li`) in the given order
- CSS-only masonry: tiny implicit rows whose height scales with the column width (container units); each item spans the number of rows derived from its intrinsic width/height by a pure helper. *Source: Q6 = A, 6a = B (no hook for JS measuring)*
- 3 / 2 / 1 columns on the theme breakpoints, gap `gridGap`
- the first `eagerCount` images load immediately with `fetchPriority="high"`; the rest via `DeferredImage`
- hover/focus effect (zoom + overlay, zoom off under reduced motion), focus ring above neighbours, `Reveal` fade-in
- click / Enter on a tile: `preventDefault` and report the index; without JavaScript the link opens the large image
- pointer enter / focus on a tile: report "intent" so the page can preload the lightbox code (Q7)
- **Knows nothing about**: shoot types, filters, URL
### Lightbox (new, shared, lazily loaded)
- **Purpose**: modal viewer over a list of gallery items (design `.lightbox`)
- **Responsibilities**:
- Chakra `Dialog` (controlled `open`), dark backdrop, accessible name; focus trap, Escape, inert background, scroll lock and focus return come from Chakra/Ark
- shows the current item's large image (`object-fit: contain`), visible caption (if given), counter "n / total"
- previous / next buttons (`iconControl`/`carouselControl` recipes, ≥ 44 px), ←/→ keys, swipe via `useSwipe`; wrap-around via a pure helper
- polite announcement of the position when browsing
- preloads the neighbouring large images; shows the (cached) thumb until the large image has loaded
- hides prev/next/counter when there is one item
- **Loaded**: with `React.lazy` on first open or on tile intent. *Source: Q7 = A*
- **Knows nothing about**: grids, filters, shoot types
### FilterBar (new, shared)
- **Purpose**: a row of single-choice filter controls
- **Responsibilities**: group of toggle buttons (`role="group"` with an accessible name, each button `aria-pressed`, one tab stop per button), labels in eyebrow style, active one underlined in `accent.deep`; reports the chosen id; renders nothing for fewer than two options. *Source: Q2 = A, Q3 = A*
- **Styling**: a new recipe `filterControl` (or a `filter` variant on the `link` recipe — decided in Code Generation, whichever keeps the eyebrow tokens in one place)
- **Knows nothing about**: what is filtered
### useSwipe (new hook, extracted)
- **Purpose**: horizontal swipe detection on touch devices, shared by the hero and the lightbox. *Source: Q5 = A*
- **Responsibilities**: touch start/end handlers; decides via a pure helper (threshold 50 px, horizontal movement larger than vertical); calls `onPrev` / `onNext`
- **Change to the hero**: `useHeroSlider` uses `useSwipe` instead of its inline handlers; behaviour identical (same threshold, same direction rules)
## Unit 3 — Portfolio page
### PortfolioGallery (new, page-specific, `components/portfolio/`)
- **Purpose**: connects filter bar, grid and lightbox for the portfolio. *Source: Q1 = A*
- **Responsibilities**:
- receives the photos, the shoot types and the active filter (from the route) plus a callback to change it
- derives the visible filters and the filtered photo list with pure helpers; maps photos to generic gallery items (caption = `shootLabel`)
- holds the open state (which item, or closed) and resets it when the filter changes
- announces the number of shown photos after a filter change
- renders the section frame (`PageSection`, visually hidden h2) with `FilterBar`, `PortfolioGrid` and the lazily loaded `Lightbox`
### Route `routes/portfolio.tsx` (rewritten)
- `validateSearch` → `{ shoot?: ShootTypeId }` (typed, allowlist check; agreed with soorten-fotoshoots)
- `head()` → `pageHead('/portfolio')` + `ImageGallery` structured data
- component: `PageIntro` → `PortfolioGallery` → `InstagramGrid`; changing the filter navigates with `replace: true`. *Source: Q4 = A*
### Content and types
- `content/portfolioContent.ts` — intro texts and the 10 photos (`PortfolioContent`, `PortfolioPhoto`)
- `content/instagramContent.ts` (unit 1) — `InstagramContent`
- `content/types.ts` — the types above; `ShootTypeId` / `ShootType` arrive with the soorten-fotoshoots commit
### SEO
- `seo.ts` — `galleryImages(...)` builder for the `ImageObject` list; uses `webPage()` from the contact-page commit
- `sitePages.ts` — `/portfolio`: `indexed: true`, `ogImage`
- `lighthouserc*.cjs` — `/portfolio` to the indexed paths
@@ -0,0 +1,19 @@
# Services — Portfolio Page
There is no service layer in this SPA (no back-end yet). "Orchestration" happens in the route and one page-specific component; everything that decides what is shown is a pure helper in `lib/`.
## Route as orchestrator (`routes/portfolio.tsx`)
- **Reads**: `portfolioContent`, `instagramContent`, `shootTypes`, `siteContent.socials`
- **URL state**: `validateSearch` turns `?shoot=` into `{ shoot?: ShootTypeId }` (allowlist). The component re-checks it against the shoot types that actually have photos (`shootFromSearch` with `shootTypesWithPhotos`), so a valid id without photos falls back to "Alles"
- **Changes**: `navigate({ search: shoot ? { shoot } : {}, replace: true, resetScroll: false })` — no history entry per filter (Q4 = A), no scroll jump
- **Head**: `pageHead('/portfolio')` + gallery JSON-LD
- **Renders**: `PageIntro` → `PortfolioGallery` → `InstagramGrid` (only with a valid Instagram link, as on the homepage)
## PortfolioGallery as page controller
- **Derives** (pure, memoised on input): filter options, filtered photos, gallery items
- **Holds** the only UI state of the page: `openIndex: number | null`; closes the lightbox when the filter changes
- **Coordinates**: grid `onOpen` → `openIndex`; grid `onIntent` → start loading the lightbox chunk; lightbox `onIndexChange` / `onClose`; filter `onChange` → route callback + polite count announcement
- **Focus return**: on close, focus goes to the tile of the item shown last (requirements FR-PF-06)
## Future API
- `GET /api/portfolio` can return `PortfolioContent` 1-to-1; the route then loads it instead of importing the module. Shoot types come from the same API as the Soorten fotoshoots page. Nothing else changes.
@@ -0,0 +1,100 @@
# Application Design Plan — Portfolio Page
Depth: standard. Business rules (filtering, wrap-around, lightbox states, masonry spans, `?shoot=` parsing, gallery structured data) follow in Functional Design for units 2 and 3.
## Plan
- [x] Answer the design questions below
- [x] Generate `components.md` — new and changed components with responsibilities and interfaces
- [x] Generate `component-methods.md` — props, hooks and pure function signatures
- [x] Generate `services.md` — composition in the route (there is no service layer in this SPA)
- [x] Generate `component-dependency.md` — dependency matrix, data flow, and where the peer commits slot in
- [x] Generate `application-design.md` — consolidated design
- [x] Validate completeness and consistency against requirements.md
## Already decided (no question needed)
- **Names as claimed with the other sessions**: `PortfolioGrid`, `Lightbox`, and `InstagramGrid` (moved). Despite the name, `PortfolioGrid` gets a generic API (a list of images, no knowledge of shoot types), so other pages can use it.
- **Gallery data for the components**: the components work with a generic item, roughly `{ id, thumb: ContentImage, full: { src, width, height }, caption? }`. The page maps its portfolio photos (with `shootType`) to that, taking the caption from `shootLabel`. So `Lightbox` and `PortfolioGrid` never import shoot types.
- **Portfolio content**: `content/portfolioContent.ts` + a `PortfolioContent` / `PortfolioPhoto` type in `content/types.ts`; photos reference `ShootTypeId` only. Instagram content: `content/instagramContent.ts` + `InstagramContent` (split off from `HomeContent`); the homepage passes the same object.
- **URL state**: `?shoot=` is read through the route's `validateSearch` and checked by a pure function in `lib/` against the shoot types that have photos, like `packageFromSearch` for `?pakket=`. The route is the single source of truth for the active filter; it navigates to change it.
- **Lightbox on Chakra `Dialog`** (focus trap, focus return, Escape, inert background and scroll lock come from Chakra/Ark); our part is the content, prev/next, counter, caption, swipe and preloading.
- **SEO**: `galleryImages(...)`-style pure builders in `seo.ts` produce the `ImageObject` list; the route's `head()` combines `pageHead('/portfolio')` with one `structuredDataScript(webPage('ImageGallery', '/portfolio', { associatedMedia }))`.
---
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe.
## Vraag 1: Hoe raster, lightbox en filter samenwerken
- A) **Drie losse onderdelen plus één pagina-onderdeel dat ze verbindt**: `PortfolioGrid` toont foto's en meldt "foto X geopend"; `Lightbox` toont een lijst foto's vanaf een startpositie; de filterbalk meldt "filter gekozen". Een pagina-specifiek onderdeel in `components/portfolio/` (bijvoorbeeld `PortfolioGallery`) bewaart welke foto open is en geeft het gefilterde lijstje aan beide door. Elk onderdeel is los te testen en los te hergebruiken, bijvoorbeeld een `Lightbox` bij de shootfoto's op Soorten fotoshoots (aanbevolen)
- B) **Raster met ingebouwde lightbox**: `PortfolioGrid` opent zelf zijn `Lightbox`. Minder losse delen, maar de lightbox is dan niet zonder raster te gebruiken
- C) Alles in de route opbouwen, zonder pagina-specifiek onderdeel
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 2: Hoe de filterbalk werkt (voor toetsenbord en screenreader)
- A) **Een groep schakelknoppen**: elke knop is een tab-stop, de actieve heeft `aria-pressed="true"`, en de groep heeft een naam ("Filter op soort shoot"). Eenvoudig en voorspelbaar (aanbevolen)
- B) **Een keuzerondjesgroep** (radiogroup): één tab-stop, je kiest met de pijltjestoetsen. Compacter voor het toetsenbord, maar minder bekend voor wie het niet kent
- C) **Tabbladen** (tablist): semantisch bedoeld voor wisselende inhoud in vaste panelen, wat hier niet helemaal past
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 3: Hoe de filterbalk eruitziet
Het ontwerp heeft geen filters, dus dit is nieuw.
- A) **Tekstlinks in labelstijl** (zoals de eyebrows: kleine hoofdletters, ruime spatiëring), de actieve onderstreept in `accent.deep`. Rustig en past bij de typografie van de site; als nieuwe variant in een recipe (aanbevolen)
- B) **Omlijnde knoppen** in de stijl van `LinkButton` `outline`, de actieve gevuld met de accentkleur. Duidelijker als "knoppen", maar zwaarder boven een fotoraster
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 4: Filter wisselen en de terugknop
- A) **Vervangen**: wisselen van filter past de URL aan zonder een stap in de geschiedenis. De terugknop verlaat de pagina, ook na vijf keer wisselen (aanbevolen)
- B) **Toevoegen**: elke filterwissel is een stap; de terugknop gaat terug naar het vorige filter
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 5: Vegen in de lightbox
De hero heeft al veeglogica, maar die zit vast in `useHeroSlider`.
- A) **Uit de hero halen** naar een gedeelde hook (bijvoorbeeld `useSwipe({ onPrev, onNext })`) en die in de hero en de lightbox gebruiken. Eén plek voor drempel en gedrag; de hero blijft precies zo werken (aanbevolen)
- B) De lightbox krijgt eigen veeglogica; de hero blijft ongemoeid
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 6: Techniek voor de masonry in rijvolgorde
- A) **Alleen CSS**: een raster met hele kleine rijen, waarbij elke foto zoveel rijen beslaat als past bij zijn verhouding. Dat aantal rekent een losse functie uit met de breedte en hoogte uit de data, en de rijhoogte schaalt mee met de kolombreedte (container-eenheden). Geen meten in de browser, dus geen verspringen bij het laden (aanbevolen)
- B) **Meten met JavaScript**: na het laden de echte hoogtes meten (ResizeObserver) en de foto's positioneren. Precies, maar het raster kan verspringen en het werkt pas als JavaScript draait
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, als het later nodig kunnen we het alsnog ombouwen
## Vraag 7: Lightbox-code apart laden
- A) **Apart laden**: de code van de lightbox laadt pas zodra je een foto opent, of al vooruit als je met muis of focus op een foto komt. De eerste weergave van de pagina blijft lichter (helpt de prestatiescore) (aanbevolen)
- B) **Direct meeladen** met de pagina. Eenvoudiger, de eerste keer openen is altijd direct
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
---
## Vervolgvraag 6a: "A, als het later nodig"
Je antwoord op vraag 6 lijkt halverwege afgebroken. Wat bedoel je?
- A) **CSS-masonry nu; meten met JavaScript alleen als CSS later tekortschiet.** Ik ontwerp de grid zo dat de berekening van de rijen op één plek zit, zodat die later vervangen kan worden zonder de rest aan te passen. Wat "tekortschiet" is, leg ik vast: zichtbare gaten groter dan één rij-eenheid, of verkeerd bijgesneden foto's in een browser die we ondersteunen (aanbevolen)
- B) **CSS-masonry, en verder niets voorbereiden.** Als het later nodig is, bouwen we het dan om
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
@@ -0,0 +1,167 @@
# Execution Plan — Portfolio Page
## Detailed Analysis Summary
### Transformation Scope (Brownfield)
- **Transformation Type**: Single component (`web/`), application-level only
- **Primary Changes**: replace the `/portfolio` placeholder with the real page; new shared gallery building blocks (masonry `PortfolioGrid`, `Lightbox`, a generic filter bar) with pure helpers in `lib/`; `InstagramGrid` moved to a shared component with its own content; page-specific SEO (indexing, `ImageGallery` JSON-LD via the shared `webPage()`, own preview image); 10 photos in two sizes
- **Related Components**: `web/src/routes/portfolio.tsx`, `web/src/routes/index.tsx`, `web/src/components/{home/InstagramGrid → InstagramGrid, PortfolioGrid, Lightbox, filter bar}`, `web/src/lib/`, `web/src/content/` (+ `types.ts`), `web/src/seo.ts`, `web/src/sitePages.ts`, `web/lighthouserc*.cjs`, `web/src/theme.ts` (possibly a `zIndex` token), `web/src/test/arbitraries.ts`, `web/public/`, `web/src/assets/portfolio/`, [LAYOUT.md](../../../../../LAYOUT.md)
### Change Impact Assessment
- **User-facing changes**: Yes — a new page with filters and a lightbox; the homepage Instagram block must look and behave exactly as before
- **Structural changes**: Minor — one component moved, new shared components; no architectural change
- **Data model changes**: Yes — new portfolio photo content (two image sizes, `ShootTypeId`), `InstagramContent` split from `HomeContent`
- **API changes**: No external API; new URL search parameter `?shoot=` on `/portfolio`; internal props for the new components
- **NFR impact**: Yes — SEO (indexed, structured data, preview image), accessibility (modal dialog, focus management, announcements), performance (photo-heavy page, Lighthouse budget 0.9 on mobile)
### Component Relationships
```mermaid
graph TD
Route["routes/portfolio.tsx"] --> PageIntro["PageIntro (existing)"]
Route --> Filter["Filter bar (new, generic)"]
Route --> Grid["PortfolioGrid (new, masonry)"]
Grid --> Lightbox["Lightbox (new, Chakra Dialog)"]
Grid --> Deferred["DeferredImage + Reveal (existing)"]
Route --> Insta["InstagramGrid (moved to shared)"]
Home["routes/index.tsx"] --> Insta
Insta --> InstaContent["content/instagramContent.ts (new)"]
Route --> PfContent["content/portfolioContent.ts (new)"]
PfContent --> ShootTypes["content/shootTypes.ts (from soorten-fotoshoots)"]
Filter --> Lib["lib/ helpers (new, pure)"]
Grid --> Lib
Lightbox --> Lib
Route --> Seo["seo.ts webPage() (from contact-page) + sitePages.ts"]
Seo --> Lhci["lighthouserc*.cjs (indexed paths)"]
classDef newpart fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef changed fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef existing fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
classDef peer fill:#CE93D8,stroke:#6A1B9A,stroke-width:1px,color:#000;
class Route,Filter,Grid,Lightbox,InstaContent,PfContent,Lib newpart;
class Insta,Home,Seo,Lhci changed;
class PageIntro,Deferred existing;
class ShootTypes peer;
```
Text alternative: the new route composes PageIntro, a generic filter bar, the new masonry PortfolioGrid (which opens the new Lightbox and reuses DeferredImage and Reveal) and the shared InstagramGrid (also used by the homepage, with its own content); portfolio content references the shoot types delivered by soorten-fotoshoots (purple); filter, grid and lightbox rely on new pure helpers in lib; SEO uses contact-page's webPage() and the Lighthouse config follows the page registry.
- **Primary Component**: `web` (front-end SPA)
- **Shared Components**: `InstagramGrid` (Minor: moved, content type split), `PortfolioGrid`, `Lightbox`, filter bar (new, generic), `lib/` (new helpers), `seo.ts` (Minor: gallery JSON-LD on top of `webPage()`)
- **Dependent Components**: the homepage route (import path and content source of `InstagramGrid` only)
- **Supporting Components**: Lighthouse CI config (Configuration-only), `theme.ts` (possibly one token), LAYOUT.md (documentation)
- **Peer dependencies**: contact-page (`webPage()` commit), soorten-fotoshoots-page (`shootTypes.ts` commit)
### Risk Assessment
- **Risk Level**: Medium — the lightbox (focus trap, inert background, swipe, preloading) and the row-order masonry are the most intricate UI in the site so far; two pieces come from parallel branches
- **Rollback Complexity**: Easy (one branch, commits per unit)
- **Testing Complexity**: Moderate — dialog behaviour in jsdom (focus, keys), URL state, stateful PBT for the lightbox; Lighthouse for a photo-heavy page
## Workflow Visualization
```mermaid
flowchart TD
Start(["User Request"])
subgraph INCEPTION["🔵 INCEPTION PHASE"]
WD["Workspace Detection<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>SKIP</b>"]
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
US["User Stories<br/><b>SKIP</b>"]
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
AD["Application Design<br/><b>EXECUTE</b>"]
UG["Units Generation<br/><b>SKIP</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
FD["Functional Design<br/><b>EXECUTE (units 2 and 3)</b>"]
NFRA["NFR Requirements<br/><b>SKIP</b>"]
NFRD["NFR Design<br/><b>SKIP</b>"]
ID["Infrastructure Design<br/><b>SKIP</b>"]
CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
Start --> WD
WD --> RA
RA --> WP
WP --> AD
AD --> FD
FD --> CG
CG --> BT
BT --> End(["Complete"])
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
linkStyle default stroke:#333,stroke-width:2px
```
Text alternative: completed Workspace Detection and Requirements Analysis lead to Workflow Planning, then Application Design, Functional Design (units 2 and 3), Code Generation per unit and Build and Test; Reverse Engineering, User Stories, Units Generation, NFR Requirements, NFR Design, Infrastructure Design and the Operations phase are skipped.
## Phases to Execute
### 🔵 INCEPTION PHASE
- [x] Workspace Detection (COMPLETED)
- [x] Reverse Engineering (SKIPPED)
- **Rationale**: shared artifacts are current with the over-mij blocks; team agreement that each feature only updates the lines about its own route/components (done during Code Generation)
- [x] Requirements Analysis (COMPLETED)
- [x] User Stories (SKIPPED)
- **Rationale**: one persona (the visitor); concrete FRs with behaviour, texts and edge cases; stories would restate the requirements
- [x] Execution Plan (IN PROGRESS)
- [ ] Application Design - EXECUTE (standard depth)
- **Rationale**: several new shared components need agreed boundaries and props before code, generic enough for other pages: `PortfolioGrid`, `Lightbox`, the filter bar, the moved `InstagramGrid` and its content type, the portfolio content model (two image sizes, `ShootTypeId`), which pure helpers go into `lib/`, where URL state lives (route search params vs. component state), whether the hero's swipe logic is extracted, and how the peer commits slot in
- [ ] Units Generation - SKIP
- **Rationale**: the split is fixed below (three units); no separate unit-of-work artifacts needed
### 🟢 CONSTRUCTION PHASE
- [ ] Functional Design - EXECUTE for units 2 and 3 (standard depth)
- **Rationale**: unit 2 has real logic (filtering, wrap-around navigation, lightbox state machine, masonry spans, preloading) whose rules and properties must be defined first (PBT-01). Unit 3 has the photo proposals (shoot type and alt text per photo, to be approved by the user — clarification 4), the OG photo choice, the `?shoot=` parsing rules and the `ImageGallery` structured data rules. Unit 1 is a behaviour-preserving move with nothing to design beyond Application Design
- [ ] NFR Requirements - SKIP
- **Rationale**: NFRs are set at requirements level (NFR-PF-01..06) and the stack is fixed (no new dependencies)
- [ ] NFR Design - SKIP
- **Rationale**: no new NFR patterns beyond what Application/Functional Design covers; existing ones (DeferredImage, Reveal, theme focus ring, `jsonLdScript`, reduced motion) are reused
- [ ] Infrastructure Design - SKIP
- **Rationale**: static assets only; no server config, CSP or deployment changes
- [ ] Code Generation - EXECUTE (ALWAYS, per unit)
- **Rationale**: implementation and tests
- [ ] Build and Test - EXECUTE (ALWAYS)
- **Rationale**: full `pnpm check` incl. Lighthouse for `/` and `/portfolio`; browser check of the lightbox on desktop and phone
### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP
- **Rationale**: Operations Configuration = No (decided at Requirements Analysis); the existing pipeline deploys to test on merge
## Units of Work (in order)
| # | Unit | Scope | Requirements | Peer dependency |
|---|---|---|---|---|
| 1 | **Shared Instagram block** | Move `InstagramGrid` to `components/InstagramGrid/` with its own `InstagramContent` (`content/instagramContent.ts`); homepage switched over with unchanged output | FR-PF-08, NFR-PF-02 | none |
| 2 | **Gallery building blocks** | Generic `PortfolioGrid` (row-order masonry, eager first N, link fallback), `Lightbox` (dialog, prev/next/wrap, keys, swipe, counter, caption, focus, preloading), generic filter bar; pure helpers in `lib/` with example and property-based tests; arbitraries; possibly a `zIndex` token and an extracted swipe hook. Tested with fixture data; not yet on a page | FR-PF-03, 05, 06, 07; NFR-PF-01..03, 05 | none |
| 3 | **Portfolio page** | 10 photos (download, two sizes, alt texts and shoot types as approved), `portfolioContent.ts` + types; route with intro, filters wired to shoot types and `?shoot=`, grid, lightbox, Instagram; SEO (indexed, `ImageGallery` JSON-LD, `ogImage`, Lighthouse indexed paths); LAYOUT.md; RE lines about `/portfolio` and the new components | FR-PF-01, 02, 04, 09; SEO-PF-01..05; NFR-PF-04, 06 | `webPage()` (contact-page) and `shootTypes.ts` (soorten-fotoshoots), cherry-picked at the start of the unit |
Units 1 and 2 have no peer dependency, so they can be built while the peers' commits are still pending. Unit 3 starts by cherry-picking both peer commits; if either is missing, it stops and reports (no parallel copy). Each unit: one or more commits on `feature/portfolio-page`, full `pnpm check` (incl. Lighthouse) before its completion message; one PR to master at the end. Whichever parallel feature merges first, the others rebase onto master; the hot files (`sitePages.ts`, `lighthouserc*.cjs`, `active-features.md`) only carry each feature's own entries.
## Estimated Timeline
- **Total stages to execute from here**: 7 (Application Design, Functional Design ×2 units, Code Generation ×3 units, Build and Test)
- **Estimated Duration**: two to three working sessions, plus waiting time on the two peer commits before unit 3
## Success Criteria
- **Primary Goal**: a finished, indexed portfolio page with filters and an accessible lightbox, matching the design, with the live photos
- **Key Deliverables**: `/portfolio` page; shared `PortfolioGrid`, `Lightbox`, filter bar and `InstagramGrid`; `portfolioContent.ts` and `instagramContent.ts`; pure helpers with example and property-based tests; 10 photos in two sizes with approved alt texts and a 1200×630 preview image; updated LAYOUT.md, Lighthouse config and RE lines
- **Quality Gates**: `pnpm check` passes (lint, format, tests with coverage thresholds, build, audits, Lighthouse: accessibility 1.0, best practices 1.0, SEO 1.0, performance ≥ 0.9 for `/portfolio`, homepage budgets unchanged); axe clean incl. the open lightbox; homepage output unchanged after unit 1
- **Integration Testing**: route tests render `/` and `/portfolio` in the shell; `/portfolio?shoot=<id>` starts filtered and an invalid value falls back to "Alles"; the lightbox opens from the grid and returns focus; canonical URL has no parameters
@@ -0,0 +1,75 @@
# Verduidelijkingsvragen — Portfoliopagina
Je antwoorden zijn compleet. Drie keuzes beïnvloeden elkaar: **masonry** (vraag 2: B), **filters per shoottype** (vraag 9: B) en **een eigen bijschrift per foto** (vraag 4: C). Daarnaast botst masonry met "eerste rij direct laden" (vraag 7: A), want bij masonry is er geen vaste eerste rij. Deze vragen lossen dat op.
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe.
---
## Verduidelijking 1: Hoe de masonry werkt
Er zijn twee manieren, en die verschillen in volgorde en toegankelijkheid.
- A) **Masonry in rijvolgorde**: een raster waarin elke foto zijn eigen hoogte krijgt naar zijn verhouding, terwijl de volgorde links-naar-rechts, rij voor rij blijft. Toetsenbord, screenreader en de "eerste rij" volgen dan de volgorde die Andrea kiest. Er kunnen kleine gaatjes onderaan de kolommen ontstaan (aanbevolen)
- B) **Masonry in kolommen** (CSS-kolommen): de kolommen sluiten perfect aan, maar de volgorde loopt per kolom van boven naar beneden. Foto 2 staat dan onder foto 1 in plaats van ernaast, en tab-volgorde springt over de pagina
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Verduidelijking 2: Welke foto's laden direct
Dit geldt bij masonry in plaats van "de eerste rij" uit vraag 7.
- A) De eerste foto's in de volgorde, zoveel als op desktop bovenaan in beeld staan (3, één per kolom), direct en met hoge prioriteit; de rest uitgesteld zoals afgesproken (aanbevolen)
- B) Alleen de allereerste foto direct, de rest uitgesteld
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Verduidelijking 3: Bijschrift en shoottype
Bij vraag 4 koos je een eigen kort bijschrift per foto, en bij vraag 9 filters per shoottype. Elke foto krijgt dus toch al een shoottype.
- A) Het bijschrift is de naam van het shoottype ("Newbornshoot", "Gezinsshoot"), uit dezelfde data als de filters. Eén gegeven per foto, nooit tegenstrijdig (aanbevolen)
- B) Een vrij bijschrift per foto (bijvoorbeeld "Gezinsshoot in de Gooise heide"), los van het shoottype voor de filters
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Verduidelijking 4: Welk shoottype elke foto heeft
Van de 10 live foto's heeft er maar één een omschrijving ("Zwanger koppel fotoshoot").
- A) Ik download de foto's, stel per foto een shoottype en alt-tekst voor in het functioneel ontwerp, en jij (of Andrea) keurt ze goed (aanbevolen)
- B) Ik vul ze nu in op basis van de bestandsnamen en de live site, zonder aparte controle
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Verduidelijking 5: Het gekozen filter in de URL
Bij vraag 5 koos je geen link naar één foto. Een link naar een **filter** is iets anders: de pagina Soorten fotoshoots zou dan per shoot kunnen linken naar "Bekijk meer newbornfoto's" → `/portfolio?shoot=newborn`.
- A) Ja: het filter staat in de URL (`?shoot=newborn`), zoals `?pakket=` op de homepage. Een ongeldige waarde toont gewoon "Alles". De canonieke URL blijft `/portfolio`, zodat zoekmachines geen dubbele pagina's zien (aanbevolen)
- B) Nee: het filter is alleen een weergave op de pagina en begint altijd op "Alles"
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Verduidelijking 6: Lightbox en filter
- A) De lightbox bladert alleen door de foto's van het gekozen filter, en de teller telt die ("2 / 4") (aanbevolen)
- B) De lightbox bladert altijd door alle foto's, ook als er een filter aan staat
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Verduidelijking 7: Filters zonder foto's
Bij 10 foto's heeft niet elk shoottype per se een foto (er is bijvoorbeeld misschien geen portretfoto).
- A) Alleen filters tonen voor shoottypes met minstens één foto, plus "Alles"; is er maar één shoottype, dan geen filterbalk (aanbevolen)
- B) Altijd alle shoottypes tonen; een leeg filter toont een korte melding
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -0,0 +1,188 @@
# Verificatievragen — Portfoliopagina
Al vastgelegd (geen vraag nodig):
- **Route** `/portfolio` bestaat al als placeholder ([portfolio.tsx](../../../../../web/src/routes/portfolio.tsx)) en wordt de echte pagina. De navigatie, de footer en de link "mijn portfolio" op Over mij verwijzen er al naar.
- **Layout en stijl** komen uit het ontwerp ([portfolio.html](../../../../../design/andreaslop-static/portfolio.html)): paginakop (eyebrow "Werk", h1 "Portfolio", intro) → fotoraster → Instagram. Foto's en teksten komen als vaste data in `web/src/content/`, in de vorm die de API straks levert (`/api/portfolio` in het ontwerp-README).
- **Hergebruik eerst**: `PageIntro` (h1), `PageSection`, `SectionHeading`, `DeferredImage`, `Reveal`, `InstagramGrid`, plus de theme-tokens en recipes (o.a. `carouselControl`/`iconControl` voor de knoppen). Geen hardgecodeerde kleuren, geen CSS-bestanden en geen nieuwe dependencies.
- **Toegankelijkheid**: dezelfde lat als bij homepage en Over mij: één h1, secties met een toegankelijke naam, contrast ≥ 4.5:1, zichtbare focus, doelen ≥ 44px, `prefers-reduced-motion`, axe in de tests en Lighthouse accessibility 1.0.
- **Indexeren**: de pagina gaat live, dus `indexed: true` in `sitePages.ts`, in de sitemap, en in `lighthouserc.cjs` naar de geïndexeerde paden (SEO 1.0).
- **Teamafspraken** (parallelle features): de JSON-LD loopt via de gedeelde `webPage()`-helper van contact-page; `PortfolioGrid`, `Lightbox` en het verplaatsen van `InstagramGrid` zijn van deze feature; foto's alleen voor portfolio komen in `web/src/assets/portfolio/`, shootfoto's (newborn, zwangerschap, gezin, loveshoot, portret) levert soorten-fotoshoots in `web/src/assets/shoots/`.
- **LAYOUT.md** heeft voor Portfolio al de blokken Portfolio → Instagram; dat klopt met het ontwerp (de paginakop hoort bij het blok Portfolio, zoals op de andere pagina's).
- **Codecommentaar** in het Engels in nieuwe code; teksten voor bezoekers in het Nederlands.
Wat ik op de live site (andreaslop.nl/portfolio) zag en wat afwijkt van het ontwerp:
| Onderdeel | Ontwerp | Live site |
| --------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| Paginakop | eyebrow "Werk", h1 "Portfolio", intro "Een selectie uit mijn werk. Klik op een foto om hem groot te bekijken." | **geen h1 en geen intro** |
| Foto's | **8** foto's (deels de homepagefoto's intro-2 en intro-4, plus newborn, portret en vier portfoliofoto's) | **10** andere, recentere foto's (2019–2026) |
| Raster | 3 kolommen, alles bijgesneden tot 3:4; 2 kolommen op tablet, 1 op telefoon | raster zonder bijschriften |
| Groot bekijken | lightbox met vorige/volgende, sluiten, bijschrift (= alt-tekst) en teller "3 / 8" | niet duidelijk aanwezig |
| Alt-teksten | algemeen ("Natuurlijke lifestylefoto") | **9 van de 10 zonder alt-tekst** |
| Filters / categorieën | geen | geen |
| Instagram | zelfde blok als op de homepage | zelfde blok als op de homepage |
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe.
---
## Vraag 1: Welke foto's
Welke foto's komen in het portfolio?
- A) De **10 foto's van de live site**, in dezelfde volgorde: originelen downloaden, eenmalig verkleinen en comprimeren (zoals bij homepage en Over mij), en per foto een beschrijvende Nederlandse alt-tekst die Andrea later kan nalezen (aanbevolen)
- B) De **8 foto's uit het ontwerp**, met beschrijvende alt-teksten
- C) De 10 live foto's, aangevuld met de shootfoto's die soorten-fotoshoots toch al verwerkt (newborn, zwangerschap, gezin, loveshoot, portret)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 2: Opbouw van het raster
Het ontwerp snijdt elke foto bij tot 3:4 (staand). Liggende foto's verliezen dan veel van het beeld; in de lightbox is de hele foto wel te zien.
- A) Zoals het ontwerp: gelijke tegels van 3:4, 3 kolommen op desktop, 2 op tablet, 1 op telefoon. Rustig en voorspelbaar; per foto een instelbaar focuspunt zodat het bijsnijden goed uitvalt (aanbevolen)
- B) Masonry: elke foto in zijn eigen verhouding, kolommen van ongelijke hoogte (meer van elke foto te zien, onrustiger, en de leesvolgorde voor toetsenbord en screenreader loopt per kolom in plaats van per rij)
- C) Gelijke tegels met af en toe een dubbel-hoge tegel (`portfolio-item--tall` staat al in de CSS van het ontwerp, maar wordt niet gebruikt)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 3: Groot bekijken (lightbox)
- A) Een toegankelijke lightbox zoals in het ontwerp: modaal dialoogvenster op Chakra `Dialog` met sluiten, vorige/volgende (knoppen, pijltjestoetsen, vegen op telefoon), teller "3 / 10", Escape sluit, focus blijft in het venster en keert na sluiten terug naar de aangeklikte foto, rondgaan na de laatste foto. Zonder JavaScript of vóór het laden opent de link gewoon de grote foto (aanbevolen)
- B) Geen lightbox: alleen het raster
- C) Elke foto opent de grote versie in een nieuw tabblad
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 4: Bijschrift in de lightbox
Het ontwerp toont de alt-tekst ook als zichtbaar bijschrift. Een goede alt-tekst beschrijft wat er te zien is ("Moeder tilt haar lachende dochter op in het bos"); als bijschrift leest dat soms wat klinisch.
- A) Geen zichtbaar bijschrift, alleen de teller; de alt-tekst blijft voor screenreaders (aanbevolen)
- B) De alt-tekst ook zichtbaar als bijschrift (zoals het ontwerp)
- C) Een apart, kort bijschrift per foto (bijvoorbeeld het soort shoot: "Gezinsshoot")
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: C
## Vraag 5: Link naar één foto (deeplink)
- A) Nee: de lightbox is alleen een weergave op de pagina; de terugknop van de browser verlaat de pagina (aanbevolen: eenvoudiger, geen extra URL's om te indexeren)
- B) Ja: de open foto staat in de URL (bijvoorbeeld `/portfolio?foto=3`), zodat je één foto kunt delen en de terugknop (ook op telefoon) de lightbox sluit, zoals `?pakket=` op de homepage
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 6: Formaat van de foto's
- A) Twee formaten per foto: een kleine voor het raster (ca. 800 px breed) en een grote voor de lightbox (ca. 1600–2000 px), die pas laadt als je de foto opent; de volgende en vorige foto worden vast vooruit geladen (aanbevolen)
- B) Eén formaat (groot) voor raster én lightbox: eenvoudiger, maar zwaarder voor telefoons en de prestatiescore
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 7: Laden van het raster
De eerste rij foto's staat op desktop direct in beeld en telt mee voor de laadsnelheid (LCP).
- A) De foto's van de eerste rij direct laden met hoge prioriteit, de rest pas na het laden van de pagina en als ze bijna in beeld komen (`DeferredImage`, zoals op de homepage) (aanbevolen)
- B) Alle foto's uitgesteld laden
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 8: Introtekst
- A) Eyebrow "Werk", h1 "Portfolio" en de intro uit het ontwerp, met "Klik" aangepast zodat het ook op telefoon klopt: "Een selectie uit mijn werk. Klik of tik op een foto om hem groot te bekijken." (aanbevolen)
- B) Precies de tekst uit het ontwerp
- C) Een intro zonder instructie, bijvoorbeeld alleen "Een selectie uit mijn werk."
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 9: Categorieën of filters
Ontwerp en live site hebben geen filters. Soorten-fotoshoots maakt wel een lijst met shoottypen (`shootTypes.ts`).
- A) Geen filters; één raster, de volgorde bepaalt Andrea (aanbevolen)
- B) Filters per shoottype (Alles, Newborn, Zwangerschap, Gezin, Loveshoot, Portret), op basis van `shootTypes.ts`; elke foto krijgt een shoottype
- C) Geen filters nu, maar wel per foto het shoottype vastleggen in de data, zodat filters later makkelijk kunnen
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 10: Instagram-blok
`InstagramGrid` staat nu in `components/home/` en krijgt zijn tekst en foto's uit `homeContent`.
- A) `InstagramGrid` verplaatsen naar een gedeelde plek (`components/InstagramGrid/`) met zijn inhoud in eigen content (bijvoorbeeld `instagramContent.ts`), en op de homepage en het portfolio hetzelfde blok met dezelfde foto's tonen (aanbevolen)
- B) Zelfde gedeelde component, maar met andere foto's op het portfolio
- C) Geen Instagram-blok op het portfolio
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 11: Titel en beschrijving (SEO)
Nu: titel "Portfolio | Andrea Slop Fotografie", beschrijving "Bekijk het portfolio van Andrea Slop Fotografie: spontane lifestylefoto's van gezinnen, stellen, zwangerschappen en newborns in Huizen en omgeving."
- A) Titel met zoekwoorden, bijvoorbeeld "Portfolio – lifestyle fotografie in Huizen", en de beschrijving controleren tegen de gekozen foto's. Ik stel ze voor in requirements.md en jij keurt ze goed (aanbevolen)
- B) Titel en beschrijving laten zoals ze zijn
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 12: Gestructureerde data (JSON-LD)
- A) Een `ImageGallery` via de gedeelde `webPage()`-helper, met per foto een `ImageObject` (URL, beschrijving = alt-tekst, maker = Andrea via de bestaande `Person`, rechthebbende = het bedrijf). Zo kan Google de foto's aan Andrea en het bedrijf koppelen (aanbevolen)
- B) Alleen een `ImageGallery` zonder lijst met foto's
- C) Geen extra gestructureerde data
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 13: Preview-afbeelding bij delen (Open Graph)
- A) Een eigen preview voor deze pagina: een van de portfoliofoto's, bijgesneden tot 1200×630 in `web/public/` (ik stel er een voor, jij kiest) (aanbevolen)
- B) De standaardafbeelding van de site houden
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
---
## Vraag: Beveiligingsextensies
Moeten de beveiligingsregels als harde vereisten worden afgedwongen voor dit project?
- A) Ja — dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten (aanbevolen voor productietoepassingen)
- B) Nee — sla alle BEVEILIGINGSREGELS over (geschikt voor PoC's, prototypes en experimentele projecten)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag: Property-Based Testing Extensie
Moeten de property-based testing (PBT) regels worden afgedwongen voor dit project?
- A) Ja — dwing alle PBT-regels af als blokkerende vereisten (aanbevolen voor projecten met bedrijfslogica, datatransformaties, serialisatie of stateful componenten)
- B) Gedeeltelijk — dwing PBT-regels alleen af voor pure functies en serialisatie round-trips (geschikt voor projecten met beperkte algoritmische complexiteit)
- C) Nee — sla alle PBT-regels over (geschikt voor eenvoudige CRUD-applicaties, UI-only projecten of dunne integratielagen zonder significante bedrijfslogica)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag: Operations-fase
Moet deze feature na Construction door de Operations-fase (deployment en monitoring inrichten)? Deployment naar test en productie en de monitoring (Sentry, Umami, UptimeRobot) bestaan al.
- A) Ja — na Construction de Operations-fase doorlopen (deployment + monitoring inrichten)
- B) Nee — stoppen na Build and Test (deployment en monitoring vallen buiten deze feature)
- C) Weet ik nog niet — vraag het opnieuw na de Construction-fase
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
@@ -0,0 +1,217 @@
# Requirements — Portfolio Page
## Intent Analysis
- **User Request**: build the portfolio page, again with attention to SEO, accessibility, reusability of code elements, Chakra and theming, like the previous feature (Over mij page).
- **Request Type**: New Feature (replaces the `/portfolio` placeholder with the real page) with a small supporting refactor (`InstagramGrid` moved to a shared component with its own content)
- **Scope Estimate**: Multiple components within one package (`web/`), plus [LAYOUT.md](../../../../../LAYOUT.md)
- **Complexity Estimate**: Moderate — a filterable masonry photo grid, an accessible lightbox (dialog, keyboard, swipe, focus management), URL state for the filter, two image sizes per photo, structured data for an image gallery, and coordination with two parallel features (shared `webPage()` helper, shared shoot types)
- **Requirements Depth**: Standard
## Source of Truth
- **Layout and styling**: [design/andreaslop-static/portfolio.html](../../../../../design/andreaslop-static/portfolio.html), `assets/css/style.css` (`.page-head`, `.section--flush-top`, `.portfolio-grid`, `.portfolio-item`, `.lightbox*`, `.instagram*`) and the lightbox behaviour in `assets/js/main.js` (`initLightbox`).
- **Photos**: the 10 photos of the live page https://andreaslop.nl/portfolio/ as of 2026-10-24, in that order. *Source: Q1 = A*
- **Decisions**: [requirement-verification-questions.md](requirement-verification-questions.md), [requirement-clarification-questions.md](requirement-clarification-questions.md)
- **Parallel-work agreements**: [aidlc-state.md § Parallel Work Agreements](../../aidlc-state.md)
## Page Structure
Shell header → **Intro** (page head, h1) → **Portfolio** (filter bar + masonry grid; lightbox on demand) → **Instagram** → shell footer.
## Dependencies on Parallel Features
- **`webPage(type: WebPageType, path, extra)`** in `seo.ts`, delivered by contact-page as a separate commit; this feature cherry-picks it and does not write its own page-level JSON-LD helper.
- **`ShootTypeId` / `ShootType` and `content/shootTypes.ts`**, delivered by soorten-fotoshoots-page as a separate commit (types, list, their shoot photos); this feature cherry-picks it and references shoot types only by `ShootTypeId`. Order of the list: newborn, zwangerschap, gezin, loveshoot, portret.
- If a dependency is not available when its unit starts, Code Generation stops at that point and reports it; no parallel copy is written.
## Out of Scope
- A link to a single photo (deep link); the lightbox is a view on the page only. *Source: Q5 = A*
- Changing the page title or meta description. *Source: Q11 = B*
- The "Bekijk meer …foto's" links on the Soorten fotoshoots page (that feature's scope; this feature only provides the `?shoot=` URL they can link to).
- A responsive image pipeline (srcset/WebP generated at build time); the two fixed sizes per photo are prepared once by hand.
- Operations phase. *Source: Operations = B*
---
## Functional Requirements
### FR-PF-01 Intro (page head)
- Eyebrow **"Werk"**, the page's only h1 **"Portfolio"**, and the intro **"Een selectie uit mijn werk. Klik of tik op een foto om hem groot te bekijken."**, via the existing `PageIntro` (design `.page-head`). *Source: Q8 = A*
### FR-PF-02 Photo data
- 10 portfolio photos, in the live order, as API-shaped static content in `web/src/content/` (e.g. `portfolioContent.ts`, interfaces in `content/types.ts`). Per photo:
- a stable `id`;
- `shootType: ShootTypeId`;
- a **grid image** (≈ 800 px wide) and a **large image** (≈ 1600–2000 px wide), each with intrinsic `width`/`height`; the grid image keeps the photo's own aspect ratio (no crop);
- a descriptive Dutch **alt text** (shared by both sizes).
- Photos are downloaded from andreaslop.nl in their original size, resized once to both sizes, compressed and stored in `web/src/assets/portfolio/` — same approach as homepage and Over mij, no new dependency. *Source: Q1 = A, Q6 = A*
- The shoot type and alt text of every photo are **proposed in Functional Design after looking at the photo**, and approved by the user (or Andrea) before code generation. *Source: clarification 4 = A*
### FR-PF-03 Filter bar
- A row of filter controls above the grid: **"Alles"** first, then one control per shoot type **that has at least one photo**, in the order of `shootTypes.ts`, labelled with the shoot type's short `name` (e.g. "Newborn", "Gezin"). *Source: Q9 = B, clarification 7 = A*
- If the photos cover only one shoot type, the filter bar is not shown.
- Exactly one filter is active; the active control is visually and programmatically marked (e.g. `aria-pressed` or a radio group — decided in design).
- Choosing a filter shows only that shoot type's photos, in their original relative order; "Alles" shows all photos.
- The number of shown photos is announced politely to screen readers after a change (e.g. "4 foto's").
- Focus stays on the chosen control; the page does not scroll.
### FR-PF-04 Filter in the URL
- The active filter is reflected as a search parameter: `/portfolio?shoot=<ShootTypeId>`; "Alles" has no parameter. *Source: clarification 5 = A*
- Opening the page with `?shoot=<id>` starts with that filter active.
- A missing, unknown or empty value, or a shoot type without photos, shows "Alles" (no error, no message); the value is never rendered.
- Changing the filter updates the URL without adding a history entry per click (decided in design: replace vs. push), and without a page reload or scroll jump.
- The canonical URL stays `https://andreaslop.nl/portfolio` for every filter (no duplicate pages for search engines); the sitemap lists only `/portfolio`.
### FR-PF-05 Masonry grid
- A masonry grid in **row order**: every photo is shown whole in its own aspect ratio, with columns of uneven height, while the DOM, tab and reading order stay left-to-right, row by row (the order Andrea chooses). Small gaps at the bottom of columns are acceptable. *Source: Q2 = B, clarification 1 = A*
- Columns: 3 on desktop, 2 on tablet, 1 on phones (the design's breakpoints on the theme breakpoints); gap from the theme (`gridGap` or the design's `--gap`).
- Each photo is a link-like control (`<a href>` to the large image) that opens the lightbox (FR-PF-06); without JavaScript, or before the app has loaded, it opens the large image itself. Its accessible name is the photo's alt text plus a hint that it opens a larger view.
- Hover and keyboard focus show the design's effect (slight zoom + darkening overlay, `cursor: zoom-in`); zoom is left out under `prefers-reduced-motion`; the theme focus ring is visible above neighbouring tiles.
- Photos fade in with the existing `Reveal`, content always in the DOM.
### FR-PF-06 Lightbox
- A modal dialog (Chakra `Dialog`, design `.lightbox`) showing the large image whole (`object-fit: contain`, fits the viewport) on a dark backdrop. *Source: Q3 = A*
- Controls: **close**, **previous**, **next** (buttons with Dutch accessible names, ≥ 44×44 px), keyboard **Escape** (close), **←/→** (previous/next), **swipe** left/right on touch devices; a click on the backdrop closes.
- Browsing **wraps around** (after the last photo comes the first, and vice versa) and covers **only the photos of the active filter**; the counter shows position and total within that set, e.g. "2 / 4". *Source: clarification 6 = A*
- **Caption**: the shoot type's full label (`shootLabel`, e.g. "Newbornshoot") as a visible caption; the alt text stays on the image for screen readers. *Source: Q4 = C, clarification 3 = A*
- Focus moves into the dialog on open, is trapped while open, and returns to the photo that was opened (or, after browsing, to the tile of the photo shown last) on close. Background content is inert and does not scroll.
- The dialog has an accessible name (e.g. "Foto groot bekijken"); the position change ("Foto 3 van 10") is announced politely when browsing.
- With a single photo in the active set, previous/next and the counter are hidden.
- Opening and switching respect `prefers-reduced-motion` (no fade/slide).
### FR-PF-07 Image loading
- **Grid**: the first 3 photos in order (one per column on desktop) load immediately with high priority; the others use the existing `DeferredImage` (after the load event, near the viewport). All grid images carry intrinsic width/height (no layout shift). *Source: Q7 = A, clarification 2 = A*
- **Lightbox**: the large image loads only when the lightbox opens; the next and previous large images (within the active set) are preloaded while it is open. While a large image loads, the grid image (already cached) or a neutral placeholder is shown — no empty flash, no layout jump. *Source: Q6 = A*
### FR-PF-08 Instagram block, shared
- Move `InstagramGrid` from `components/home/` to a shared `components/InstagramGrid/`, with its texts and photos in their own content module (e.g. `content/instagramContent.ts` with an `InstagramContent` type) instead of `homeContent.instagram`. *Source: Q10 = A*
- Use it on the homepage (unchanged output and behaviour) and on this page below the grid, with the same photos and the same profile link (checked https link via `visibleSocials`; without a valid link the block is left out, as on the homepage).
### FR-PF-09 LAYOUT.md
- Update the "Portfolio" diagram to **Intro → Portfolio → Instagram**, following [.ai/layout-conventions.md](../../../../../.ai/layout-conventions.md). "Intro" is added for consistency with the other page diagrams (About me, Types of shoots, Contact), which start with their page head. The filter bar is part of the Portfolio block.
---
## SEO Requirements
### SEO-PF-01 Indexing
- `/portfolio` becomes **indexed** when this feature merges: `indexed: true` in `sitePages.ts` (no `robots noindex`, included in `sitemap.xml`), and moved to the indexed paths in `web/lighthouserc.cjs` / `.desktop.cjs` (the existing sync test must pass). Only this feature's own entries are changed (team agreement).
### SEO-PF-02 Title and description
- Unchanged: title "Portfolio" (rendered "Portfolio | Andrea Slop Fotografie") and the existing description. *Source: Q11 = B*
### SEO-PF-03 Structured data
- An `ImageGallery` JSON-LD for `/portfolio`, built with the shared `webPage('ImageGallery', '/portfolio', extra)` helper. `extra` holds the photo list as `ImageObject`s (e.g. `associatedMedia`), each with:
- `contentUrl`: absolute https URL of the large image;
- `thumbnailUrl`: absolute https URL of the grid image (optional, decided in design);
- `description`: the alt text;
- `creator`: Andrea, by `@id` (`personId`);
- `copyrightHolder`: the business, by `@id` (`businessId`).
- Always all 10 photos, independent of the active filter. No e-mail address. Escaped through the existing `jsonLdScript`. Built by pure functions in `seo.ts` (100% coverage threshold applies). *Source: Q12 = A*
### SEO-PF-04 Preview image (Open Graph)
- A page-specific preview image: one portfolio photo cropped to **1200×630**, stored in `web/public/` (stable URL, outside the bundle), set as the page's `ogImage` in `sitePages.ts` with its own alt text. The photo is proposed in Functional Design; the user chooses. *Source: Q13 = A*
### SEO-PF-05 Semantic structure
- One h1; `section` landmarks named by their heading; heading outline h1 Portfolio → h2 for the grid section (visually hidden if the design shows no heading, e.g. "Foto's") → h2 Instagram; images with width/height and descriptive alt texts; grid photos as a list (`ul`/`li`).
---
## Non-Functional Requirements
### NFR-PF-01 Accessibility (WCAG 2.1 AA as guideline)
- Heading outline and landmarks as in SEO-PF-05; no skipped levels.
- Text contrast ≥ 4.5:1 (also the lightbox caption and counter on the dark backdrop); non-text contrast ≥ 3:1 for the filter controls' active state and the lightbox buttons.
- All controls keyboard operable with the theme focus ring; targets ≥ 44×44 px; nothing depends on hover or on swiping alone.
- Lightbox as specified in FR-PF-06 (dialog semantics, focus trap and return, Escape, inert background, announcements); filter changes announced (FR-PF-03).
- `prefers-reduced-motion` respected (reveal, tile zoom, lightbox transitions).
- Works at 200% zoom and from 320 px wide; the lightbox controls stay reachable on small and landscape phones.
- Axe checks in the component and route tests (including the open lightbox); Lighthouse accessibility 1.0 for `/portfolio` (mobile and desktop).
### NFR-PF-02 Styling and reuse
- Reuse before building: `PageIntro`, `PageSection`, `SectionHeading`, `DeferredImage`, `Reveal`, `InstagramGrid` (shared), `RouterLink`, the recipes `iconControl` / `carouselControl` for the lightbox buttons, theme tokens (`paper.deep`, `gridGap`, durations, easing, z-index) and text styles. A new `zIndex` token for the lightbox if needed.
- Swipe handling: reuse or extract the existing swipe logic of the hero slider (`useHeroSlider`) instead of writing a second one, if it fits; decided in design.
- New shared components get a generic API so other pages can use them: **`PortfolioGrid`** (masonry grid of photos that open a lightbox) and **`Lightbox`** (dialog over a list of images with prev/next, counter and caption). The filter bar is generic over its options (id + label), not tied to shoot types.
- Logic that decides what is shown lives in pure helpers in `lib/` (e.g. visible filters, filtered photos, URL parameter parsing, wrap-around navigation, masonry row spans), not in components.
- No hard-coded colours, CSS files or Tailwind; Chakra primitives where they fit (`Dialog`, `Grid`, `Image`).
- Components in their own folders under `components/`, Prettier style; code comments in English; visitor-facing texts in Dutch.
- Responsive from 320 px to ultrawide, mobile-first, no horizontal scroll.
### NFR-PF-03 Testing
- **Example-based**: page content and structure (heading outline, section names, list of photos, intro text), filter bar (which filters appear, active state, URL sync, invalid parameter → "Alles", announcements), grid (order, link targets, first 3 eager), lightbox (open from a tile, prev/next/wrap, counter, caption, Escape, backdrop close, focus trap and return, filtered set, single photo), the homepage `InstagramGrid` unchanged in output, head tags (title, description, no `noindex`, canonical without parameters, `og:image`), structured data, axe checks.
- **Property-based** (fast-check, shared arbitraries in `src/test/arbitraries.ts`, domain generators for portfolio photos and shoot types) for the pure helpers, e.g.: filtering preserves order and only returns photos of that type (invariant), filtering twice equals filtering once (idempotence), "Alles" returns all; visible filters are a subset of the shoot types in list order and exactly those with photos; URL parameter parse/format round-trip for every valid id and fallback for everything else; wrap-around navigation stays in range and next-then-previous returns to the start (round-trip); the lightbox state (open/next/previous/close/filter change) against a simple model (stateful); masonry spans are positive and grow with the photo's height ratio; the gallery JSON-LD has one `ImageObject` per photo, only absolute https URLs and never an e-mail address. *Source: PBT extension = A (full)*
- `pnpm check` (lint, format, tests incl. coverage thresholds, build, audits, Lighthouse) passes.
### NFR-PF-04 Security (Security Baseline extension enabled)
- No new third parties: no external scripts, fonts, embeds, lightbox libraries or endpoints; CSP in `web/config/securityHeaders.ts` unchanged. All photos self-hosted.
- The `?shoot=` parameter is validated against the allowlist of `ShootTypeId`s before use; any other value falls back to "Alles" and is never rendered or put into the DOM, head or structured data (misuse scenario: crafted or oversized parameter values).
- No e-mail address in markup, bundle, content or structured data.
- Structured data goes through `jsonLdScript` (escapes `<`, `>`, `&`).
- No new runtime dependencies; image processing is a one-off local step, not a build dependency.
### NFR-PF-05 Performance
- Lighthouse performance for `/portfolio`: ≥ 0.9 on mobile and desktop (the default budget for pages other than the homepage).
- Grid images ≈ 800 px wide and compressed; only the first 3 load before the load event; large images only on demand (FR-PF-07).
- No layout shift from images (intrinsic sizes) or from the filter bar.
- The lightbox code may be split from the initial bundle if that measurably helps; decided in design.
### NFR-PF-06 Content for the future API
- Portfolio content (photos with id, shoot type, two image sizes, alt text; intro texts) and Instagram content are plain data so the API (`/api/portfolio` in the design README) can deliver them 1-to-1; shoot types are referenced by id only.
---
## Extension Compliance — Requirements Level
### Security Baseline
| Rule | Status | Rationale |
|---|---|---|
| SECURITY-01 Encryption | N/A | No data stores |
| SECURITY-02 Access logging | N/A | No intermediaries added; hosting unchanged |
| SECURITY-03 Application logging | N/A | No server-side component; client errors already go to Sentry |
| SECURITY-04 HTTP security headers | Compliant | Existing header set unchanged; no CSP loosening (NFR-PF-04) |
| SECURITY-05 Input validation | Compliant | The only input is the `?shoot=` URL parameter, validated against an allowlist with a safe fallback (FR-PF-04, NFR-PF-04); no API endpoint |
| SECURITY-06 Least privilege | N/A | No IAM |
| SECURITY-07 Network configuration | N/A | No network infrastructure |
| SECURITY-08 Access control | N/A | Public content |
| SECURITY-09 Hardening | Compliant | No debug output; no new configuration |
| SECURITY-10 Supply chain | Compliant | No new dependencies (no lightbox or masonry library) |
| SECURITY-11 Secure design | Compliant | Misuse scenario (crafted `?shoot=`) addressed; structured data escaped; e-mail kept out of the page |
| SECURITY-12 Authentication | N/A | No authentication |
| SECURITY-13 Integrity | Compliant | No external CDN resources; all assets self-hosted |
| SECURITY-14 Alerting | N/A | No server-side component; existing monitoring unchanged |
| SECURITY-15 Exception handling | Compliant | Existing global error handling and error page; invalid input falls back safely |
### Property-Based Testing
| Rule | Status | Rationale |
|---|---|---|
| PBT-01 Property identification | Planned | Properties of the filter, URL, navigation, masonry and JSON-LD helpers identified in Functional Design |
| PBT-02 Round-trip | Planned | `?shoot=` parse/format; next/previous navigation |
| PBT-03 Invariants | Planned | Filter order and membership, visible filters subset, index range, span positivity, JSON-LD photo count and URL form |
| PBT-04 Idempotency | Planned | Filtering twice equals filtering once |
| PBT-05 Oracle | Planned | Masonry row spans or filters checked against a simple reference where one is trivial to write; otherwise N/A with rationale in design |
| PBT-06 Stateful | Planned | Lightbox state (open/next/previous/close/filter change) against a model |
| PBT-07 Generators | Planned | Domain generators for portfolio photos and shoot types in `src/test/arbitraries.ts` |
| PBT-08 Shrinking/reproducibility | Compliant | Existing seed logging (`config/testSeed.ts`) |
| PBT-09 Framework | Compliant | fast-check already configured |
| PBT-10 Complementary testing | Planned | Example-based tests for the page and components alongside PBT |
---
## Summary of Key Decisions
| # | Decision |
|---|---|
| Q1 | The 10 live photos, re-processed, descriptive alt texts |
| Q2 + C1 | Masonry in row order (whole photos, own aspect ratio, reading order kept) |
| Q3 | Accessible lightbox on Chakra `Dialog` (close, prev/next, keys, swipe, counter, wrap, focus management) |
| Q4 + C3 | Visible caption = shoot type label (`shootLabel`); alt text for screen readers |
| Q5 | No link to a single photo |
| Q6 | Two sizes per photo; large loads on open, neighbours preloaded |
| Q7 + C2 | First 3 photos eager with high priority, rest deferred |
| Q8 | Eyebrow "Werk", h1 "Portfolio", intro with "Klik of tik" |
| Q9 + C7 | Filters per shoot type from `shootTypes.ts`; only types with photos, plus "Alles" |
| C4 | Shoot type and alt text per photo proposed in Functional Design, approved by the user |
| C5 | Filter in the URL (`?shoot=`), canonical stays `/portfolio` |
| C6 | Lightbox browses within the active filter |
| Q10 | `InstagramGrid` shared with its own content; same block on home and portfolio |
| Q11 | Title and description unchanged |
| Q12 | `ImageGallery` with `ImageObject`s via the shared `webPage()` |
| Q13 | Own 1200×630 preview image from a portfolio photo |
| — | LAYOUT.md: Intro → Portfolio → Instagram (consistency with the other pages) |
| Ext. | Security Baseline: Yes · PBT: Yes (full) · Operations: No |