@palate/cli 0.0.0-stage → 0.0.1

package/kb/sections/scroll-scrubbed-product-demo.md

@@ -0,0 +1,103 @@
+---
+id: scroll-scrubbed-product-demo
+name: Scroll-scrubbed product stage
+kind: demo
+shape: full-bleed-media
+layout: "a full-width pinned stage (the product, large, on a tinted band) that steps through 3–5 states as the page scrolls past at native speed; a caption column at the left changes with each state"
+fits: [saas, developer, ai, productivity, technical, hardware, cinematic, crafted, b2b]
+avoid: [low-bandwidth, accessibility-first, crisis, government, daily-tool, food, portfolio]
+needs: ["3–5 real states of one product screen that tell a story in order", "one short caption per state", "the states built in code from real data"]
+imagery: product-ui
+density: airy
+effort: l
+moves: [scroll-scrubbed-product-film, sticky-scroll-story, scroll-progress-chapters]
+---
+
+## When it's right
+
+The product has one screen whose story is a sequence of states (empty → first record → organised → shared; a layout before, during and after a change), and the reader should control the pace. The stage stays put while the page scrolls past it at its normal speed, and each stretch of scroll moves the product one state on. The scroll is the playhead; nothing hijacks the wheel (L15).
+
+Use it once per page, as the page's cinematic moment, on a band of its own. If you need words and visual side by side for 4+ features, use `sticky-feature-narrative` instead (that one is about features; this one is about one screen changing). If the visitor should cause the change, use `explorable-control-demo`.
+
+Not for short pages (a 300vh pinned section on a 4-section page is most of the page), dense tools whose visitors scan, or audiences on slow devices.
+
+## Structure
+
+```
+1440 ─ full-bleed band (--paper-2 or a tinted brand band), track height = (states + 1) × 100svh
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ band top: H2 one line, left on container edge, --s-9 above the pin                      │
+│ ┌ pinned viewport (position: sticky; top: 0; height: 100svh) ───────────────────────────┐│
+│ │                                                                                       ││
+│ │  caption col (cols 1–3)      stage (cols 4–12, ~900×580, product frame)              ││
+│ │  ─────────────────           ┌────────────────────────────────────────────────────┐  ││
+│ │  02 / 04  (tabular, small)   │                                                    │  ││
+│ │  Sorted                      │   the product screen in state 2:                   │  ││
+│ │  one sentence, 2 lines,      │   rows regrouped, a label applied,                 │  ││
+│ │  ink-2                       │   the changed part highlighted for one beat        │  ││
+│ │                              │                                                    │  ││
+│ │  ▮▮▯▯  progress ticks        │                                                    │  ││
+│ │                              └────────────────────────────────────────────────────┘  ││
+│ └───────────────────────────────────────────────────────────────────────────────────────┘│
+│   scroll continues under the pin: each 100svh of track = one state                      │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390 (and reduced motion) ─ no pin; stacked static frames, side padding 16
+┌──────────────────────────────┐
+│ H2                           │
+│ Empty                        │  ← caption: state name + sentence
+│ ┌ frame, state 1, 4:5 ─────┐ │
+│ └──────────────────────────┘ │
+│ Sorted                       │
+│ ┌ frame, state 2 ──────────┐ │
+│ └──────────────────────────┘ │
+│ … 3–5 frames, --s-7 apart    │
+└──────────────────────────────┘
+```
+
+At 390 and under `prefers-reduced-motion: reduce` there is no pin and no scrubbing: each state is its own static frame with its caption above it, cropped to the part that changed, 4:5, at most 480px tall each, `--s-7` between them. Same content, same order.
+
+## Finish
+
+- Mechanism: CSS scroll-driven animations first. The track is a tall wrapper with `view-timeline-name: --demo`; the stage's state layers use `animation-timeline: --demo` with `animation-range` slices (`contain 0% contain 25%`, …) to switch opacity and transform. JS fallback (IntersectionObserver on invisible step markers in the track) only sets a `data-state` attribute; CSS does the rest. No wheel listeners, no smooth-scroll libraries, no snapping on the page.
+- Track height (states + 1) × 100svh at most; 4 states = 500svh. The last state holds for a full 100svh so the result can be read before the pin releases.
+- Stage: the product frame from `_finish.md` (`--r-lg`, `--shadow-2`) on a band of its own (`--paper-2`, or a tinted band with `--sh-tint` set to its darkest shade). Grain from `_finish.md` on the band at 4% if the page uses material bands; never on the frame.
+- Caption column: state index in `--t-small`, tabular figures, `--ink-3` ("2 / 4": a real sequence, so numbering is honest); state name in `--t-h3`, weight 600; one sentence in `--t-body`, `--ink-2`, max 32ch. Captions crossfade (200ms) in place, all stacked in one grid cell so the column never changes height.
+- Progress ticks: 4 ticks 16×3px, `--hairline-strong`, the passed ones in `--ink`. They are the only progress UI.
+- Highlight what changed: the part of the screen that changed gets a 2px `--brand` outline (radius nested from its container) for 600ms, then fades. One change per state.
+
+## Content
+
+- 3–5 states of the same screen, in the order a real user lives through them. Each state's data follows from the last (the same records, now sorted; the same doc, now shared).
+- Captions: a one- or two-word state name in the product's vocabulary, then one plain sentence of what the user did and what the product did in response.
+- H2 above the pin names the story ("From a pile of notes to a plan your team can read"), not "How it works".
+- All data from the project's demo data or plausible domain data; never invented customer names or metrics.
+
+## States and motion
+
+- No-JS and unsupported browsers: the stacked static frames (the 390 layout at desktop widths), so nothing is lost.
+- Reduced motion: stacked frames, no pin.
+- Scrubbing is reversible: scrolling up runs the states backwards; nothing is triggered once and stuck.
+- The pinned region has an sr-only list of the states in order; the stage is `aria-hidden`; captions are real text in the reading order.
+- Keyboard: Tab never lands inside the pinned stage (no focusable product parts); the section is skippable with one scroll of the space bar per state.
+
+## Pitfalls
+
+- Scrolljacking: wheel-driven timelines, snapping or slowed scroll (L15). The page must scroll at native speed.
+- A track so tall (8–10 screens) that the visitor thinks the page is broken. 4 states max is the usual right answer.
+- States that differ by a few pixels: the visitor scrolls 100svh and sees nothing change. Each state must be visibly different at a glance.
+- Important copy only inside the scrubbed stage (L15): captions are real text outside it.
+- A blank band at the start or end of the pin while the first state fades in (P38). The first state is fully visible as the pin engages.
+- Pinned at 390: tiny product, jumpy sticky, address-bar resize jank.
+
+## Floor checks
+
+- In any screenshot of the pinned stage, does the product frame fill at least 60% of the section's width at 1440?
+- Is there a caption next to the stage naming the current state in words?
+- Is a progress indicator visible showing how many states there are and which one is showing?
+- Do the captured states differ visibly from each other at a glance (not only by small details)?
+- Is the section free of an empty band taller than 160px at the start or end of the pinned stretch?
+- At 390, are the states shown as separate static frames with their captions instead of a pinned sequence?
+- Does the band have its own ground (a tone or tint different from its neighbours) so it reads as one chapter?

