Files
AndreaSlopFotografie/aidlc-docs/features/contact-page/inception/requirements/requirements.md
T
SluijsensandClaude Opus 5.5 9127eba776 Plans the Contact page and records unit 1 as generated
Workspace detection, a reverse engineering delta, requirements with the
approved layout mockups, the execution plan and the application design
for the Contact page, plus the code generation plan and summary of the
webPage helper. Corrects the contact payload in the shared API notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 08:50:48 +01:00

19 KiB
Raw Blame History

Requirements — Contact Page

Intent Analysis

  • User Request: build the Contact page, again with attention to SEO, accessibility and reuse of code elements, Chakra and theming, like the previous feature (Over mij).
  • Request Type: New Feature (replaces the /contact placeholder with the real page) with supporting refactors (shared contact form panel, shared contact details block, generic structured-data helper)
  • Scope Estimate: Multiple components within one package (web/), plus LAYOUT.md; one shared helper (webPage() in seo.ts) consumed by two parallel features
  • Complexity Estimate: Moderate — one page with a layout that deviates from the design on purpose, two extractions from the homepage contact section, a URL parameter, responsive image handling (large photo not loaded on phones), SEO additions
  • Requirements Depth: Standard

Source of Truth

Page Structure

Shell header → Intro (page head, h1) → Contact section: Contact form (left) and Photo with contact card (right) on wide screens; Contact card (with small portrait) above the Contact form on narrow screens → shell footer.

Out of Scope

  • The back-end (POST /api/contact), the robot check (Friendly Captcha) and switching the form on: the form stays behind the existing "Binnenkort" gate. Source: Q4 = A
  • The content of /privacyverklaring (still a placeholder; only linked). Source: Q11 = A
  • The service area wording in siteContent and areaServed in professionalService(): owned by the soorten-fotoshoots-page feature; this page only uses the same visible wording.
  • A responsive image pipeline (srcset/WebP) beyond what FR-CP-05 needs.
  • Operations phase. Source: Q19 = B

Functional Requirements

FR-CP-01 Intro (page head)

  • Eyebrow "Neem contact op", the page's only h1 "Contact" and an intro sentence, via the existing PageIntro.
  • Intro (proposal, to confirm at review): "Wil je een fotoshoot boeken of meer informatie ontvangen? Stuur me een berichtje, ik reageer binnen 1-2 werkdagen." The design's "via onderstaand formulier" is dropped, because while the form is gated the visitor reaches Andrea via the mail button or the contact card. The reply time comes from the shared value in FR-CP-07.

FR-CP-02 Contact form

  • The same form as on the homepage: Naam, E-mail, "In welke shoot heb je interesse?" (the shown packages, then "Overig") and "Stel hier je vraag"; same validation, honeypot, time check, focus handling, sent and failed states, and payload { naam, email, shoot, bericht }. Source: Q1 = A
  • Submit label stays "(Aan)vraag versturen". Source: Q10 = A
  • Behind the same "Binnenkort" gate as on the homepage, controlled by the same switch (siteContent.contactForm.enabled), so both forms go live together. Source: Q4 = A
  • On this page the form loads with the page (it is above the fold); on the homepage it keeps loading lazily as today.
  • Field ids are unique per page (idPrefix), so both forms can coexist in the code without clashes.
  • The form section has a heading visible only to assistive technology: "Stuur me een bericht" (h2). Source: clarification on Q7

FR-CP-03 Preselect a shoot via the URL

  • /contact?pakket=<packageId> preselects that shoot in the form, with exactly the homepage rules: case and surrounding spaces ignored, unknown or non-text values ignored, the value is never shown on the page. Known ids today: zwangerschap, newborn, gezin. Source: Q3 = A
  • The chosen package also goes into the mail subject of the gate's mail button and the failure message ("Aanvraag fotoshoot: Newborn"), as on the homepage.
  • After applying it, ?pakket= is removed from the address bar without a new history entry. The page is a fresh page load, so focus stays at the start of the page (no focus move).
  • This URL format is the contract for the soorten-fotoshoots-page feature ("Stuur een berichtje" links per shoot; shoots without a package link to plain /contact).

