Files
AndreaSlopFotografie/aidlc-docs/features/homepage-sections/inception/requirements/requirements.md
T
SluijsensandClaude Opus 5.5 c81dcd3979 Adds the inception docs and design for the homepage sections
Refreshes the shared reverse engineering docs, adds the requirements,
application design and units for the homepage-sections feature, and
updates the static design: live prices and form fields, the new
Lieve woorden block and the coming-soon gate over the contact form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 23:46:30 +02:00

17 KiB
Raw Blame History

Requirements — Homepage Sections

Intent Analysis

  • User Request: add the homepage blocks below the existing hero with AI-DLC, one feature with one unit per block; suggest a temporary solution for the contact form while there is no back-end. Extended at Reverse Engineering review with the Instagram block and the "Lieve woorden" (testimonials) block from the live site, and with a contact form overlay, anti-spam and a robot check.
  • Request Type: New Feature (new user-facing sections on an existing page)
  • Scope Estimate: Multiple components within one package (web/), plus the static design reference (design/andreaslop-static/) and LAYOUT.md
  • Complexity Estimate: Moderate — six mostly presentational sections, one small carousel, one form with validation and anti-spam logic, content and image preparation
  • Requirements Depth: Standard

Source of Truth

Section Order

Hero (exists) → Lifestyle fotografie → Over mij → Prijzen → Lieve woorden → Contact → Instagram. Source: Q4 = A

Each of the six new sections is a separate unit of work.

Out of Scope

  • The hero (exists; unchanged)
  • A working contact form submission, server-side spam checks, rate limiting and the actual robot check integration — all part of the future API feature
  • The /contact page (stays a placeholder; it will reuse the contact form component in its own feature). Source: Q16 = A
  • A live Instagram feed (needs the API). Source: Q6 = A
  • The decorative banner image between Prices and Lieve woorden on the live site (landing-img-18.png) and the decoration next to the live contact form — the design's own pricing decorations are used instead
  • Responsive image pipeline (srcset/WebP). Source: Q5 = A
  • Operations phase: undecided, asked again at Build and Test. Source: Operations = C

Functional Requirements

FR-HP-01 Static design and LAYOUT.md updated first

  • Add the Lieve woorden section to design/andreaslop-static/index.html and its styles to assets/css/style.css, following the chosen design (FR-HP-05), so it can be reviewed in the browser before it is built in React.
  • Align the static design's homepage content with the live site: price cards (FR-HP-04) and contact form fields (FR-HP-06).
  • Update the Home diagram in LAYOUT.md to the seven blocks in the section order above, following .ai/layout-conventions.md.
  • Source: Q3 = A, user request ("eventueel verwerken in het design in deze workspace")

FR-HP-02 Lifestyle fotografie

  • Heading "Lifestyle fotografie" (h2) with lead text "Jouw favoriete momenten, vastgelegd op een natuurlijke en ongedwongen manier."
  • A gallery of four photos (the four current live photos), layout as .intro-gallery in the design.
  • Every photo has a descriptive Dutch alt text (to be reviewed by Andrea).
  • The live page's stray headings "Foto2" and "Foto" are not carried over.
  • Source: Q1 = A

FR-HP-03 Over mij

  • Photo of Andrea (live photo) next to the text block, layout as .about in the design, on the paper.alt background.
  • Eyebrow "Over mij", heading "Lifestyle fotograaf met een passie voor storytelling" (h2) and the three paragraphs from the live site / design (identical).
  • Link "Lees mijn verhaal" to /over-mij.

