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>
20 KiB
20 KiB
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
/portfolioplaceholder with the real page) with a small supporting refactor (InstagramGridmoved 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
- Layout and styling: design/andreaslop-static/portfolio.html,
assets/css/style.css(.page-head,.section--flush-top,.portfolio-grid,.portfolio-item,.lightbox*,.instagram*) and the lightbox behaviour inassets/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-clarification-questions.md
- Parallel-work agreements: aidlc-state.md § Parallel Work Agreements
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)inseo.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/ShootTypeandcontent/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 byShootTypeId. 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 incontent/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).
- a stable
- 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 shortname(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-pressedor 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/portfoliofor 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 (
gridGapor 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 underprefers-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
InstagramGridfromcomponents/home/to a sharedcomponents/InstagramGrid/, with its texts and photos in their own content module (e.g.content/instagramContent.tswith anInstagramContenttype) instead ofhomeContent.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
/portfoliobecomes indexed when this feature merges:indexed: trueinsitePages.ts(norobots noindex, included insitemap.xml), and moved to the indexed paths inweb/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
ImageGalleryJSON-LD for/portfolio, built with the sharedwebPage('ImageGallery', '/portfolio', extra)helper.extraholds the photo list asImageObjects (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 inseo.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'sogImageinsitePages.tswith its own alt text. The photo is proposed in Functional Design; the user chooses. Source: Q13 = A
SEO-PF-05 Semantic structure
- One h1;
sectionlandmarks 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-motionrespected (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 recipesiconControl/carouselControlfor the lightbox buttons, theme tokens (paper.deep,gridGap, durations, easing, z-index) and text styles. A newzIndextoken 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) andLightbox(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
InstagramGridunchanged in output, head tags (title, description, nonoindex, 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 oneImageObjectper 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.tsunchanged. All photos self-hosted. - The
?shoot=parameter is validated against the allowlist ofShootTypeIds 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/portfolioin 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 |