Files
slp-modular-cms/aidlc-docs/features/hero-module/inception/requirements/site-contract-agreed-with-asf.md
T

4.9 KiB

Hero contract with the websites: points agreed with the ASF session (2026-11-16)

Input for Application Design. Source: message of "Andrea Slop Fotografie - ASF - Main" (technical answer; the crop/focus model stays Bryan's choice). The SLS side is delivered by the SLS session (three title lines with screen-reader text derived from the lines).

Agreed

Topic Agreement
Buttons buttons[] of {label, target}, 0 to 2. ASF shows one (the first, style "light"); a second would be "outline"; 0 buttons = no button.
Title One text; a new line is a line break (ASF title is one line today). tagline stays the label above the title in the same h1.
Lead ASF does not render it; if present the site ignores it.
Decorative decorative: true renders alt="" and is not read aloud.
Display single: no arrows, pause button or progress bar (ASF already does that for one slide).
204 / schedule / error The baked hero stays (fail-open). ASF shows the baked hero on 204, not nothing. If the host ever means "no hero at all", that must be said explicitly (not planned).
Image addresses Same origin /media/hero/<hash>/…, immutable; the CSP img-src does not change.
Markers <!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML--> (title, tagline, button(s), the FIRST slide as <picture>), <!--CMS:HERO-PRELOAD--> in the head, key hero in #cms-data with all slides. Fail-open: no marker, 204 or an error leaves the baked page.
Hydration The region holds neutral HTML (fixed classes, no Chakra classes); React takes over with the same source after hydration; slides 2..n load afterwards. The first slide of the data block must equal the first slide the host wrote into the HTML (same source, same cache rule).
Golden files ASF delivers input JSON, expected HTML region and expected preload, with a README and the commit, in web/contract/host-injection/hero/ on a new ASF branch feature/hero-module. They start once Bryan chose the crop model. An A/B-neutral subset (title, tagline, button, first slide <img> without <picture>) can be delivered earlier.

Crop/focus model: input for Bryan's choice

  • A: a focus point only; the site uses object-position; one ratio per width.
  • B (recommended by both sessions): the host cuts variants per named ratio around the focus point (or an administrator-set crop), the focus point stays in the data. ASF can use <picture> per ratio.

ASF proposal if B is chosen:

Ratio Name Widths Notes
3:2 wide 960, 1600, 2560 (the host may choose its own steps, but never upscale) the img itself
4:5 tall 640, 960, 1280 <source media="(orientation: portrait)">
  • sizes="100vw". Selection is by orientation, not by width, because the hero height comes from the screen (100svh with object-fit cover). The focus point stays as object-position for in-between shapes (tablet, narrow window).
  • Two preload links: tall with media="(orientation: portrait)" and wide with media="(orientation: landscape)", each with imagesrcset, imagesizes="100vw", fetchpriority="high". srcset, sizes and media in the preload must be byte-for-byte equal to those in <source>/<img> in HERO-HTML (the golden files check this).

Source images for the seed

The 8 ASF photos are already resized exports, not camera originals: all landscape 3:2, 1600x1067 (five), 2048x1362 (two) and 2560x1702 (one). The host must never upscale: for the five 1600-wide photos a variant wider than 1600 does not exist. Bryan may supply better originals (needed for good AVIF variants and a true portrait crop); the focus point per photo is Bryan's choice, set in the CMS after the seed.

Order, with the current alt texts (path K:\Development\SlpSoftware\Projects\AndreaSlopFotografie\web\src\assets\hero-N.jpg):

# File Size Alt
1 hero-8 1600x1067 Zwangerschapsfoto in de duinen
2 hero-7 1600x1067 Knusse newbornfoto met de familie
3 hero-1 2560x1702 Lifestyle fotografie
4 hero-2 1600x1067 Zwangerschapsshoot in de buitenlucht
5 hero-3 1600x1067 Newbornshoot van een pasgeboren baby
6 hero-4 2048x1362 Spontaan portret buiten
7 hero-5 1600x1067 Natuurlijke lifestylefoto
8 hero-6 2048x1362 Portret in de natuur

Seed values: title "Andrea Slop", tagline "Lifestyle fotograaf · Huizen", button "Lees meer" to /over-mij, display slideshow.

Consequences for the design

  • A <picture> region needs a stable, deterministic rendering of srcset/sizes/media shared by the HERO-HTML and the preload (one generator, golden-tested).
  • Variants are limited by the source size (no upscaling); the public data lists only variants that exist.
  • Two preload links (portrait, landscape) are needed when a tall ratio exists.
  • The first-slide data in #cms-data and in the HTML must come from the same computation.