@palate/cli 0.0.0-stage → 0.0.1

package/kb/sections/annotated-product-shot.md

@@ -0,0 +1,105 @@
+---
+id: annotated-product-shot
+name: Annotated product view with leader lines
+kind: demo
+shape: object-first
+layout: "one large code-built product view centred on cols 2–11, with 3–5 short notes in the side margins joined to real parts of the UI by 1px leader lines that end in a dot; a small heading above"
+fits: [saas, developer, technical, productivity, hardware, crafted, honest, b2b, data-rich, scientific]
+avoid: [luxury, fashion, playful-kids, crisis, food, portfolio]
+needs: ["one product screen dense enough to have 3–5 parts worth naming", "a one-line note per part saying what it does for the user", "real labels and data for the screen"]
+imagery: product-ui
+density: balanced
+effort: m
+moves: [technical-drawing-lines, hand-drawn-annotations, screenshot-detail-crops, code-drawn-diagram]
+---
+
+## When it's right
+
+The product has one screen where several small, considered details do the work (a status bar that tells you what changed, a shortcut hint, a diff view, an undo trail), and they get lost in a feature grid. Show the screen large, once, and point at the details the way an engineering drawing points at parts: a hairline from the note to the exact pixel, ending in a small dot. The visitor reads the product and the reasons together.
+
+Good as the second demo on a long page, or the only demo for products whose behaviour is a state rather than a flow. It is a calmer partner to `self-playing-run-demo` and a sharper replacement for `asymmetric-bento-dominant` when the features all live on one screen.
+
+Not for screens with nothing worth naming, or more than five notes (it becomes a diagram to study, not a section to read).
+
+## Structure
+
+```
+1440 ─ container 1240; product view cols 2–11 (~1000px), notes in the outer margins
+┌──────────────────────────────────────────────────────────────────────────────────────┐
+│ H2 h2, one line, left on col 1                                                       │
+│                                                                                      │
+│ note A ───────────────●                                                              │
+│ 2 lines, small   ┌ product frame, radius 20, shadow-2 ─────────────────┐             │
+│                  │ chrome (skeleton)                    ●────────────── note B        │
+│                  │ ┌ list ─────┐ ┌ main pane ──────────────────────┐ │   2 lines     │
+│                  │ │           │ │                                  │ │               │
+│ note C ──────────────●         │ │      real content              ●──────────── note D │
+│ 2 lines          │ │           │ │                                  │ │   2 lines     │
+│                  │ └───────────┘ └──────────────────────────────────┘ │               │
+│                  │ status bar ●                                        │               │
+│                  └─────────────│───────────────────────────────────────┘               │
+│                                └──────── note E, under the frame, 1 line             │
+└──────────────────────────────────────────────────────────────────────────────────────┘
+  notes are 160–200px wide; leader lines are horizontal or one 90° bend, never diagonal spaghetti
+```
+
+```
+390 ─ side padding 16
+┌──────────────────────────────┐
+│ H2                           │
+│ ┌ frame, cropped to the    ┐ │  ← crop to the densest region, 4:5, text ≥ 12px
+│ │ annotated region; 1 2 3  │ │    numbered markers (20px circles) on the parts
+│ │ markers on the parts     │ │
+│ └──────────────────────────┘ │
+│ ① note A                     │  ← notes become a ruled list with matching
+│ ─────────────────────────    │    numbered markers
+│ ② note B                     │
+│ ─────────────────────────    │
+│ ③ note C …                   │
+└──────────────────────────────┘
+```
+
+At 390 the leader lines go away: the view crops to the region that holds the annotated parts (an `object-position`-style crop of the code-built view, never shrunk below 12px text), the dots become numbered 20px markers, and the notes become a ruled list under the view with the same numbers. If the parts are too far apart for one crop, use two crops (move `screenshot-detail-crops`).
+
+## Finish
+
+- Product view: the product frame from `_finish.md` (`--r-lg`, `--shadow-2`), built in HTML from real data; text inside readable at 100%.
+- Leader lines: one absolutely positioned SVG over the whole figure (`pointer-events: none`), 1px strokes in `--ink` at 55% (or `--hairline-strong` on dark), `vector-effect: non-scaling-stroke`, horizontal runs with at most one right-angle bend, ending in a 5px filled dot sitting on the part plus a 2px `--paper` halo so it reads on any UI colour. Anchor points are computed from the parts' bounding boxes (`getBoundingClientRect` relative to the figure, recomputed on resize via ResizeObserver) so lines land at every width; the server renders them for the default 1440 layout.
+- Notes: `--t-small`, `--ink`, first phrase in weight 600 then the rest in `--ink-2`; 2 lines max, 160–200px wide, aligned to the leader's y. Left notes right-aligned toward the figure, right notes left-aligned.
+- Numbered markers on phone (and optionally on desktop): 20px circles, `--ink` fill, `--paper` numeral in tabular figures, 11px weight 600. Numbering is honest here: it maps markers to notes.
+- Ground: `--paper` or `--paper-2`; the paper-fibre texture from `_finish.md` is allowed on the band behind the frame for a drawing-office feel (move `technical-drawing-lines`), never on the frame.
+- Heading to figure `--s-7`; the notes stay inside the container (no note crosses the viewport edge at 1280+).
+
+## Content
+
+- 3–5 notes, each about one visible part. Lead with what it does for the user, not the component name ("Every change is undoable: the trail keeps the last 200 steps", not "History panel").
+- Pick parts that are distinctive to this product, not generic chrome (search bar, avatar).
+- Screen content from the project's real vocabulary and plausible data.
+- H2 names the screen's job ("Everything a reviewer needs, on one screen").
+
+## States and motion
+
+- Static by default; the figure works as a still.
+- One optional moment: on first view, the leader lines draw in (stroke-dashoffset, 500ms ease-out, staggered 80ms) and the dots pop (scale .6 → 1). Below the fold only; reduced motion shows them drawn.
+- Hovering or focusing a note highlights its part with a 2px `--brand` outline (radius nested from its container) and dims the others to 70%; the notes are buttons or have `tabindex="0"` for this.
+- Accessibility: the figure is `role="img"` with an `aria-label` summarising the screen; the notes are real text in reading order (left notes, right notes, bottom note) or a hidden list mirroring them.
+
+## Pitfalls
+
+- Leader lines that miss their part by a few pixels at some width: recompute anchors on resize, test at 1280, 1440 and 1920 (P01 spirit).
+- Diagonal lines crossing each other or crossing the UI's text.
+- Notes that restate the label on the part ("Sidebar: the sidebar").
+- A screenshot `<img>` with arrows drawn on it: blurry, and the lines cannot track the parts (L01).
+- Shrinking the view at 390 until the annotated parts are unreadable.
+- More than five notes.
+
+## Floor checks
+
+- Is the product view the dominant object, at least 60% of the container width at 1440?
+- Does every note connect to a specific visible part of the UI with a line or a matching marker?
+- Are there between three and five notes, each two lines or shorter?
+- Do the leader lines avoid crossing each other and the UI's text?
+- Is the UI inside the frame readable at 100% zoom?
+- If the frame is cropped by an edge, is the cut part secondary UI rather than a part a note points at?
+- At 390, are the notes shown as a list with markers that match markers on a cropped, readable view?
+- Is the product shown without fake browser chrome?

