@palate/cli 0.0.0-stage → 0.0.2

package/kb/sections/footer-closing-scene.md

@@ -0,0 +1,84 @@
+---
+id: footer-closing-scene
+name: A footer that rewards the end
+kind: footer
+shape: full-bleed-media
+layout: "a normal, readable link grid on top; beneath and behind it the page's closing scene: a small reveal that resolves the hero's picture or idea, with one last line in the brand's voice"
+fits: [crafted, playful, artsy, editorial, community, portfolio, agency, warm, cultural, music, food, travel, launch]
+avoid: [enterprise-compliance, data-dense-tool, government, clinical, crisis, low-bandwidth]
+needs: ["a hero picture, character or idea the footer can resolve", "the reward asset under ~200 KB, lazy", "the footer's real links (product, company, legal)"]
+imagery: any
+density: balanced
+moves: [colophon, console-easter-egg, engraving-colour-lens, footer-live-status, footer-rewards-the-end, made-with-proof]
+effort: m
+---
+
+## When it's right
+
+Marketing sites, portfolios, studios and community products where people browse to the bottom. The footer is the closing scene: the hero's painting at dusk, the illustrated character arriving home, the product's cursor signing off, the dawn page ending at sunset; with the links still there and easy. Implements the move `footer-rewards-the-end`; pairs with `engraving-colour-lens`, `colophon`, `console-easter-egg`. Not for docs or dense tools where the footer is navigation (use `footer-editorial-sitemap`), or pages so long nobody reaches the end.
+
+## Structure
+
+```
+1440 ─ full bleed; links inside the 1200 container
+┌────────────────────────────────────────────────────────────────────────────┐
+│   Acme                Product       Company       Resources     Legal       │  ← link grid, 5 cols, on a solid
+│   one line about us   Pricing       About         Docs          Privacy     │     or calm area of the scene
+│                       Changelog     Careers       Status ●      Terms       │
+│                                                                            │
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+│ ░░ the closing scene: 320–480px tall, resolves the hero (same picture in  ░ │
+│ ░░ another light, the character home, the drawing finished)               ░ │
+│ ░░        small interaction: pointer lens / hover detail / click note     ░ │
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+│   © 2026 Acme · Made in Lisbon          "Thanks for reading to the end."  │  ← sign-off line in the brand voice
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390
+links: 2 columns of groups, 44px targets
+scene: full bleed, 240–320px, cropped to its focal point (interaction becomes tap or static)
+© line, sign-off line (stacked)
+```
+
+At 390 the link groups become two columns (or accordions if more than 4 groups); the scene crops to its focal point; pointer effects become a tap-to-reveal or a static final state.
+
+## Finish
+
+- Links stay a working footer: group labels small 600 secondary; links body-small primary, 8–12px apart, ≥ 44px tall touch targets at 390 (padding, not bigger type). Contrast ≥ 4.5:1 against whatever is behind them; put the grid on a solid or calm area, never on top of the busy part of the scene.
+- The scene is full-bleed and sits below the links (or behind them only where the image is calm), 320–480px tall at 1440. It continues the page's visual language exactly (same palette, same illustration hand, same texture).
+- Top of the footer: no hard divider stacked on a section edge (M28); a hairline or a change of surface, not both.
+- Sign-off line in the brand voice, small, secondary, right side of the bottom row; copyright left. If the page was made with the product, the `made-with-proof` sentence goes here.
+- Status dot (optional, `footer-live-status`) only if wired to a real status source.
+
+## Content
+
+- The reward resolves something from the top of the page; it's not a random flourish.
+- Links: only real pages. Group them by job (Product, Company, Resources, Legal), 3–6 each.
+- Any image used needs a credit (here, or in a colophon linked from here).
+- The sign-off is short and in voice; a joke only if the brand jokes elsewhere.
+
+## States and motion
+
+- The reveal triggers once when the footer arrives (IntersectionObserver, `rootMargin: 0px 0px -20% 0px`); assets lazy-load a few screens earlier.
+- Pointer interactions only for fine pointers; touch gets a tap or nothing. No scroll-jacking.
+- Reduced motion and no-JS: the scene shows in its final state.
+- Purely visual rewards are `aria-hidden`; meaningful ones (a note) are real text.
+
+## Pitfalls
+
+- A giant wordmark as the only idea (now a cliché).
+- The reward covering or moving the links.
+- Heavy video or 3D loading at page start for a footer most visitors see last.
+- A scene unrelated to the rest of the page.
+- Replaying the reveal each time the footer scrolls in and out.
+
+## Floor checks
+
+- Are the footer links laid out in clear groups and readable against what's behind them?
+- Is there a visual closing moment beyond links (a scene, picture or reveal)?
+- Does the closing visual match the page's visual language (palette, illustration or photo style)?
+- Is the closing visual clear of the links rather than sitting under busy text?
+- Is there a copyright line and a short sign-off?
+- At 390, are links in tidy columns with comfortable tap spacing and the scene cropped sensibly?