FR-HP-04 Prijzen

  • Heading "Prijzen" (h2) with lead "Pakketten", and the design's two decorative images (deco-1.png, deco-2.png, decorative only).

  • Three price cards (h3 per package), in the live order and with the live content:

    Package Price Included
    Zwangerschap € 175 1 uur fotografie · Minstens 30 zorgvuldig nabewerkte foto's · Persoonlijke online fotogalerij
    Newborn € 185 1-2 uur fotografie · Minstens 40 zorgvuldig nabewerkte foto's · Persoonlijke online fotogalerij
    Gezin € 175 1 uur fotografie · Minstens 30 zorgvuldig nabewerkte foto's · Persoonlijke online fotogalerij
  • Each card has a "Boek je shoot" button that moves to the contact section on the homepage and preselects that package in the shoot field (FR-HP-06). Source: Q9 = A

  • The packages are one data list in content/; the price cards and the shoot field options are both derived from it. Source: Q8 = A

FR-HP-05 Lieve woorden (testimonials)

  • Heading "Lieve woorden" (h2).
  • One review at a time, large: photo on the left; on the right a large decorative quotation mark, the shoot type as a label, the review text in Marcellus and the names below it. Stacked on small screens. Source: Q2 = A
  • Previous/next buttons and dots; no autoplay. Keyboard operable; the change of review is announced to screen readers. With only one review the controls are not shown.
  • Content (from the live site, each with its live photo):
    • Trouwshoot — "Super mooie foto's door Andrea gemaakt op onze trouwdag en pré-wedding shoot. Wij zijn er super blij mee! Een aantal hebben wij laten afdrukken en hangen nu ingelijst aan de muur, dus wij genieten er nog elke dag van." — Majella & Mark
    • Newbornshoot — "Heel tevreden met de newbornshoot. De foto's zijn prachtig geworden en we zijn erg blij met het resultaat. Zeker aan te raden!" — Demi & Kevin
  • The data list supports any number of reviews, so more can be added later without code changes.
  • Source: user request, Q2 = A, Q4 = A

FR-HP-06 Contact — form

  • Heading "Contact" (h2) with lead "Wil je meer informatie ontvangen? Neem gerust contact met mij op." Section anchor #contact.
  • Fields (live site): Naam, E-mail, "In welke shoot heb je interesse?" (select: the package names + Overig, with an empty "Kies een optie..." default), Bericht ("Stel hier je vraag"). Submit button "(Aan)vraag versturen". Source: Q7 = A, Q8 = A
  • Client-side validation with an error message per field and aria-invalid, as in the design: required fields, valid e-mail format, maximum lengths.
  • Submission goes through one function submitContactForm(payload). Until the API exists it is not called (see FR-HP-07); the payload shape is ready for POST /api/contact.
  • The form is a reusable component so the /contact page can use it later. Source: Q16 = A

FR-HP-07 Contact — "coming soon" overlay

  • While the form is switched off, it is visible but dimmed and cannot be used: the fields are inert, so keyboard and screen reader users never land in a form that does nothing.
  • Over the form is a panel with the text "Het contactformulier komt binnenkort. Mail me voor nu op info@andreaslop.nl" and a button "Stuur een e-mail" (mailto).
  • The e-mail address comes from siteContent.email and is assembled only in the browser, as in the footer (anti-spam). If the address is invalid, the panel still shows the coming-soon text without the address and button.
  • One setting (contactFormEnabled) switches between overlay and working form, in both directions, so the form can also be switched off again later if needed. Source: Q10 = A, Q11 = A (+ user note)

FR-HP-08 Contact — anti-spam (browser side)

  • A honeypot field: hidden from sighted users and assistive technology, not focusable, no autocomplete. A filled honeypot means the submission is treated as spam.
  • A time check: a submission less than ±3 seconds after the form was shown is treated as spam.
  • Spam is rejected silently (the visitor sees the normal success flow; nothing is sent).
  • Both checks are small pure functions in lib/ with tests.
  • Server-side checks and rate limiting are required in the API feature; the browser checks are not the only line of defence.
  • Source: Q12 = A

FR-HP-09 Contact — robot check (decided, integrated later)

  • The chosen service is Friendly Captcha (EU, privacy-friendly, invisible proof-of-work). Source: Q14 = B
  • The form has a place for the widget, but no Friendly Captcha script is loaded in this feature; it is integrated, together with server-side token verification and the required CSP changes, in the API feature. Source: Q13 = A

