@palate/cli 0.0.0-stage → 0.0.1

package/kb/sections/_finish.md

@@ -0,0 +1,325 @@
+---
+title: The shared finishing standard for every section archetype
+---
+
+# Finish: the shared standard
+
+Every archetype in `kb/sections/` points here instead of repeating these recipes. They are the difference between a layout that is right and a page that looks finished. Values are starting points tuned for a 16–17px body; keep the ratios when the project's scale differs. When the project already has tokens for any of this, use the project's tokens and keep the rule.
+
+**This is craft, not a look.** How a shadow is built, how radii nest, how a button behaves: those hold everywhere. The page's look (its ground, its type, its texture, its header, its buttons, its imagery) is not here: it comes from the product's own research and the blueprint, and it must differ from palate's recent pages. A page that is cream paper with grain, a serif headline, a framed product card and a pill button top right because those are "palate's defaults" has failed, however well it is finished. The colour values below are placeholders to show the roles, not a palette.
+
+## Tokens the archetypes refer to
+
+```css
+:root {
+  /* spacing: one scale, nothing off it (P12) */
+  --s-1: 4px; --s-2: 8px; --s-3: 12px; --s-4: 16px; --s-5: 24px; --s-6: 32px;
+  --s-7: 48px; --s-8: 64px; --s-9: 96px; --s-10: 128px;
+
+  /* type: one ratio (here ×1.25 from 16), each size has a job */
+  --t-caption: 13px;   /* credits, footnotes, units */
+  --t-small: 14px;     /* secondary UI, labels */
+  --t-body: 16px;      /* 17–18px on reading-heavy pages */
+  --t-lead: 20px;      /* the paragraph under a headline */
+  --t-h3: 25px;
+  --t-h2: clamp(32px, 2.2vw + 18px, 48px);
+  --t-display: clamp(44px, 5.2vw + 12px, 88px);
+  --t-giant: clamp(96px, 14vw, 240px);   /* one per page at most: a numeral or a statement */
+
+  /* layout */
+  --container: 1240px;           /* 1200–1280 */
+  --gutter: 24px;                /* 12-column grid at 1440 */
+  --page-x: clamp(16px, 4vw, 48px);  /* side padding; 16–20px at 390 */
+
+  /* radius scale: three steps plus pill (P27) */
+  --r-sm: 6px; --r-md: 12px; --r-lg: 20px; --r-pill: 999px;
+
+  /* colour roles: ink is the text colour, everything tints from it */
+  --ink: oklch(22% 0.02 260);
+  --ink-2: color-mix(in oklab, var(--ink) 72%, var(--paper));  /* secondary text */
+  --ink-3: color-mix(in oklab, var(--ink) 52%, var(--paper));  /* tertiary, still ≥ 4.5:1 on paper: check */
+  --paper: oklch(98.5% 0.006 85);   /* page ground: a placeholder. The blueprint decides it from the product (white, a colour, a dark ground, a photograph, a warm stock); no default */
+  --paper-2: color-mix(in oklab, var(--paper) 94%, var(--ink));  /* second surface tone */
+  --surface: color-mix(in oklab, var(--paper) 60%, white);      /* raised cards sit lighter than the ground */
+  --brand: oklch(55% 0.17 250);
+  --on-brand: white;
+  --focus: var(--brand);
+}
+```
+
+Section archetypes say "h2", "lead", "`--s-7`", "`--r-lg`" and mean these.
+
+## Raised surfaces: the layered shadow
+
+One shadow is a smudge. Real depth is a tight contact shadow plus a soft ambient one, tinted with the ink colour so it belongs to the palette (grey shadows on a warm paper look dirty, M34). Three levels only (P29): resting, raised, floating.
+
+```css
+:root {
+  --sh-tint: var(--ink);
+  --shadow-1: /* resting: cards that sit on the page */
+    0 0 0 1px color-mix(in oklab, var(--sh-tint) 7%, transparent),
+    0 1px 2px color-mix(in oklab, var(--sh-tint) 8%, transparent),
+    0 2px 6px -2px color-mix(in oklab, var(--sh-tint) 8%, transparent);
+  --shadow-2: /* raised: the product frame, the dominant tile */
+    0 0 0 1px color-mix(in oklab, var(--sh-tint) 7%, transparent),
+    0 2px 4px -2px color-mix(in oklab, var(--sh-tint) 12%, transparent),
+    0 16px 32px -12px color-mix(in oklab, var(--sh-tint) 18%, transparent);
+  --shadow-3: /* floating: menus, popovers, the hero object lifted off a photo */
+    0 0 0 1px color-mix(in oklab, var(--sh-tint) 8%, transparent),
+    0 4px 8px -4px color-mix(in oklab, var(--sh-tint) 14%, transparent),
+    0 32px 64px -16px color-mix(in oklab, var(--sh-tint) 26%, transparent);
+}
+/* On a coloured band, tint the shadow with that band's darkest shade, not the page ink. */
+.band-brand { --sh-tint: color-mix(in oklab, var(--brand), black 55%); }
+```
+
+- The first layer (`0 0 0 1px`) replaces a border: do not add a `border` as well (that is two edges, M36).
+- Negative spread on the big layer keeps the shadow under the object instead of haloing its sides.
+- **Dark surfaces:** shadows barely read on dark. Separate by lightness (each level about 4% L lighter) plus a top highlight: `box-shadow: inset 0 1px 0 rgb(255 255 255 / .06), 0 0 0 1px rgb(255 255 255 / .08), 0 16px 32px -12px rgb(0 0 0 / .5);`
+- Not every surface is raised. Text columns, ruled lists and image bands are flat; a page where every box has a shadow has no depth at all.
+
+### The product frame
+
+How product UI built in code is presented (heroes, demos, feature tiles). No traffic-light dots, no fake URL bar (M19, L03).
+
+```css
+.product-frame {
+  border-radius: var(--r-lg);             /* 16–20 */
+  background: var(--surface);
+  box-shadow: var(--shadow-2);
+  overflow: clip;
+  padding: 0;                              /* the UI inside owns its padding */
+}
+.product-frame > .chrome {                 /* the product's own top bar, skeletonised (L02) */
+  height: 40px; display: flex; align-items: center; gap: var(--s-2); padding-inline: var(--s-4);
+  border-bottom: 1px solid var(--hairline);
+}
+```
+
+Inside: real labels and data from the project, unimportant chrome reduced to soft bars (`background: var(--paper-2); border-radius: var(--r-sm); height: 8px`), and one thing that happens. Text inside the frame must be readable at 100% on desktop (P40): if it is not, crop tighter and scale up.
+
+## Product frames
+
+How a product window, a screenshot or a device sits in a hero or a section. The recipe for the frame itself is above; this is about its size and its edges.
+
+- Size: the window takes about two thirds of its stage's width (never under half in a hero). A small window floating in the middle with a margin all round reads as a thumbnail, not a product (the floor's FRAME_SMALL).
+- Bleed: it runs off one edge of the section. In a split hero, the right edge to the viewport; under a centred lockup, the bottom edge into the next band. The section clips it (`overflow-x: clip` or `overflow: clip`), so the page never scrolls sideways.
+- Only filler bleeds. What the edge cuts is secondary UI: the end of a sidebar, extra rows, the older half of a chart. The part the words talk about sits fully in view. If the edge would cut it, move the content inside the frame, not the edge.
+- One frame style per page: the same radius, the same edge (a shadow or a 1px border, not both) and the same shadow level on every window, screenshot and device. A second style only for a different kind of object (a phone beside a desktop window), and then still the same shadow.
+- Real screenshots follow the same rules as code-built UI: real data, readable at 100%, no fake browser chrome, no glow behind.
+
+## Bento grids
+
+A bento is a hierarchy, not a grid of boxes.
+
+- One lead tile. It spans two columns or two rows and carries the section's main point; the other tiles support it. Equal tiles say every point is equal; then use a list (BENTO_FLAT).
+- Neighbours contrast. Two tiles that touch differ in size, surface or content type: a picture beside text, a figure beside a fragment, a light tile beside the inverted one. Never two identical tiles side by side (BENTO_TWINS).
+- One inverted tile per grid: exactly one tile on the inverse ground (dark on a light page, light on a dark page), as the accent on the supporting point that matters most. Alternating light and dark is noise (INVERT_OVERUSE). A grid where every tile is dark is a dark system, not an accent, and that is fine.
+- A figure sits close under its words. Never pin it to the tile's bottom with an empty band above it; give spare height to a picture pinned to the bottom edge instead (TILE_VOID).
+- Never cut real words. A tile may crop decorative filler at its edge (a UI fragment, a pattern, a photo); a heading, a sentence or a number stays whole inside the padding (WORDS_CUT fails it).
+- One radius, one gap (`--s-4`), one tile padding (`--s-5`) across the grid; nested frames inside tiles follow radius nesting.
+- Motion: at most one motion per tile, at most one tile moving on its own, entrances staggered 60–90ms apart. All of it off under `prefers-reduced-motion: reduce`, with each tile in its finished state.
+- At 390: the lead tile first, the rest in order of importance, full width; two short tiles may pair only if both still read.
+
+## Buttons
+
+How a button looks is not here: it is the page's **button language**, chosen per product in the blueprint (`look.buttons`) from a library of languages in `_buttons.md` (an underlined line in the display face, a stamped ticket, a tracked outline, a keycap, a big pill, a tinted button, a price inside the button…). palate writes `.btn-primary` and `.btn-secondary` for it into the tokens. Use those two classes everywhere; a section never invents its own button, and never falls back to a filled box with an underlined link because that is the habit.
+
+What every language keeps, whatever it looks like:
+
+- **One primary per view** (P09). It is the heaviest action in the section, and in the hero it outweighs the header's action. Any second action is quieter: the language's secondary, never a second primary of equal weight.
+- **Labels name the action and its object** ("Pre-order the box", "Install the CLI", "Ask about your date"), never "Get started" or "Learn more" (M09). An arrow only when the action goes somewhere.
+- **States**: hover, pressed (a 1px sink or a closing offset), `:focus-visible` (a 2px outline in the focus colour, offset 2px, or 4px for a text action), disabled (half opacity, `not-allowed`, no press), loading (keeps its label, adds a spinner after 150ms, D02).
+- **Contrast**: the label at 4.5:1 or more on its own fill (or on the ground, for a text action or an outline); an outline's edge at 3:1 against what's behind it. On a photograph, a calm area or a scrim under it.
+- **Tap area**: 44px or more on every action. A compact button keeps its look and grows its hit area with a pseudo-element; a text action gets the height from its box, not from padding you can see.
+- **One height per row** (never two sizes side by side), and the same language in the hero, the plans, the forms and the closing.
+- **Motion**: 160ms ease-out on hover and press; under `prefers-reduced-motion: reduce`, no movement, only the colour change.
+- **No gradients, no glossy top highlight**: they read as software chrome on most products, and the user's rules may forbid them.
+
+## Hairlines
+
+```css
+:root {
+  --hairline: color-mix(in oklab, var(--ink) 12%, transparent);         /* dividers, ruled lists, frames */
+  --hairline-strong: color-mix(in oklab, var(--ink) 22%, transparent);  /* inputs, secondary buttons, table heads */
+}
+hr, .rule { border: 0; border-top: 1px solid var(--hairline); }
+```
+
+- Always 1px, always tinted from the ink (or from the band's colour on a coloured band), never `#e5e5e5` (P28, M34). Two hairline tokens for the whole site.
+- A rule is a structural line: use it to separate rows in a list or a table, and to set a section's top edge in an editorial layout. Never stack a rule against a background change or a card edge (M28).
+- Rules in ruled lists run the full width of the list column, including under the number or label; they do not stop at the text.
+
+## Radius nesting
+
+Inner radius = outer radius − the padding between them (M35, P27). When the padding is equal to or larger than the outer radius, the inner radius is small (2–6px), not zero and not equal.
+
+| Outer | Padding | Inner |
+|---|---|---|
+| 20 (`--r-lg`) | 8 | 12 |
+| 20 | 12 | 8 |
+| 12 (`--r-md`) | 4 | 8 |
+| 12 | 16 | 4 |
+| pill | 4 | pill |
+
+```css
+.frame { --r: var(--r-lg); --pad: 8px; border-radius: var(--r); padding: var(--pad); }
+.frame > * { border-radius: max(4px, calc(var(--r) - var(--pad))); }
+```
+
+Images inside a card with no padding inherit the card's radius through `overflow: clip`; do not round the image separately.
+
+## Numbers
+
+- Numbers that are compared, aligned in columns or that change (prices, tables, timers, counters, stats) get tabular figures **in the body face**: `font-variant-numeric: tabular-nums lining-nums;` (P25, D11). Check the face has `tnum`; some faces change numeral shapes when it is on.
+- Monospace only for real code, IDs, hashes, timestamps in logs and measured technical values shown as the machine prints them (`p95 182 ms` in a trace). Not for stats, prices, labels or section numbers (M18).
+- A non-breaking space between number and unit (`12 min`), a thin space or the locale's separator for thousands, one decimal rule per context (D12). Units step down to small size and secondary colour beside a big figure, on the same baseline.
+- Never count up on scroll (M11). Show the final value.
+- Every number on a marketing page has a source the project can name: a footnote, a date, a link. If it has none, it is not shown.
+
+## Section rhythm
+
+- Two section spacings, set by role, never case by case (P14):
+  ```css
+  :root { --section: clamp(72px, 7vw + 24px, 128px); --section-tight: clamp(48px, 4vw + 16px, 80px); }
+  ```
+  `--section` between unrelated sections; `--section-tight` where one section continues the last (a demo straight under its hero, a stat after the claim it backs).
+- Two sections on the same background share one gap, not two paddings added together. Use `padding-block` on sections with their own ground and `margin-block` (which collapses) or a single spacer when grounds match.
+- Inside a section: heading to its content `--s-7` (48), heading to its lead `--s-4`–`--s-5`, lead to buttons `--s-6`. More space above a heading than below it (P13).
+- No band inside a section taller than 160px with nothing in it (P38). If the layout leaves a hole, the layout is wrong; do not fill it with a decorative blob.
+
+## Background planning
+
+Plan the page's grounds before building sections. A page is a sequence of bands, and the eye reads the band changes as chapters.
+
+- At least two surface tones (`--paper` and `--paper-2`, 3–6% apart in lightness), or one material or imagery band (a full-bleed photograph, a painted stage, a dark inverted band, a textured band). Never one flat colour top to bottom.
+- Change ground at role boundaries (hero → product, product → story, story → pricing, pricing → closing): 2–4 changes per page. Not a zebra: alternating every section is as flat as never changing.
+- One inverted band at most (ink ground, paper text) and usually near the end (closing or a single statement). Darken by the brand's darkest shade, not `#000`.
+- Write the plan into the brief as a line, e.g. `paper · paper-2 (demo) · photo band · paper · ink (closing) · paper (footer)`.
+- A band change never sits directly against a card edge or a rule (M28): leave at least `--s-8` inside the band before the first raised surface.
+
+## Textures in code
+
+Texture is for material bands, image stages and illustration grounds, and only when the product's own material calls for it (paper for a bindery, speckle for a pottery, nothing for most software). It is not a default finish: a page with no texture is normal. Never over body text, forms or product UI. Static: no animated grain.
+
+### Grain (fine noise, 3–6%)
+
+```css
+.grain { position: relative; isolation: isolate; }
+.grain::after {
+  content: ""; position: absolute; inset: 0; z-index: 1; pointer-events: none; border-radius: inherit;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='180' height='180'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.85' numOctaves='3' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23g)'/%3E%3C/svg%3E");
+  opacity: .05;                 /* 0.03–0.06 on flat grounds; 0.3–0.45 with overlay on paintings (see move canvas-grain) */
+  mix-blend-mode: multiply;     /* light grounds; use screen on dark grounds, overlay on photographs */
+}
+```
+
+### Paper fibre
+
+Stretched turbulence reads as fibres; a second, coarse layer gives the uneven mottling of real paper.
+
+```css
+.paper {
+  background-color: var(--paper);
+  background-image:
+    url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='400'%3E%3Cfilter id='f'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.004 .32' numOctaves='2' seed='3' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23f)' opacity='.5'/%3E%3C/svg%3E"),
+    url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='600' height='600'%3E%3Cfilter id='m'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.012' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23m)' opacity='.35'/%3E%3C/svg%3E");
+  background-blend-mode: multiply, multiply;
+}
+```
+
+Tune so the fibre is only visible at 200% zoom on a calibrated screen. If you can see it at arm's length, halve it.
+
+### Halftone
+
+Dots on a grid, sized by a gradient. Good for an illustration ground, a band edge or a printed feel (pairs with moves `halftone-dot-imagery` and `riso-print-texture`).
+
+```css
+.halftone {
+  --dot: color-mix(in oklab, var(--ink) 18%, transparent);
+  background: radial-gradient(circle, var(--dot) 0 1.1px, transparent 1.5px) 0 0 / 7px 7px;
+  -webkit-mask-image: linear-gradient(to bottom, #000 0%, transparent 85%);
+          mask-image: linear-gradient(to bottom, #000 0%, transparent 85%);
+}
+```
+
+For a halftone of a photograph, do it at build time (sharp/canvas threshold into dots) or with an SVG filter on a small image; never ship a full-colour photo and a dot overlay that fight.
+
+## Image treatment
+
+- **One treatment for every photograph on the page.** Either duotone (two colours from the palette) or tone-matched (the same grade applied to all: white balance, contrast and saturation brought together). Mixed treatments make a page look assembled from stock.
+- **Duotone** (pairs with move `duotone-photography`):
+  ```html
+  <svg width="0" height="0" aria-hidden="true" style="position:absolute">
+    <filter id="duo" color-interpolation-filters="sRGB">
+      <feColorMatrix type="matrix" values=".33 .33 .33 0 0  .33 .33 .33 0 0  .33 .33 .33 0 0  0 0 0 1 0"/>
+      <!-- shadows → ink (r .09 g .10 b .16), highlights → paper (r .98 g .97 b .94) -->
+      <feComponentTransfer>
+        <feFuncR type="table" tableValues=".09 .98"/>
+        <feFuncG type="table" tableValues=".10 .97"/>
+        <feFuncB type="table" tableValues=".16 .94"/>
+      </feComponentTransfer>
+    </filter>
+  </svg>
+  <img class="duo" src="…" alt="…" width="1600" height="1067" style="filter:url(#duo)">
+  ```
+  Better still: bake it at build time so the file is small and the filter costs nothing.
+- **Tone-matched**: `filter: saturate(.86) contrast(1.04) sepia(.06);` on all photos, or the same LUT applied at build time. Check side by side: skin tones and whites should agree across images.
+- **Crops**: pick two aspect ratios for the page (for example 3:2 for bands, 4:5 for portraits) and crop to them; set `width`/`height` so nothing shifts; `object-fit: cover` with a deliberate `object-position` on the subject.
+- **Credits** in caption size, secondary colour, under the image or inside its bottom corner on a scrim: `Photo: Name, Source (licence)`. A painting's caption gives artist, title, year and collection. Credits are not optional for anything you did not make.
+- **Never** stock "team at a laptop", generated people, or a photo that is not of this product, its makers, its users or its subject (M47). If the project has no real images, choose an archetype with `imagery: type`, `texture`, `illustration` or `product-ui`.
+- Text over a photo sits on a scrim (`linear-gradient(to top, color-mix(in oklab, var(--ink) 70%, transparent), transparent 60%)`) or in a calm area of the picture, and passes 4.5:1 at every crop (P36).
+
+## Type details
+
+- **Two faces at most**: a display face with character and a quiet text face, or one family used well. Two or three weights (P19).
+- **Optical sizes**: `font-optical-sizing: auto;` on variable faces with an `opsz` axis; for display sizes in a face without one, use its Display cut.
+- **Tracking by size** (P20, P21):
+
+  | Size | Tracking |
+  |---|---|
+  | ≤ 13px | +0.01em |
+  | 14–24px | 0 |
+  | 25–47px | −0.015em |
+  | 48–71px | −0.025em |
+  | 72–119px | −0.03em |
+  | 120px + | −0.035em to −0.04em |
+  | Caps labels ≤ 20px | +0.06em to +0.1em |
+
+- **Leading**: display 0.95–1.05, h2 1.1, h3 1.2, body 1.5–1.6, captions 1.4 (P18).
+- **Wrapping**: `text-wrap: balance` on headings (up to 6 lines), `text-wrap: pretty` on paragraphs and captions (P24, M31). Paragraphs `max-width: 62ch` (P17).
+- **Hanging punctuation**: opening quotes and bullets hang into the margin so the text edge stays straight.
+  ```css
+  blockquote, .pull-quote { hanging-punctuation: first allow-end last; }   /* Safari only */
+  .hang { margin-left: -0.42em; }   /* elsewhere: wrap the opening “ in <span class="hang">; tune per face */
+  ```
+- **Punctuation**: curly quotes, `…`, en dash for ranges (2–4), em dash or spaced en dash for breaks, `×` for dimensions, `→` only for links that go somewhere (M32).
+- **Small caps and figures**: `font-variant-caps: all-small-caps` for acronyms in running text if the face has them; oldstyle figures (`onum`) in long editorial prose, lining tabular figures everywhere numbers are compared.
+- **Emphasis** comes from size, weight and the line break. No gradient text, no single accented word (M02, M14).
+
+## Motion defaults
+
+- Ease-out `cubic-bezier(.23,1,.32,1)` for things that enter or respond; 160–240ms for UI, 400–700ms for a section's one moment.
+- Nothing in the first viewport starts at `opacity: 0` (M45). Reveal only below the fold, and not every section the same way (M44).
+- One loud moment per two sections at most (L17). Everything that loops pauses off screen, while hovered or focused, and under `prefers-reduced-motion: reduce` shows its finished state.
+
+## Logos and icons in demos and mockups
+
+- **Placeholder company logos** (a product mockup's integrations list, a fictional customer's workspace, a benchmark demo): take them from Hugeicons' free placeholder logos (https://hugeicons.com/logos: "free placeholder company logos for your next design mockup"). Copy the SVG you need into the project when you use it; palate doesn't bundle them. They look like real, well-drawn marks without being any real company's.
+- **Never as proof.** On a real product's page, placeholder logos must not appear as "trusted by", customers or press: that's inventing customers. Real logos there only when the project has them, in their official colours (the user's rules R5, R6).
+- **Never draw a fake logo** or a fake object (a barcode card, a stamped receipt) to stand in for something real.
+- **Icons:** the project's own set first. With none, Hugeicons' free icons (MIT: keep the licence notice with the source files) or lucide, one set, one size and one stroke per page.
+
+## Phone rules (390)
+
+- Side padding 16–20px; nothing scrolls the page sideways. Check `document.documentElement.scrollWidth === innerWidth`.
+- Display type steps down to 40–48px (the giant numeral to 96–120px); h2 to 28–32px; body stays 16–17px.
+- Order follows meaning, not the desktop's left-to-right: the headline, then the object it describes, then the supporting text; a split's visual moves under its words unless the visual is the point.
+- The first screen (812px tall) shows the headline, the primary action and the top of the product object. A hero taller than 1.4 screens on phone is too tall.
+- Wide product UI does not shrink to unreadable: crop to the part that matters, scale it to at least 1:1 text, or let it scroll inside its frame with a visible edge.
+- Horizontal strips are allowed inside a section: `overflow-x: auto; scroll-snap-type: x mandatory; scroll-padding-inline: 16px;` with the next item peeking at least 24px, and no scrollbar hiding on desktop.
+- Sticky and scroll-scrubbed sequences become plain stacked content: each step a static frame with its text.
+- Wide photographs re-crop to 4:5 or 1:1 around the subject (`<picture>` with a phone source) instead of becoming a thin strip.
+- Hover-only reveals become visible by default; tap targets 44px; inputs 16px text.
+- Use `100svh`, never `100vh`, for anything sized to the screen.
+- Section spacing steps down to 56–80px; two spacings still.

package/kb/sections/about-founder-note.md

@@ -0,0 +1,85 @@
+---
+id: about-founder-note
+name: A signed note from the people behind it
+kind: about
+shape: editorial-columns
+layout: "a short first-person letter in a readable text column, beside a real photo of the founder(s) at work; signed, dated, with a way to write back"
+fits: [crafted, honest, warm, editorial, launch, waitlist, community, nonprofit, calm, quiet, local, food, sustainability, heritage]
+avoid: [enterprise-compliance, data-dense-tool, government, serious-news]
+needs: ["a real note (150–300 words) from a named founder or small team", "a real photo of them, ideally doing the work", "a way to reach them (email or handle)"]
+imagery: photo
+density: balanced
+moves: [duotone-photography, honest-testimonial-wall]
+effort: s
+---
+
+## When it's right
+
+Early products, small studios, independent makers and nonprofits, where who made it is part of why you'd trust it. A first-person note (why this exists, what they care about, what they won't do) replaces borrowed proof when there are no customers yet; it's the honest alternative the move `honest-testimonial-wall` recommends for products in preview. Not for large companies where a founder letter reads as PR, or regulated contexts that need a formal "About".
+
+## Structure
+
+```
+1440 ─ container 1200
+┌──────────────────────────────────────────────────────────────────────────┐
+│ ┌ photo (cols 1–5) ──────────────┐   ┌ note (cols 7–11) ───────────────┐ │
+│ │                                │   │ H2 "Why we're building this"    │ │
+│ │  real photo of the founder     │   │                                 │ │
+│ │  at the bench / desk / kiln,   │   │ I spent six years fixing other  │ │  ← letter, lead size (`--t-lead`), 60ch
+│ │  4:5, their hands in the work  │   │ people's onboarding… (3–4 short │ │
+│ │                                │   │ paragraphs)                     │ │
+│ │                                │   │                                 │ │
+│ └────────────────────────────────┘   │ What we won't do: sell your     │ │
+│ Ana in the Porto studio, Oct 2026    │ data, add ads, lock your files. │ │
+│                                      │                                 │ │
+│                                      │ ~ Ana Ruiz  (signature)         │ │  ← signature + name + role
+│                                      │ Founder · ana@acme.com          │ │
+│                                      └─────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+```
+390
+photo, full content width, 4:5 cropped to face/hands, caption
+H2
+note (body, 3–4 short paragraphs)
+signature, name, email
+```
+
+At 390 the photo comes first so the reader knows who is talking, then the note in one column.
+
+## Finish
+
+- Photo 5 columns, 4:5, small or no radius (a photograph, not a card), inset 1px outline at 6% (D20), caption under it in small secondary (who, where, when). No filters that fight the page's palette; duotone only if the page uses it elsewhere (`duotone-photography`).
+- The note's column top aligns with the photo's top (P04). Heading h2; letter in lead size (`--t-lead`) (18–20px), line-height 1.6, max 60ch, paragraphs 16px apart, `text-wrap: pretty`.
+- One short "what we won't do" or "what we promise" paragraph set in weight 600 lead words, so a skimmer gets the promise.
+- Signature: a real scanned signature as SVG (40–56px tall, ink colour = primary text) or the name in the display face; then name body 600, role and email small secondary. Email is a link.
+- No quote marks around the letter; it's a letter, not a testimonial.
+
+## Content
+
+- Written by the founder in first person, in their voice; edited for length, not turned into marketing. Specific origin (the moment the problem was felt), what's different, what they won't do.
+- Dated or seasoned ("Written October 2026") if it refers to the present.
+- The photo is of them, real, recent. Never stock, never AI-generated.
+- A real address to write back to, which someone reads.
+
+## States and motion
+
+- Static. The signature may draw itself once on entering view (stroke-dashoffset, 1.2s); final state under reduced motion and no JS.
+- Image lazy-loaded with fixed aspect ratio.
+
+## Pitfalls
+
+- A corporate "Our mission" paragraph in first-person plural with no name.
+- A headshot against a grey backdrop when a photo of them working exists.
+- Long letters: over 300 words, people stop.
+- A cursive font faking a signature.
+
+## Floor checks
+
+- Is there a real photo of the person or people behind the product?
+- Is the note signed with a real name and role?
+- Is the note written in first person with specific details rather than generic mission language?
+- Is the text in a readable column (comfortable line length, left-aligned)?
+- Is there a direct way to contact the author?
+- Do the photo and the note align at the top, with no large empty area beside either?

package/kb/sections/about-team-roster.md

@@ -0,0 +1,86 @@
+---
+id: about-team-roster
+name: The team as a ruled roster, with the work they did
+kind: about
+shape: list-ruled
+layout: "one large real photo of the team or the place on top; under it a ruled roster, one row per person: small photo, name, role, one real thing they made here, where they are, a link"
+fits: [agency, crafted, editorial, community, honest, saas, developer, nonprofit, portfolio, warm, b2b, local]
+avoid: [crisis, data-dense-tool, playful-kids]
+needs: ["3–20 real team members who agreed to be listed", "a real photo of each (or consistent illustrated portraits if the brand uses them)", "one real thing each person made or owns"]
+imagery: photo
+density: balanced
+effort: m
+---
+
+## When it's right
+
+Studios, agencies and small product teams where the people are the product or a reason to trust it. The stock team grid (square headshots, name, title, three social icons) says nothing about who does what. A ruled roster reads like the credits of a film: each row says what this person actually made here, which is the information a buyer or candidate wants. The large photo on top shows the team together or the place where the work happens. Not for large companies (link to a careers page instead) or teams that don't want to be named.
+
+## Structure
+
+```
+1440 ─ container 1200
+┌──────────────────────────────────────────────────────────────────────────┐
+│ H2 "Who makes it"                                     We're hiring: 2 →   │
+│ ┌──────────────────────────────────────────────────────────────────────┐ │
+│ │ one real photo: the team at work / the studio / the workshop, 21:9  │ │
+│ └──────────────────────────────────────────────────────────────────────┘ │
+│ The Porto studio, October 2026                                            │
+│ ────────────────────────────────────────────────────────────────────────  │
+│ (●) Ana Ruiz     Founder, design      Drew the first engine; runs taste  Porto  ↗ │
+│ ────────────────────────────────────────────────────────────────────────  │
+│ (●) Tom Hale     Engineering          Built the renderer that makes pages Lisbon ↗│
+│ ────────────────────────────────────────────────────────────────────────  │
+│ (●) Mei Lin      Support              Answers every email within a day    Remote ↗│
+│ ────────────────────────────────────────────────────────────────────────  │
+└──────────────────────────────────────────────────────────────────────────┘
+cols: photo+name 1–3 | role 4–5 | what they made 6–10 | place 11 | link 12
+```
+
+```
+390
+H2, hiring link
+photo full width (cropped 4:3)
+rows: (●) name / role
+            what they made (2 lines max)
+            place · link
+```
+
+At 390 each row becomes a compact block: avatar 40px beside name and role, then the "made" line, then place and link in small type. Hairlines stay.
+
+## Finish
+
+- Big photo: content width, 21:9 at 1440 (4:3 at 390), small or no radius, caption small secondary. It is the section's focal point.
+- Roster rows: 64–72px at 1440, hairline between (`_finish.md` hairlines), columns aligned across rows (P35). Avatar 40px circle, real photo (D32), one shape for everyone; illustrated portraits only if every person has one in the same hand.
+- Name body 600 primary; role body secondary; "what they made" body primary (it's the content); place small secondary; link an arrow icon with a 44px hit area and an accessible name ("Ana Ruiz on GitHub").
+- Rows sorted by something meaningful (team, or when they joined), stated if not obvious.
+- Hiring link (only if hiring) as a text link with a real count, on the heading's baseline at the right.
+
+## Content
+
+- Every person agreed to be listed with their photo, name and line.
+- "What they made" is concrete and true ("Built the renderer"), written or approved by them, not a personality line ("Coffee lover").
+- One link per person to a place they actually use, or none.
+- The big photo is real and recent. No stock, no AI-generated team.
+
+## States and motion
+
+- Static. Row hover (fine pointer): background tint one step; the avatar can show a second photo at work (crossfade 150ms) if the team has them.
+- Images lazy-loaded with fixed sizes.
+- Long names and roles wrap within their column without breaking the row's alignment.
+
+## Pitfalls
+
+- Square headshot grid with titles and three social icons each.
+- Personality lines instead of work.
+- Mixed photo styles (studio portrait, selfie, illustration) in one list.
+- A team page with people who've left.
+
+## Floor checks
+
+- Is each person shown with a real photo, full name and role?
+- Does each person's row say a concrete thing they made or own?
+- Are the roster's columns aligned across rows, divided by hairlines?
+- Is there one larger real photo of the team or place that leads the section?
+- Are all portraits in one consistent style and shape?
+- At 390, does each person's entry stay readable without sideways scrolling?

package/kb/sections/alternating-rows-live-tiles.md

@@ -0,0 +1,110 @@
+---
+id: alternating-rows-live-tiles
+name: Alternating rows, each with a live tile
+kind: features
+shape: stacked-rows
+layout: "2–4 rows; words 5/12 and a live product tile 7/12, sides alternate per row; each tile performs its feature once; rows differ in tile height and content"
+fits: [saas, developer, ai, productivity, b2b, technical, honest, crafted]
+avoid: [luxury, fashion, heritage, crisis, food, portfolio]
+needs: ["2–4 features that each have a visible moment in the product", "real labels and data for each moment"]
+imagery: product-ui
+density: balanced
+effort: m
+moves: [self-playing-product-demo, screenshot-detail-crops, calm-motion-system]
+---
+
+## When it's right
+
+The product has two to four features that each change something you can see on screen: a filter narrows a list, a draft becomes a review, a failing check turns green. Each row names one feature and shows that exact moment in a small piece of working UI beside it, so the section reads like a sequence of proofs rather than a list of claims (L07). Alternating sides keeps the eye moving down the page in a gentle zigzag.
+
+It only works when the rows are not clones. The tiles differ in what they show (a list, a diff, a chart, a form) and in height, so the section has a rhythm instead of a template. Not for more than four features (use `ruled-list-pinned-visual` or `spec-sheet-features`), or for features with nothing to show (use `numbered-editorial-columns`). If one feature matters far more than the rest, use `sticky-feature-narrative` or give it its own `self-playing-run-demo`.
+
+## Structure
+
+```
+1440 ─ container 1240, 12 cols, gutter 24
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ H2 cols 1–7, plain, one line or two                                           │
+│ lead cols 1–6, ink-2                                                          │
+│                                                         --s-8                 │
+│ ┌ cols 1–5 ─────────────┐   ┌ cols 6–12 ──────────────────────────────────┐   │
+│ │ h3 feature name        │   │ live tile (product frame, r-lg, shadow-1)   │   │  row A: tile 420 tall
+│ │ 2–3 lines, ink-2, 40ch │   │  a list narrows as a filter chip is applied │   │
+│ │ link to docs →         │   │                                             │   │
+│ └────────────────────────┘   └─────────────────────────────────────────────┘   │
+│                                                         --s-9 between rows    │
+│ ┌ cols 1–7 ───────────────────────────────────┐   ┌ cols 8–12 ─────────────┐   │
+│ │ live tile: a diff resolves, two lines        │   │ h3 feature name        │   │  row B: tile 320 tall,
+│ │ change colour, a check appears               │   │ 2–3 lines, ink-2       │   │  sides swapped
+│ └──────────────────────────────────────────────┘   └────────────────────────┘   │
+│                                                                               │
+│ ┌ cols 1–5 ─────────────┐   ┌ cols 6–12, bleeds right to viewport ──────────────
+│ │ h3 feature name        │   │ live tile: a chart draws its last week         │  row C: tile 480 tall,
+│ │ 2–3 lines              │   │                                                │  may bleed
+│ └────────────────────────┘   └─────────────────────────────────────────────────
+└──────────────────────────────────────────────────────────────────────────────┘
+  words are top-aligned to the tile's first line of content, not vertically centred
+```
+
+```
+390 ─ one column, side padding 16
+┌──────────────────────────────┐
+│ H2 28–32px                   │
+│ lead                         │
+│ h3 feature A                 │
+│ 2–3 lines                    │
+│ ┌ tile A, full width ──────┐ │  ← 280–360 tall, cropped to the working part
+│ └──────────────────────────┘ │
+│            --s-8             │
+│ h3 feature B                 │  ← words always before their tile on phone
+│ ┌ tile B ──────────────────┐ │
+│ └──────────────────────────┘ │
+└──────────────────────────────┘
+```
+
+At 390 every row becomes words then tile, regardless of desktop side, so the reader always meets the claim before the proof. Tiles go full width inside the gutter (a bleeding tile bleeds right only), are 280–360px tall, and crop to their working part: text inside stays at 12px or more. Rows are `--s-8` apart.
+
+## Finish
+
+- Row gap `--s-9` (96) at 1440, `--s-8` at 390; heading block to the first row `--s-8`. The column gap between words and tile is `--s-7`.
+- Tile widths alternate between 7/12 and 7/12 mirrored; one row may take the bleed treatment from `split-hero-live-object` for variety. Tile heights differ by at least 80px between neighbouring rows.
+- Feature names: h3 (`--t-h3`), weight 600, tracking −0.015em. Body: `--t-body`, `--ink-2`, `max-width: 40ch`. No eyebrow above each h3 (M16); no icon chip (M04).
+- Tiles: the product frame from `_finish.md` at resting depth (`--shadow-1`, `--r-lg`), no fake chrome; the dominant row may use `--shadow-2`. Inner elements nest radii (outer 20, padding 12 → inner 8). Unimportant chrome is skeleton bars.
+- Ground: the section sits on `--paper-2` when the hero above is on `--paper`, so tiles (on `--surface`) lift off it without heavier shadows.
+- Optional link per row: a text link with underline offset `.2em`, `--t-small`, to the feature's docs. Never a button per row.
+
+## Content
+
+- Heading: what these features add up to, in one plain sentence ("Everything a review needs, in the pull request").
+- Each row: a feature name that says what happens ("Filters that remember the team"), then two or three sentences: what the user does, what changes, why it matters.
+- Each tile: the product moment for that feature, with the project's real field names and believable records. One thing changes in it; the rest is still.
+- Order rows by how often a new user meets them, not by how impressive they are.
+- No numbers in tiles that pose as results ("+43% faster") unless the project can source them.
+
+## States and motion
+
+- Server render shows each tile in its finished state (the filtered list, the resolved diff), never empty.
+- When a tile is 40% in view, it plays its one change once (600–1200ms, ease-out `cubic-bezier(.23,1,.32,1)`), then holds. A small replay on hover or focus is allowed; no loops by default.
+- Only one tile animates at a time; different rows use different kinds of change (a list filter, a colour state, a chart draw), not the same fade-up (M44, L17).
+- Reduced motion: finished state, no play. No JS: finished state.
+- Long feature names wrap to two lines; the words column stays top-aligned with the tile.
+
+## Pitfalls
+
+- The "heading left + two cards" template: rows of equal height, each with a generic card on one side (M21).
+- Words vertically centred against a tall tile, leaving holes above and below the text.
+- Every tile the same screenshot crop with a different caption: the reader stops looking after row two.
+- Tiles as `<img>` screenshots in browser frames (M19, L01).
+- Five or more rows: the zigzag becomes a slog; switch archetype.
+- On phone, the tile coming before its words on alternate rows.
+
+## Floor checks
+
+- Does every row pair its words with a piece of product UI that shows that specific feature?
+- Do neighbouring rows put their tiles on opposite sides at 1440?
+- Do the tiles differ visibly from each other in content and height, rather than repeating one card template?
+- Is the text inside each tile readable at 100% zoom?
+- Are the words in each row aligned to the top of their tile, with no empty band taller than 160px beside them?
+- Where a tile bleeds off an edge, is the cut part secondary UI (extra rows, a sidebar's end), with every heading, sentence and number in the tile whole?
+- Is the section free of icon chips and eyebrow labels above each feature name?
+- At 390, does every feature's name and text come before its tile?