Adds the AI-DLC documents of the testimonials redesign
Continuous Integration / check (pull_request) Successful in 1m45s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 8m44s
Continuous Integration / deploy-production (pull_request) Skipped

Requirements, execution plan, functional design, code summaries, build and test results and the audit log; the reverse-engineering notes and the feature registry are updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-06 01:24:15 +01:00
co-authored by Claude Sonnet 5.5
parent b03b18f58e
commit 7a5e713b69
26 changed files with 1593 additions and 5 deletions
@@ -0,0 +1,45 @@
# Code Generation Plan: section-heading (unit 1)
This plan is the single source of truth for Code Generation of this unit. Application code goes in `web/` of the worktree `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-testimonials-redesign`; only the summary (Step 6) goes under `aidlc-docs/`.
## Unit context
- **Goal**: `SectionHeading` shows its title in uppercase with wide letter-spacing, as in the approved canvas (FR-TR-05). It applies to all eight places that use `SectionHeading` (`AboutBlock`, `ContactSection`, `IntroGallery`, `Pricing`, `Testimonials`, `InstagramGrid`, `AboutIntro`, `ShootPage`) without changing those callers.
- **Dependencies**: none. Unit 2 (testimonials) comes after it and uses the same heading.
- **Stories**: none (User Stories skipped). Traceability is to requirements: FR-TR-05, assumptions A1 and A2, NFR-TR-01.
- **Functional Design**: skipped for this unit (a style change without logic). PBT-01 is N/A: there is no logic to give properties.
- **Existing files to modify** (brownfield, in place, no copies): `web/src/theme.ts`, `web/src/components/SectionHeading/SectionHeading.tsx`, `web/src/components/SectionHeading/SectionHeading.test.tsx`.
- **New files**: the code summary under `aidlc-docs/features/testimonials-redesign/construction/section-heading/code/`.
## Design of the change
| Item | Decision |
|---|---|
| New text style | `sectionHeading` in `theme.ts`: heading font, `textTransform: uppercase`, `letterSpacing: caps` (the existing token, 0.22em), line-height 1.15, size 26 px on phones (`base`) and 30 px from `md`. |
| Old text style | `sectionTitle` stays as it is: five other h2 elements use it directly (`CallToAction`, `PackageBlock`, `ShootBlock`, `ShootPage` twice, `StoryBlocks`), and they keep their style (assumption A1). Its comment is corrected, because it no longer belongs to `SectionHeading`. |
| `SectionHeading` | The `Heading` uses `textStyle="sectionHeading"`. No new props, no change to alignment, spacing, eyebrow or lead. The text in the DOM does not change (the case is only CSS), so accessible names and every existing test that looks for the title text keep working. |
| Size on phones | The canvas used 26 px on the phone artboard and 30 px on desktop; FR-TR-05 only says 30 px. This plan follows the canvas: 26 px below `md`. Requirements are updated to say so (Step 5). |
| Wrapping | Uppercase and letter-spacing make titles wider. The longest title is "Lifestyle fotograaf met een passie voor storytelling" (52 characters, `AboutBlock`, maximum width 620 px). By my estimate it takes about three lines on desktop and four on a phone. That is checked in Build and Test (assumption A2); this unit does not shorten any text. |
## Steps
- [x] **Step 1: Theme.** In `web/src/theme.ts` add the text style `sectionHeading` next to `sectionTitle` and correct the comment of `sectionTitle` (no longer used by `SectionHeading`; still used by the five direct h2 elements).
- [x] **Step 2: Component.** In `web/src/components/SectionHeading/SectionHeading.tsx` switch the `Heading` to `textStyle="sectionHeading"` and update the component comment (design reference: uppercase, letter-spaced title).
- [x] **Step 3: Unit tests.** In `SectionHeading.test.tsx` add example tests (PBT-10: not a property case, there is no logic):
- the h2 keeps its text exactly as given (the accessible name is not uppercased in the DOM), also for a long title;
- the generated CSS rules for the h2 contain `text-transform: uppercase` and the wide letter-spacing (using `cssRulesFor`, since jsdom does not compute responsive styles);
- the five direct `sectionTitle` headings do not get the new style (a render of `CallToAction` or `PackageBlock` checks that its h2 has no `text-transform: uppercase`).
- [x] **Step 4: Callers.** Search the other tests and the e2e tests for assumptions about the old heading style (`sectionTitle`, letter-spacing, text case); adjust only if one fails.
- [x] **Step 5: Requirements note.** In `requirements.md` change FR-TR-05 to "30 px from `md`, 26 px below" and mark A2 with the estimate of the longest title.
- [x] **Step 6: Code summary.** Write `aidlc-docs/features/testimonials-redesign/construction/section-heading/code/code-summary.md` (files changed, the decision, extension compliance).
- [x] **Step 7: Build and test this unit (Step 13.5).** In `web/`: `pnpm exec tsc --noEmit` (or the project's type check), lint, and the unit tests of `SectionHeading` and of every component that uses it; then the whole unit-test run (`pnpm test`) once. Fix failures inside this stage. The prerender build, the e2e tests and Lighthouse are part of the phase-level Build and Test.
- [x] **Step 8: Progress.** Update `aidlc-state.md`, check the plan checkboxes and set `active-features.md` to `🟢 Construction`.
## Extension compliance for this unit
- **Security Baseline**: SECURITY-04 (CSP) compliant by design: a theme text style produces a CSS class, no inline style, no new header. SECURITY-10 N/A: no dependency changes. All other rules N/A (front-end style change).
- **Property-Based Testing**: PBT-01..09 N/A (no logic, no pure function added). PBT-10: example tests only, because there are no properties to check; the existing property tests of other units are not touched.
## Scope and size
One theme entry, one component line, three small test cases, one summary and one requirements line. No new dependencies.
@@ -0,0 +1,61 @@
# Code Generation Plan: testimonials (unit 2)
This plan is the single source of truth for Code Generation of this unit. Application code goes in `web/` of the worktree `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-testimonials-redesign`; only summaries go under `aidlc-docs/`.
## Unit context
- **Goal**: the "Lieve woorden" section matches the approved canvas: card over a landscape photo, counter "X / Y" with arrows, no autoplay and no dots, a horizontal slide on change, a crop position per review (FR-TR-01..04, 06..14).
- **Design**: `construction/testimonials/functional-design/` (domain-entities, business-rules BR-TR-01..09, business-logic-model with the testable properties, frontend-components).
- **Dependencies**: unit 1 (`SectionHeading` style) is done. No new packages; `fast-check` is already there.
- **Brownfield rules**: files are changed in place; no copies. New files are only the two helpers and their tests.
- **Stories**: none (User Stories skipped); traceability is to FR-TR / NFR-TR and BR-TR / BR-REV.
## Files
| File | Action |
|---|---|
| `web/src/content/types.ts` | Modify: optional `imagePosition` on `Testimonial` |
| `web/src/content/testimonials.ts` | Modify: `imagePosition: '50% 42%'` on the trouwshoot review |
| `web/src/lib/normalizeImagePosition.ts` and `.test.ts` | Create |
| `web/src/lib/slideCounter.ts` and `.test.ts` | Create |
| `web/src/test/arbitraries.ts` | Modify: `imagePositionValid`, `imagePositionAny`; optional `imagePosition` on `testimonial` and `anyTestimonial` |
| `web/src/lib/visibleTestimonials.test.ts` | Modify: new property (an `imagePosition` never changes what is shown) |
| `web/src/recipes/carouselControl.ts` | Modify: drop `dot`; arrow without border, 44 px, opacity on hover |
| `web/src/components/home/Testimonials/TestimonialSlide.tsx` | Rebuild: card over photo, two layouts, crop |
| `web/src/components/home/Testimonials/TestimonialCarousel.tsx` | Modify: spacing 0, no item padding, counter, new bar placement, no dots |
| `web/src/components/home/Testimonials/Testimonials.tsx` | Modify: placeholder without padding wrappers, spacer below `lg` only |
| `web/src/components/home/Testimonials/TestimonialSlide.test.tsx`, `Testimonials.test.tsx` | Modify |
| `web/src/app.test.tsx` and other tests that name the dots or the old slide | Modify only if they fail |
| `aidlc-docs/_shared/reverse-engineering/` (`api-documentation.md`, `architecture.md`, `business-overview.md`) | Modify the lines about the testimonials (FR-TR-14) |
| `LAYOUT.md` | Check: the home diagram holds only the block name "Testimonials", which does not change; edit only if the diagram needs it |
| `aidlc-docs/features/testimonials-redesign/construction/testimonials/code/code-summary.md` | Create |
## Steps
- [x] **Step 1: Content model.** Add `imagePosition?: string` to `Testimonial` with a comment (raw `object-position`, normalised before use); set `'50% 42%'` on the trouwshoot review in `testimonials.ts`.
- [x] **Step 2: `normalizeImagePosition`.** Create `web/src/lib/normalizeImagePosition.ts` per the decision flow: `(value: unknown) => string`; two numbers with `%`, whitespace between and around, digits with optional decimals, each 0 to 100 inclusive; output `"X% Y%"` in shortest form; everything else `"50% 50%"`; never throws.
- [x] **Step 3: `slideCounter`.** Create `web/src/lib/slideCounter.ts`: `(index: number, count: number) => string` giving `"X / Y"`; odd input is made safe (count below 1 or not finite counts as 1; index is cut to a whole number and moved into range; non-finite index is 0).
- [x] **Step 4: Generators.** In `web/src/test/arbitraries.ts` add `imagePositionValid` (two numbers 0..100, whole or with one or two decimals, random whitespace) and `imagePositionAny` (`fc.oneof` of valid, out-of-range, other strings and non-string values); give `testimonial` and `anyTestimonial` an optional `imagePosition` (PBT-07: shared, reusable).
- [x] **Step 5: Property tests and example tests for the helpers (PBT-02..04, 07, 08, 10).**
- `normalizeImagePosition.test.ts`: invariant (any value gives the form with numbers 0..100), idempotence, round-trip with whitespace variants, easy verification (invalid gives exactly the centre); examples: `"50% 42%"`, `"050.0% 42%"` to `"50% 42%"`, `"120% 40%"`, `"50 42"`, `undefined`, `""`.
- `slideCounter.test.ts`: invariant over any numbers (including NaN and negatives) with 1 <= X <= Y, round-trip on valid positions, oracle against the plain template; examples `(0, 2)` is `"1 / 2"`, `(1, 2)` is `"2 / 2"`, `(5, 2)` is `"2 / 2"`, `(0, 0)` is `"1 / 1"`.
- `visibleTestimonials.test.ts`: any `imagePosition` (valid, garbled, missing) does not change which reviews are shown or their order.
- fast-check keeps shrinking on and prints its seed (already configured in the test setup; checked in Step 12).
- [x] **Step 6: Control recipe.** In `carouselControl.ts` remove the `dot` kind, make `arrow` a 44 px square without border or background with an `opacity` transition (0.55 on hover and focus-visible), and update the comment.
- [x] **Step 7: `TestimonialSlide`.** Rebuild per `frontend-components.md`: one grid cell with the photo layer and the card layer from `lg`; stacked in a wrapper of at most 640 px below `lg`, card overlapping the photo by 36 px; `DeferredImage` with `objectPosition` from `normalizeImagePosition`; no `FramedImage`; card `paper.deep`; shoot type, quote (`blockquote`) and names (`figcaption`, `accent.deeper`), no quotation mark; card minimum height 400 px with the 66 px control room at the bottom from `lg`. `data-testid="testimonial-{id}"` stays.
- [x] **Step 8: `TestimonialCarousel`.** `spacing` 0 (check that the next slide does not show at the edge), remove the items' `ps` and `pb`, remove the dots, add the counter (`aria-hidden`, `data-testid="testimonials-counter"`, text from `slideCounter(carousel.page, count)`), place the bar at the bottom right from `lg` (aligned with the card column) and centred below the slides under `lg`; keep the arrow keys, the instant flag for reduced motion, the live region and all other test ids.
- [x] **Step 9: `Testimonials` placeholder.** Remove the padding wrappers; show the longest review as a plain slide; keep the other reviews visually hidden, `aria-hidden` and `inert`; the spacer for the control bar only below `lg`, still with `data-requires-js`. Update the comments of the section and the placeholder.
- [x] **Step 10: Component tests.** Update `Testimonials.test.tsx` (no dots; counter "1 / 2" and "2 / 2" after next; arrows and arrow keys still call the API with `instant` under reduced motion; announcement unchanged; single review without controls and counter; prerendered HTML still holds every review) and `TestimonialSlide.test.tsx` (crop position from `imagePosition`, centre when missing, card contains shoot type, quote and names, no decorative quotation mark). Example tests pin the key scenarios; fix other tests that name the dots or the old slide only if they fail (`app.test.tsx` and the hydration and prerender tests).
- [x] **Step 11: Documentation.** Update the testimonials lines in `_shared/reverse-engineering/` (`api-documentation.md`: `Testimonial` field and the two new helpers; `architecture.md` and `business-overview.md`: the section's behaviour); check `LAYOUT.md` against `.ai/layout-conventions.md` and change it only if needed.
- [x] **Step 12: Code summary.** Write `construction/testimonials/code/code-summary.md` (files, decisions, verification, extension compliance, and what needs a real browser).
- [x] **Step 13: Build and test this unit (Step 13.5).** In `web/`: `tsc --noEmit`, `eslint .`, `prettier --check .`, the tests of the touched folders, then the whole `vitest run` once. Fix failures inside this stage. The prerender build, e2e, Lighthouse, swipe and visual checks are the phase-level Build and Test.
- [x] **Step 14: Progress.** Update `aidlc-state.md` and tick the checkboxes.
## Extension compliance for this unit
- **Security Baseline**: SECURITY-04: styles come from Chakra classes, no inline style attribute, no header change; the crop value is normalised before it reaches a style. SECURITY-05 (in spirit): content is validated, not trusted. SECURITY-10: no dependency change. SECURITY-15: the helpers never throw and fall back safely. Other rules N/A.
- **Property-Based Testing**: PBT-01 done in Functional Design; PBT-02 round-trips, PBT-03 invariants, PBT-04 idempotence (`normalizeImagePosition`) in Step 5; PBT-05 oracle for `slideCounter`; PBT-06 N/A (state is Chakra's); PBT-07 shared domain generators in Step 4; PBT-08 shrinking on, seed logged, runs in CI with the rest of `pnpm test`; PBT-09 `fast-check`; PBT-10 example tests next to every property.
## Scope and size
Two new helpers with tests, one content field, three components and one recipe changed, and test and documentation updates. No new dependencies.
@@ -0,0 +1,50 @@
# Vragen bij het functioneel ontwerp: testimonials
Vul achter elke `[Answer]:` de letter van je keuze in. Past geen enkele optie, kies dan de laatste (Anders) en licht je keuze toe. Bij elke vraag staat welke optie ik aanbeveel en waarom.
**Vaste uitgangspunten, hierover hoef je niets te beslissen:**
- Het canvas is de visuele referentie: desktop (1440 px) en telefoon (390 px). Voor het gebied daartussen is niets getekend.
- De carousel blijft gebouwd op Chakra's carousel; de loop, gelijke hoogte, de aankondiging "Review n van m" en het gedrag zonder JavaScript blijven zoals in de huidige spec.
- Tussen twee slides is geen ruimte (zoals in het canvas): de slide komt direct tegen de vorige aan schuiven.
- De teller "X / Y" is zichtbare tekst die schermlezers overslaan; de aankondiging bij een wissel doet de live region.
## Vraag 1
Vanaf welke breedte krijgt de testimonial de liggende opstelling met de kaart over de foto (zoals op desktop)? Het canvas tekent alleen 1440 px en 390 px. Nu staat de huidige opstelling gestapeld onder 1024 px (`lg`).
- A) Vanaf `lg` (1024 px), zoals nu; daaronder gestapeld met de foto op ten hoogste 640 px breed en gecentreerd, zodat hij op een tablet niet het hele scherm vult (aanbevolen: sluit aan bij de breekpunten van de rest van de site, en een kaart over een foto is op 768 px nog erg krap)
- B) Vanaf `md` (768 px): ook een tablet in de liggende opstelling, met een smallere kaart en kleinere tekst
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
## Vraag 2
In het canvas is de kaart 400 px hoog. De langste review (213 tekens) past daar op 1440 px ruim in, maar op 1024 px is de tekstkolom veel smaller en wordt de tekst hoger. Hoe bepalen we de hoogte van de kaart?
- A) Minimaal 400 px (of in verhouding tot de breedte), en hoger als de tekst dat nodig heeft; alle slides krijgen de hoogte van de hoogste, zodat de pagina eronder niet verspringt (aanbevolen: de tekst wordt nooit afgeknipt, en de gelijke hoogte van BR-REV-07 blijft kloppen)
- B) Vast 400 px; bij een lange review op een smal scherm wordt de tekst kleiner (risico: onleesbaar klein bij een lange review)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
## Vraag 3
De huidige foto heeft een zandkleurig blok dat links en onderaan achter de foto uitsteekt (`FramedImage`). In het goedgekeurde canvas staat dat blok niet meer: de kaart zelf is het vlak achter de foto. Wat doen we?
- A) Geen zandblok meer; de foto is een gewone afbeelding met de bijsnijpositie (aanbevolen: zo staat het in het canvas, en de kaart vervult die rol al)
- B) Het zandblok blijft achter de foto, naast de kaart
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
## Vraag 4
Het veld `imagePosition` bevat twee percentages (bijvoorbeeld `"50% 42%"`). Wat gebeurt er met een waarde die buiten het bereik valt, bijvoorbeeld `"120% 40%"`, of een typefout als `"50 42"`?
- A) Elke waarde die niet precies uit twee percentages van 0 tot en met 100 bestaat telt als ongeldig en valt terug op het midden (`"50% 50%"`) (aanbevolen: voorspelbaar, en het is wat de requirements al zeggen: "ongeldige waarden vallen terug op het midden")
- B) Waarden buiten het bereik worden begrensd (`"120% 40%"` wordt `"100% 40%"`); alleen een onleesbare tekst valt terug op het midden
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
@@ -0,0 +1,13 @@
# Functional Design Plan: testimonials (unit 2)
Only the checklist. The questions are in `testimonials-fd-questions.md`.
- [x] **Step 1: Analyse unit context.** Requirements FR-TR-01..04 and 06..14, NFR-TR-01..06, the approved canvas, and the existing design of the section (`homepage-sections/construction/lieve-woorden/functional-design`, BR-REV-01..11, BR-LZY-02).
- [x] **Step 2: Questions.** Four layout and behaviour questions the canvas does not settle (tablet layout, card height, sand block, out-of-range crop values).
- [x] **Step 3: Collect and check the answers.**
- [x] **Step 4: Domain entities.** `Testimonial` with the optional `imagePosition`; the normalised position; the counter text; invariants. File: `domain-entities.md`.
- [x] **Step 5: Business rules.** Updated rule table (what replaces BR-REV-04, 06, 09, 11; new rules for the counter, the crop and the card) and decision flowcharts. File: `business-rules.md`.
- [x] **Step 6: Business logic model.** Navigation (button, key, swipe, loop), announcement, placeholder swap, and the two pure helpers with their **testable properties (PBT-01)**. File: `business-logic-model.md`.
- [x] **Step 7: Frontend components.** Component hierarchy, layout geometry for desktop, tablet and phone, props, equal height, slide animation on Chakra's carousel, placeholder height, accessibility, test ids. File: `frontend-components.md`.
- [x] **Step 8: Extension compliance** for this stage (Security Baseline, PBT-01).
- [ ] **Step 9: Completion message and approval.** (message presented; awaiting approval)