package/kb/sections/footer-editorial-sitemap.md

@@ -0,0 +1,85 @@
+---
+id: footer-editorial-sitemap
+name: Editorial footer with a full sitemap and a wordmark
+kind: footer
+shape: editorial-columns
+layout: "a ruled sitemap in editorial columns with one useful extra (newsletter, latest post, office hours), above a large wordmark set to the container width that ends the page"
+fits: [editorial, publishing, media, agency, saas, crafted, premium, b2b, docs, bold, cultural]
+avoid: [crisis, low-bandwidth, kids]
+needs: ["15–40 real footer links in 3–6 groups", "the brand wordmark as type or SVG", "one useful extra: a newsletter with a real cadence, the latest article, a contact address"]
+imagery: type
+density: dense
+moves: [footer-live-status, footer-rewards-the-end, kinetic-variable-type]
+effort: s
+---
+
+## When it's right
+
+Sites with a lot to navigate (publications, studios with many case studies, products with docs, changelog and careers) where the footer is a genuine index and the brand wants a confident ending. The sitemap is set like a magazine's masthead page: ruled, dense, easy to scan. A wordmark ends it, but it is never the only idea: the extra (the latest piece, the newsletter, the office address with local time) gives the footer a job beyond links. Not for single-page products with five links (use `footer-minimal-credits`).
+
+## Structure
+
+```
+1440 ─ container 1200
+┌──────────────────────────────────────────────────────────────────────────┐
+│ ─────────────────────────────────────────────────────────────────────── │
+│ Latest                    │ Product      │ Work         │ Studio        │  ← cols: 4 | 2 | 2 | 2 | 2
+│ "How we set type for the  │ Pricing      │ Case studies │ About         │
+│  Halden catalogue" →      │ Changelog    │ Clients      │ Careers (3)   │  ← counts only if real
+│ 6 min · 21 Oct 2026       │ Docs         │ Process      │ Press         │
+│                           │ Status       │              │ Contact       │
+│ Newsletter, monthly       │              │              │               │
+│ [ email        ][Subscribe]│              │              │               │
+│ ─────────────────────────────────────────────────────────────────────── │
+│ Lisbon 14:32 · hello@acme.studio     Privacy  Terms  Cookies   © 2026    │  ← meta row, small
+│                                                                          │
+│ ACME STUDIO                                                              │  ← wordmark, spans container width
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390
+Latest + newsletter (full width)
+link groups in 2 columns
+meta row stacked (2–3 lines)
+wordmark at container width (it scales down with the width)
+```
+
+At 390 the extra comes first, then link groups in two columns, then the meta lines, then the wordmark, which scales with the viewport (`font-size` in `vw` clamped) so it still spans the content width.
+
+## Finish
+
+- Columns: the extra takes 4 of 12, link groups 2 each. Vertical hairlines between columns optional; one horizontal hairline above the grid and one above the meta row (`_finish.md` hairlines). No boxes.
+- Group labels small 600 secondary; links body-small primary, line-height 1.9 so the column scans like a list. Link hover: underline with offset 3px, colour unchanged.
+- Extra: the latest article as a real link with reading time and date (D13); newsletter as a joined field + button (the page's input, and its `.btn-primary`) with the real cadence in its label.
+- Meta row: small secondary; local time computed live if shown (`footer-live-status`), email as a link, legal links, copyright.
+- Wordmark: the brand's display face or logo SVG, sized so it spans the container exactly (fit-text: measure and set `font-size`, or an SVG with `width: 100%`), letter-spacing tightened for display (P20), colour one step lighter than primary or the brand colour. Its baseline sits 32–48px above the page's end; descenders may be cropped by the page edge only if done deliberately.
+- Background: the page's darkest or lightest surface, so it reads as the end.
+
+## Content
+
+- Every link goes to a real page; no "Blog" link to an empty blog.
+- The extra must be live and true: a real latest article, a newsletter that actually sends at the stated cadence.
+- Counts ("Careers (3)") only when they come from data.
+
+## States and motion
+
+- No entrance animation. The wordmark may do one quiet thing on hover (variable weight shift, see `kinetic-variable-type`), off under reduced motion.
+- Newsletter form: loading, success in place ("Check your inbox to confirm"), inline error.
+- Live time updates once a minute with `tabular-nums`; no-JS shows the city without time.
+
+## Pitfalls
+
+- A huge wordmark with nothing else of value: the cliché `footer-rewards-the-end` warns about.
+- 40 links with no groups.
+- A newsletter with no cadence and no idea what you'll get.
+- The wordmark overflowing the container at some widths.
+
+## Floor checks
+
+- Are links grouped under clear labels and aligned in columns?
+- Is there something useful besides links (a latest article, a newsletter with a stated cadence, contact details)?
+- Does the large wordmark fit the container width cleanly without overflowing or clipping by accident?
+- Is the meta row (legal links, copyright) present and quieter than the sitemap?
+- Are columns divided by quiet hairlines or space rather than boxed cards?
+- At 390, are link groups in two tidy columns and the wordmark still fitting the width?

package/kb/sections/footer-minimal-credits.md

@@ -0,0 +1,80 @@
+---
+id: footer-minimal-credits
+name: Minimal footer with credits
+kind: footer
+shape: stacked-rows
+layout: "two or three quiet rows: the few links that matter, then credits (who made it, image and type credits, tools), then the legal line; like the last page of a well-made book"
+fits: [minimal, quiet, calm, crafted, editorial, portfolio, artsy, honest, launch, waitlist, publishing, heritage, nature, nonprofit]
+avoid: [enterprise, data-dense-tool, ecommerce]
+needs: ["the 3–8 links a visitor actually needs", "real credits: people, photographers, illustrators, typefaces, licences", "the legal line"]
+imagery: none
+density: airy
+moves: [colophon]
+effort: s
+---
+
+## When it's right
+
+Small sites (a launch page, a waitlist, a portfolio, a book, a nonprofit campaign) where a big footer would be furniture. What's left is honest and useful: a few links, and credits for everyone whose work is on the page, including image and type credits, which licences often require anyway. It reads like a colophon in miniature (see `colophon` for the long form). Not for sites with many sections to index (use `footer-editorial-sitemap`).
+
+## Structure
+
+```
+1440 ─ container 1200
+┌──────────────────────────────────────────────────────────────────────────┐
+│ ─────────────────────────────────────────────────────────────────────── │
+│ Acme                         Changelog   Docs   Contact   GitHub ↗       │  ← row 1: name + links, one line
+│                                                                          │
+│ Made by Ana Ruiz and Tom Hale in Porto. Photographs by Joana Reis.       │  ← row 2: credits, small, 2–3 lines
+│ "The Hay Wain" by John Constable, public domain, via the National        │     max 80ch
+│ Gallery. Set in Source Serif and Inter. Built with Astro.                │
+│                                                                          │
+│ © 2026 Acme Ltd · Privacy · Terms                         Back to top ↑  │  ← row 3: legal + back to top
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390
+name
+links (wrap onto 2 lines, 44px tall targets)
+credits paragraph
+legal line, back to top
+```
+
+At 390 everything stacks; links wrap with comfortable gaps; the credits stay a paragraph (left-aligned).
+
+## Finish
+
+- One hairline above the footer (or a surface change, not both; M28). Rows 24px apart at 1440, 20 at 390. Footer padding 48 top, 32 bottom.
+- Row 1: brand name body 600; links body-small primary, 24px apart, on one baseline with the name.
+- Row 2: credits in small size, secondary colour, max 80ch, `text-wrap: pretty`. Names of people and works are links where a portfolio or source exists. Italic for titles of works if the type system uses italics elsewhere.
+- Row 3: small tertiary-to-secondary; "Back to top" as a text link right-aligned, focusable.
+- Left-aligned throughout; no centring (M06).
+- No icons except the external-link arrow on outbound links.
+
+## Content
+
+- Credits are true and complete for what the page shows: every photographer, illustrator, painting (title, artist, licence, source), typeface (and foundry if the licence asks), and the people who made it. Never the tools that built the page (no "built with" an AI tool, palate or a framework): credits are for people, images and type. If AI tools were used for imagery, say so plainly.
+- Only links people need. Social links only to accounts that post.
+- Legal line: the real company name and the real policy pages.
+
+## States and motion
+
+- Static. Links have hover (underline) and focus states.
+- "Back to top" scrolls smoothly unless reduced motion is set, and moves focus to the top of the page.
+
+## Pitfalls
+
+- Missing image credits for licensed or public-domain works.
+- "Made with ♥" and nothing else.
+- Fifteen social icons on a three-link footer.
+- Grey 11px text that fails contrast.
+
+## Floor checks
+
+- Does the footer credit the sources of its images, artwork and type (people and works, never the tools that built the page)?
+- Are the links few, readable and on a single tidy line or wrap?
+- Is there a legal line with copyright?
+- Is all text left-aligned with readable line lengths?
+- Is the footer separated from the content by a single quiet divider or surface change?
+- Is the small text still clearly readable (not faint grey)?

package/kb/sections/full-bleed-image-band.md

@@ -0,0 +1,103 @@
+---
+id: full-bleed-image-band
+name: Full-bleed image band with a caption
+kind: story
+shape: full-bleed-media
+layout: "one photograph or painting edge to edge, 70–90vh tall at 1440, no text over the subject; a caption block (one sentence + credit) pinned to a calm corner or set in a narrow strip under the image on the page ground"
+fits: [editorial, crafted, heritage, nature, travel, food, cultural, cinematic, artsy, calm, premium, hardware, sustainability, nonprofit, fashion, quiet]
+avoid: [data-dense-tool, enterprise-compliance, low-bandwidth, daily-tool]
+needs: ["one real photograph or painting of the product, its makers, its place or its subject, at least 2400px wide", "the right to use it and a credit line", "one sentence that says why this picture is here"]
+imagery: photo
+density: airy
+effort: s
+moves: [duotone-photography, canvas-grain, museum-painting-backdrop, product-in-context]
+---
+
+## When it's right
+
+The page has been words and UI for a while and needs to breathe, and the project has one picture that is true and worth seeing large: the workshop where the thing is made, the trail the gear was built for, the dish, the hardware on a real desk, a painting that is the brand's world. The band is a chapter break: it changes the ground of the page (it counts as the page's material band in `_finish.md` background planning) and resets attention before the next argument.
+
+One per page, two at most and never adjacent. Not for software with nothing physical to photograph (a screenshot blown up to full bleed is not this; use `annotated-product-shot`), and not when the only pictures available are stock (M47): then use `one-huge-number` or `editorial-essay-pull-quote` for the pause instead.
+
+## Structure
+
+```
+1440 ─ the image ignores the container; the caption aligns to the container's column 1 or column 9
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ previous section on --paper                                                              │
+╞══════════════════════════════════════════════════════════════════════════════════════════╡ ← image top edge = band edge, no rule, no gap
+│                                                                                          │
+│                     photograph, full width, 70–90vh (630–810 at 900 tall)               │
+│                     subject placed on a third, never under the caption                  │
+│                                                                                          │
+│                                                                                          │
+│                                                     ┌ caption, cols 9–12 ────────────┐  │
+│                                                     │ One sentence, lead size, paper  │  │ ← on a soft scrim, bottom-right
+│                                                     │ Photo: Name, Place, 2025        │  │   (or bottom-left: the calm corner)
+│                                                     └─────────────────────────────────┘  │
+╞══════════════════════════════════════════════════════════════════════════════════════════╡
+│ next section on --paper-2 (the ground changes after the band)                            │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+
+variant B (busy picture, no calm corner): caption under the image on the page ground
+╞══════════════════════════════════════════════════════════════════════════════════════════╡
+│                               photograph, full width                                     │
+╞══════════════════════════════════════════════════════════════════════════════════════════╡
+│ cols 1–5: the sentence, lead size                    cols 9–12: credit, caption size     │ ← 24px below the image, one line each
+```
+
+```
+390 ─ full width, no side padding on the image
+┌──────────────────────────────┐
+│ photo re-cropped 4:5         │ ← a phone source in <picture>, cropped around the subject,
+│ (≈ 390 × 488)                │   not the desktop strip shrunk to 390 × 160
+│                              │
+│                              │
+├──────────────────────────────┤
+│ sentence, 17–18px, ink       │ ← caption always moves under the image at 390, on the page ground
+│ Photo: Name, Place · 13px    │
+└──────────────────────────────┘
+```
+
+At 390 the image becomes a 4:5 (or 1:1) crop around the subject from its own `<picture>` source, full width, never taller than 560px. The caption always sits under the image on the page ground at 390 (no text on the picture at phone width), with 16px side padding.
+
+## Finish
+
+- Image: `width: 100%; height: clamp(520px, 80vh, 860px); object-fit: cover; object-position: <subject>;` with explicit `width`/`height` attributes so it reserves space. Serve AVIF/WebP at 1600, 2400 and 3200 widths via `srcset`; `loading="lazy"` (it is never in the first viewport) and `decoding="async"`.
+- Treatment: the page's one photo treatment from `_finish.md` (duotone or tone-matched). A painting gets the canvas grain (move `canvas-grain`, overlay 0.3–0.45); a photograph gets either nothing or grain at 0.03–0.05. Never both a duotone and a colour photo on one page.
+- No radius, no shadow, no border: a full-bleed band has no edges except the viewport. The section above ends at the image's top edge with no rule (M28) and no padding gap of a different colour.
+- Caption on the image: max width 4 columns (about 380px), `--s-6` from the image's bottom and side edges (aligned to the container's column, not the viewport). Sentence in `--t-lead`, weight 400, paper colour; credit in `--t-caption`, paper at 80%. Behind it, a scrim on the image, not a box: `linear-gradient(to top left, color-mix(in oklab, var(--ink) 62%, transparent), transparent 55%)` from the caption's corner. Contrast ≥ 4.5:1 at every crop (P36); test the lightest crop.
+- Caption under the image (variant B and phone): sentence in `--t-lead`, `--ink`; credit in `--t-caption`, `--ink-3`, on the same baseline at the right. `--s-5` below the image.
+- Rhythm: the band itself has no padding. The section before ends with its normal bottom padding; the section after starts with `--section`.
+
+## Content
+
+- The picture: real, specific, and of this product's world (its makers, users, place, material or subject). A painting must be public domain or licensed, with artist, title, year and collection in the credit.
+- The sentence: what we are looking at and why it matters to the reader, in under 20 words ("Every frame is welded in the same shed in Leeds it was in 1987."). Not a slogan placed over a mood photo.
+- Credit: `Photo: Name, Place, Year` or the painting's full caption. Always present.
+- No button on the band. If an action belongs here, it goes in the next section.
+
+## States and motion
+
+- Static by default. Optional: a very slow scale from 1.04 to 1 as the band scrolls through the viewport (CSS `animation-timeline: view()`, `animation-range: entry 0% exit 100%`), transform only, off under reduced motion. No parallax that makes the image lag behind the scroll.
+- Loading: a background colour sampled from the image (its average) on the `<img>` container, so the band never flashes white; optionally a 24px blurred placeholder inlined as a data URI.
+- If the image fails, the band collapses to the caption on the page ground (the container keeps the sampled colour only while loading).
+
+## Pitfalls
+
+- A stock or generated photo (M47): the band amplifies whatever is in it; a generic picture at full bleed is the most generic thing on the page.
+- Headline text over the subject's face or the detail that matters; text over a busy area with no scrim (P36).
+- The desktop strip shrunk to a 390 × 160 sliver on phone instead of re-cropped.
+- A rounded, shadowed "full-bleed" image inside the container: that is a card, not a band.
+- Two image bands back to back, or one after every section: the chapter break stops working.
+- A missing credit.
+
+## Floor checks
+
+- Does the image run edge to edge of the viewport with no rounded corners or frame?
+- Is the image a real, specific photograph or painting of this product's world rather than generic stock?
+- Is the band at least 60% of the viewport height at 1440?
+- Is the caption sentence readable against what is behind it, with the subject of the picture left uncovered?
+- Is there a visible credit line for the image?
+- Does the page ground change on at least one side of the band, with no rule or hard edge stacked against the image edge?
+- At 390, is the image re-cropped to a tall or square frame (not a thin strip) with the caption under it?

