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>
This commit is contained in:
2026-10-19 23:46:30 +02:00
co-authored by Claude Opus 5.5
parent 38c5c3e262
commit c81dcd3979
33 changed files with 2354 additions and 275 deletions
@@ -0,0 +1,94 @@
# Application Design Plan — homepage-sections
Depth: **standard**. One front-end package; the design pins down component boundaries, props, content modules, the Prijzen → Contact interaction and what is reused from Chakra and the theme (NFR-HP-02). Detailed behaviour rules (validation, carousel, anti-spam) follow in Functional Design per unit.
## Plan
- [x] 1. Answer the design questions below
- [x] 2. Analyze answers for ambiguities (follow-up questions if needed)
- [x] 3. Static design reference (FR-HP-01)
- [x] 3a. Download the live photos (gallery, Andrea, reviews) into `design/andreaslop-static/assets/img` and add them to `manifest.txt`
- [x] 3b. `index.html`: live content for Lifestyle fotografie (photos), Prijzen (packages), Contact (form fields); new Lieve woorden section between Prijzen and Contact
- [x] 3c. `style.css`: styles for Lieve woorden (and the select field); `main.js`: prev/next/dots for the reviews
- [x] 3d. `LAYOUT.md`: Home diagram with seven blocks, per `.ai/layout-conventions.md`
- [x] 4. Generate `components.md` — component definitions and responsibilities
- [x] 5. Generate `component-methods.md` — props/signatures of components, hooks and helpers
- [x] 6. Generate `services.md` — content provisioning, Prijzen → Contact handover, contact submission adapter
- [x] 7. Generate `component-dependency.md` — dependency matrix, data flow
- [x] 8. Generate `application-design.md` — consolidated design
- [x] 9. Validate completeness and consistency (FR-HP-01…12, NFR-HP-01…06, Security/PBT applicability)
## Already decided (no question needed)
These follow from the requirements and the reuse principle (NFR-HP-02):
- **Shared section heading**: one `SectionHeading` component (optional eyebrow, the h2, optional lead; centred or left), used by all six sections — the design's `.section__head`.
- **Section wrapper**: one `HomeSection` component for the padding (`--section-y`), the optional `paper.alt` background and the accessible name (`aria-labelledby` on its heading).
- **Scroll reveal**: a `Reveal` wrapper component on top of a `useReveal` hook (IntersectionObserver), no-op under reduced motion.
- **Form fields**: Chakra's `Field` (label, error text, `aria-invalid`/`aria-describedby` wiring), `Input`, `Textarea` and `NativeSelect`, styled to the design's square fields via a recipe or theme slot overrides.
- **Buttons**: the existing `LinkButton` (`linkButton` recipe) for "Boek je shoot"; a `button` variant of the same recipe for the submit button.
- **Form state**: plain React state plus pure helpers in `lib/` — no form library (no new dependencies).
- **Contact payload**: `{ naam, email, shoot, bericht }`; `submitContactForm(payload): Promise<void>` in its own module, the single place the API call goes later.
- **Images**: imported from `web/src/assets` (Vite hashes them), with explicit width/height and `loading="lazy"`.
---
## Questions
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**.
## Vraag 1: Mappenstructuur van de componenten
- A) Plat, net als nu: elk component een eigen map onder `components/`, met Engelse namen uit de README van het ontwerp: `IntroGallery/`, `AboutBlock/`, `Pricing/`, `Testimonials/`, `ContactSection/` + `ContactForm/`, `InstagramGrid/`, en de gedeelde `HomeSection/`, `SectionHeading/`, `Reveal/`.
- B) Gegroepeerd: de zes blokken onder `components/home/` (bijv. `components/home/Pricing/`), en wat elders terugkomt (ContactForm, SectionHeading, HomeSection, Reveal) gewoon onder `components/`. Zo zie je in één oogopslag wat bij de homepage hoort, en blijft wat herbruikbaar is apart. (aanbevolen)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 2: Contentmodules
Hoe verdelen we de nieuwe vaste data over `content/`?
- A) Per onderwerp: `packages.ts` (pakketten; straks ook nodig op Soorten fotoshoots), `testimonials.ts` (reviews; kunnen later ook op andere pagina's) en `homeContent.ts` (teksten van de blokken, galerij, Over mij-foto, Instagram). Dat sluit aan op de API-endpoints uit het ontwerp (`/api/packages`, `/api/pages`). (aanbevolen)
- B) Alles in één `homeContent.ts`
- C) Eén bestand per blok (zes bestanden)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 3: De slider van Lieve woorden
- A) **Chakra's ingebouwde `Carousel`** (op Ark UI). Toegankelijkheid zit erin: rol en labels per slide, puntjes, toetsenbord en swipe. Wij voegen alleen de stijl en een melding voor schermlezers toe. Minder eigen code om te onderhouden. (aanbevolen)
- B) Zelf bouwen met een kleine eigen hook, naar het voorbeeld van `useHeroSlider` (zonder autoplay)
- C) Een gedeelde `useCarousel`-hook uit `useHeroSlider` halen, die zowel de hero als de reviews gebruikt. Dat refactort de hero, die net is opgeleverd.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 4: Hoe geeft "Boek je shoot" het pakket door aan het formulier?
- A) Via de URL: de knop linkt naar `/?pakket=newborn#contact`. De route controleert de waarde (alleen bestaande pakketten), het formulier leest hem en de browser scrollt naar `#contact`. Werkt ook na een refresh, en de link is te delen ("boek een newbornshoot"). (aanbevolen)
- B) Via gedeelde React-state op de homepage (de route geeft een callback aan Prijzen en een waarde aan Contact). Geen zichtbare URL-wijziging; gaat verloren bij een refresh.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 5: Waar staat de instelling `contactFormEnabled`?
- A) In de content (`siteContent.contactForm.enabled`), naast het e-mailadres. Hoort bij de vorm die de API straks levert, zodat het formulier dan ook vanuit het CMS aan of uit kan. (aanbevolen)
- B) Als constante in de code (bijv. `src/features.ts`), los van de content
- C) Per omgeving via de hostname, net als monitoring: dan kan het formulier eerst alleen op test aan
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 6: Foto in Lieve woorden
Hoe ziet de foto bij een review eruit? (De tekst krijgt in alle gevallen het grote aanhalingsteken in heidegroen.)
- A) Zoals bij Over mij: een rechthoekige foto met de verschoven zandkleurige rand erachter (`.about__media`). Consistent met de rest van de site. (aanbevolen)
- B) Een boogvorm (afgeronde bovenkant), een veelgebruikte, zachte stijl bij fotografen. Nieuw element in het ontwerp.
- C) Een kleine ronde foto boven de tekst, de tekst zelf centraal
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -0,0 +1,157 @@
# Execution Plan — Homepage Sections
## Detailed Analysis Summary
### Transformation Scope
- **Transformation Type**: Single component (application change inside `web/`), plus the static design reference and LAYOUT.md
- **Primary Changes**: six new homepage section components, a reusable contact form, shared section building blocks (section heading, scroll reveal), new content types and static content, new images
- **Related Components**: `routes/index.tsx`, `content/types.ts`, `content/*`, `lib/*`, `test/arbitraries.ts`, `design/andreaslop-static/index.html` + `style.css`, `LAYOUT.md`
### Change Impact Assessment
- **User-facing changes**: Yes — the homepage gains six sections below the hero
- **Structural changes**: No — the shell, routing and hosting stay the same
- **Data model changes**: Yes (front-end only) — new content interfaces (`PricingPackage`, `Testimonial`, `GalleryPhoto`, `InstagramContent`, section texts) and the contact payload shape
- **API changes**: No live API; the contact payload is designed for the future `POST /api/contact`
- **NFR impact**: Yes, contained — accessibility (carousel, form, overlay), performance (lazy images within the Lighthouse budget), security (no new third parties, CSP unchanged)
### Component Relationships
```mermaid
graph LR
Home["routes/index.tsx"] --> Sections["New section components (6)"]
Sections --> Shared["Shared: SectionHeading, useReveal, LinkButton"]
Sections --> Content["content/ (types + static data)"]
Prices["Prijzen"] -->|"package list + preselect"| Contact["Contact form"]
Contact --> Lib["lib/ (validation, honeypot, time check)"]
Contact --> Site["siteContent.email"]
Design["design/andreaslop-static + LAYOUT.md"] -.->|"reference"| Sections
classDef route fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef comp fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef data fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef ref fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,stroke-dasharray:5 5,color:#000;
class Home route;
class Sections,Shared,Prices,Contact comp;
class Content,Lib,Site data;
class Design ref;
```
Text alternative: the home route renders six new sections that use shared building blocks and content data; Prijzen feeds the package list and preselection into the contact form, which uses pure helpers in lib/ and the site e-mail; the static design is the reference.
| Component | Change Type | Priority |
|---|---|---|
| `routes/index.tsx` | Minor (adds sections) | Critical |
| New section components | Major (new) | Critical |
| `content/types.ts`, new content modules | Minor (additive) | Critical |
| `lib/` new helpers | Minor (additive) | Important |
| `design/andreaslop-static`, `LAYOUT.md` | Minor | Important (gate for React work) |
| `config/securityHeaders.ts` | None (unchanged) | — |
### Risk Assessment
- **Risk Level**: Low — additive changes on one page, no infrastructure or dependency changes
- **Rollback Complexity**: Easy — revert the merge
- **Testing Complexity**: Moderate — carousel and form behaviour, overlay/inert, property-based tests for helpers, Lighthouse budget
## Workflow Visualization
```mermaid
flowchart TD
Start(["User Request"])
subgraph INCEPTION["🔵 INCEPTION PHASE"]
WD["Workspace Detection<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>COMPLETED</b>"]
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
US["User Stories<br/><b>SKIP</b>"]
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
AD["Application Design<br/>+ static design update<br/><b>EXECUTE</b>"]
UG["Units Generation<br/><b>EXECUTE</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE (per unit)"]
FD["Functional Design<br/><b>EXECUTE for Prijzen, Lieve woorden, Contact</b>"]
NFRA["NFR Requirements<br/><b>SKIP</b>"]
NFRD["NFR Design<br/><b>SKIP</b>"]
ID["Infrastructure Design<br/><b>SKIP</b>"]
CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
Start --> WD
WD --> RE
RE --> RA
RA -.-> US
RA --> WP
WP --> AD
AD --> UG
UG --> FD
FD --> CG
UG --> CG
CG -.->|"next unit"| FD
CG --> BT
BT --> End(["Complete (Operations decided at Build and Test)"])
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RE fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
linkStyle default stroke:#333,stroke-width:2px
```
Text alternative: Inception runs Application Design (including the static design update) and Units Generation, skipping User Stories; Construction loops per unit through Functional Design (only for Prijzen, Lieve woorden and Contact) and Code Generation, skipping the NFR and Infrastructure stages, then Build and Test; Operations is omitted until decided at Build and Test.
## Phases to Execute
### 🔵 INCEPTION PHASE
- [x] Workspace Detection (COMPLETED)
- [x] Reverse Engineering (COMPLETED — refresh)
- [x] Requirements Analysis (COMPLETED)
- [x] User Stories (SKIPPED — single visitor persona, concrete requirements)
- [x] Execution Plan (IN PROGRESS)
- [ ] Application Design — EXECUTE
- **Rationale**: new components (six sections, reusable ContactForm, testimonial carousel, SectionHeading, `useReveal`), new content interfaces and one cross-section interaction (Prijzen → Contact preselection). This stage also delivers **FR-HP-01**: the Lieve woorden design and the live content in `design/andreaslop-static` plus the updated LAYOUT.md, so the design can be reviewed in the browser before any React work.
- [ ] Units Generation — EXECUTE
- **Rationale**: the user asked for one unit per block; this stage fixes the six units, their order and dependencies, and where the shared building blocks land.
### 🟢 CONSTRUCTION PHASE
Proposed unit order: **1 Lifestyle fotografie** (also introduces the shared SectionHeading, `useReveal` and image conventions) → **2 Over mij** → **3 Prijzen** → **4 Lieve woorden** → **5 Contact** (needs the package list from Prijzen) → **6 Instagram**.
- [ ] Functional Design — EXECUTE for **Prijzen**, **Lieve woorden** and **Contact**; SKIP for Lifestyle fotografie, Over mij and Instagram
- **Rationale**: those three contain logic (package → shoot options and preselection; carousel index and announcements; validation, honeypot, time check, overlay/toggle, submit states) and need PBT-01 property identification. The other three are presentational: content + layout already defined by the design and the application design.
- [ ] NFR Requirements — SKIP
- **Rationale**: NFRs are fully set at requirements level (NFR-HP-01…06); the tech stack is fixed and no new dependencies are added.
- [ ] NFR Design — SKIP
- **Rationale**: no new NFR patterns beyond what Functional Design and the code plans cover (inert overlay, lazy images, reduced motion).
- [ ] Infrastructure Design — SKIP
- **Rationale**: no infrastructure changes; the CSP and server configs stay unchanged.
- [ ] Code Generation — EXECUTE (ALWAYS), per unit
- [ ] Build and Test — EXECUTE (ALWAYS)
### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation — UNDECIDED
- **Rationale**: Operations Configuration = Undecided; asked again at Build and Test. The existing pipeline already deploys to test on merge to master.
## Package Change Sequence
Single package (`web/`). Sequence inside it: static design + LAYOUT.md (Application Design) → shared building blocks (unit 1) → units 2–6 in order. Feature branch `feature/homepage-sections`, created before the first Code Generation.
## Estimated Timeline
- **Total Stages to execute**: Application Design, Units Generation, 3× Functional Design, 6× Code Generation, Build and Test
- **Estimated Duration**: several working sessions; one unit per session is a comfortable pace
## Success Criteria
- **Primary Goal**: the homepage shows all six sections below the hero, matching the (updated) design, with live-site content
- **Key Deliverables**: updated static design + LAYOUT.md; six section components; reusable ContactForm with overlay, validation and browser-side anti-spam; content modules; images; tests
- **Quality Gates**: `pnpm check` green (lint, format, tests incl. PBT and axe, build, audits, Lighthouse: accessibility/best practices 1.0, home mobile performance ≥ 0.8); Security Baseline and PBT compliance per stage; CI green on the PR
- **Integration Testing**: home route renders all sections in order; "Boek je shoot" → contact preselection works across sections
@@ -0,0 +1,52 @@
# Unit of Work Plan — homepage-sections
The decomposition itself is already decided: one unit per homepage block (user request), in the order approved in the execution plan, with the shared building blocks introduced by the first unit that needs them. This plan fixes the boundaries and asks how the units are delivered.
## Plan
- [x] 1. Answer the questions below
- [x] 2. Analyze answers for ambiguities (follow-up questions if needed)
- [x] 3. Generate `unit-of-work.md` — the six units, their scope (components, content, helpers, images, tests) and where shared pieces land
- [x] 4. Generate `unit-of-work-dependency.md` — dependency matrix and order
- [x] 5. Generate `unit-of-work-story-map.md` — no user stories were written, so this maps every requirement (FR-HP / NFR-HP) to its unit(s)
- [x] 6. Validate boundaries and dependencies; check that every requirement is assigned
## Already decided (no question needed)
| # | Unit | Brings in (besides the section itself) |
| --- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Lifestyle fotografie | `HomeSection`, `SectionHeading`, `Reveal` + `useReveal`, `ContentImage` and `HomeContent` types, `homeContent.ts`, image conventions (download, resize, dimensions) |
| 2 | Over mij | `FramedImage` |
| 3 | Prijzen | `PricingPackage`, `packages.ts`, `formatPrice`, `packageFromSearch`, `validateSearch` on `/` |
| 4 | Lieve woorden | `Testimonial`, `testimonials.ts`, `slideLabel`, Chakra Carousel styling |
| 5 | Contact | `ContactForm` + `ContactFormGate`, `contact/` types and adapter, `shootOptions`, `validateContact`, `toContactPayload`, `isLikelySpam`, `siteContent.contactForm`, field styling |
| 6 | Instagram | profile URL derived from `siteContent.socials` |
- Work happens on one branch, `feature/homepage-sections`, created before the first Code Generation.
- Each unit adds its section to `routes/index.tsx`, so the homepage grows unit by unit and is never broken in between.
---
## Questions
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**.
## Vraag 1: Opleveren per unit of per feature
Een merge naar `master` gaat automatisch naar test.andreaslop.nl.
- A) **Eén pull request voor de hele feature.** Per unit één of meer commits op `feature/homepage-sections`; aan het eind één PR naar `master`. Test krijgt de homepage pas als hij af is. Een unit tussendoor op test bekijken kan via de handmatige run "Deploy to Test" op de branch. (aanbevolen)
- B) **Een pull request per unit.** Na elke unit een PR naar `master`, dus de homepage groeit stap voor stap op test. Meer PR's en CI-runs, maar kleinere reviews.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 2: Controle na elke unit
Elke unit wordt na het genereren automatisch gebouwd en getest. Hoe zwaar is die controle?
- A) **Volledige `pnpm check` per unit**, inclusief Lighthouse. Een unit met grote foto's die het performancebudget van de homepage overschrijdt, valt dan meteen op en niet pas aan het eind. Kost een paar minuten per unit. (aanbevolen)
- B) Lint, opmaak, tests en build per unit; Lighthouse alleen bij Build and Test
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A