@palate/cli 0.0.0-stage → 0.0.2

package/kb/sections/split-hero-live-object.md

@@ -0,0 +1,108 @@
+---
+id: split-hero-live-object
+name: Split hero with the live object
+kind: hero
+shape: split
+layout: "words left 5/12, the product's live object right 7/12 bleeding past the container edge to the viewport; headline 56–88px; the object is code-built UI doing one thing"
+fits: [saas, developer, ai, productivity, b2b, technical, crafted, honest, launch]
+avoid: [luxury, fashion, heritage, crisis, food, portfolio]
+needs: ["a product UI that can be shown working", "one real moment of the product (a task done, a result appearing) with real labels and data"]
+imagery: product-ui
+density: balanced
+effort: m
+moves: [self-playing-product-demo, screenshot-detail-crops, product-in-context]
+---
+
+## When it's right
+
+The product is software with a screen, and the fastest way to say what it does is to show its main object (the editor, the inbox, the board, the run log) doing one thing. The words do the naming; the object does the convincing. This is the workhorse hero for tools, and it only reads as designed when the object is large, real and slightly too big for the box: it leaves the container on the right and runs to the viewport edge, so the page feels like a window onto a bigger product.
+
+Not for products with no interface worth showing (use `full-bleed-image-hero` or `typographic-statement-hero`), or when the interface is the whole message and the words can be small (use `object-first-hero`).
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gutter 24; the object column ignores the right container edge
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ nav ──────────────────────────────────────────────────────────────────── [Secondary][Pri]│
+│                                                                                          │
+│  ┌ cols 1–5 ───────────────────┐   ┌ cols 6–12 + bleed to viewport edge ───────────────────
+│  │                             │   │ product frame (radius 20, shadow-2)                  │
+│  │ H1 display 64–88px          │   │ ┌ chrome: product's own bar, skeletonised ─────────  │
+│  │ three lines max,            │   │ │ ▤ list        │ the working area                   │
+│  │ left aligned                │   │ │ ▤             │ one real moment happening:         │
+│  │                             │   │ │ ▤             │ a row arrives, a result renders,   │
+│  │ lead 20px, 2–3 lines,       │   │ │               │ a cursor clicks                    │
+│  │ ink-2, max 44ch             │   │ │               │                                    │
+│  │                             │   │ │               │                                    │
+│  │ [Primary action] link →     │   │ └───────────────┴────────────────────────────────────
+│  │                             │   │                                                      │
+│  │ one fact line: small, ink-3 │   │  object top aligns with H1 cap height;               │
+│  └─────────────────────────────┘   │  object height 560–680; crops at the viewport edge   │
+│                                                                                          │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  hero height: 760–880 at 1440×900; the object's bottom may run 64–120px into the next band
+```
+
+```
+390 ─ one column, side padding 16
+┌──────────────────────────────┐
+│ nav            [Pri]  ☰      │
+│ H1 40–48px, 3–4 lines        │
+│ lead 17px, 3 lines           │
+│ [Primary action, full width] │
+│ link →                       │
+│ ┌ object, bleeds right ─────── │  ← starts above the 812 fold; cropped to the working area,
+│ │ text ≥ 12px at this size   │    left edge on the 16px gutter, right edge off screen
+│ └─────────────────────────── │
+└──────────────────────────────┘
+```
+
+At 390 the order is headline, lead, action, object. The object keeps its left edge on the gutter and bleeds off the right edge, cropped to the working area (drop the sidebar). It is 360–440px tall, its text never below 12px, and its top shows within the first 812px. Nothing scrolls sideways at page level: the bleed is clipped by the hero (`overflow-x: clip`).
+
+## Finish
+
+- Grid: words in columns 1–5, object starts at column 6 (a `--s-6`–`--s-7` gap between them) and extends to the viewport: `margin-right: calc(-1 * (100vw - min(100vw, var(--container))) / 2 - var(--page-x));` on the object, `overflow-x: clip` on the hero.
+- Vertical: hero padding top `--s-9` below the nav, bottom `--s-9`; the object's top lines up with the H1's cap height, not its line box. If the object runs into the next band, the next section's ground changes (`--paper-2`) so the overlap reads as deliberate.
+- H1: `--t-display` (64–88px), weight 600 (or the display face's regular), tracking −0.025em to −0.03em, leading 1.0, `text-wrap: balance`, 3 lines max at 1440. Lead: `--t-lead`, `--ink-2`, `max-width: 44ch`, `--s-5` below the H1.
+- Actions: one primary and its secondary in the page's button language (`.btn-primary`, `.btn-secondary`), `--s-6` below the lead. The hero primary outweighs the nav's action.
+- Fact line under the actions: one true, specific fact in `--t-small`, `--ink-3` ("Free for one project. Runs on your machine."). No logo row here; proof is its own section.
+- Size and bleed: the object takes about two thirds of the hero's width (never under half) and runs off the right edge to the viewport. What the edge cuts is filler: the end of the inspector, extra columns, the rest of a list. The part the headline talks about sits fully inside, on the left of the object. If the edge would cut it, shift the object's content left or crop a different side.
+- Object: the product frame from `_finish.md` (`--r-lg`, `--shadow-2`, no fake chrome). One frame style per page: every product window, screenshot and device uses the same radius, the same edge (a shadow or a border, not both) and the same shadow level, the system's product frame from `_finish.md`. Inner panes nest radii concentrically. Text inside is readable at 100% (13px minimum at 1440). Unimportant chrome is skeleton bars; the working area carries real labels and data.
+- Ground: the hero sits on `--paper`; a very soft ground behind the object only if it has a reason (a band of `--paper-2` that starts at the object's vertical centre, so the object straddles two tones). No glow blobs behind it (M20).
+
+## Content
+
+- H1: what the product does and for whom, in words a founder would say aloud. Six to ten words. No "Build faster", no tricolon (M09).
+- Lead: the mechanism in one or two sentences: how it does it, what changes for the user.
+- Primary action: the real first step ("Install the CLI", "Start a free project"). Link: the second most useful thing ("Read the docs", "See a real run").
+- Object: the product's main screen at the moment of its value, with content from the project (real field names, a believable record, the product's own vocabulary). If the product is not built yet, the object shows the intended flow and the page says it is a preview.
+- Never invented customer names, metrics or avatars inside the object; use the project's demo data or obviously sample data ("Acme" is lazy, prefer a plausible record in the product's domain).
+
+## States and motion
+
+- Server render shows the object in its finished, informative state: never blank, never at `opacity: 0` (M45).
+- One thing happens in it after load: a row arrives, a result builds, a cursor completes a click (pairs with move `self-playing-product-demo` for a full run, or a single 3–6s loop). Pauses off screen, on hover and focus; reduced motion keeps the finished state.
+- Both actions have hover, press and focus (`_finish.md`).
+- Very long headlines (translation): the H1 may take a fourth line; the object's top stays aligned to the H1 cap height and the object grows downward, never shrinks.
+
+## Pitfalls
+
+- Shrinking the object into the right half of the container so it becomes a thumbnail (L04). It should be the largest thing on the screen.
+- A screenshot `<img>` in a browser frame with traffic lights (M19, L03).
+- Words column vertically centred against a tall object, leaving holes above and below the text. Top-align both.
+- A gradient glow or blurred blob behind the object (M20).
+- Pill badge above the H1 (M07) and a logo strip crammed under the buttons.
+- At 390, the object shrunk to fit the width with 6px text, or pushed below a tall stack so the first screen is only words.
+
+## Floor checks
+
+- Does the product object fill about two thirds of the hero's width at 1440 (at least half) and run off the right edge to the viewport, rather than floating inside the container with a margin all round?
+- Is the part the edge cuts secondary UI (a sidebar's end, extra rows or columns), with the part the headline describes fully in view?
+- Is the product shown as working UI with real-looking labels and data, rather than a screenshot in a fake browser frame?
+- Is the text inside the product object readable at 100% zoom?
+- Is the headline the heaviest text on the screen and no longer than three lines at 1440?
+- Is there exactly one primary action in the hero, visibly heavier than the nav's?
+- Do the top of the headline and the top of the product object start at about the same height, with no empty band taller than 160px above or below the words?
+- At 390, does the top of the product object appear within the first screen, after the headline and the button?
+- Is the hero free of a pill badge above the headline and of glow blobs behind the object?

package/kb/sections/sticky-feature-narrative.md

@@ -0,0 +1,104 @@
+---
+id: sticky-feature-narrative
+name: One feature per screen beside a sticky stage
+kind: features
+shape: split
+layout: "a sticky product stage 7/12 on one side holds still while 3–5 feature texts (5/12) scroll past, one per screen height; the stage changes state for each feature"
+fits: [saas, ai, developer, productivity, technical, cinematic, honest, crafted, launch]
+avoid: [low-bandwidth, crisis, data-dense-tool, food, portfolio]
+needs: ["3–5 features that are states of one screen or one object", "a stage that can show each state in code (or one image per state)"]
+imagery: product-ui
+density: airy
+effort: l
+moves: [sticky-scroll-story, scroll-progress-chapters, shape-continuity-morph, self-playing-product-demo]
+---
+
+## When it's right
+
+Three to five features that are all aspects of one screen: the same editor gets suggestions, then review, then a merge; the same map gets layers, then routes, then live traffic. Holding one stage still and changing its state as the reader scrolls past each feature tells a story of the product getting more capable, and each feature has a full screen's attention. It is the archetype for a product's three biggest ideas, placed once, mid-page.
+
+Native scroll only: the text scrolls normally, the stage is `position: sticky` and changes when each text block reaches the middle of the screen (L15). Not for features that are unrelated screens (use `alternating-rows-live-tiles`), for more than five features, or right after `scroll-scrubbed-product-demo` (two scroll-driven sections in a row is one too many). Pairs with moves `sticky-scroll-story` and `scroll-progress-chapters`.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gutter 24; section height ≈ (features × 90vh) + heading
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ H2 cols 1–6 (scrolls away normally)                                           │
+│ lead                                                                          │
+│ ┌ cols 1–5: text track ─────────┐   ┌ cols 6–12: stage, sticky top: 12vh ───┐ │
+│ │                                │   │ height 76svh max 720                   │ │
+│ │ ▸ 1 of 4 ▪▪▫▫ (progress)        │   │ product frame, shadow-2                │ │
+│ │                                │   │                                        │ │
+│ │ h3 feature one                 │   │   state 1: the editor with a          │ │
+│ │ 3–4 lines, 40ch                │   │   suggestion appearing inline          │ │
+│ │                                │   │                                        │ │
+│ │ (block min-height: 90svh,      │   │   → state 2, 3, 4 as each text block  │ │
+│ │  content centred at 50svh)     │   │     crosses the middle                 │ │
+│ │                                │   │                                        │ │
+│ │ h3 feature two …               │   └────────────────────────────────────────┘ │
+│ │ h3 feature three …             │                                             │
+│ │ h3 feature four …              │   stage releases with the last text block   │
+│ └────────────────────────────────┘                                             │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ one column, side padding 16, no sticky
+┌──────────────────────────────┐
+│ H2                           │
+│ lead                         │
+│ h3 feature one               │
+│ 3–4 lines                    │
+│ ┌ stage in state 1 ────────┐ │  ← static frame, 4:3, cropped to the working part
+│ └──────────────────────────┘ │
+│           --s-8              │
+│ h3 feature two               │
+│ ┌ stage in state 2 ────────┐ │
+│ └──────────────────────────┘ │
+└──────────────────────────────┘
+```
+
+At 390 nothing is sticky: each feature becomes its words followed by a static frame of the stage in that state (4:3, 300–360px tall, text inside at 12px or more). Section height drops to roughly one phone screen per feature. Under reduced motion on desktop, the same stacked layout can be used, or the stage swaps instantly.
+
+## Finish
+
+- Text blocks: `min-height: 90svh; display: grid; align-content: center`. h3 `--t-h3` to `--t-h2` (this is the section's star, so the feature titles may be large), weight 600, tracking −0.02em; body `--t-lead`, `--ink-2`, `max-width: 40ch`.
+- Inactive text blocks dim to `--ink-3` (opacity 0.4 is too faint; use the colour token) so the current one leads; transition 300ms.
+- Progress: a small row of 4 segments or "2 of 4" in `--t-small`, tabular figures, at the top of the text track and sticky with the stage. Optional; it helps with five features (move `scroll-progress-chapters`).
+- Stage: the product frame from `_finish.md` at `--shadow-2`, `--r-lg`, sticky `top: 12svh`, height `min(76svh, 720px)`. It is on `--surface` over a band of `--paper-2` that spans the section, or over a textured or painted ground if the page has one (then `--shadow-3`).
+- States: each state differs in one clear region (a panel opens, a layer draws, a row resolves). Keep the frame and chrome identical across states so the change is legible.
+
+## Content
+
+- Heading: the arc ("From first draft to merged, in one window"). Lead optional.
+- Each feature: an h3 that says what the reader can now do, 2–4 sentences of how, and optionally one text link.
+- Each stage state: the same screen with the project's real data, showing the result of that feature. The states build on each other (state 3 still shows what state 2 added) so the stage ends at its richest.
+- Three features is ideal; five is the limit.
+
+## States and motion
+
+- An IntersectionObserver with `rootMargin: "-45% 0px -45% 0px"` on each text block sets the active index; the stage renders that state. Never tie state to scroll position pixel by pixel (that belongs to `scroll-scrubbed-product-demo`).
+- State change: 300–500ms, ease-out `cubic-bezier(.23,1,.32,1)`; parts that persist stay put, new parts enter with opacity and a 6–8px rise or a shared-element morph (move `shape-continuity-morph`).
+- Within a state, an optional 2–4s micro-loop (a caret, a row arriving), paused under reduced motion.
+- Server render and no JS: stacked layout (the phone layout) at every width, or the sticky layout with each state's frame inline. Never a stage stuck on state 1 beside four texts.
+- The stage has `aria-hidden` on its decorative internals and a label per state; the texts carry the meaning.
+
+## Pitfalls
+
+- Scroll-jacking: snapping the page, slowing the wheel, or hijacking to horizontal (L15).
+- States that change everything at once, so the reader can't see what the feature added.
+- Text blocks short enough that two are on screen together and the stage flickers between states.
+- A stage taller than the viewport, so its bottom is never seen while sticky.
+- Hiding all feature text until it scrolls in (M45 if it's in the first viewport; M44 elsewhere).
+- Running this right after another scroll-driven section.
+
+## Floor checks
+
+- Does the product stage take at least half the section's width at 1440 and fit inside one screen height?
+- Does each feature's text sit beside a stage state that clearly differs from the previous state?
+- Is the text for the current feature visibly stronger than the others?
+- Is the frame and chrome of the stage the same across states, with only the relevant region changing?
+- Is there a clear, large heading for each feature rather than paragraphs alone?
+- At 390, is each feature shown as its words plus a static frame, with no sticky stage?
+- Is the section free of empty screens where the stage is visible but no text is near it?

package/kb/sections/todays-board-hero.md

@@ -0,0 +1,112 @@
+---
+id: todays-board-hero
+name: Today's board beside the counter
+kind: hero
+shape: split
+layout: "a real photograph of the place's counter, window or bench on one side (7 cols); on the other (5 cols) the name and today's facts set like the shop's own board: open today until when, what's in the oven, this week's special, the cut-off for orders, one action"
+fits: [food, local, warm, friendly, community, crafted, tactile, heritage]
+avoid: [saas, developer, b2b, enterprise, data-dense-tool]
+needs: ["one real photograph of the place at work (the counter, the bench, the window, the hearth), ≥ 2000px wide, with a phone crop", "today's real facts: hours, what's on, this week's special, the order cut-off", "one real next step (pre-order, book a table, book a service)"]
+imagery: photo
+density: balanced
+effort: m
+moves: [product-in-context, time-of-day-theming]
+---
+
+## When it's right
+
+A neighbourhood place whose regulars come to the site with one question: is it open, what's on, can I order. A bakery, a café, a wood-fired restaurant, a florist, a repair shop. The median hero gives them a mood photo and "Baked with love"; this one gives them the photograph and the answer, the way the shop's own chalkboard or printed notice does at the door. It is warm because it is useful and specific, not because of the adjectives.
+
+Use it when the place has facts that change (today's hours, this week's special, the pre-order cut-off) and someone keeps them true. If the place is a destination people visit once and the feeling matters more than today's facts (a coastal inn, a rail journey), use `full-bleed-image-hero`. Never for software.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gutter 24
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ Mabel's Bakehouse                              Menu   Pre-order   Visit   Classes        │
+│                                                                                          │
+│ ┌ photograph, cols 1–7, 4:5 or 1:1 ─────────────┐   Mabel's Bakehouse                   │ ← name in the display face,
+│ │                                               │   Leith, Edinburgh                    │   H1, 56–72px
+│ │   the bench at 6 am: trays of cardamom buns,  │                                       │
+│ │   flour on the wood, a baker's hands          │   ┌ the board ───────────────────┐    │
+│ │                                               │   │ Open today  8 am – sold out   │    │ ← the board: ruled lines,
+│ │                                               │   │             usually 1 pm Sat  │    │   label left, fact right,
+│ │                                               │   │ In the oven cardamom buns,    │    │   on --paper-2 or a slate
+│ │                                               │   │             country sourdough │    │   tone with chalk-white type
+│ │                                               │   │ This week   brown butter and  │    │
+│ │                                               │   │             pear danish       │    │
+│ │                                               │   │ Pre-orders  close Thu 9 pm    │    │
+│ │                                               │   └───────────────────────────────┘    │
+│ │                                               │   [ Pre-order for the weekend ]       │ ← one primary
+│ └───────────────────────────────────────────────┘   22 Great Junction St · Visit →        │
+│ Photo: the bench at 6 am, by Ewan Laird                                                  │ ← credit, 13px
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  hero ≤ 100svh; the photograph's top aligns with the name's cap height
+```
+
+```
+390 ─ name, the board, the action, then the photograph
+┌──────────────────────────────┐
+│ Mabel's            ☰         │
+│ Mabel's Bakehouse            │ ← H1 40–44px
+│ Leith, Edinburgh             │
+│ ┌ the board ───────────────┐ │
+│ │ Open today 8 am–sold out │ │
+│ │ This week  pear danish   │ │
+│ │ Pre-orders close Thu 9pm │ │
+│ └──────────────────────────┘ │
+│ [ Pre-order for the weekend ]│ ← full width, above 812px
+│ ┌──────────────────────────┐ │
+│ │ photograph, 4:5 crop     │ │
+│ └──────────────────────────┘ │
+└──────────────────────────────┘
+```
+
+At 390 the answer comes first: name, the board (three or four lines, the most time-sensitive first), the primary action full width, then the photograph in its 4:5 phone crop. The board keeps its two-column rows; long facts wrap under their own label column, never under the label.
+
+## Finish
+
+- Photograph: `<picture>` with a phone source, `fetchpriority="high"`, `object-position` on the subject (the hands, the trays), radius `--r-sm` or none. Tone-matched to the page (`_finish.md` image treatment); warm white balance, not orange.
+- The board is the signature: a block on `--paper-2` with a 1px `--hairline-strong` rule between rows, or, if the brand has one, a slate tone (`oklch(28% 0.01 250)`) with chalk-white type and paper-fibre grain at 4% (`_finish.md` textures). Padding `--s-5`. Radius `--r-sm` at most: it is a sign, not a card. No shadow, or a single `--shadow-1` if it sits over a textured ground.
+- Board rows: label in `--t-small`, weight 600, small caps or caps with +0.08em tracking, `--ink-2`; fact in `--t-body` or `--t-lead`, `--ink`, `tabular-nums` for times and prices. Label column fixed at 112px so facts align.
+- Lettering: the board may use the shop's real signwriting face or a hand-lettered display face for its labels only if the shop's sign uses one; the facts stay in the text face so they read at a glance. Never a novelty "chalk" font for body text.
+- H1: the place's name in the display face, `--t-display` at the smaller end (56–72px), tracking −0.025em; the neighbourhood line under it in `--t-lead`, `--ink-2`.
+- The page's `.btn-primary`, labelled with the action and its time ("Pre-order for the weekend"); the address and "Visit →" as a quiet line under it.
+- Credit under the photograph, `--t-caption`, `--ink-2`.
+
+## Content
+
+- Facts are true today. "Open today" is computed from the real opening hours (and says "Closed today, open Wednesday 8 am" on Monday). "Sold out" times are honest ("usually 1 pm on Saturdays").
+- "In the oven" or "On today" names real things from the real menu, two or three of them.
+- "This week" is the real special; if there isn't one, the row goes.
+- The cut-off is stated plainly with day and time ("Pre-orders close Thursday 9 pm for Saturday and Sunday pickup").
+- The photograph is of this place and its people at work, taken by someone credited. Not a stock croissant on marble.
+- No "artisan", "baked with love", "passion": the board's facts are the warmth.
+
+## States and motion
+
+- Static on first paint; the board is server-rendered from the opening hours so "open today" is right without JS, then refreshed on the client for the visitor's local time.
+- With move `time-of-day-theming`, the board's first row changes through the day ("Ovens on since 3 am" before opening, "Open now until sold out", "Sold out for today, back Wednesday"). The ground does not change colour.
+- If a fact is unknown (the special not set this week), its row is omitted rather than showing a placeholder.
+- No entrance animation on the board or the photograph (M45). Button hover and focus per `_finish.md`.
+
+## Pitfalls
+
+- A status pill ("● Open now" in a green capsule) or a live-dot badge: app chrome. The board says it in words.
+- The board built as a dashboard card with icons per row (clock icon, oven icon, calendar icon).
+- Facts that go stale: last month's special still on the board, "open today" on a closed day.
+- A stock or generated photo of bread, or a moody photo with nothing of the place in it.
+- A carousel of hero photographs.
+- A novelty chalkboard font for every line, unreadable at 16px.
+- At 390, the photograph first and the hours two screens down.
+
+## Floor checks
+
+- Is there a real photograph of the place or its work (counter, bench, hearth, window) rather than a generic stock image?
+- Does the hero state today's practical facts (opening hours, what's on, the order cut-off) in plain words?
+- Are those facts set like a sign or board (ruled rows, labels aligned) rather than as app cards with icons or status pills?
+- Is there exactly one primary action, named for what it does and when?
+- Is the place's name the headline, with no slogan or adjectives standing in for facts?
+- Is the board's text clearly readable (no novelty font for the facts, sufficient contrast on its ground)?
+- At 390, do the name, the board and the action appear before the photograph and within the first screen?

package/kb/sections/touchable-tool-hero.md

@@ -0,0 +1,111 @@
+---
+id: touchable-tool-hero
+name: A tool you can touch in the hero
+kind: hero
+shape: object-first
+layout: "a short headline 40–56px and one line of lead above; a working instrument 960–1240px wide below: a real control (input, slider, drop zone or prompt box) on the left or top, the product's real response beside or under it, pre-filled with an example result on first paint"
+fits: [developer, ai, technical, education, scientific, productivity, saas, playful, honest, experimental, data-rich]
+avoid: [luxury, fashion, heritage, crisis, enterprise-compliance, low-bandwidth, food, portfolio]
+needs: ["a product action that runs in the browser (or a fast public endpoint) in under ~500ms", "a good default input whose result tells the story", "honest limits stated in small type (sample size, offline model, rate limit)"]
+imagery: product-ui
+density: balanced
+effort: l
+moves: [explorable-control, real-world-data, copy-confirmation, honest-progress-narration]
+---
+
+## When it's right
+
+The product does something you can try in five seconds: format code, convert a colour, generate a palette, parse a date, compress an image, rewrite a sentence, price a shipment. Then the hero should be the tool itself: a real control the visitor can change and the product's real answer right next to it. Nobody reads the headline twice when the thing works under their hands. It pairs with move `explorable-control` for the one-variable version.
+
+It is wrong when the action is slow, needs an account, or can't run honestly in a page (then show it with `self-playing-run-demo`), or when trying it would cost the business real money per visitor without a cap.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gutter 24
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ nav ──────────────────────────────────────────────────────────────────── [Secondary][Pri]│
+│                                                                                          │
+│   H1 44–56px, 1–2 lines, cols 1–8                                                        │
+│   lead 18px, one line, ink-2                                                             │
+│                                                                                          │
+│ ┌ instrument: product frame, cols 1–12, radius 20, shadow-2 ─────────────────────────────┐│
+│ │ ┌ input pane: cols 1–5 ───────────────┐ ┃ ┌ output pane: cols 6–12 ──────────────────┐ ││
+│ │ │ label: "Paste a date in any format" │ ┃ │ the product's real result for the        │ ││
+│ │ │ ┌ input, pre-filled example ──────┐ │ ┃ │ example, rendered richly:                │ ││
+│ │ │ │ next tues 3pm PST               │ │ ┃ │   2026-11-03 15:00 −08:00                 │ ││
+│ │ │ └─────────────────────────────────┘ │ ┃ │   in your zone: 00:00 Wed, CET           │ ││
+│ │ │ examples: [chip] [chip] [chip]      │ ┃ │ [Copy]                                   │ ││
+│ │ └─────────────────────────────────────┘ ┃ └──────────────────────────────────────────┘ ││
+│ │ status line 13px: "Parsed in 2 ms, in your browser"            [Primary: Install →]   ││
+│ └────────────────────────────────────────────────────────────────────────────────────────┘│
+│   instrument top within 380px of the hero top; instrument height 360–520                │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 ─ one column, side padding 16
+┌──────────────────────────────┐
+│ nav            [Pri]  ☰      │
+│ H1 34–40px, 2–3 lines        │
+│ lead 16px                    │
+│ ┌ instrument ──────────────┐ │
+│ │ label                    │ │
+│ │ [input, 16px text]       │ │
+│ │ [chip][chip] → scrolls   │ │  ← example chips scroll horizontally inside
+│ │ ───────────────────────  │ │
+│ │ output, pre-filled       │ │
+│ │ [Copy]                   │ │
+│ └──────────────────────────┘ │
+│ status line                  │
+│ [Primary action, full width] │
+└──────────────────────────────┘
+```
+
+At 390 the instrument stacks: control on top, output under it, separated by a hairline. The input text is 16px (no iOS zoom), the keyboard must not cover the output (scroll the output into view on `focus` if needed). The example chips scroll horizontally inside the instrument. The pre-filled result is visible within the first screen.
+
+## Finish
+
+- H1: `--t-h2`–`--t-display` low end (44–56px), weight 600, tracking −0.025em, `text-wrap: balance`; it is an instruction or a promise, not a poem. Lead one line, `--ink-2`. H1 to instrument `--s-7`.
+- Instrument: the product frame from `_finish.md`, `--r-lg` (20), `--shadow-2`, padding `--s-6`. Input and output panes divided by a 1px `--hairline` column rule, not two cards (M23). Inner control radius = 20 − 32 padding → `--r-sm` (6).
+- Control: a native element with a visible `<label>` (D08), height 48px, 1px `--hairline-strong` ring, focus ring per `_finish.md`. Range sliders get printed values in tabular figures beside them. A drop zone shows a dashed 1.5px border only while dragging.
+- Example chips: `--t-small`, 32px pills with a `--hairline-strong` ring and the states in `_finish.md`; clicking one fills the control and runs.
+- Output: the product's real rendering at a large, legible size: the result in `--t-h3`–`--t-h2` with tabular figures for numbers; monospace only if the output is code or machine values (`_finish.md` numbers). A copy button with a "Copied" confirmation (move `copy-confirmation`).
+- Status line `--t-caption`, `--ink-3`: what happened and the honest limit ("Runs locally. Nothing is uploaded.").
+- The page's `.btn-primary` bottom-right of the instrument, plus the secondary in the nav. The ground behind the instrument: `--paper-2` band starting at its middle.
+
+## Content
+
+- The default input is chosen to tell the story: a realistic, slightly messy case the product handles well, not the trivial one.
+- 3–5 example chips covering the range of what it does, including one surprising case.
+- Output is real: computed by the product's code, never a canned string pretending to be live. If the real engine can't run in the page, this archetype is wrong.
+- Status line states the mechanism and the limit truthfully.
+- Primary action: what to do once convinced ("Install the package", "Use it on your files").
+
+## States and motion
+
+- First paint: control pre-filled, output showing the default result, server-rendered (works without JS as a static example; the control is disabled with a note when JS is off).
+- Typing: recompute on `input` when it costs under ~16ms, otherwise debounce 150ms; show "Working…" only after 200ms (D02). Output changes with a 150ms crossfade, no layout jump (reserve height).
+- Empty input: a one-line hint, not an error. Invalid input: a plain-language message next to the control, input preserved (M39). Over a limit: say the limit.
+- Output region `aria-live="polite"`, announcing on `change`, not every keystroke.
+- Reduced motion: values snap; no crossfades.
+
+## Pitfalls
+
+- A blank control waiting for input: the visitor sees nothing happen and leaves. Always pre-fill.
+- A fake tool that returns canned answers (the visitor tries their own case and finds out).
+- Five controls and a settings panel: it becomes a form (M27). One control, two at most.
+- Output too small to notice it changed.
+- The instrument below the fold under a big headline.
+- Placeholder used as the label (D08).
+
+## Floor checks
+
+- Is there a real, labelled input control visible in the hero at 1440 without scrolling?
+- Is a filled-in example result visible next to or under the control without interacting?
+- Is the result shown large and clearly, as the most prominent part of the instrument?
+- Are there example inputs (chips or similar) that suggest what to try?
+- Is the instrument at least 75% of the container width at 1440?
+- Is there a short line stating what happens to the input or the tool's limit?
+- Is there one primary action for the real next step?
+- At 390, are the control and its pre-filled result both on the first screen or immediately after it, with no sideways scroll?

package/kb/sections/typographic-statement-hero.md

@@ -0,0 +1,99 @@
+---
+id: typographic-statement-hero
+name: Oversized typographic statement with one detail
+kind: hero
+shape: single-statement
+layout: "one statement set at 120–200px across the full container, 2–3 lines, left aligned; a single detail placed in the statement's ragged space (a small live product fragment, a footnote mark, or one drawn line); a short lead and one action below on the grid"
+fits: [editorial, bold, minimal, crafted, agency, portfolio, publishing, launch, honest, quiet, serious, artsy]
+avoid: [data-dense-tool, kids, playful-kids, ecommerce, low-bandwidth]
+needs: ["a statement of 4–9 words that says what the product does or believes, and survives being read alone", "one detail that is true to the product (a tiny live fragment, a sourced footnote, or a mark)", "a display face with a real heavy or tight cut"]
+imagery: type
+density: airy
+effort: s
+moves: [kinetic-variable-type, hand-drawn-annotations, pointer-highlight-word, typographic-numeral-hero]
+---
+
+## When it's right
+
+The brand has a voice and a point of view, and no picture would say it better than the sentence itself. A studio, a writing tool, a launch with a sharp claim, a product whose idea is the selling point. Type at architectural size is confident; one carefully placed detail beside it (a 3-line live fragment of the product, a footnote that sources the claim, a single hand-drawn underline) proves the page was composed, not generated.
+
+It fails when the statement is vague ("Design for the future") or doesn't say what the product does: an oversized slogan with no subject is the most expensive way to say nothing. If the strongest thing is a number, use `one-huge-number` or move `typographic-numeral-hero`.
+
+## Structure
+
+```
+1440 ─ container 1240; the statement uses all 12 cols
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ nav ──────────────────────────────────────────────────────────────────── [Pri]          │
+│                                                                                          │
+│ Notes that write                                                  ┌ detail ─────────┐   │  ← statement 140–200px,
+│ themselves back                                                   │ a 3-line live   │   │    leading 0.92;
+│ into your week.¹                                                  │ fragment, 280w  │   │    the detail sits in the
+│                                                                   └─────────────────┘   │    ragged right of line 2–3
+│ ───────────────────────────────────────────────────────────────────────────────────────  │  ← hairline, full container
+│ lead 20px, 2 lines, cols 1–5        [Primary action]  link →        ¹ footnote, cols 9–12│
+│                                                                                          │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  hero height 720–860; statement top --s-9 under the nav
+```
+
+```
+390 ─ one column, side padding 16
+┌──────────────────────────────┐
+│ nav            [Pri]  ☰      │
+│ Notes that                   │  ← 52–64px, 4–5 lines, leading 0.95
+│ write                        │
+│ themselves                   │
+│ back into                    │
+│ your week.¹                  │
+│ ┌ detail, full width ──────┐ │  ← moves under the statement
+│ └──────────────────────────┘ │
+│ lead 17px                    │
+│ [Primary action, full width] │
+│ ¹ footnote                   │
+└──────────────────────────────┘
+```
+
+At 390 the statement steps down to 52–64px and may take 4–5 lines; it never breaks a word or overflows (check the longest word fits 358px). The detail moves under the statement at full width. Lead, action and footnote stack below the hairline. The primary action stays above 812px.
+
+## Finish
+
+- Statement: a display cut, 140–200px at 1440 (`clamp(56px, 12vw, 200px)`), weight per the face (heavy grotesque or tight serif), tracking −0.035em to −0.04em, leading 0.9–0.95, `text-wrap: balance`, `font-optical-sizing: auto`. Set as the H1. Ink colour, solid: no gradient, no accented word (M02, M14).
+- Shape the rag deliberately: break lines by meaning with `<br>` at desktop only, so lines 2–3 leave a pocket on the right for the detail. The detail top-aligns to a line's cap height.
+- Hanging punctuation: opening quotes hang into the margin (`_finish.md` type details); the left edge of the statement aligns optically with the lead below (pull the H1 left by its side bearing, 0.04–0.06em).
+- One detail, 240–320px wide: a product fragment in the product frame style at `--r-md` with `--shadow-1`, or a footnote mark (superscript ¹ in the body face at 0.3em, linked to the footnote), or one drawn mark (an SVG underline stroke, 2–3px, ink or brand) from move `hand-drawn-annotations`. Never two.
+- Hairline (`--hairline`) across the container `--s-8` under the statement; the lower row sits `--s-5` under it: lead cols 1–5 in `--t-lead`, `--ink-2`; actions cols 6–8; footnote cols 9–12 in `--t-caption`, `--ink-3`.
+- Ground: `--paper` with grain at 4% (`_finish.md`) if the brand is crafted; flat if minimal. No images, no shapes, no blobs.
+- The page's primary action (`.btn-primary`, in its button language).
+
+## Content
+
+- Statement: 4–9 words, says what the product does or the belief it acts on, with a subject ("Contracts your lawyer can read in five minutes"). Read it alone: if a stranger can't guess the category, rewrite.
+- Detail: true to the product. A live fragment shows the real thing (three lines of a note rewriting itself); a footnote sources the claim ("¹ Median across 1,200 drafts in our beta, Sept 2026") and only exists if the source does.
+- Lead: the mechanism in plain words. Action: the real first step.
+
+## States and motion
+
+- The statement is visible on first paint: no letter-by-letter reveal of the H1 (M45). If the brand is kinetic, a variable-weight settle (move `kinetic-variable-type`) on the statement may run once, starting from a readable state.
+- The live fragment may loop gently (4–6s), paused off screen and under reduced motion.
+- A drawn mark may draw in once with `stroke-dashoffset` over 600ms, after load, not gating anything.
+- Footnote mark is a real link with a focus ring; the footnote is reachable by keyboard.
+
+## Pitfalls
+
+- A vague slogan at 180px: maximum volume, no message (M09).
+- Two or three details competing with the statement; the composition is the restraint.
+- Centred statement: at this size a ragged left edge is unreadable (M06, P03).
+- Default tracking at 180px: the words fall apart (P20).
+- Overflow at 390 because one long word is wider than the screen.
+- The second-order tell: an italic serif word inside a sans statement (M13, M14).
+
+## Floor checks
+
+- Is the statement the dominant element, set at least about three times the size of normal headings?
+- Can you tell what the product is or does from the statement and lead alone?
+- Is there exactly one supporting detail (a fragment, a footnote, or a mark) and nothing else decorative?
+- Is the statement tightly tracked and leaded, reading as one block rather than loose lines?
+- Is the statement left aligned with no accented, gradient or differently styled word?
+- Is there one primary action below the statement?
+- At 390, does the statement fit without words overflowing the screen, with the button on the first screen?