FR-CP-04 Contact card ("Direct contact")

  • A card with a small visible heading "Direct contact" (h2, eyebrow style) and a list of contact channels, each an icon plus link text, no per-channel headings: Source: Q6 = A, clarification on Q7
    • E-mail: the address as link text, mailto: with the default subject "Vraag via andreaslop.nl";
    • Instagram and Facebook: a readable name or handle as link text, opening the profile.
  • Data from siteContent (same source as the footer): the e-mail address is only assembled in the browser and the item is left out if it is invalid; social items only for valid links (visibleSocials). If no channel is valid, the card is not rendered.
  • Icons come from the icon set already used (@iconify-icons/ant-design, offline) and are decorative (hidden from assistive technology). Each row is fully clickable with a target of at least 44 px high.
  • Built as a reusable component (working name ContactDetails), not tied to this page.

FR-CP-05 Layout and photo

  • Wide screens (from the breakpoint where two columns fit; the design switches at 960 px): the form in the wider left column (about 3/5), on the right the contact photo (portrait crop 4:5) with the contact card overlapping its bottom edge, so photo and card read as one unit. Source: clarification A = A (proposal 1a)
  • Narrow screens: intro → contact card → form. The large photo is not shown and not downloaded. Instead the card shows a small round portrait (a separate small face crop, a few kB) next to "Direct contact" and the name "Andrea Slop". Source: clarification B = C
  • The large photo: the original from andreaslop.nl, resized once and compressed (as for Over mij), with a descriptive Dutch alt text for Andrea to review. The small portrait is decorative (the name next to it says who it is). Source: Q9 = A
  • Scroll reveal as on the other pages (existing Reveal), respecting prefers-reduced-motion.

FR-CP-06 Privacy line

  • Below the submit button of both forms (shared component): "Lees in de privacyverklaring wat ik met je gegevens doe.", with "privacyverklaring" linking to /privacyverklaring (underline link variant). Source: Q11 = A

FR-CP-07 Reply time in one place

  • The reply time "1-2 werkdagen" is one content value (in siteContent), used by the intro of this page and by the form's thank-you message ("Bedankt voor je bericht! Ik reageer binnen 1-2 werkdagen."), so they never disagree. Source: Q2 = A

FR-CP-08 Shared contact form panel

  • The wiring that the homepage ContactSection does today (gate, form, shoot options from the packages, preselect from ?pakket=, mail subject) moves into one shared component (working name ContactPanel), used by the homepage section and this page. The homepage looks and behaves exactly as before, including lazy loading, the placeholder height, the URL clean-up and moving focus to its heading after a "Boek …" click. Source: Q5 = A
  • On Over mij, "neem contact op" and "Boek je shoot" change from /#contact to /contact. The "Boek …" links on the homepage price cards keep going to the homepage form (/?pakket=…#contact). Source: Q12 = A

FR-CP-10 Content

  • All page texts and images live as API-shaped static data in web/src/content/ (a new content object with an interface in content/types.ts), passed into the components from the route, as for the other pages.

FR-CP-11 LAYOUT.md

  • Update the "Contact" diagram to the approved structure (Intro; Contact form beside Photo with contact details), following .ai/layout-conventions.md.

SEO Requirements

SEO-CP-01 Indexing

  • /contact becomes indexed when this feature merges: indexed: true in sitePages.ts (no robots noindex, in sitemap.xml), and moved to the indexed paths in web/lighthouserc.cjs / .desktop.cjs (the sync test must pass). Source: Q13 = A