package/kb/sections/asymmetric-bento-dominant.md

@@ -0,0 +1,114 @@
+---
+id: asymmetric-bento-dominant
+name: Asymmetric bento with one dominant tile
+kind: features
+shape: bento
+layout: "one lead tile about 2/3 wide and two rows tall, plus 3–4 supporting tiles that contrast with their neighbours, one of them inverted; every tile is a product fragment or a real figure, not an icon card"
+fits: [saas, developer, ai, productivity, technical, crafted, data-rich, launch]
+avoid: [luxury, heritage, serious-news, crisis, clinical, food, portfolio]
+needs: ["one feature that matters most and can be shown working", "3–4 smaller features, each with a fragment of product UI or a real figure"]
+imagery: product-ui
+density: dense
+effort: m
+moves: [bento-live-tiles, inline-sparklines-in-copy, screenshot-detail-crops]
+---
+
+## When it's right
+
+The product has one headline capability and a handful of supporting ones that are real but smaller. The grid states the hierarchy at a glance: the lead tile is the reason to buy, the small tiles are the reasons it holds up. This is the honest version of the bento: unequal on purpose, every tile showing a piece of the product (a log line, a filter, a chart, a settings row), never an icon in a tinted square over a sentence (M04).
+
+Not when all features are equal (use `ruled-list-pinned-visual`), when there is nothing to show in the small tiles (use `spec-sheet-features`), or directly after a hero that is also a dense grid of UI. Pairs with move `bento-live-tiles`.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gutter 16 inside the grid (tighter than the page gutter)
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ H2 cols 1–6                                   lead cols 8–12, aligned to H2   │
+│                                                 baseline, ink-2               │
+│                                                          --s-7                │
+│ ┌ lead tile: cols 1–8, rows 1–2 (≈ 640 tall) ────────┐ ┌ tile B: cols 9–12 ─┐ │
+│ │ title + one line, top-left, inside the tile          │ │ title + line       │ │
+│ │                                                      │ │ fragment: a toggle │ │  B: 312 tall
+│ │ the main capability working: a large product         │ │ and its effect     │ │
+│ │ fragment, bleeding off the tile's right and bottom   │ └────────────────────┘ │
+│ │ edges (clipped by the tile radius); only its         │ ┌ tile C: cols 9–12 ─┐ │
+│ │ secondary rows are cut, never the title              │ │ INVERTED: a real   │ │  C: 312 tall, the
+│ │                                                      │ │ figure close under │ │  grid's one tile on
+│ │                                                      │ │ its line           │ │  the inverse ground
+│ └──────────────────────────────────────────────────────┘ └────────────────────┘ │
+│ ┌ tile D: cols 1–5 (≈ 260) ────────┐ ┌ tile E: cols 6–12 (≈ 260) ─────────────┐ │
+│ │ a log line or command, live       │ │ a list row with its states             │ │
+│ └───────────────────────────────────┘ └────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────────┘
+  3 or 4 supporting tiles; B and C share a size, so they differ in surface and content (a fragment
+  beside a figure, light beside inverted); no two neighbours alike
+```
+390 ─ one column, side padding 16, gap 12
+┌──────────────────────────────┐
+│ H2                           │
+│ lead                         │
+│ ┌ lead (≈ 440) ────────────┐ │  ← first, fragment cropped to its working part
+│ └──────────────────────────┘ │
+│ ┌ B ─────────┐┌ C ─────────┐ │  ← two small tiles may pair at 2 cols if each is
+│ └────────────┘└────────────┘ │    readable at 175px wide; otherwise stack
+│ ┌ D ───────────────────────┐ │
+│ └──────────────────────────┘ │
+│ ┌ E ───────────────────────┐ │
+│ └──────────────────────────┘ │
+└──────────────────────────────┘
+```
+
+At 390 the lead tile comes first at about 440px tall, its fragment cropped (not shrunk) so text stays at 12px or more. Supporting tiles stack full width at 200–280px each, in order of importance; two tiny tiles may sit side by side only if their content still reads. The whole grid is never taller than about 2.5 phone screens: cut a tile before shrinking them all.
+
+## Finish
+
+- Grid gap 16 (`--s-4`); the page gutter stays 24. Tiles are the raised surface from `_finish.md`: `--surface` on a `--paper-2` ground, `--shadow-1`, radius `--r-lg`. The lead tile alone gets `--shadow-2`.
+- One lead tile. It spans two columns or two rows (here both) and carries the section's point; the others support it. If every tile is the same size, it is not this archetype.
+- Neighbours contrast. Two tiles that touch differ in at least one of size, surface or content type: a fragment beside a figure, a picture beside text, a light tile beside the inverted one. Never two identical boxes side by side (the floor's BENTO_TWINS).
+- One inverted tile: exactly one tile on the inverse ground (`--ink` ground with `--paper` text on a light page; the light surface on a dark page). It is the accent, so put it on the supporting point that matters most. Two or more make a checkerboard (INVERT_OVERUSE).
+- Tile padding `--s-5` (24); title and line sit top-left inside the tile, the fragment below and allowed to bleed off the tile's right or bottom edge, clipped by `overflow: clip`. Only filler bleeds: the fragment's extra rows, a sidebar's end, a chart's older weeks. Never cut real words, a title or a number: keep text inside the padding and let the fragment do the bleeding (WORDS_CUT fails a heading, paragraph or number cut by an edge). Nested radii: tile 20, padding 24 → the fragment's own frame 4–6.
+- A figure sits close under its line (`--s-3` to `--s-4`), never pinned to the tile's bottom with a void above it (`margin-top: auto` is the usual cause; TILE_VOID measures it). If the tile is taller than its words and figure, give the space to a picture or fragment pinned to the bottom edge.
+- Titles: `--t-body` weight 600, ink; one line beneath in `--t-small`, `--ink-2`. The lead tile's title steps up to h3. Same lead-in slot in every tile so titles start at one height in a row (P04).
+- No icon chips, no gradient borders, no Border Beam or spotlight effects (M12). Besides the inverted tile, one tile may carry a texture or tinted ground (4% toward the brand); only one.
+- Figures inside tiles: tabular figures in the body face, with a footnote marker if they are measured (`_finish.md` numbers).
+
+## Content
+
+- Heading: the promise the lead tile proves. Lead: one sentence on how the smaller pieces support it.
+- Lead tile: the main capability caught in its most useful moment, with real data from the project.
+- Supporting tiles: one feature each, named plainly ("Keyboard first", "Runs offline", "Audit log"), with the smallest fragment that proves it: the shortcut overlay, the offline badge on a synced row, three log lines.
+- A tile with a number shows a real, sourced figure (pairs with move `inline-sparklines-in-copy`), never "10x".
+- Five tiles maximum. If you have eight features, use `spec-sheet-features` for the rest.
+
+## States and motion
+
+- Server render: every tile in its informative state.
+- At most one motion per tile. The lead tile may run a short loop (4–8s) of its moment; supporting tiles respond on hover or focus with a single micro-change (a toggle flips, a row highlights), 160–240ms. Never more than one tile moving on its own; entrances, if any, are staggered (60–90ms apart), not all at once.
+- Hover on a tile does not lift or scale the whole tile (it is not a link); if a tile links to docs, the link is a text link inside it.
+- Reduced motion: every loop and entrance is off; each tile shows its finished frame. Long titles wrap to two lines and every tile in that row reserves two lines.
+
+## Pitfalls
+
+- Equal tiles with icons and two-word titles: the stock three-card row in a grid costume (M04, M21).
+- Two identical tiles side by side, or every other tile inverted: the grid reads as a pattern, not a hierarchy.
+- A heading or figure cut by the tile edge because the fragment pushed it out: crop the fragment, never the words.
+- A figure pinned to the bottom of its tile under an empty band.
+- A lead tile that leads only in size, with a sparse or decorative fragment inside.
+- Every tile animating at once: nothing is the focal point (P08).
+- Tiny unreadable UI in the small tiles (P40); crop tighter instead.
+- Glass tiles on a gradient, beams on borders (M08, M12).
+- Cards inside cards inside the tile (M23).
+
+## Floor checks
+
+- Is there one lead tile, spanning two columns or two rows and at least twice the area of any other tile, that carries the section's main point?
+- Does every tile show a piece of the product or a real figure rather than an icon and a sentence?
+- Do neighbouring tiles differ in size, surface or kind of content, so no two identical tiles sit side by side?
+- Is exactly one tile on the inverse ground (dark on a light page, light on a dark page), rather than none or several?
+- Does each figure sit close under its line, with no empty band above a figure pinned to the tile's bottom?
+- Are all titles, sentences and numbers whole, with only product fragments or pictures cropped by a tile's edge?
+- Is the text inside the tiles readable at 100% zoom?
+- Do the titles in tiles that share a row start at the same height?
+- Does each tile have at most one motion, is at most one tile moving on its own, and is everything still under reduced motion?
+- At 390, does the lead tile come first and stay readable without shrinking its text?

package/kb/sections/before-after-features.md

@@ -0,0 +1,104 @@
+---
+id: before-after-features
+name: Before and after on one stage
+kind: features
+shape: object-first
+layout: "a wide stage (10–12/12) showing the same input before and after the product, split by a draggable divider or a two-state toggle; 2–3 named differences called out on the stage; heading small above"
+fits: [ai, developer, productivity, technical, honest, saas, crafted, data-rich]
+avoid: [luxury, fashion, heritage, crisis, nonprofit, food, portfolio]
+needs: ["one real input and the product's real output for it", "2–3 differences that a reader can point at"]
+imagery: product-ui
+density: balanced
+effort: m
+moves: [before-after-slider, hand-drawn-annotations, explorable-control]
+---
+
+## When it's right
+
+The product transforms something: messy into clean, slow into fast, a draft into a finished piece, a noisy image into a sharp one, a failing build into a passing one. The most convincing thing you can show is the same input on both sides of the change. One wide stage holds both states; the reader drags a divider (or flips a toggle) to compare, and two or three labelled call-outs point at exactly what changed. The stage is the section; the heading is a caption above it.
+
+Honest by construction: the same input, the product's real output, no retouching of the "after". Not for products that create something new from nothing (there is no "before"), or when the difference is invisible at a glance (use `explorable-control-demo` to show a relationship instead). Pairs with move `before-after-slider`.
+
+## Structure
+
+```
+1440 ─ container 1240; stage cols 1–12 (or 2–11 for type-heavy content)
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ H2 cols 1–7, h2 size                      [ Before | After ] toggle cols 10–12│  ← toggle only if no divider
+│ one line lead, ink-2                                                          │
+│                                                         --s-6                 │
+│ ┌ stage: product frame, 16:9 or 16:10, 1240 × 700 ────────────────────────┐   │
+│ │ BEFORE                     ┃  AFTER                                       │   │  ← "Before"/"After" labels
+│ │                            ┃                                              │   │    pinned top corners
+│ │ the raw input as it is     ◀┃▶ the same input after the product           │   │  ← divider: 2px line + a 40px
+│ │                            ┃                       ①──── call-out:        │   │    round handle, at 50%
+│ │                            ┃                            "Imports sorted"  │   │
+│ │                            ┃        ②─── "Dead code removed"              │   │
+│ │                            ┃                                              │   │
+│ └────────────────────────────┸──────────────────────────────────────────────┘   │
+│ ① ② ③ legend line under the stage (optional): small, names each difference     │
+│ input source line: caption, ink-3 ("Input: the project's own README, unedited")│
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ side padding 16
+┌──────────────────────────────┐
+│ H2                           │
+│ lead                         │
+│ [ Before | After ] toggle    │  ← divider replaced by a toggle on phone
+│ ┌ stage 4:5, full width ───┐ │    (dragging fights page scroll)
+│ │ cropped to the region    │ │
+│ │ where the change is      │ │
+│ │ ① call-out               │ │
+│ └──────────────────────────┘ │
+│ ① ② list of differences      │
+│ caption                      │
+└──────────────────────────────┘
+```
+
+At 390 the divider becomes a two-option toggle above the stage, because horizontal dragging fights vertical scroll. The stage re-crops to 4:5 around the region where the change is, keeping content at real size (12px text minimum), and the call-outs move into a numbered list under it if they would cover the content.
+
+## Finish
+
+- Stage: the product frame from `_finish.md` at `--r-lg`, `--shadow-2`, as wide as the container (or bleeding to the viewport on a full-bleed band). This is the biggest object in the section by far.
+- Labels "Before" and "After": `--t-small`, weight 600, on small solid chips (`--surface`, `--r-sm`, `--shadow-1`) pinned `--s-4` from the stage's top corners. Not uppercase mono (M18).
+- Divider: 2px line in `--surface` with a 1px `--hairline-strong` edge on each side; handle 40px round, secondary button style, with a left/right chevron pair. Start at 50% or at the position that best shows the first difference.
+- Call-outs: a 1px ink leader line ending in a 6px dot on the exact thing, with a label in `--t-small` on a `--surface` chip. Two or three only. Hand-drawn style if the brand is warm (move `hand-drawn-annotations`). The "before" side gets no call-outs; the point is what changed.
+- Heading block is small: h2 at `--t-h2`, lead one line. The stage is the headline here.
+- Source caption: `--t-caption`, `--ink-3`, says where the input came from and that the output is unedited.
+
+## Content
+
+- Heading: the change in words ("Your logs, readable"). Lead: what the product did, in one sentence.
+- Before: a real, typical input from the project's domain, not a strawman made deliberately bad.
+- After: the product's actual output for that input. If it was edited, say so or don't use it.
+- Call-outs: 2–3 differences named as outcomes ("Errors grouped by cause", "PII masked"), each pointing at the place it is visible.
+- No invented timing or percentage claims on the stage.
+
+## States and motion
+
+- The divider is a real control: `<input type="range">` styled as the handle, labelled "Compare before and after", arrow keys move it in 5% steps, Home/End jump to the ends. Pointer drag on the whole stage, `touch-action: pan-y` so vertical scroll still works.
+- Call-outs appear only when their region is on the "after" side of the divider (fade 150ms).
+- One hint on first view: the handle nudges 24px left and back (600ms) once, then never again; nothing under reduced motion.
+- No JS: the stage shows a static 50/50 split (or after-only with the before as a small inset), call-outs visible.
+- Toggle variant: crossfade 200ms between states, `aria-pressed` on the options.
+
+## Pitfalls
+
+- Different inputs on each side, or a "before" made worse than reality: visitors notice, and it reads as a lie.
+- A stage too small to see the difference; it should be the largest object in the section.
+- Call-outs covering the very content they describe.
+- A divider that only works with a mouse drag (no keyboard, no touch).
+- A drag-to-compare on phone that hijacks vertical scroll.
+- Five or more call-outs: the stage becomes a diagram of labels.
+
+## Floor checks
+
+- Does the comparison stage span at least 80% of the container width at 1440?
+- Do both sides visibly show the same input, so the only difference is the product's effect?
+- Are the "Before" and "After" sides clearly labelled?
+- Are there 2–3 call-outs pointing at specific visible differences?
+- Is there a visible handle or toggle that says the stage can be compared?
+- Is the text inside the stage readable at 100% zoom?
+- At 390, is the comparison operated by a toggle or keeps vertical scrolling usable, with the stage cropped to where the change is?

package/kb/sections/before-after-repair.md

@@ -0,0 +1,107 @@
+---
+id: before-after-repair
+name: Before and after of a real repair
+kind: comparison
+shape: split
+layout: "1–3 pairs of photographs of the same object before and after a repair or restoration, same framing and light, side by side (or one frame with a drag divider); under each pair a caption with what was done, how long it took, the price and who did it"
+fits: [local, crafted, sustainability, honest, tactile, heritage, hardware]
+avoid: [saas, developer, b2b, data-dense-tool]
+needs: ["1–3 real repairs photographed before and after from the same position and in the same light", "for each: what was done, how long it took, the price, and the maker's name", "the owner's permission to show their object"]
+imagery: photo
+density: balanced
+effort: m
+moves: [before-after-slider]
+---
+
+## When it's right
+
+The business fixes, mends or restores things, and the best proof of its skill is the object itself: a pair of jeans with a hole in the knee turned into a sashiko patch (Patch & Mend), a drivetrain caked in grime made silent again (Torque Cycles), a chair reupholstered, a print restored, a coat relined, a watch serviced. Two photographs of the same thing, before and after, say more than any paragraph about care.
+
+The median page shows features with icons (“Expert repairs”, “Fast turnaround”) or a SaaS-style before/after with UI screenshots. This archetype shows the real object twice, honestly photographed, with the facts of the job under it like a workshop's job tag.
+
+Not for software (use `before-after-features` or `comparison-same-task-two-ways`), not for makeovers where the “after” is a new object, and not when the photos don't match in framing and light: a mismatched pair looks faked.
+
+## Structure
+
+```
+1440 ─ container 1240; one lead pair large, up to two more smaller below (or one pair only)
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ H2 "The hole in the knee"                                   one-line lead, ink-2, right  │
+│                                                                                          │
+│ ┌ before, 4:5 ─────────────────────┐  ┌ after, 4:5 ──────────────────────┐               │
+│ │                                  │  │                                  │               │
+│ │  the jeans, torn knee,           │  │  same jeans, same angle,         │               │
+│ │  flat light, on the bench        │  │  sashiko patch in indigo         │               │
+│ │                                  │  │                                  │               │
+│ │ Before                    ◂ 13px │  │ After                     ◂ 13px │               │ ← small label in a corner
+│ └──────────────────────────────────┘  └──────────────────────────────────┘               │
+│ Levi's 501s, 9 years old. Sashiko patch in indigo and white thread, 2½ hours, £18.       │ ← job caption: what,
+│ Mended by Amina Siddiq.                                                                  │   time, price, who
+│ ──────────────────────────────────────────────────────────────────────────────────────── │
+│ ┌ before ─────┐┌ after ──────┐   ┌ before ─────┐┌ after ──────┐                          │ ← two smaller pairs,
+│ │ coat lining │└─────────────┘   │ zip         │└─────────────┘                          │   3:4, same anatomy
+│ └─────────────┘                  └─────────────┘                                          │
+│ Wool coat relined, £75, Ross Kerr  Jacket zip replaced, £22, Amina Siddiq                │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  lead pair cols 1–10 (each photo 5 cols), smaller pairs 6 cols each; gap between the photos of a pair --s-2
+```
+
+```
+390 ─ side padding 16; one pair per screen
+┌──────────────────────────────┐
+│ H2                           │
+│ ┌ one frame, 4:5 ──────────┐ │
+│ │ before │ after           │ │ ← drag divider (before-after-
+│ │        ◀▶                │ │   slider), or before above after
+│ └──────────────────────────┘ │
+│ Levi's 501s … £18.           │
+│ Mended by Amina Siddiq.      │
+│ ──────────────────────────── │
+│ next pair, same anatomy      │
+└──────────────────────────────┘
+```
+
+At 390 each pair becomes either one 4:5 frame with a drag divider (move `before-after-slider`, starting at 50%, with a 44px handle) or the before stacked directly above the after with an 8px gap. The caption follows each pair. Two pairs at most on phone.
+
+## Finish
+
+- Photographs: same camera position, same light, same crop for both halves of a pair; set `width`/`height`; one image treatment across the page (`_finish.md` image treatment, tone-matched by default). Shot on the workshop bench or a plain surface the business really uses, not a seamless studio white unless that's their way.
+- Pair spacing: `--s-2` between the two photos so they read as one object; `--s-7` between pairs. Radius `--r-md` on each photo (or the outer corners only, so the pair reads as one frame). No cards, no borders, no shadows.
+- Labels: “Before” and “After” in `--t-caption`, weight 600, on a small paper-coloured tab in the photo's bottom-left corner (`--paper` at 90%, `--r-sm`, padding 4px 8px), not a coloured pill.
+- Caption: `--t-body` for what was done, `tabular-nums` for time and price, maker's name in weight 500; `--t-small` `--ink-2` for any second line. Max 62ch. It reads like a job tag, not marketing copy.
+- Slider (if used): a 2px `--paper` divider line with a 44px round handle in `--paper` with `--shadow-2`, arrows inside; keyboard operable (arrow keys move 5%); starts at 50%.
+- Heading row: H2 left, a one-line lead right on the same baseline (“Every repair is guaranteed for a year.”).
+- Ground: `--paper`; if the previous section is a photograph band, use `--paper-2` here.
+
+## Content
+
+- Real jobs from the shop, with the owner's permission. Name the object specifically (“Levi's 501s, 9 years old”, “Brompton, 2014, rear hub”).
+- The facts: what was done, how long it took, what it cost, who did it. Real prices from the price list.
+- One to three pairs; choose range (a small fix, a big one) over three of the same.
+- No retouching beyond tone-matching both photos. If the after photo is in better light, reshoot the before.
+
+## States and motion
+
+- Static by default; the pair is fully visible in screenshots and with no JS.
+- Slider: drag, click or arrow keys; `role="slider"` with `aria-valuenow` and a label (“Reveal before and after”); under reduced motion it still works but doesn't animate a hint. Optional: a single 600ms nudge from 50% to 40% and back when it first enters view; off under reduced motion.
+- Images lazy-load below the fold with their average colour as a placeholder.
+- Each photo has alt text describing the object and its state (“Jeans with a 6 cm tear across the left knee”).
+
+## Pitfalls
+
+- Before and after from different angles, distances or light: it looks staged, and it is.
+- Stock photos of “a repair”.
+- An after photo heavily retouched or graded while the before is left flat.
+- Before/after labels as coloured status pills, or a SaaS comparison card with ticks and crosses.
+- Six pairs in a carousel: one strong pair beats six weak ones.
+- No price or time, so the visitor still doesn't know what to expect.
+
+## Floor checks
+
+- Does each pair show the same object from the same position and in the same light?
+- Are the photos clearly real objects from this business rather than stock?
+- Does each pair have a caption saying what was done, how long it took or what it cost, and who did it?
+- Are the before and after labels small and quiet rather than coloured pills or badges?
+- Is the section free of cards, ticks-and-crosses comparison tables and app-style UI?
+- Are there three pairs or fewer, with one clearly leading?
+- At 390, is each pair readable (a slider frame or before above after) with nothing scrolling sideways?