package/kb/sections/full-bleed-image-hero.md

@@ -0,0 +1,105 @@
+---
+id: full-bleed-image-hero
+name: Full-bleed photograph or painting with a type lockup
+kind: hero
+shape: full-bleed-media
+layout: "one photograph or painting edge to edge, 88–100svh tall; a compact type lockup (headline 56–96px, one line of lead, one action) set inside the picture's calm area, usually bottom-left; a small credit line in a corner"
+fits: [travel, food, nature, heritage, hardware, cultural, events, nonprofit, sustainability, cinematic, calm, editorial, consumer, local, crafted]
+avoid: [data-dense-tool, developer, enterprise-compliance, clinical, low-bandwidth]
+needs: ["one real photograph or a public-domain painting at ≥ 2400px wide that is about the product's subject", "a calm area in the picture large enough for the lockup", "a phone crop of the same picture (4:5) around the subject"]
+imagery: photo
+density: airy
+effort: m
+moves: [museum-painting-backdrop, duotone-photography, canvas-grain, product-in-context]
+---
+
+## When it's right
+
+The product's value is something you can see in the world: a place, a dish, a machine, a landscape, an event, a made object. A single strong picture carries the mood and the subject at once, and the words only have to name it. This is the hero for hotels, restaurants, hardware, outdoor brands, festivals, foundations, and for crafted brands that use a painting as their world (pairs with move `museum-painting-backdrop`).
+
+It fails when the picture is generic (stock, generated, a mood shot unrelated to the product) or when the product is software whose screen should be seen: use `split-hero-live-object`. No picture at all? Use `typographic-statement-hero`.
+
+## Structure
+
+```
+1440 ─ the picture spans the viewport; the lockup sits on the container's grid
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ nav (over the picture, on a scrim or in its calm top band) ──────────────── [Pri]       │
+│                                                                                          │
+│                    the photograph / painting, object-fit: cover,                         │
+│                    subject placed on a third (right or upper)                            │
+│                                                                                          │
+│                                                                                          │
+│                                                                                          │
+│  ┌ lockup: cols 1–6, in the picture's calm area ───┐                                     │
+│  │ H1 56–96px, 2–3 lines, paper colour             │                                     │
+│  │ lead 18–20px, one or two lines                  │                                     │
+│  │ [Primary action]  link →                        │                                     │
+│  └─────────────────────────────────────────────────┘          Photo: Name, Source  ◂ 13px│
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  height: min(100svh, 960px), min 680; lockup baseline sits --s-9 above the picture's bottom edge
+```
+
+```
+390 ─ the picture re-crops to 4:5 around the subject; lockup moves under or onto a calm band
+┌──────────────────────────────┐
+│ nav (on scrim)      ☰        │
+│                              │
+│   picture, 4:5 crop,         │  ← <picture> with a phone source, subject centred
+│   subject centred            │
+│                              │
+│ H1 40–44px, paper, on the    │  ← lockup on the picture's bottom scrim,
+│ bottom scrim                 │    or below the picture on --paper if no calm area
+│ [Primary action, full width] │
+│ Photo: Name, Source          │
+└──────────────────────────────┘
+```
+
+At 390 the picture uses its own phone crop (`<source media="(max-width: 600px)">` at 4:5, roughly 1080×1350), not the desktop picture squeezed into a strip. If the crop has a calm bottom third, the lockup stays on it over a scrim; if not, the picture becomes a 4:5 block and the lockup sits under it on `--paper`. The hero never exceeds 1.3 screens; the primary action is above 812px.
+
+## Finish
+
+- Picture: `<picture>` with AVIF/WebP, `width`/`height` set, `fetchpriority="high"`, no lazy loading (it is the LCP). `object-fit: cover; object-position` set on the subject, not `center` by default.
+- One treatment for every photograph on the page (`_finish.md` image treatment): tone-matched by default; duotone if the brand is graphic (pairs with move `duotone-photography`). Paintings get the canvas grain at 0.3–0.45 with overlay (move `canvas-grain`).
+- Scrim: only where the lockup sits, `linear-gradient(to top right, color-mix(in oklab, var(--ink) 62%, transparent), transparent 55%)`, never a flat dark wash over the whole picture. Check 4.5:1 for the lead and 3:1 for the headline at the crop's busiest point (P36).
+- H1: `--t-display` (56–96px), paper colour, weight to suit the display face, tracking −0.03em, leading 1.0, `text-wrap: balance`. Lead `--t-lead`, paper at 88%.
+- Lockup: left-aligned on grid col 1, max 6 cols wide, bottom-aligned with `--s-9` below it. Lockup items spaced `--s-5` / `--s-6`.
+- The page's primary action (`.btn-primary`), lifted off the picture: `--shadow-3` under a boxed button, a scrim or a calm area under a text action. The secondary in the language's quieter form, in paper colour.
+- Nav over the picture: transparent with a soft top scrim (`linear-gradient(to bottom, ink 40%, transparent)` 120px tall), switching to a solid `--paper` bar on scroll.
+- Credit: `--t-caption`, paper at 75%, bottom-right on the container grid, "Photo: Name, Source" or for a painting "Artist, Title, Year. Collection." (`_finish.md`).
+- The next section starts on `--paper` with no rule or card touching the picture's bottom edge (M28).
+
+## Content
+
+- Picture: of this product, place, food, object or its subject; made by the project or properly licensed (public-domain paintings from museum open-access collections are ideal). Never stock "people smiling at laptops", never generated people (M47).
+- H1: the promise in the subject's own terms ("A cabin on the fjord, one hour from Bergen"). Six to ten words.
+- Lead: the practical fact a visitor needs next (dates, location, what it is).
+- Action: the real next step ("Check dates", "See the menu", "Reserve a unit").
+- Credit is required for anything the project did not make.
+
+## States and motion
+
+- Static by default; the picture is visible on first paint (no fade-in on the LCP, M45).
+- Optional: a slow 1.04 → 1.0 scale on load over 1200ms, only if the image is already decoded; off under reduced motion.
+- Optional parallax of 8–12% on scroll for the picture only, never the text; off under reduced motion and on phone.
+- Nav swaps from transparent to solid with a 200ms background transition once the hero leaves.
+- Missing or slow image: the hero's `background-color` is the picture's dominant colour (extracted at build time), so the lockup stays legible.
+
+## Pitfalls
+
+- A flat 50% black overlay over the whole picture to make text pass: it kills the picture. Scrim only behind the lockup.
+- Lockup centred over the subject's face or the busiest part of the image (P36).
+- The desktop crop on phone: a 16:9 strip 220px tall with the subject lost.
+- Mixed treatments: one duotone hero, then tone-matched photos below.
+- No credit, or a credit at 9px and 40% opacity.
+- A carousel of hero images: pick the one picture.
+
+## Floor checks
+
+- Does the picture run edge to edge of the viewport with no container margin around it?
+- Is the picture clearly of the product's own subject rather than a generic stock scene?
+- Does the headline sit in a calm area of the picture with clearly readable contrast?
+- Is the darkening limited to the area behind the lockup, leaving most of the picture at full strength?
+- Is there exactly one primary action, legible and lifted off the picture?
+- Is there a small credit line for the picture?
+- At 390, is the picture re-cropped around its subject (not a thin wide strip) with the button visible on the first screen?