SEO-CP-02 Title and description

  • Title: "Contact – fotoshoot boeken in Huizen" → "Contact – fotoshoot boeken in Huizen | Andrea Slop Fotografie" (61 characters; one over the ~60 guideline, accepted to keep "Contact" first). Source: clarification C = A (supersedes Q14 = B)
  • Description: "Neem contact op voor een newborn-, zwangerschaps- of gezinsshoot in Huizen, het Gooi en omgeving. Ik denk graag met je mee en reageer binnen 1-2 werkdagen." (155 characters). The service area wording matches the one approved in soorten-fotoshoots-page. Source: clarification D = A

SEO-CP-03 Structured data

  • A ContactPage JSON-LD on this page whose subject is the existing business (about / mainEntity referencing businessId). No e-mail address, as everywhere. Escaped through jsonLdScript. Source: Q15 = A
  • Built on a new generic, pure helper webPage(type: WebPageType, path, extra) in seo.ts (@context, @type, @id = url = canonical URL, name and description from sitePages, inLanguage: 'nl-NL', then extra), with WebPageType = 'WebPage' | 'AboutPage' | 'ContactPage' | 'ImageGallery' | 'CollectionPage'.
  • aboutPage() is rebuilt on webPage() with identical output and an unchanged signature.
  • webPage() (with the aboutPage() refactor and tests, nothing else) is delivered as a separate first commit, because portfolio-page and soorten-fotoshoots-page build on it (agreed with those sessions; hash to be sent to them).

SEO-CP-04 Preview image (Open Graph)

  • A page-specific preview image: the contact photo cropped to 1200×630 in web/public/, set as the page's ogImage in sitePages.ts with its own alt text. Source: Q16 = A

SEO-CP-05 Semantic structure

  • One h1; heading outline h1 "Contact" → h2 "Stuur me een bericht" (visually hidden) and h2 "Direct contact"; section landmarks with accessible names; descriptive link texts; images with width and height.

Non-Functional Requirements

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

  • Heading outline as in SEO-CP-05, no skipped levels.
  • Form: visible labels linked to the fields, errors linked and announced as today, focus to the first invalid field, the gate keeps keyboard and screen reader users out of the inactive form (inert) and offers the mail button.
  • Contact card: a list with an accessible name; decorative icons hidden; link texts that make sense on their own; focus ring from the theme; targets ≥ 44×44 px.
  • Text contrast ≥ 4.5:1 (accent.deep for eyebrow-styled text, ink.soft for running text); the card's border and shadow are not the only cue for its boundaries.
  • Order in the DOM matches the visual order on every screen size (no CSS reordering that changes the reading order).
  • prefers-reduced-motion respected; works at 200% zoom and 320 px wide without horizontal scrolling.
  • Axe checks in component and route tests; Lighthouse accessibility 1.0 for /contact (mobile and desktop).

NFR-CP-02 Styling and reuse

  • Reuse before building: PageIntro, PageSection (flushTop), FramedImage / DeferredImage where they fit, Reveal, Eyebrow, ContactForm, ContactFormGate, Link (underline), the linkButton recipe, theme tokens and text styles.
  • New shared pieces (ContactPanel, ContactDetails, the privacy line, webPage()) are generic and live in components/ or seo.ts, not inside the route. Styling that another page may need goes into tokens, text styles or recipes, not inline per page.
  • No hard-coded colours, CSS files or Tailwind; Chakra primitives where they fit; Prettier style; code comments in English in new code; visitor-facing texts in Dutch.
  • Coordination with parallel features: only this feature's own entries in sitePages.ts, lighthouserc*.cjs and active-features.md; PageIntro not changed without notifying the other sessions; components claimed by portfolio-page (PortfolioGrid, Lightbox, InstagramGrid) and soorten-fotoshoots-page (shootTypes, CallToAction, MediaText reverse) are not touched.

