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>
19 KiB
19 KiB
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
/contactplaceholder 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()inseo.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
- Layout: the approved mockup proposal 1a (desktop, mobile with portrait), which deviates from design/andreaslop-static/contact.html on purpose. Styling (colours, type, spacing, form fields) follows the design and the existing theme. Source: clarification A = A, B = C
- Form behaviour: the existing homepage contact form (homepage-sections feature), unchanged except where stated here.
- Decisions: requirement-verification-questions.md, requirement-clarification-questions.md
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
siteContentandareaServedinprofessionalService(): 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.
- E-mail: the address as link text,
- 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), respectingprefers-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(underlinelink 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
ContactSectiondoes today (gate, form, shoot options from the packages, preselect from?pakket=, mail subject) moves into one shared component (working nameContactPanel), 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
FR-CP-09 Links to the contact page
- On Over mij, "neem contact op" and "Boek je shoot" change from
/#contactto/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 incontent/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
/contactbecomes indexed when this feature merges:indexed: trueinsitePages.ts(norobots noindex, insitemap.xml), and moved to the indexed paths inweb/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
ContactPageJSON-LD on this page whose subject is the existing business (about/mainEntityreferencingbusinessId). No e-mail address, as everywhere. Escaped throughjsonLdScript. Source: Q15 = A - Built on a new generic, pure helper
webPage(type: WebPageType, path, extra)inseo.ts(@context,@type,@id=url= canonical URL,nameanddescriptionfromsitePages,inLanguage: 'nl-NL', thenextra), withWebPageType = 'WebPage' | 'AboutPage' | 'ContactPage' | 'ImageGallery' | 'CollectionPage'. aboutPage()is rebuilt onwebPage()with identical output and an unchanged signature.webPage()(with theaboutPage()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'sogImageinsitePages.tswith 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";
sectionlandmarks 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.deepfor eyebrow-styled text,ink.softfor 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-motionrespected; 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/DeferredImagewhere they fit,Reveal,Eyebrow,ContactForm,ContactFormGate,Link(underline), thelinkButtonrecipe, theme tokens and text styles. - New shared pieces (
ContactPanel,ContactDetails, the privacy line,webPage()) are generic and live incomponents/orseo.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*.cjsandactive-features.md;PageIntronot changed without notifying the other sessions; components claimed by portfolio-page (PortfolioGrid, Lightbox, InstagramGrid) and soorten-fotoshoots-page (shootTypes, CallToAction, MediaTextreverse) 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 theContactPanelextraction, the Over mij link targets, head tags (title, description, nonoindex, canonical,og:image), axe checks. - Property-based (fast-check, existing arbitraries):
webPage()invariants (@id=url= canonical URL of the path,@typepreserved,extramerged, 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 |