package/kb/sections/self-playing-run-demo.md

@@ -0,0 +1,104 @@
+---
+id: self-playing-run-demo
+name: Self-playing run on a wide stage
+kind: demo
+shape: object-first
+layout: "a wide stage (10–12 of 12 columns, 16:10) playing the product's main flow by script, with a narrow ruled step list beside or under it that lights the current step; a one-line heading above, small"
+fits: [saas, developer, ai, productivity, b2b, technical, honest, crafted, launch]
+avoid: [luxury, heritage, fashion, low-bandwidth, crisis, food, portfolio]
+needs: ["a main flow that can be shown in 15–30 seconds", "real labels, data and wording from the product for every frame", "a finished end state worth stopping on"]
+imagery: product-ui
+density: balanced
+effort: l
+moves: [self-playing-product-demo, honest-progress-narration, calm-motion-system]
+---
+
+## When it's right
+
+The product's value is a flow that happens over time (a request turns into a result, an agent works through a task, a ticket moves from open to shipped), and a still picture cannot show it. Right under the hero, the page stops talking and runs the product once, end to end, in real HTML. A short ruled list of the run's steps sits beside the stage and lights up as the run passes each one, so a visitor who glances away can find their place, and a visitor who never watches still reads the flow.
+
+This is the most expensive section on the page and should be the most convincing. Use it once. If the hero is already `object-first-hero` with a running object, use `annotated-product-shot` or `explorable-control-demo` here instead; two runs back to back cancel each other.
+
+Not for products whose value is physical, emotional or instant (one click, done), or when the flow cannot be shown truthfully.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols; stage cols 1–9, step list cols 10–12
+┌──────────────────────────────────────────────────────────────────────────────────────┐
+│ H2 h2-size, one line, left: "One request, start to finish"      fact line, ink-3   │
+│                                                                                      │
+│ ┌ stage: product frame, 16:10, radius 20, shadow-2 ────────────┐   step list         │
+│ │ chrome: product's own bar, skeletonised                      │   ─────────────────  │
+│ │ ┌ request box: typed text + caret ───────────────────────┐   │   ● Ask              │  ← current: ink,
+│ │ └────────────────────────────────────────────────────────┘   │   ─────────────────  │    weight 600,
+│ │ plan rows  ✓ ✓ ◌                                             │   ○ Plan             │    a 2px bar on
+│ │ ┌ the result building, section by section ─────────────┐     │   ─────────────────  │    the rule's left
+│ │ │ ███████████                                          │     │   ○ Build            │
+│ │ │ █████                         ↖ pointer clicks       │     │   ─────────────────  │
+│ │ └──────────────────────────────────────────────────────┘     │   ○ Check            │
+│ │                                                              │   ─────────────────  │
+│ └──────────────────────────────────────────────────────────────┘   ○ Done             │
+│                                                                    ─────────────────  │
+│ caption under stage: what you are watching, ink-3, small           step text: 1 line  │
+└──────────────────────────────────────────────────────────────────────────────────────┘
+  stage ~ 900×560; section on --paper-2 so the stage's shadow has a ground to sit on
+```
+
+```
+390 ─ one column, side padding 16
+┌──────────────────────────────┐
+│ H2 28–32px, 2 lines          │
+│ ┌ stage, full width, 4:5 ──┐ │  ← re-composed for portrait: request on top,
+│ │ request                  │ │    result below; no sidebar
+│ │ plan ✓ ✓ ◌               │ │
+│ │ result building          │ │
+│ └──────────────────────────┘ │
+│ ● Plan  — current step only, │  ← the list collapses to one live line + a
+│   ▬▬▬▭▭ 5 small ticks        │    5-tick progress row under the stage
+└──────────────────────────────┘
+```
+
+At 390 the stage goes full width at 4:5 (not 16:10 shrunk), re-laid out in its em grid so text stays at least 12px; the sidebar and secondary panes are dropped. The step list becomes one line naming the current step plus five small ticks. Stage height at most 520px.
+
+## Finish
+
+- Stage: the product frame from `_finish.md` (`--r-lg`, `--shadow-2`, no traffic lights). Size it with `container-type: inline-size` and `font-size: calc(100cqw / 40)` so every part, cursor and caret is placed in em and lands correctly at every width (move `self-playing-product-demo`, step 2).
+- Ground: the section sits on `--paper-2` (one of the page's two surface tones), padding `--section-tight` at the top because it continues the hero, `--section` at the bottom.
+- Heading: h2 at the small end (32–36px), one line, left aligned, with a one-line fact on the same baseline at the right in `--t-small`, `--ink-3` ("Real run, sped up 2×"). Heading to stage `--s-7`.
+- Step list: a ruled list (`--hairline` between items, full width of the column), items 48px tall, `--t-small` in `--ink-3`; the current step in `--ink`, weight 600, with a 2px bar in `--ink` on its left edge that slides between items (transform, 240ms ease-out). Done steps keep a quiet check. No numbers unless the steps are a real sequence the product names.
+- Inside the stage: carets and spinners in CSS keyframes; UI changes 180–320ms `cubic-bezier(.23,1,.32,1)`; the pointer is a crisp SVG arrow with a 1px paper outline, scaling to .9 on press.
+- Caption under the stage: `--t-caption`, `--ink-3`, says what is real ("Recorded from v2.3 with sample data").
+
+## Content
+
+- One run of the product's main flow, 15–25 seconds, 4–6 beats: the request, the plan, the work, the result, one correction, the end state. Each beat uses the product's own vocabulary and plausible data in its domain.
+- Step list labels: one or two words each, the same verbs the product uses in its UI.
+- The first frame already says something (the request typed, the app as it is today); the last frame is the finished result, and it is what the server renders.
+- No invented speed ("done in 2s") the product cannot match. If the run is sped up, the caption says so.
+
+## States and motion
+
+- Server and no-JS: the finished end state, every step marked done. Under reduced motion: the same, plus a small note "Motion is reduced, so this is the finished run".
+- Starts when the stage is well in view (`rootMargin: 0px 0px -40% 0px`), pauses off screen, while hovered or focused, and when the tab is hidden; holds the end 4–5s, then loops. No play/pause chrome, no progress bar on the stage (move `self-playing-product-demo`). Because it loops for more than 5s, a visitor must be able to stop it: hovering or focusing pauses it, and the section has a small text button "Pause" for keyboard users.
+- The step list's live line is `aria-live="polite"`; an sr-only paragraph narrates the whole run; the stage is `aria-hidden`.
+- Height never changes while playing (reserve the result area), so the page below does not jump.
+
+## Pitfalls
+
+- A blank first frame or a spinner as the opening shot: the visitor scrolls past before anything happens.
+- A video or GIF instead of code: blurry, heavy, cannot match the theme (L01, L11).
+- A step list of numbered paragraphs that competes with the stage (M22). Keep it to labels.
+- Every beat at the same speed: let the slow part be visibly slow and the result arrive with a beat of its own.
+- The stage shrunk at 390 instead of re-composed: unreadable text, cursors missing their targets.
+- A second self-playing demo elsewhere on the page.
+
+## Floor checks
+
+- Is the stage the largest object in the section, at least two thirds of the container width at 1440?
+- Does the frame captured mid-run show real product UI with readable labels and data, not placeholder bars only?
+- Is it clear from the step list (or its phone line) which step of the run is showing?
+- Does the static or reduced-motion screenshot show a complete, finished result rather than a blank or loading stage?
+- Is the product shown without fake browser chrome (no traffic-light dots, no fake URL bar)?
+- Does the section sit on a different surface tone from the hero above it?
+- At 390, is the stage re-laid out for portrait with text that is still readable, rather than the desktop stage shrunk?

package/kb/sections/services-price-ledger.md

@@ -0,0 +1,106 @@
+---
+id: services-price-ledger
+name: Services and prices as the workshop's price board
+kind: pricing
+shape: table
+layout: "one ruled ledger of the shop's services, like the board behind the counter: service, what's done, how long it takes, price; a line on what changes the price and whether you book or walk in; one action under it"
+fits: [local, honest, crafted, trustworthy, friendly, sustainability, hardware]
+avoid: [saas, developer, b2b, luxury]
+needs: ["4–10 real services with real prices (or honest “from” prices)", "what each service includes, in the shop's words", "how long each takes and whether it needs booking"]
+imagery: none
+density: balanced
+effort: s
+---
+
+## When it's right
+
+A local service business (a bike shop, a tailor, a repair café, a florist, a print studio) whose visitors want to know three things before they come in: do you do my job, what will it cost, how long will it take. The shop already has the answer on a board behind the counter. This archetype sets that board on the page: a ruled ledger read top to bottom, with honest "from" prices and the conditions that change them.
+
+Use it instead of plan columns. Not for subscriptions with tiers (use `pricing-plans-ledger` for software, `printed-menu-card` for food), and not for bespoke work with no published prices (say "quoted per job" and use `book-a-slot-honest` or a contact form instead).
+
+## Structure
+
+```
+1440 ─ container 1240; ledger on cols 1–9, notes column on cols 10–12
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ H2 "Services and prices"                                                                 │
+│ one line: “Prices include labour. Parts are extra and we ask before fitting them.”       │
+│                                                                                          │
+│ ─────────────────────────────────────────────────────────────────── ┌ notes ──────────┐ │
+│ Flat fix            Tube or patch, tyre checked      15 min  $25    │ Walk in         │ │
+│                     no booking, while you wait                      │ Flat fixes, no  │ │
+│ ─────────────────────────────────────────────────────────────────── │ booking.        │ │
+│ Safety check        Brakes, gears, bolts torqued     same day  $49  │                 │ │
+│ ─────────────────────────────────────────────────────────────────── │ Book            │ │
+│ Standard service    Clean, adjust, true wheels       same day $129  │ Everything else.│ │
+│ ─────────────────────────────────────────────────────────────────── │ Drop off by 9,  │ │
+│ Full overhaul       Strip, clean, rebuild            2 days   $289  │ ride home by 5. │ │
+│ ─────────────────────────────────────────────────────────────────── │                 │ │
+│ E-bike service      Bosch, Shimano Steps, Tern   same day from $169 │ [Book a service]│ │
+│ ─────────────────────────────────────────────────────────────────── └─────────────────┘ │
+│ What changes the price: worn parts (we text a photo first), cargo bikes +$20.            │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+  columns: service 3 · what's done 4 · time 1 · price 1 (right-aligned); rows 56–72px
+```
+
+```
+390 ─ each service becomes a ruled block
+┌──────────────────────────────┐
+│ H2 "Services and prices"     │
+│ one line on parts            │
+│ ──────────────────────────── │
+│ Flat fix               $25   │  ← name and price on one baseline
+│ Tube or patch, tyre checked  │
+│ 15 min · walk in             │
+│ ──────────────────────────── │
+│ Safety check           $49   │
+│ …                            │
+│ What changes the price …     │
+│ Walk in / Book notes         │
+│ [ Book a service ]           │
+└──────────────────────────────┘
+```
+
+At 390 each row becomes a block: service name and price on one baseline, what's done under it, then time and booking in `--t-small` `--ink-2`. The notes column moves under the ledger, followed by the action full width. Never a table that scrolls sideways.
+
+## Finish
+
+- Ledger rows: hairlines from `_finish.md` between rows, a `--hairline-strong` rule above the first and below the last. No zebra stripes, no vertical rules, no card around the table.
+- Service name `--t-body` weight 600; what's done `--t-body` `--ink-2`; time `--t-small` `--ink-2`; price `--t-body` or `--t-lead` weight 600, `tabular-nums`, right-aligned on one edge. "from" in `--t-small` before the number, never as a superscript asterisk.
+- Use real `<table>` markup with a visually quiet header row (`--t-caption` caps, +0.08em) at 1440; at 390 the same rows restyle as blocks (`display: grid` per row) so screen readers keep the structure.
+- The board feel comes from type and rules, not decoration: the shop's display face for the H2 and service names, generous row height, optionally `--paper-2` ground or a chalk/enamel-sign tone if the brand has one.
+- Notes column: two short headed paragraphs ("Walk in", "Book") and the page's one `.btn-primary`. Sticky at 1440 only if the ledger is taller than a screen.
+- "What changes the price" line in `--t-small` under the ledger, max 80ch.
+
+## Content
+
+- Real services and prices from the shop's own price list; "from" only when the price genuinely varies, with the reason stated.
+- What's done in the shop's words, concrete ("strip, clean, rebuild"), not adjectives ("premium care").
+- Turnaround as the shop actually delivers it ("same day if dropped off by 9 am", "5 working days", "48-hour express +50%").
+- Walk-in vs booking stated plainly. One action: "Book a service", "Book a drop-off".
+- A guarantee only if real ("Free repairs on our own repairs for a year").
+
+## States and motion
+
+- Static. Rows may get a faint `--paper-2` hover at 1440 only if each row links to booking that service (then the whole row is the link, with a visible focus ring).
+- Sold-out or paused service: kept in the ledger with "not taking these until March" in words.
+- No entrance animation; no price count-up.
+
+## Pitfalls
+
+- Plan cards with a “Most popular” badge for a flat fix and an overhaul: services are not tiers.
+- Status pills for turnaround ("Same day!" in green capsules) instead of a plain time column.
+- Prices hidden behind "Get a quote" for jobs with standard prices.
+- An icon per service in a circle (wrench, scissors) as the main visual (M17).
+- Prices not aligned, or "from" prices with no reason given.
+- A table that scrolls sideways at 390.
+
+## Floor checks
+
+- Is every service on its own ruled row with its price aligned on one right edge?
+- Does each service say what is done and how long it takes, in plain words?
+- Are “from” prices explained by a line on what changes the price?
+- Is it clear which services need booking and which are walk-in?
+- Is the section free of plan cards, badges and coloured status pills?
+- Is there exactly one primary action for booking or getting in touch?
+- At 390, does each service read as a block with name and price on one line and nothing scrolling sideways?

package/kb/sections/signup-form-with-next-steps.md

@@ -0,0 +1,86 @@
+---
+id: signup-form-with-next-steps
+name: Signup form beside exactly what happens next
+kind: signup
+shape: form-led
+layout: "the signup form on the left, short and complete; on the right the three things that happen after submitting, each shown as the real artefact (the email, the first screen, the invite), in time order"
+fits: [saas, b2b, education, health, finance, trustworthy, honest, calm, productivity, nonprofit, events, consumer]
+avoid: [experimental, artsy, gaming, playful-kids, food, portfolio]
+needs: ["a signup that needs 2–5 fields (a demo request, an account, an application, a booking)", "the real next steps and their timing", "the real first email or first screen to show"]
+imagery: product-ui
+density: balanced
+effort: m
+---
+
+## When it's right
+
+Signups with more than one field and some anxiety attached: requesting a demo, applying to a programme, booking a consultation, creating an account that will email you. The visitor's hidden question is "what happens after I press this?". The right column answers it with the real artefacts (the confirmation email as it will arrive, the calendar invite, the first screen), so the form feels safe to fill. Not for one-field waitlists (use `signup-waitlist-place-in-line`).
+
+## Structure
+
+```
+1440 ─ container 1200
+┌──────────────────────────────────────────────────────────────────────────┐
+│ ┌ form (cols 1–5) ─────────────────┐   ┌ what happens next (cols 7–12) ─┐ │
+│ │ H2 "Book a 20-minute walkthrough"│   │ ① Within a minute              │ │
+│ │                                  │   │ ┌ email, as it arrives ──────┐ │ │
+│ │ Work email                       │   │ │ From: Priya at Acme        │ │ │
+│ │ [ you@company.com            ]   │   │ │ Pick a time that suits you │ │ │
+│ │ Team size                        │   │ └────────────────────────────┘ │ │
+│ │ [ 1–10 ▾ ]                       │   │ ② On the call                  │ │
+│ │ What should we cover? (optional) │   │   your data, not a slide deck; │ │
+│ │ [                            ]   │   │   20 min, ends on time         │ │
+│ │                                  │   │ ③ After                        │ │
+│ │ [ Book the walkthrough ]         │   │   a trial workspace with your  │ │
+│ │ No sales follow-up unless you    │   │   setup, kept for 30 days      │ │
+│ │ ask. Privacy →                   │   │                                │ │
+│ └──────────────────────────────────┘   └────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390
+H2
+form fields (full width), button full width, reassurance
+"What happens next" heading, then ① ② ③ stacked, artefacts full width
+```
+
+At 390 the form comes first; the next steps follow under a small heading. On submit, the page scrolls the confirmation into view at the form's position.
+
+## Finish
+
+- Form column on the page surface; the next-steps column on a quiet surface one step off the background (no shadow), with the artefacts inside it raised slightly (`--shadow-1` (resting, `_finish.md`)), radii nested concentrically.
+- Fields: the page's input recipe, 48px tall, labels above (not placeholders as labels, D08), 20px between fields, optional fields marked "(optional)" rather than required ones starred. Correct `type` and `autocomplete` on each.
+- One primary button, full form width, label names the outcome ("Book the walkthrough"). The page's `.btn-primary`. Reassurance line small secondary with a privacy link.
+- Steps: real numbers (it's a sequence), 24px circles in `--hairline`; step titles body 600 with the timing; artefacts at product scale (the email built in HTML as it renders in a mail client, simplified to its essentials, with the real sender name and subject).
+- Column tops aligned (P04); the steps column's height roughly matches the form so there's no empty half.
+
+## Content
+
+- Ask only what the next step needs; every field must be used. Two to five fields.
+- The steps are what really happens, with real timings, sender names and promises the team keeps ("ends on time", "no follow-up unless you ask").
+- The email artefact uses the real subject line and sender. If those don't exist yet, write them and ship them.
+
+## States and motion
+
+- Validation on submit (not while typing), messages under each field with the fix, focus to the first error, input kept (M39, M42).
+- Submitting: button keeps its label with a spinner (D02). Success: the form is replaced in place by a confirmation that names the next step ("Check you@company.com: Priya's email is on its way") and step ① in the right column gets a "done" check (300ms). Reduced motion: instant.
+- Error from the server: a message above the button with a fallback (an email address).
+- No-JS: the form posts normally to a server-rendered confirmation page.
+
+## Pitfalls
+
+- Ten fields for a demo request.
+- A right column of marketing bullets instead of what happens next.
+- Promises in the steps the team doesn't keep.
+- Placeholder text as the only label.
+
+## Floor checks
+
+- Does every form field have a visible label above it?
+- Is there exactly one primary button, labelled with what the visitor gets?
+- Does the section show what happens after submitting, in order, with timings?
+- Is at least one next step shown as a real artefact (an email, an invite, a screen) rather than only text?
+- Is there a reassurance or privacy line near the button?
+- Are the form and the next-steps column aligned at the top with no large empty area beside either?
+- At 390, does the form come first with full-width fields and button?

package/kb/sections/signup-waitlist-place-in-line.md

@@ -0,0 +1,90 @@
+---
+id: signup-waitlist-place-in-line
+name: Waitlist form that becomes your place in line
+kind: signup
+shape: form-led
+layout: "one email field and an honest line about the wait; on submit the form morphs in place into the visitor's real position, what moves them up, and their referral link"
+fits: [waitlist, launch, saas, ai, developer, community, consumer, honest, friendly]
+avoid: [enterprise-compliance, government, clinical, luxury, finance-trust-first, crisis]
+needs: ["a backend that stores signups and returns a real position", "a real count and cadence of invites (e.g. 50 a week)", "a referral rule that actually moves people up, if referrals are used"]
+imagery: none
+density: airy
+moves: [copy-confirmation, referral-reward-reveal, shape-continuity-morph, waitlist-position-live]
+effort: m
+---
+
+## When it's right
+
+Invite-only and pre-launch products. The usual waitlist form ends with "Thanks!" and the visitor forgets. This one ends with something real: your number, how fast the line moves, and what you can do to move up. Combines the moves `waitlist-position-live` and `referral-reward-reveal`, with `shape-continuity-morph` for the transition. Use as the signup section or as the page's closing when the hero doesn't carry the form. Not when there is no real queue (a fake number is worse than none).
+
+## Structure
+
+```
+1440 ─ container 1200, form block cols 3–10 (or left-aligned cols 1–7 beside a quiet aside)
+BEFORE
+┌──────────────────────────────────────────────────────────────────────────┐
+│ H2 "We let in 50 people a week"                                          │
+│ 2,184 people are waiting. We invite in signup order, every Tuesday.      │  ← real count, real cadence
+│ ┌───────────────────────────────────────┬────────────────────┐          │
+│ │ you@work.com                          │ Join the waitlist  │          │  ← joined field + button
+│ └───────────────────────────────────────┴────────────────────┘          │
+│ One email when it's your turn. No newsletter.                            │
+└──────────────────────────────────────────────────────────────────────────┘
+AFTER (same box, morphed)
+┌──────────────────────────────────────────────────────────────────────────┐
+│ You're #2,185                                    about 6 weeks at 50/wk  │  ← position, display size
+│ ▕████████████████████████░░░░░░░░░░▏  invited so far: 1,840             │  ← progress of the queue
+│ Move up 100 places for each friend who joins:                            │
+│ ┌──────────────────────────────────────────┬────────┐                    │
+│ │ acme.com/w/k7f2                          │ Copy ⧉ │                    │  ← referral link, copy confirmation
+│ └──────────────────────────────────────────┴────────┘                    │
+│ We sent a confirmation to you@work.com. Wrong address? Change it         │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390
+H2, count line
+field (full width), button (full width), reassurance
+after: position, estimate under it, queue bar, referral link + copy (stacked), confirmation line
+```
+
+At 390 the field and button stack (both 52px tall, full width); after submit, the same box shows the position, then the estimate on its own line.
+
+## Finish
+
+- The form block sits on a raised surface (`--shadow-1` (resting, `_finish.md`), `--r-lg`) only if the section needs a focal object; otherwise directly on the page. One container, morphing between states, so the result appears where the eye already is.
+- Joined field + button, 52–56px tall; field's inner radius and the button's radius nest concentrically inside the joined container (D24). Field label visually present or a clear placeholder plus an `aria-label`; `type="email"`, `autocomplete="email"`.
+- Count line body secondary; the count `tabular-nums`. Reassurance small secondary.
+- After state: position in display size, `tabular-nums`, weight 600; estimate small secondary on the same baseline right. Queue bar 6px, track `--hairline`, fill accent (`scaleX`). Referral link in mono (it's a value), with a copy button (`copy-confirmation`).
+- The page's `.btn-primary`; label "Join the waitlist", not "Submit".
+
+## Content
+
+- The count and the invite cadence are real and come from the backend; if invites are irregular, say "We invite in batches; the last was 12 Oct".
+- The estimate is computed from the real cadence and shown as a range or "about"; never promised.
+- Referral rule stated exactly and enforced by the backend. If there is no referral, skip that row and show "what happens next" instead.
+- One email field only. No name, company, role before the visitor is in.
+
+## States and motion
+
+- Submit: button keeps its label with an inline spinner (D02); on success the box morphs (height and content crossfade, 300ms, ease-out) into the after state; focus moves to the position heading; `role="status"` announces "You're number 2,185".
+- Already on the list: show their existing position, not an error.
+- Invalid email: inline message under the field with the fix, input preserved (M39). Network error: say so, keep the value, offer retry.
+- Reduced motion: instant swap. No-JS: the form posts and the server renders the after state on its own page.
+
+## Pitfalls
+
+- A fake, ever-rising count or a position that's random.
+- Confetti and a modal over the result.
+- Asking for five fields to join a waitlist.
+- Referral links that don't actually move anyone.
+
+## Floor checks
+
+- Is there a single email field with one clearly labelled button?
+- Does the section state a real count or invite cadence, so the wait is concrete?
+- Is there a reassurance line about what emails the visitor will get?
+- Is the field and button pair visually joined or clearly grouped, with matching heights?
+- Is the form the focal point, with no competing primary action in the section?
+- At 390, are the field and button full width and at least 44px tall?

package/kb/sections/spec-sheet-features.md

@@ -0,0 +1,108 @@
+---
+id: spec-sheet-features
+name: Features as a spec sheet
+kind: features
+shape: table
+layout: "features as grouped ruled rows (label | value | note) in 7/12, an optional technical drawing pinned in 5/12; tabular figures, exact units, group headings on the rules"
+fits: [hardware, developer, technical, scientific, serious, honest, data-rich, crafted, b2b, enterprise]
+avoid: [playful-kids, kids, fashion, luxury, consumer]
+needs: ["8–30 precise facts about the product (limits, formats, sizes, versions, standards)", "optional: a drawing or diagram of the product or its architecture"]
+imagery: none
+density: dense
+effort: s
+moves: [technical-drawing-lines, code-drawn-diagram, real-world-data]
+---
+
+## When it's right
+
+The buyer reads specifications: an engineer comparing SDKs, a purchaser checking a device, an admin checking limits and compliance. For them, a well-set spec sheet is more persuasive than any illustration: grouped, ruled rows of label, value and note, with exact units and real versions, the way a datasheet or a camera's spec page is set. Paired with a technical drawing of the product (or its architecture), the section looks engineered rather than marketed.
+
+Use it after the product has been shown working, as the section that answers "and the details?". Not for consumer brands sold on feeling, or when the facts are few and vague (fewer than eight facts: use `ruled-facts-table` as a short stats block instead). For plan differences, use a pricing archetype.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gutter 24
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ H2 cols 1–6 ("Specifications")            download datasheet (PDF) link, right│
+│                                                                    --s-7      │
+│ ┌ cols 1–7: the sheet ─────────────────────────────┐ ┌ cols 8–12, sticky ────┐│
+│ │ Runtime ─────────────────────────────────────────│ │                        ││  ← group heading sits on the
+│ │ Languages     TypeScript 5.4+, Python 3.10+   ¹  │ │  technical drawing:    ││    rule (label, then the line
+│ │ Cold start    38 ms p50 · 120 ms p99          ²  │ │  the device in three   ││    continues)
+│ │ Memory        128 MB – 4 GB, per function        │ │  views, or the system  ││
+│ │ Storage ─────────────────────────────────────────│ │  as a line diagram,    ││
+│ │ Max object    5 TB                               │ │  ink lines 1–1.5px,    ││
+│ │ Durability    11 nines, 3 zones                ³ │ │  dimension marks       ││
+│ │ Compliance ──────────────────────────────────────│ │                        ││
+│ │ Certified     SOC 2 Type II (2025), ISO 27001    │ │  dims in caption size  ││
+│ │ …                                                │ └────────────────────────┘│
+│ │ label 3/7 · value 3/7 · note 1/7                 │                           │
+│ └──────────────────────────────────────────────────┘                           │
+│ ¹ ² ³ footnotes: source, date, conditions — caption size, ink-3                │
+└──────────────────────────────────────────────────────────────────────────────┘
+  rows 44–52 tall; 3–5 groups of 3–8 rows
+```
+
+```
+390 ─ one column, side padding 16
+┌──────────────────────────────┐
+│ H2                           │
+│ ┌ drawing, 4:3, small ─────┐ │  ← drawing first, 240px tall max
+│ └──────────────────────────┘ │
+│ Runtime ──────────────────── │
+│ Languages                    │  ← label on its own line,
+│ TypeScript 5.4+, Py 3.10+ ¹  │    value under it, note marker inline
+│ ──────────────────────────── │
+│ Cold start                   │
+│ 38 ms p50 · 120 ms p99    ²  │
+│ …                            │
+│ footnotes                    │
+└──────────────────────────────┘
+```
+
+At 390 the drawing moves above the sheet at 4:3 (max 240px tall). Rows become two-line pairs: label in `--ink-2` small, value under it in ink; the note becomes a footnote marker. Groups stay; nothing scrolls sideways. With more than 20 rows, groups after the first two become disclosure sections, closed by default.
+
+## Finish
+
+- The sheet is a real `<table>` per group (or a `<dl>` with grid), with `<caption>` or a group heading. Rows `padding-block: --s-3`, 1px `--hairline` between rows, `--hairline-strong` on the group rule (`_finish.md` hairlines). No zebra, no vertical rules, no boxes.
+- Group heading: `--t-small`, weight 600, ink, sentence case, sitting on its rule (the rule starts after the word: a flex row with the line as `flex: 1; border-top`). Tracked caps allowed here only if the page uses them nowhere else (M16, M18).
+- Label column: `--t-small`–`--t-body`, `--ink-2`. Value column: `--t-body`, ink, weight 500, `font-variant-numeric: tabular-nums lining-nums`, units after a non-breaking space in `--ink-2` (`_finish.md` numbers). Monospace only for literal values the machine prints (version strings, CLI flags, MIME types).
+- Notes: superscript markers that link to footnotes; or a short note column in `--t-caption`, `--ink-3`.
+- Drawing: line art in ink at 1–1.5px with dimension lines and arrowheads, labels in `--t-caption` (move `technical-drawing-lines`), on `--paper` with optional faint grid (`--hairline` at 24px). Sticky `top: 96px` beside the sheet. Never a rendered 3D blob.
+- Ground: `--paper` or `--paper-2`; this section can carry a faint paper fibre if the page is crafted (`_finish.md` textures), never grain over the numbers.
+- Datasheet link: a text link with a file type and size ("Datasheet, PDF, 420 KB"), only if the file exists.
+
+## Content
+
+- Every value exact and from the project: versions, limits, sizes, standards, dates. Ranges with an en dash, units in SI or the domain's convention.
+- Measured values carry conditions in a footnote ("p50 over 7 days, us-east, Oct 2026").
+- Group by the questions buyers ask (Runtime, Limits, Security, Integrations), 3–8 rows each, most-asked group first.
+- Never round to impress or invent a certification. "Planned" items are marked as planned with a date, or left out.
+- The drawing shows the real product or architecture, with real dimensions if it is hardware.
+
+## States and motion
+
+- Static. Row hover: a faint `--paper-2` row background so the eye can track across (only on desktop, only if rows are wide).
+- Drawing: optional one-time line draw on entering view (stroke-dashoffset, 900ms), finished state under reduced motion and no JS.
+- Disclosure groups (phone, long sheets): native `<details>`, the group heading as `<summary>` with a chevron rotating 90° in 160ms.
+- Footnote markers jump to their note and back (anchor links with `scroll-margin-top`).
+
+## Pitfalls
+
+- Vague values ("Fast", "Enterprise-grade", "Unlimited*") in a format that promises precision.
+- Mono everywhere to look technical (M18).
+- Ticks and crosses: that is a comparison table, not a spec sheet.
+- A drawing that is decoration (an isometric blob, a generic server icon) rather than this product.
+- Rows of very long prose values: move prose to docs and keep the value terse.
+- Zebra stripes plus rules plus boxes (P28, M36).
+
+## Floor checks
+
+- Are the facts set as ruled rows of label and value, grouped under clear headings?
+- Do the values use exact figures with units rather than adjectives?
+- Do numbers in the value column line up, using tabular figures?
+- Are measured values or claims marked with a note or footnote that gives conditions or a source?
+- If there is a drawing, does it show this product or its architecture with line work and labels, rather than a generic illustration?
+- Is the sheet free of zebra stripes, boxed cells and tick/cross marks?
+- At 390, does every row read as label then value without sideways scrolling?