NFR-CP-03 Testing

  • Example-based: page structure (heading outline, landmarks, the card's channels and their targets, the privacy link), layout per breakpoint where testable, ?pakket= preselect and URL clean-up on this page, the homepage contact section unchanged in output and behaviour after the ContactPanel extraction, the Over mij link targets, head tags (title, description, no noindex, canonical, og:image), axe checks.
  • Property-based (fast-check, existing arbitraries): webPage() invariants (@id = url = canonical URL of the path, @type preserved, extra merged, never an e-mail address), aboutPage() output equal to the previous implementation for generated content, and any new pure helper (e.g. deriving the channel label from a social link). Source: PBT = A (full)
  • pnpm check (lint, format, tests incl. coverage thresholds, build, audits, Lighthouse) passes.

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

  • No new third parties: no external scripts, fonts, embeds or endpoints; CSP unchanged.
  • No e-mail address in markup at build time, bundle, content or structured data (assembled in the browser).
  • ?pakket= is validated against the known package ids and never reflected; form input is validated client-side as today (server-side validation belongs to the API feature).
  • Structured data through jsonLdScript; no new runtime dependencies; image processing is a one-off local step.

NFR-CP-05 Performance

  • On wide screens the contact photo is likely the largest contentful paint and must not be deferred; on narrow screens it must not be downloaded at all (only the small portrait). How this is done (e.g. <picture> with a media query, or rendering by breakpoint) is decided in design.
  • Lighthouse performance for /contact ≥ 0.9 on mobile and desktop, including the form loading with the page.
  • No layout shift from images or the form (intrinsic sizes, reserved space).

NFR-CP-06 Content for the future API

  • The page content is plain data (strings, ContentImage, link targets) so the API can deliver it 1-to-1; the reply time is one value.

Extension Compliance — Requirements Level

Security Baseline

Rule Status Rationale
SECURITY-01 Encryption N/A No data stores; nothing is sent while the form is gated
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-CP-04)
SECURITY-05 Input validation Compliant Existing client-side form validation and length limits; ?pakket= checked against an allow-list and never reflected (FR-CP-03); server-side validation is part of 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
SECURITY-09 Hardening Compliant No debug output; no new configuration; submit errors show a generic message only
SECURITY-10 Supply chain Compliant No new dependencies
SECURITY-11 Secure design Compliant E-mail kept out of the page source; honeypot and time check kept; structured data escaped
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 Failed submit falls back to a generic message with the mail address; global error page unchanged

Property-Based Testing

Rule Status Rationale
PBT-01 Property identification Planned Properties of webPage(), aboutPage() and new helpers identified in design
PBT-02 Round-trip Planned Structured data through jsonLdScript parses back to the same object (extend if not covered)
PBT-03 Invariants Planned @id = url = canonical; no e-mail in structured data; card shows only valid channels
PBT-04 Idempotency Planned Applying the same ?pakket= twice gives the same form state (if a new pure function is introduced)
PBT-05 Oracle Planned New aboutPage() equals the previous implementation for generated content
PBT-06 Stateful Compliant contactFormReducer is already covered; unchanged
PBT-07 Generators Planned Reuse/extend 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 Same form fields as the homepage (shoot select), one payload
Q2 Reply time "1-2 werkdagen", one content value for intro and thank-you
Q3 Preselect via /contact?pakket=<packageId> (contract for soorten-fotoshoots-page)
Q4 Same "Binnenkort" gate and switch as the homepage
Q5 Shared ContactPanel for the homepage and this page
Q6 Contact card with e-mail, Instagram and Facebook from siteContent
Q7 / A Icons instead of per-channel headings; layout proposal 1a (form left, photo with overlapping card right)
Q8 / B Phones: card above the form, no large photo, small round portrait in the card
Q9 Original live photo, resized once, descriptive alt text
Q10 Submit label "(Aan)vraag versturen"
Q11 Privacy line with link under both forms
Q12 Over mij links → /contact; homepage "Boek" links unchanged
Q13 Indexed on merge
C / D Title "Contact – fotoshoot boeken in Huizen"; description with "Huizen, het Gooi en omgeving"
Q15 ContactPage JSON-LD via a generic webPage() helper, delivered as a separate first commit
Q16 Own 1200×630 preview image
Ext. Security Baseline: Yes · PBT: Yes (full) · Operations: No