FR-HP-10 Instagram

  • Heading "Instagram" (h2) with @andreaslopfotografie as a link to the profile.
  • A grid of six fixed photos, each linking to the profile, layout as .instagram__grid in the design.
  • The photo list lives in content/, so the API can later fill it with the real feed (fetched server-side).
  • Initial selection: six existing site photos (Andrea can swap them).
  • Source: Q6 = A

FR-HP-11 Scroll reveal

  • Sections fade in gently when scrolled into view, as .reveal in the design, via a small useReveal hook (IntersectionObserver).
  • Disabled under prefers-reduced-motion. Without JavaScript or IntersectionObserver the content is simply visible.
  • Source: Q15 = A

FR-HP-12 Content and images

  • All section content lives as API-shaped static data in web/src/content/ with interfaces in content/types.ts, passed into the components from the home route.
  • Photos are downloaded from andreaslop.nl (and the design for the decorations), resized once to at most ±1600 px wide, compressed, and stored in web/src/assets. No new dependency. Source: Q5 = A

Non-Functional Requirements

NFR-HP-01 Accessibility (WCAG 2.1 AA as guideline)

  • The hero title remains the page's only h1; sections use h2, cards and reviews h3 where a heading is needed.
  • Each section is a section with an accessible name (its heading).
  • Text contrast ≥ 4.5:1: reuse the shell's choices (ink.soft instead of ink.muted, accent.deep instead of accent for small text on light backgrounds). The overlay panel text keeps full contrast; only the form behind it is dimmed.
  • Form: visible labels linked to fields, errors linked via aria-describedby, error announcement, focus to the first invalid field on submit.
  • Carousel: buttons with Dutch labels, current dot marked (aria-current), polite live region for manual changes, no autoplay.
  • Touch targets ≥ 44×44 px; keyboard operable; visible focus ring (theme).
  • prefers-reduced-motion respected (reveal, carousel transitions, smooth scrolling to #contact).
  • Axe checks in the component tests; Lighthouse accessibility stays 1.0.

NFR-HP-02 Styling and consistency

  • Same principles as the shell (frontend-shell NFR-02/02a): reuse theme tokens, text styles, recipes and components first (LinkButton, linkButton variants, eyebrow, paper.alt, Container); use Chakra primitives where they fit; lift repeated styling (e.g. the section heading block used by five sections) into a shared component or recipe; no hard-coded colours, CSS files or Tailwind.
  • Components in their own folders under components/, Prettier style.
  • Code comments in English in all new code, including new comments added to existing files. Existing Dutch comments are not translated as part of this feature. Visitor-facing texts (labels, messages, alt texts, aria labels) stay Dutch. Source: user change request at Requirements review
  • Responsive from 320 px to ultrawide, mobile-first, no horizontal scroll, works at 200% zoom.

NFR-HP-03 Testing

  • Example-based tests per section: rendered content, links and attributes, carousel controls, form validation messages, overlay behaviour (inert form, mailto, toggle), "Boek je shoot" preselection, axe checks.
  • Property-based tests (fast-check, existing setup and shared arbitraries) for the pure logic, e.g. form validation, honeypot/time check, shoot options derived from packages, carousel index wrapping.
  • Coverage: new pure helpers in src/lib/** fall under the existing 100% threshold.
  • pnpm check (lint, format, tests, build, audits, Lighthouse) passes.
  • Source: PBT extension = A (full)

NFR-HP-04 Security (Security Baseline extension enabled)

  • No new third parties: no external scripts, widgets, fonts or form endpoints in this feature. The CSP in web/config/securityHeaders.ts stays unchanged (form-action 'self', connect-src self/Umami/Sentry).
  • External links (Instagram) use target="_blank" with rel="noopener noreferrer" and a "opent in nieuw tabblad" hint for screen readers, as in the footer.
  • E-mail address never appears literally in HTML, bundle or content (assembled in the browser).
  • Input handling: client-side length limits and format checks on all fields; user input is rendered only as text by React (no HTML injection). The payload is ready for server-side validation in the API (SECURITY-05 applies there).
  • Defence in depth / misuse: honeypot + time check now; Friendly Captcha + server-side validation + rate limiting in the API feature (SECURITY-11). The overlay disables the form entirely while there is no server.
  • Fail safe: a failing submitContactForm shows a generic message and leaves the visitor's input intact; no internal details (SECURITY-15).
  • Dependencies: no new runtime dependencies (SECURITY-10).
  • For the API feature: Friendly Captcha requires CSP additions (script/worker and connect to its EU endpoint) and a privacy statement entry — recorded here, not done now.

NFR-HP-05 Performance

  • The homepage mobile Lighthouse budget (performance 0.8, see lighthouserc.cjs) and desktop 0.9 still pass.
  • All new images are below the fold: loading="lazy", explicit width/height (no layout shift), compressed per FR-HP-12.
  • No new network requests other than the bundled images.

NFR-HP-06 Content for the future API

  • Content interfaces are plain data (strings, numbers, arrays, image references) so the API can deliver them 1-to-1: PricingPackage, Testimonial, GalleryPhoto, InstagramContent and the section texts.
  • The contact payload is { naam, email, shoot, bericht } (the design's onderwerp becomes the shoot choice).

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-HP-04)
SECURITY-05 Input validation Compliant (planned) No API endpoint in this feature; client-side limits/format checks now, server-side validation required in the API feature
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, no protected resources
SECURITY-09 Hardening Compliant (planned) No debug output; generic messages
SECURITY-10 Supply chain Compliant (planned) No new dependencies
SECURITY-11 Secure design Compliant (planned) Misuse case (form spam) addressed: overlay, honeypot, time check; captcha + rate limiting assigned to the API feature
SECURITY-12 Authentication N/A No authentication
SECURITY-13 Integrity Compliant No external CDN resources; captcha script deferred
SECURITY-14 Alerting N/A No server-side component; existing monitoring unchanged
SECURITY-15 Exception handling Compliant (planned) Generic failure message in the form; existing global error handling

Property-Based Testing

Rule Status Rationale
PBT-01 Property identification Planned Done per unit in Functional Design
PBT-02 … PBT-06 Planned Applied to the pure helpers identified in Functional Design (validation invariants, carousel index wrapping, derived shoot options)
PBT-07 Generators Planned Domain generators added to src/test/arbitraries.ts
PBT-08 Shrinking/reproducibility Compliant Existing seed logging and shrinking (config/testSeed.ts)
PBT-09 Framework Compliant fast-check already configured
PBT-10 Complementary testing Planned Example-based tests per section alongside PBT

Summary of Key Decisions

# Decision
Q1 Content from the live site, layout/style from the design
Q2 Lieve woorden: one large review at a time, photo + quote, prev/next + dots, no autoplay
Q3 Add Lieve woorden (and live content) to the static design and LAYOUT.md first
Q4 Lieve woorden between Prijzen and Contact
Q5 Download live photos, resize once, no new dependency
Q6 Instagram: fixed grid of 6 photos in content/, real feed later via the API
Q7 / Q8 Live form fields; shoot options = package names + Overig
Q9 "Boek je shoot" scrolls to contact and preselects the package
Q10 / Q11 Dimmed, inert form under a coming-soon overlay with mailto; one setting toggles it both ways
Q12 Honeypot + time check + length limits now
Q13 / Q14 Robot check: Friendly Captcha, integrated in the API feature
Q15 Scroll reveal with reduced-motion support
Q16 /contact stays a placeholder
Ext. Security Baseline: Yes · PBT: Yes (full) · Operations: undecided