package/kb/sections/gallery-first-hero.md

@@ -0,0 +1,109 @@
+---
+id: gallery-first-hero
+name: Gallery-first hero, the work hung on the wall
+kind: hero
+shape: masonry
+layout: "the first screen is the work: 3–5 real pictures hung at their own aspect ratios across the full width like prints on a wall, ragged tops aligned to one rail; the name and one line set small in a corner; each picture captioned and linked to its project"
+fits: [portfolio, artsy, editorial, cinematic, fashion, quiet, crafted, music, agency]
+avoid: [saas, developer, b2b, data-dense-tool, enterprise-compliance, low-bandwidth]
+needs: ["3–5 of the strongest finished pictures, real work by the maker, at ≥ 2000px on the long edge", "a caption for each: project or couple, place, year", "the maker's name and one plain line of what they do and where"]
+imagery: photo
+density: airy
+effort: m
+moves: [link-preview-peek, view-transitions-between-pages]
+---
+
+## When it's right
+
+The visitor came to judge the work, and the work is visual: a documentary wedding photographer, an architect's finished buildings, a print studio's posters, an illustrator. For these people a headline is a delay. The hero hands over the pictures at once, at their real shapes, in the order the maker would hang them, and the name sits small like a label on a gallery wall. It says "look" before it says anything.
+
+It is not `full-bleed-image-hero`: that one is a single picture carrying a promise and a button. This is a selection, so the visitor sees range (a portrait, a wide room, a detail) in one screen. Not for a maker with fewer than three pictures they would stand behind, not for software, and not when the pictures need explanation before they make sense (use `case-study-band` lower down for that).
+
+## Structure
+
+```
+1440 ─ full width with --page-x side padding; pictures share one top rail
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ Mira Okafor                                    Work   Weddings   Day In   Enquire        │ ← nav: name left in text face,
+│                                                                                          │   4 links right, no button chrome
+│ ┌──────────────┐  ┌──────────────────────────────┐  ┌───────────┐  ┌──────────────┐      │
+│ │              │  │                              │  │           │  │              │      │
+│ │   4:5        │  │          3:2 (largest)       │  │   2:3     │  │   4:5        │      │ ← tops on one rail; heights differ
+│ │   portrait   │  │          the lead picture    │  │           │  │              │      │   by ratio; widths set so the row
+│ │              │  │                              │  │           │  │              │      │   fills the container
+│ │              │  └──────────────────────────────┘  │           │  └──────────────┘      │
+│ └──────────────┘  Tolu & James, Hackney, 2025       └───────────┘  Skye, 2024            │
+│ Lagos, 2024                                         Day In, Leith                        │ ← caption under each, 13px
+│                                                                                          │
+│ Documentary weddings and family photographs, London and anywhere.     22 weddings a year │ ← one line, small, bottom-left;
+│ Enquire for 2027 →                                                    booked 12–18 months│   one practical fact right
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  the row of pictures is 62–72svh tall at its tallest; total hero ≤ 100svh
+```
+
+```
+390 ─ the lead picture first, then the others in a sideways strip
+┌──────────────────────────────┐
+│ Mira Okafor            ☰     │
+│ ┌──────────────────────────┐ │
+│ │                          │ │  ← lead picture re-cropped 4:5,
+│ │   lead picture, 4:5      │ │    full container width
+│ │                          │ │
+│ └──────────────────────────┘ │
+│ Tolu & James, Hackney, 2025  │
+│ ┌──────┐ ┌──────┐ ┌───       │  ← the other 2–4 in a snap strip,
+│ │ 4:5  │ │ 2:3  │ │          │    each 62vw wide, next one peeking
+│ └──────┘ └──────┘ └───       │
+│ Documentary weddings …       │
+│ Enquire for 2027 →           │
+└──────────────────────────────┘
+```
+
+At 390 the lead picture comes first, full container width, cropped to 4:5 around its subject with its own phone source. The remaining pictures sit in a horizontal snap strip (`overflow-x: auto; scroll-snap-type: x mandatory`, items 62vw wide, the next peeking at least 24px). The line and the enquiry link sit under the strip and are visible within the first 812px.
+
+## Finish
+
+- Hanging: a flex row with `align-items: flex-start` and widths computed from each picture's ratio so the row fills the container exactly (`flex: <ratio>` per item, where ratio = width ÷ height, gives equal heights; for the deliberate ragged hang, give the lead picture 1.25× the flex of the rest). Gutter `--s-5` between pictures. No two pictures the same width.
+- Pictures: no radius or `--r-sm` at most, no border, no shadow, no card. They sit on the ground like prints pinned to a wall. One treatment for all of them (`_finish.md` image treatment; tone-matched by default, black and white only if the maker works in it).
+- Ground: `--paper` warmed a step toward the work's own palette, or a deep ink ground if the work is dark and filmic; never pure white. No gradient.
+- Name: in the nav, `--t-body` weight 600 or the display face at `--t-h3`; it is a label, not a headline. No H1 above the pictures. The visually hidden H1 is "Mira Okafor, documentary wedding and portrait photographer".
+- Captions: `--t-caption`, `--ink-2`, `--s-2` under each picture, left-aligned to the picture's edge. Project, place, year. They are the only text near the pictures.
+- The line: `--t-lead` or `--t-body`, `--ink`, max 56ch, bottom-left, `--s-7` under the tallest caption. The enquiry is the page's quietest action (a text action, with an arrow if the language has one), not a filled box; a filled box would be the loudest thing on a page that belongs to the pictures.
+- The fact on the right ("22 weddings a year, booked 12–18 months ahead") in `--t-small`, `--ink-2`, `tabular-nums`, right-aligned on the same baseline as the line.
+- Nav: four text links, `--t-small`, `--s-6` apart; current page underlined.
+
+## Content
+
+- Pictures: the maker's own strongest finished work, chosen for range: one close (a face, a hand, a detail), one wide (the room, the street, the building in its place), one that only this maker would have taken. The lead picture is the one they would put on the cover.
+- Every picture is real and published with the subjects' permission (weddings and families: written consent). No stock, no generated images, no mock-ups of work that does not exist.
+- Captions name the work the way the maker files it: "Tolu & James, Hackney Town Hall, July 2025"; "Hus Fjæra, Hitra, 2022"; "Night Bus posters for Die Kerzen, 300 copies".
+- The line says what they do and where, in plain words. No "capturing timeless moments", no "passionate storyteller".
+- One practical fact that a buyer needs (booking lead time, turnaround, where they work).
+
+## States and motion
+
+- Static. Pictures visible on first paint: the lead picture is the LCP (`fetchpriority="high"`, no lazy loading, no fade-in, M45); the others load eagerly with their dominant colour as background so the hang never jumps.
+- Hover (desktop): the hovered picture stays, the others dim to 70% over 200ms; its caption underlines. Each picture links to its project; with move `view-transitions-between-pages` the picture morphs into the project page's lead image.
+- Focus: a 2px focus ring offset 3px around the picture, following its edges.
+- Reduced motion: no dimming transition, no morph; links still work.
+- One picture fails to load: its box keeps its ratio and dominant colour, and the caption stays.
+
+## Pitfalls
+
+- A big headline ("Capturing love stories") on top of or before the pictures: the words compete with the work.
+- Every picture cropped to the same square or 16:9, which erases the range the hero exists to show.
+- A slideshow or auto-advancing carousel: the visitor sees one picture at a time and waits.
+- Pictures in cards with shadows and rounded corners, or with hover zoom: they read as product tiles, not prints.
+- A filled "Book now" button as loud as the work.
+- App chrome near the work: tag pills ("Wedding", "Portrait"), counters, like hearts.
+- At 390, five pictures stacked full width, so the visitor scrolls three screens before the name.
+
+## Floor checks
+
+- Is the first thing on the screen the work itself (several real pictures), with no large headline above or over it?
+- Do the pictures keep different aspect ratios, hung along one shared top edge rather than cropped to one shape?
+- Is the maker's name present but small, reading as a label rather than a headline?
+- Does each picture carry a short caption (project or subject, place, year)?
+- Are the pictures free of card frames, shadows, tag pills and other app-style chrome?
+- Is the enquiry or next step a quiet text link rather than a loud filled button competing with the work?
+- At 390, does the lead picture appear first at full width, with the remaining pictures in a sideways strip and no sideways scrolling of the page itself?