Files
AndreaSlopFotografie/aidlc-docs/features/homepage-sections/inception/requirements/requirements.md
T
SluijsensandClaude Opus 5.5 3e530df0af Shows the Lifestyle fotografie photos as a swipeable row on phones
Four stacked photos were too much on a phone screen. Below the small
breakpoint the gallery is now a scroll-snap row with one photo at a
time and the next one peeking in; tablets and desktops keep the grid.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 00:14:47 +02:00

214 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](../../../../../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
- **Layout and styling**: `design/andreaslop-static/` (`index.html`, `assets/css/style.css`) and [LAYOUT.md](../../../../../LAYOUT.md). *Source: Q1 = A*
- **Content** (texts, prices, packages, photos, form fields, reviews): the live site https://andreaslop.nl/ as of 2026-10-19, because it is newer than the design. *Source: Q1 = A*
- **Decisions**: [requirement-verification-questions.md](requirement-verification-questions.md)
## 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](../../../../../LAYOUT.md) to the seven blocks in the section order above, following [.ai/layout-conventions.md](../../../../../.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: 4 columns on desktop, 2 on tablet.
- **On phones one photo at a time** in a horizontally swipeable row (scroll snap), with the next photo peeking in so it is clear there is more; the row is keyboard-scrollable. *Source: user change request at unit 1 review*
- 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 |