Files
SluijsensandClaude Opus 5.5 9efa7fc596 Adds the portfolio page
The ten live photos in a filterable masonry grid with an accessible
lightbox, filters per shoot type kept in the URL (?shoot=), the shared
Instagram block, and an indexed page with image gallery structured data
and its own preview image. Soorten fotoshoots now only links to the
portfolio for shoot types that have photos there.

The filter bar stays on one row, so the web font loading no longer
shifts the photos below it, and no photo loads before the page has: the
grid fades in, so loading its photos early only delayed the fonts and the
intro text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 19:05:13 +01:00

21 KiB
Raw Permalink Blame History

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

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: all photos use the existing DeferredImage (after the load event, near the viewport); none load eagerly. All grid images carry intrinsic width/height (no layout shift). Source: Q7 = A, clarification 2 = A; changed at Code Generation unit 3 (2026-10-27): the grid fades in (Reveal), so its photos are never the largest paint, and the 3 eager photos only delayed the fonts and the intro text — mobile Lighthouse 0.80 with, 0.91 without
  • 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. "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 ImageObjects (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 ShootTypeIds 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 ImageObjects 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