package/kb/sections/bento-lead-tile.md

@@ -0,0 +1,112 @@
+---
+id: bento-lead-tile
+name: Bento with one lead tile and mixed material
+kind: features
+shape: bento
+layout: "a lead tile spanning two columns and two rows that carries the main point, plus 3–5 supporting tiles that each differ from their neighbours in size, surface or material (a photo, a figure, a quote, a short fact); exactly one tile inverted"
+fits: [crafted, warm, friendly, local, food, consumer, community, nonprofit, sustainability, hardware, travel, education, launch]
+avoid: [serious-news, crisis, government, enterprise-compliance, data-dense-tool, luxury]
+needs: ["one main reason a photo or a real figure can show on its own", "3–5 smaller reasons, each with its own material: a photo, a measured figure, a short quote, a plain fact"]
+imagery: any
+density: balanced
+effort: m
+moves: [real-world-data, duotone-photography, product-in-context]
+---
+
+## When it's right
+
+The section gives several reasons at once and one of them matters most: why this bakery, why this repair shop, why this kit. A bento says that in one look when it is built as a hierarchy. One lead tile states the main reason and shows it (a photo of the oven at 5am, the figure that proves it). The other tiles back it up, and each is made of something different: a photo next to a number, a quote next to a short fact. The grid feels composed because no two neighbours are alike and one tile, only one, is inverted.
+
+Not when the reasons are equal and short (use `ruled-list-pinned-visual` or `spec-sheet-features`), when every reason is a product fragment (use `asymmetric-bento-dominant`), or when there are no real photos or figures to fill the tiles: a bento of icons and sentences is the stock card grid.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gap 16 inside the grid
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ H2 cols 1–7, the main reason in a sentence                                   │
+│ lead cols 1–6, ink-2                                     --s-7               │
+│ ┌ LEAD: cols 1–7, rows 1–2 (≈ 600) ─────────────┐ ┌ B: cols 8–12 (≈ 292) ──┐ │
+│ │ photo fills the tile, cropped by its edges      │ │ a real figure, large   │ │  B: stat on --surface
+│ │                                                 │ │ its line close under   │ │
+│ │                                                 │ │ it, then a source      │ │
+│ │                                                 │ └────────────────────────┘ │
+│ │ ┌ caption plate, bottom-left ───────────┐      │ ┌ C: cols 8–12 (≈ 292) ──┐ │
+│ │ │ h3 the main reason + one line          │      │ │ INVERTED: a short      │ │  C: the grid's one
+│ │ └────────────────────────────────────────┘      │ │ quote and who said it  │ │  inverse tile
+│ └─────────────────────────────────────────────────┘ └────────────────────────┘ │
+│ ┌ D: cols 1–4 (≈ 240) ──────┐ ┌ E: cols 5–12 (≈ 240) ─────────────────────────┐ │
+│ │ a plain fact: title +     │ │ a photo on the left half, title + line on the │ │
+│ │ two lines, on --paper-2   │ │ right half                                    │ │
+│ └───────────────────────────┘ └───────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────────┘
+  every pair of touching tiles differs in size, surface or material; one inverted tile
+```
+
+```
+390 ─ one column, side padding 16, gap 12
+┌──────────────────────────────┐
+│ H2                           │
+│ lead                         │
+│ ┌ LEAD (≈ 420) ────────────┐ │  ← first; photo re-cropped to 4:5 around its subject
+│ │ caption plate            │ │
+│ └──────────────────────────┘ │
+│ ┌ B figure ─┐┌ C quote ────┐ │  ← two short tiles may pair if both read at 175px;
+│ └───────────┘└─────────────┘ │    otherwise stack
+│ ┌ D fact ──────────────────┐ │
+│ └──────────────────────────┘ │
+│ ┌ E photo + line ──────────┐ │
+│ └──────────────────────────┘ │
+└──────────────────────────────┘
+```
+
+At 390 the lead tile comes first at about 420px tall, its photo re-cropped around the subject (a `<picture>` source per width), never squeezed into a thin strip. The other tiles follow in order of importance. The inverted tile keeps its ground on phone, so the accent survives. The whole grid stays under about 2.5 phone screens; drop the weakest tile before shrinking them all.
+
+## Finish
+
+- One lead tile: two columns wide and two rows tall, at least twice the area of any other tile. It holds the main reason and the section's strongest material. Everything else is smaller.
+- Neighbours contrast. Any two tiles that touch differ in at least one of size, surface or material: picture beside figure, light beside inverted, a wide tile beside a narrow one. If two must share a size, give them different grounds and different content. The floor warns on identical neighbours (BENTO_TWINS) and on a grid of equal boxes (BENTO_FLAT).
+- One inverted tile: exactly one tile on the inverse ground (`--ink` ground and `--paper` text on a light page, the light surface on a dark page). Put it on the supporting reason that matters most, usually the quote or the figure. Never alternate light and dark (INVERT_OVERUSE).
+- Surfaces: tiles on `--surface` with `--shadow-1` or on `--paper-2` flat, one radius (`--r-lg`), grid gap `--s-4`. Picture tiles have no padding; the photo fills the tile and the tile's radius crops it (`overflow: clip`).
+- Words on a photo sit on a caption plate (`--surface` at 92%, radius `--r-md`, padding `--s-4`) pinned to one corner, or below the photo, never straight on a busy area of it.
+- Only filler is cropped: a photo, a pattern, a UI fragment may run off the tile's edge. A heading, a sentence or a number never does (WORDS_CUT). Keep text inside the tile's padding with room for its longest translation.
+- A figure sits close under its line (`--s-3`), its source in `--t-caption` under that. Never pin the figure to the tile's bottom with a gap above it (TILE_VOID).
+- Type: tile titles `--t-h3` in the lead, `--t-body` weight 600 elsewhere; one line of `--t-small` in `--ink-2` under each. Figures in the display face at `--t-h2` or larger, tabular.
+- No icon chips, no gradient borders, no glow behind tiles (M04, M12, M20).
+
+## Content
+
+- Heading: the main reason in plain words ("Bread baked at 5am, sold by 11"). The lead tile proves it.
+- Lead tile: the strongest real photo or figure the project has, with one sentence that names what it shows.
+- Supporting tiles: one reason each, each in its own material. A measured figure with its source. A short quote with a real name. A plain fact ("Open Sundays"). A second photo of a different subject than the lead.
+- Every photo and figure is real: the project's own, or licensed and credited. Never a stock photo standing in for the place, never an invented number.
+- Four to six tiles. More reasons than that belong in a list.
+
+## States and motion
+
+- Server render: every tile complete; photos have their width and height set so nothing shifts.
+- At most one motion per tile, and few tiles moving at all: a photo may ease in from 1.04 scale once as the grid enters, a figure may count up once. Entrances are staggered (60–90ms between tiles), never all at once.
+- Hover does not lift or tilt tiles; a tile that links somewhere shows a text link inside it.
+- Reduced motion: no entrance, no count-up, no scale; every tile shows its final state.
+
+## Pitfalls
+
+- Six equal boxes with an icon, a title and a sentence each: the stock card grid wearing a bento name.
+- Two identical tiles side by side, or a checkerboard of light and dark tiles.
+- A lead tile that is big but says the least, or holds a weaker photo than a small tile.
+- A caption or a figure cut by the tile's edge because the photo or the padding pushed it out.
+- A figure pinned to the bottom of its tile under an empty band.
+- Every tile fading in at once on scroll.
+- At 390, the lead photo squeezed into a 16:9 strip.
+
+## Floor checks
+
+- Is there one lead tile, spanning two columns and two rows and at least twice the area of any other tile, that carries the section's main reason?
+- Do neighbouring tiles differ in size, surface or material, so no two identical tiles sit side by side?
+- Is exactly one tile on the inverse ground (dark on a light page, light on a dark page), rather than none or several?
+- Does every tile hold real material (a photo, a measured figure, a quote with a name, a specific fact) rather than an icon and a sentence?
+- Are all headings, sentences and numbers whole, with only photos, patterns or fragments cropped by a tile's edge?
+- Does each figure sit close under its line, with no empty band above it?
+- Is text on a photo set on a plate or beside the photo, and readable?
+- Does each tile have at most one motion, staggered across tiles, and is everything still under reduced motion?
+- At 390, does the lead tile come first with its photo re-cropped around the subject rather than squeezed?