@mitcsutt/kiln-ui 0.2.2 → 0.4.0

package/skills/custom-theme/references/tokens.md

@@ -45,25 +45,25 @@ Type roles:
 
 | Token | Paper |
 | --- | --- |
-| `--font-display` | `'Schibsted Grotesk', ui-sans-serif, system-ui, sans-serif` |
-| `--font-text` | `'Schibsted Grotesk', ui-sans-serif, system-ui, sans-serif` |
-| `--font-prose` | `'Newsreader', 'Iowan Old Style', Georgia, serif` |
-| `--font-mono` | `'Martian Mono', ui-monospace, 'SFMono-Regular', Menlo, monospace` |
-| `--font-numeric` | `'Newsreader', 'Iowan Old Style', Georgia, serif` |
+| `--font-display` | `'Golos Text', ui-sans-serif, system-ui, sans-serif` |
+| `--font-text` | `'Golos Text', ui-sans-serif, system-ui, sans-serif` |
+| `--font-prose` | `'Golos Text', ui-sans-serif, system-ui, sans-serif` |
+| `--font-mono` | `'Atkinson Hyperlegible Mono', ui-monospace, 'SFMono-Regular', Menlo, monospace` |
+| `--font-numeric` | `'Golos Text', ui-sans-serif, system-ui, sans-serif` |
 | `--type-base` | `1rem` |
 | `--display-scale` | `1` |
 | `--type-ratio` | `1.25` |
-| `--display-weight` | `640` |
+| `--display-weight` | `740` |
 | `--display-style` | `normal` |
 | `--display-stretch` | `100%` |
 | `--display-transform` | `none` |
-| `--display-tracking` | `-0.04em` |
+| `--display-tracking` | `-0.025em` |
 | `--display-opsz` | `72` |
 | `--heading-font` | `var(--font-display)` |
-| `--heading-weight` | `620` |
+| `--heading-weight` | `650` |
 | `--heading-tracking` | `-0.015em` |
 | `--heading-transform` | `none` |
-| `--label-weight` | `560` |
+| `--label-weight` | `600` |
 | `--label-tracking` | `0` |
 | `--label-transform` | `none` |
 | `--numeric-stretch` | `100%` |
@@ -71,7 +71,7 @@ Type roles:
 | `--leading-tight` | `1` |
 | `--leading-snug` | `1.2` |
 | `--leading-body` | `1.55` |
-| `--prose-size` | `1.125rem` |
+| `--prose-size` | `1.0625rem` |
 | `--prose-leading` | `1.6` |
 
 Structure & temperament:
@@ -86,38 +86,38 @@ Structure & temperament:
 | `--icon-stroke` | `1.5` |
 | `--border-width` | `1px` |
 | `--border-width-strong` | `2px` |
-| `--radius-action` | `0.375rem` |
-| `--radius-field` | `0.375rem` |
-| `--radius-surface` | `0.5rem` |
-| `--radius-media` | `0.25rem` |
-| `--radius-chip` | `0.375rem` |
+| `--radius-action` | `0.25rem` |
+| `--radius-field` | `0.25rem` |
+| `--radius-surface` | `0.375rem` |
+| `--radius-media` | `0.125rem` |
+| `--radius-chip` | `999px` |
 | `--radius-avatar` | `50%` |
 
 Colour:
 
 | Token | Paper |
 | --- | --- |
-| `--color-canvas` | `light-dark(oklch(0.976 0.004 85), oklch(0.188 0.005 85))` |
-| `--color-surface` | `light-dark(oklch(0.993 0.002 85), oklch(0.215 0.006 85))` |
-| `--color-surface-sunken` | `light-dark(oklch(0.955 0.005 85), oklch(0.165 0.005 85))` |
-| `--color-surface-raised` | `light-dark(oklch(0.997 0.002 85), oklch(0.245 0.006 85))` |
-| `--color-surface-inverse` | `light-dark(oklch(0.235 0.008 85), oklch(0.93 0.005 85))` |
-| `--color-ink` | `light-dark(oklch(0.215 0.008 85), oklch(0.935 0.005 85))` |
-| `--color-ink-muted` | `light-dark(oklch(0.435 0.008 85), oklch(0.755 0.006 85))` |
-| `--color-ink-subtle` | `light-dark(oklch(0.515 0.008 85), oklch(0.64 0.006 85))` |
-| `--color-ink-inverse` | `light-dark(oklch(0.965 0.004 85), oklch(0.2 0.008 85))` |
-| `--color-line` | `light-dark(oklch(0.9 0.005 85), oklch(0.3 0.006 85))` |
-| `--color-line-strong` | `light-dark(oklch(0.8 0.006 85), oklch(0.4 0.007 85))` |
-| `--color-accent` | `light-dark(oklch(0.25 0.008 85), oklch(0.92 0.005 85))` |
-| `--color-accent-hover` | `light-dark(oklch(0.34 0.008 85), oklch(0.84 0.006 85))` |
-| `--color-accent-ink` | `light-dark(oklch(0.975 0.004 85), oklch(0.2 0.008 85))` |
-| `--color-accent-text` | `light-dark(oklch(0.25 0.008 85), oklch(0.92 0.005 85))` |
-| `--color-accent-soft` | `light-dark(oklch(0.925 0.006 85), oklch(0.285 0.007 85))` |
-| `--color-highlight` | `light-dark(oklch(0.935 0.035 228), oklch(0.315 0.045 235))` |
+| `--color-canvas` | `light-dark(oklch(0.952 0.006 250), oklch(0.17 0.008 250))` |
+| `--color-surface` | `light-dark(oklch(0.995 0.002 250), oklch(0.215 0.009 250))` |
+| `--color-surface-sunken` | `light-dark(oklch(0.935 0.006 250), oklch(0.14 0.008 250))` |
+| `--color-surface-raised` | `light-dark(oklch(0.998 0.002 250), oklch(0.25 0.009 250))` |
+| `--color-surface-inverse` | `light-dark(oklch(0.26 0.06 256), oklch(0.93 0.012 250))` |
+| `--color-ink` | `light-dark(oklch(0.26 0.06 256), oklch(0.94 0.01 250))` |
+| `--color-ink-muted` | `light-dark(oklch(0.42 0.06 256), oklch(0.77 0.015 250))` |
+| `--color-ink-subtle` | `light-dark(oklch(0.47 0.06 256), oklch(0.66 0.015 250))` |
+| `--color-ink-inverse` | `light-dark(oklch(0.96 0.006 250), oklch(0.2 0.05 256))` |
+| `--color-line` | `light-dark(oklch(0.9 0.006 250), oklch(0.3 0.01 250))` |
+| `--color-line-strong` | `light-dark(oklch(0.78 0.012 252), oklch(0.42 0.012 250))` |
+| `--color-accent` | `light-dark(oklch(0.37 0.1 255), oklch(0.86 0.06 250))` |
+| `--color-accent-hover` | `light-dark(oklch(0.31 0.095 255), oklch(0.92 0.045 250))` |
+| `--color-accent-ink` | `light-dark(oklch(0.985 0.005 250), oklch(0.2 0.05 256))` |
+| `--color-accent-text` | `light-dark(oklch(0.35 0.1 255), oklch(0.86 0.06 250))` |
+| `--color-accent-soft` | `light-dark(oklch(0.93 0.025 252), oklch(0.285 0.03 252))` |
+| `--color-highlight` | `light-dark(oklch(0.925 0.045 228), oklch(0.33 0.05 235))` |
 | `--color-highlight-ink` | `var(--color-ink)` |
 | `--color-focus` | `var(--color-ink)` |
 | `--color-selection` | `light-dark(oklch(0.88 0.06 228), oklch(0.42 0.07 235))` |
-| `--color-scrim` | `light-dark(oklch(0.22 0.008 85 / 0.4), oklch(0.07 0.005 85 / 0.66))` |
+| `--color-scrim` | `light-dark(oklch(0.22 0.04 258 / 0.4), oklch(0.07 0.01 250 / 0.66))` |
 | `--tone-positive` | `light-dark(oklch(0.52 0.11 155), oklch(0.72 0.12 158))` |
 | `--tone-positive-soft` | `light-dark(oklch(0.94 0.035 155), oklch(0.28 0.045 158))` |
 | `--tone-positive-text` | `light-dark(oklch(0.45 0.1 155), oklch(0.78 0.11 158))` |
@@ -141,8 +141,8 @@ Colour:
 | `--color-cat-5` | `light-dark(oklch(0.8 0.05 300), oklch(0.7 0.06 300))` |
 | `--color-cat-6` | `light-dark(oklch(0.82 0.06 125), oklch(0.72 0.07 125))` |
 | `--color-cat-7` | `light-dark(oklch(0.8 0.05 195), oklch(0.7 0.06 195))` |
-| `--color-cat-8` | `light-dark(oklch(0.8 0.01 85), oklch(0.7 0.01 85))` |
-| `--color-cat-ink` | `oklch(0.21 0.008 85)` |
+| `--color-cat-8` | `light-dark(oklch(0.8 0.01 250), oklch(0.7 0.01 250))` |
+| `--color-cat-ink` | `oklch(0.21 0.03 258)` |
 
 Edges & depth:
 
@@ -151,13 +151,13 @@ Edges & depth:
 | `--shadow-surface` | `none` |
 | `--active-shift` | `0px` |
 | `--shadow-active` | `none` |
-| `--shadow-float` | `0 1px 2px oklch(0.2 0.008 85 / 0.1), 0 8px 24px -6px oklch(0.2 0.008 85 / 0.18)` |
-| `--shadow-overlay` | `0 2px 4px oklch(0.15 0.008 85 / 0.12), 0 20px 56px -12px oklch(0.15 0.008 85 / 0.32)` |
+| `--shadow-float` | `0 1px 2px oklch(0.2 0.04 258 / 0.1), 0 8px 24px -6px oklch(0.2 0.04 258 / 0.18)` |
+| `--shadow-overlay` | `0 2px 4px oklch(0.15 0.04 258 / 0.12), 0 20px 56px -12px oklch(0.15 0.04 258 / 0.32)` |
 | `--canvas-image` | `none` |
 
 ## Optional theme tokens
 
-Some themes set a few more: Fiesta's inks for text on its gold rows, Ledger's table rule. Every theme scope resets these first, so a theme nested inside another falls back to the component's default instead of inheriting its parent's value. Set them only when your theme's idea needs them:
+Some themes set a few more: Fiesta's and Riso's inks for text on their tinted rows, Ledger's table rule. Every theme scope resets these first, so a theme nested inside another falls back to the component's default instead of inheriting its parent's value. Set them only when your theme's idea needs them:
 
 `--canvas-image-size`, `--control-checked-border`, `--highlight-accent-text`, `--highlight-tone-caution-text`, `--highlight-tone-critical-text`, `--highlight-tone-info-text`, `--highlight-tone-positive-text`, `--marquee-edge`, `--numeral-scale`, `--numeral-weight`, `--section-divider-color`, `--stat-fit`, `--table-foot-rule`, `--table-head-font`
 
@@ -170,7 +170,7 @@ A component exposes a few tokens of its own where a theme might reasonably diffe
 Radii are roles, not one global roundness. A theme can make actions pills and surfaces square.
 
 
-One edge treatment per element: a border, a shadow or a change of fill, never all three. Static structure uses hairlines. Soft shadows are only for things that float, like popovers and dialogs. Fiesta's hard offset is its one deliberate exception: it's the print misregistration, and it _is_ the edge.
+One edge treatment per element: a border, a shadow or a change of fill, never all three. Static structure uses hairlines. Soft shadows are only for things that float, like popovers and dialogs. Hard offsets never go on static surfaces in a new theme. Fiesta keeps its hard offset as a legacy preset: it's the print misregistration, and it _is_ the edge. Riso's misregistered offset, the second ink drum printing slightly off, is floating-only.
 
 
 ## Axes and scoping
@@ -178,13 +178,13 @@ One edge treatment per element: a border, a shadow or a change of fill, never al
 Three attributes select tokens, and they're independent of each other.
 
 ```html
-<html data-theme="monograph" data-mode="dark">
-  <div data-theme="fiesta">a Fiesta panel that keeps the page's dark mode</div>
+<html data-theme="flightdeck" data-mode="dark">
+  <div data-theme="riso">a Riso panel that keeps the page's dark mode</div>
   <div data-density="compact">a denser table</div>
 </html>
 ```
 
-- `data-theme` is `paper`, `monograph`, `ledger`, `fiesta`, or the name of a theme you wrote. No attribute means Paper.
+- `data-theme` is `paper`, `monograph`, `ledger`, `fiesta`, `flightdeck`, `riso`, or the name of a theme you wrote. No attribute means Paper.
 - `data-mode` is `light`, `dark` or `system`. It drives `color-scheme`, which drives every `light-dark()` colour. Leave it off nested scopes and they inherit the page's mode.
 - `data-density` is `compact` or `comfortable`, and multiplies the theme's own density.
 

package/skills/custom-theme/references/type.md

@@ -20,7 +20,7 @@ A theme picks at most two families (plus a mono where it needs one) and assigns
 | Numeric | `--font-numeric`, `--numeric-stretch`                                                                                    | `Numeral`, `Amount`, `Stat`, numeric cells |
 | Mono    | `--font-mono`, `--mono-stretch`                                                                                          | `Code`, `CodeBlock`, `Kbd`                 |
 
-Fiesta sets `--heading-transform: uppercase` for poster headlines; Ledger sets its numerals in condensed Martian Mono so a column of figures reads like receipt tape. Neither needed a component change.
+Fiesta sets `--heading-transform: uppercase` for poster headlines. Ledger sets `--numeric-stretch` so its figures use a condensed width of the same family, and a column of money reads like receipt tape. Flightdeck keeps its numerals in B612, whose digits are already equal width, so columns align without a monospace. Neither needed a component change. Riso's Shantell Sans has no tabular figures, so its numerals don't line up in columns.
 
 ## The scale
 
@@ -50,12 +50,15 @@ Every number that aligns or updates uses tabular, lining figures: counts, money,
 
 Kiln self-hosts every face its themes use, so there's nothing to set up:
 
-| Face                | Used by                              | Ships in            |
-| ------------------- | ------------------------------------ | ------------------- |
-| Schibsted Grotesk   | Paper, Monograph, Ledger             | `styles.css`        |
-| Newsreader          | Paper (prose and figures), Monograph | `styles.css`        |
-| Martian Mono        | code everywhere, Ledger's figures    | `styles.css`        |
-| Big Shoulders       | Fiesta display                       | `themes/fiesta.css` |
-| Bricolage Grotesque | Fiesta text                          | `themes/fiesta.css` |
-
-Browsers download a face only when something renders in it, so a declared face you never use costs nothing. All five are licensed under the SIL Open Font License 1.1, and the licences ship in the package at `dist/assets/fonts/licenses/`. A theme of your own loads its own fonts: see [Theming](../SKILL.md#5-load-its-fonts).
+| Face                               | Used by                         | Ships in                                    |
+| ---------------------------------- | ------------------------------- | ------------------------------------------- |
+| Golos Text                         | Paper                           | `styles.css`                                |
+| Atkinson Hyperlegible Mono         | code in Paper, Ledger and Riso  | `styles.css`                                |
+| Newsreader, Schibsted Grotesk      | Monograph                       | `themes/monograph.css`                      |
+| Martian Mono                       | code in Monograph and Fiesta    | `themes/monograph.css`, `themes/fiesta.css` |
+| Archivo                            | Ledger                          | `themes/ledger.css`                         |
+| Big Shoulders, Bricolage Grotesque | Fiesta                          | `themes/fiesta.css`                         |
+| B612, B612 Mono                    | Flightdeck (B612 Mono for code) | `themes/flightdeck.css`                     |
+| Shantell Sans                      | Riso                            | `themes/riso.css`                           |
+
+Browsers download a face only when something renders in it, so a declared face you never use costs nothing. All of them are licensed under the SIL Open Font License 1.1, and the licences ship in the package at `dist/assets/fonts/licenses/`. A theme of your own loads its own fonts: see [Theming](../SKILL.md#5-load-its-fonts).

package/skills/design-rules/SKILL.md

@@ -20,7 +20,7 @@ These rules come from [DESIGN.md](https://github.com/mitcsutt/kiln/blob/main/DES
 ## Principles
 
 1. **Themes are data, components are structure.** A component never knows which theme it is in. Everything visual is a token; a new theme is one CSS file and zero component changes.
-2. **One idea per theme, drawn from its subject.** Paper is a typeset proof on good stock. Monograph is a scholar's monograph read under a desk lamp. Ledger is an accountant's ruled book. Fiesta is a screen-printed festival poster. If a choice can't be justified by the idea, it doesn't ship.
+2. **One idea per theme, drawn from its subject.** Paper is an office that prints for everyone, on grey recycled stock in blue-black ink. Monograph is a scholar's monograph read under a desk lamp. Ledger is an accountant's columnar pad. Fiesta is a screen-printed festival poster. Flightdeck is a glass-cockpit display. Riso is a two-drum risograph zine. Monograph and Fiesta predate the second-order rules in §2 and keep their original design for compatibility (Fiesta's status and categorical inks have since been tuned apart for real use). Every choice in a theme designed since has a one-line reason traced to its subject, written in the stylesheet next to the value. If you can't write the reason, the choice is wrong and it doesn't ship.
 3. **Props, not styles.** Consumers compose layout and intent through typed props (`gap={5}`, `tone="critical"`, `width="text"`). No utility classes, no inline style soup, no raw px/hex/ms at call sites. `className` exists as an escape hatch, not a workflow.
 4. **Durable by default.** Every component forwards refs, spreads native props, works with React 18 and 19, is keyboard- and screen-reader-complete, respects `prefers-reduced-motion`, and renders on the server.
 5. **Specific beats safe.** The median choice is the wrong choice (see [Not AI slop](#not-ai-slop)).
@@ -34,16 +34,45 @@ Generated UI converges on the statistical median: indigo buttons, Inter, gradien
 - Authored in **OKLCH**. Neutrals are **tinted** (chroma 0.004–0.02 toward the theme's hue). Never `#000`/`#fff` surfaces, never stock slate/zinc.
 - **One accent, ~5–10% of pixels**: the primary action, the current item, live state, key data. A second hue only when it carries meaning (`--color-highlight` = "you" / selected; tones = status).
 - **No gradients** unless they encode data. No gradient text. No glow halos in dark mode.
-- No indigo/violet as a primary. No cream `#F4F1EA` + terracotta `#D97757`.
+- No indigo/violet as a primary. No warm cream canvas (such as `#F4F1EA`) and no terracotta or ember accent (such as `#D97757`). See _Second-order tells_ below.
 
 ### Type
 
 - **Two families max per theme** (+ a mono for code/figures where the theme needs it), clearly distinct, one with real character.
 - **Big contrast**: the largest display step is ≥ 5× body. Display tracking tightens with size (−0.02 to −0.04em); line-height drops to ~0.9–1.05.
 - **`tabular-nums` on every number that aligns or updates**: counts, money, tables, dates. `<Numeral>`/`<Amount>` do this for you.
+- **Navigation text stays off the caption steps.** Links, nav items and tabs are read and scanned like body copy: `NavLinks` is `--text-md` (`sm`: `--text-sm`), and no navigation label uses `--text-xs` or `--text-2xs`. Those steps are for captions, badges, keyboard hints and metadata. A label that must stay compact, like `BottomNav`'s under its icon, floors at `0.75rem`. The `Usage` stories of `NavLinks`, `Tabs` and `BottomNav` enforce this in the browser (`pnpm test:storybook`), checking each label's computed size in the current theme.
 - Prose measure ≤ 70ch (`width="text"`). `text-wrap: balance` on headings, `pretty` on paragraphs (the reset does it).
 - **Banned patterns:** accenting one word of a headline in italic/colour; a tracked ALL-CAPS eyebrow over every section; `01 / 02 / 03` numbering on things that aren't a sequence; monospace used as decoration for small labels.
 
+### Second-order tells
+
+Models that are told to avoid the tells above converge on a second set instead ([research](https://github.com/mitcsutt/kiln/blob/main/docs/research/ai-design-tells.md), [ADR 0030](https://github.com/mitcsutt/kiln/blob/main/docs/adr/0030-theme-family-without-ai-tells.md)). None of these ships in a new built-in theme:
+
+- A **cream or warm-paper canvas** (hue 40 to 100, with any visible chroma), including apricot and beige.
+- An **ember, terracotta or burnt-orange accent**.
+- A **near-black canvas with one acid or ember accent**.
+- A **mint or sage canvas with a forest-green accent**, which is the cream tell in another hue.
+- **Hard-offset "neo-brutalist" shadows on static surfaces.** A hard offset is allowed only where the theme's subject explains it, and only on floating layers. Fiesta, the legacy preset, keeps its hard offset on static surfaces; no new theme may.
+- **Grain, noise or halftone** on the canvas (`--canvas-image` stays `none`).
+- **Monospace beyond code**: for labels, eyebrows or every figure as decoration. A mono is allowed for figures only when the subject really uses one.
+- A **serif display with one italic accent word**.
+- A font from the banned list below.
+
+`packages/ui/src/themes/tells.test.ts` enforces the checkable part for Paper, Ledger, Flightdeck and Riso, reading the light half of each `light-dark()` pair:
+
+- no banned font family in their stylesheets or in any font stylesheet under `tokens/` except the legacy ones;
+- no warm-cream canvas: `--color-canvas` fails when its lightness is above 0.85, its chroma above 0.008 and its hue 40 to 100;
+- no ember, terracotta or indigo accent: `--color-accent` fails when its chroma is above 0.08 and its hue is 25 to 60 (ember) or above 262 up to 300 (indigo).
+
+The rest is review.
+
+**Legacy exemption.** Monograph and Fiesta are listed as `LEGACY` in that test and are exempt, along with the font stylesheets only they use (`fonts-monograph.css`, `fonts-fiesta.css` and `fonts-martian-mono.css`), because they keep their design from before these rules ([ADR 0030](https://github.com/mitcsutt/kiln/blob/main/docs/adr/0030-theme-family-without-ai-tells.md)). Monograph still has its ember accent and serif display, and Fiesta its apricot canvas and halftone. Do not treat them as precedent: a new theme gets no exemption, and a redesigned Monograph or Fiesta loses its own.
+
+The banned font families, from the research: the first-order defaults plus the faces models now reach for as "distinctive" escapes (several are on Anthropic's own recommended list): Inter, Roboto, Open Sans, Poppins, Montserrat, Space Grotesk, Space Mono, Geist, DM Sans, DM Serif, Manrope, Plus Jakarta Sans, Outfit, Sora, Syne, Satoshi, Cabinet Grotesk, Clash Display, General Sans, Instrument Sans, Instrument Serif, Fraunces, Playfair Display, Cormorant, Lora, EB Garamond, Newsreader, Bricolage Grotesque, IBM Plex, JetBrains Mono and Fira Code. The list goes stale as model defaults move: change the list in the test and here together.
+
+Beyond the checks, a theme has a subject, and each colour, face, radius and easing has a one-line reason in the stylesheet that traces it to that subject. Each theme also mixes radii on purpose (for example square fields with pill chips), so no theme is one uniform roundness.
+
 ### Layout
 
 - **Left-aligned by default.** Centre is an exception (empty states, a lone CTA).
@@ -55,15 +84,17 @@ Generated UI converges on the statistical median: indigo buttons, Inter, gradien
 ### Components & depth
 
 - **Radii are roles**, not a global roundness: `--radius-action`, `--radius-field`, `--radius-surface`, `--radius-media`, `--radius-chip`, `--radius-avatar`. Nested radii shrink (inner = outer − padding).
-- **One edge treatment per element**: a border _or_ a shadow _or_ a fill change. Static structure uses hairlines; soft shadows are only for things that float (popover, menu, dialog). Fiesta's hard offset is its one deliberate exception: it's the print misregistration, and it _is_ the edge.
-- **Icons**: the library ships ~20 glyphs on a 20px grid with a themed stroke. At most one icon per row; never an icon in a tinted chip; never emoji as UI.
+- **One edge treatment per element**: a border _or_ a shadow _or_ a fill change. Static structure uses hairlines; soft shadows are only for things that float (popover, menu, dialog). Hard-offset shadows never go on static surfaces in a new theme. Fiesta keeps its hard offset as a legacy preset: it is the print misregistration, and it _is_ the edge. Riso's misregistered offset (the second ink drum slightly off) is floating-only.
+- **Icons**: the library ships ~40 glyphs on a 20px grid with a themed stroke: the ones its components need, plus common navigation and page-furniture glyphs so apps don't mix in a second set. At most one icon per row; never an icon in a tinted chip; never emoji as UI.
 - **No left-border-accent callouts.** Alerts are a neutral hairline frame; the tone lives only in the glyph and a short tab on the top edge (`variant="soft"` for a tinted box when it must shout).
-- **Empty states** mark their frame with printer's crop marks, not a dashed box.
+- **Categorical colour marks who, never how.** A row or card with `color` draws a thin rail or a top keyline in `--color-cat-N`, matching that person's or team's `Tag` and `Avatar`. It's identity, not status or emphasis, so it's not the accent callout above; tones stay in badges and figures.
+- **Empty states** mark their frame with printer's crop marks, not a dashed box. So does a placeholder `Card`, a slot not yet decided.
 - **Focus is neutral** (`--color-focus` = ink) and always visible on `:focus-visible`. Focus must never look like validation; only error/warning/success tint a field.
 
 ### Motion
 
 - Motion answers an action or shows a state change (count updated, row expanded, panel opened). **No fade-up-on-scroll, no hover-scale on static cards, no parallax.**
+- To point at something that just changed or that a link just opened on, wrap it in `Flash`: one primitive for any element, not a flash prop on each component. It's an outline that fades, so it never moves layout, and under reduced motion it holds and goes instead of fading.
 - Durations and easings are tokens (`--dur-1/2/3`, `--ease-out`, `--ease-spring`) and collapse to ~0 under `prefers-reduced-motion`.
 
 ### Copy (for stories, docs and examples)

package/skills/layout-composition/references/app-shell.md

@@ -92,7 +92,7 @@ export function Usage() {
 
 `AppShell.Header`, `AppShell.Sidebar`, `AppShell.Main`, `AppShell.Footer` and `AppShell.BottomBar` place themselves, so their order in JSX doesn't affect the layout. Keep it the same as the reading order anyway: header, sidebar, main, footer, bottom bar.
 
-- **Header** is sticky by default (`sticky={false}` to scroll it away). Put a `Container` and an `Inline` inside.
+- **Header** is sticky by default (`sticky={false}` to scroll it away). While it sticks, in-page links and `scrollIntoView` land just below it, whatever its height. Put a `Container` and an `Inline` inside.
 - **Sidebar** appears from `navBreakpoint` up. It sits at the start of the main region (`side="end"` for the other side), scrolls on its own, and stays below the header.
 - **Main** is the `<main>` landmark and the skip link's target.
 - **BottomBar** is pinned to the bottom of the viewport below `navBreakpoint`, and pads for the phone's home indicator.
@@ -117,7 +117,7 @@ Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `sticky` | `boolean` | `true` | Stick to the top of the viewport while scrolling. Default `true`. |
+| `sticky` | `boolean` | `true` | Stick to the top of the viewport while scrolling. Default `true`. While it sticks, in-page links and `scrollIntoView` land below it, however tall it grows. |
 
 Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 

package/skills/layout-composition/references/box.md

@@ -39,7 +39,7 @@ export function Usage() {
 | `padding` | `Responsive<Space>` |  | Padding on every side. Responsive. |
 | `paddingX` | `Responsive<Space>` |  | Inline (left/right) padding; overrides `padding` on that axis. Responsive. |
 | `paddingY` | `Responsive<Space>` |  | Block (top/bottom) padding; overrides `padding` on that axis. Responsive. |
-| `surface` | `'none' \| 'surface' \| 'canvas' \| 'sunken' \| 'raised' \| 'inverse'` | `none` | Background fill. `inverse` also re-points ink and line colours for its children. |
+| `surface` | `'none' \| 'surface' \| 'canvas' \| 'sunken' \| 'raised' \| 'inverse' \| 'cat-6' \| 'cat-3' \| 'cat-5' \| 'cat-1' \| 'cat-2' \| 'cat-4' \| 'cat-7' \| 'cat-8'` | `none` | Background fill. `inverse` and the categorical `cat-1` to `cat-8` (one person's or team's colour, matching their `Tag`) also re-point ink and line colours for its children. |
 | `border` | `boolean` | `false` | Hairline border in `--color-line`. One edge treatment per element — a border *or* a fill. |
 | `radius` | `'none' \| 'surface' \| 'field' \| 'media'` | `none` | Corner radius, by role. |
 | `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'li' \| 'span'` | `div` |  |

package/skills/layout-composition/references/divider.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/divider
 
 `Divider` separates groups. For a rule between every item of a list, use `Stack dividers` instead, which spaces the rules for you.
 
+A labelled divider is a band rather than a separator: its label is content that screen readers read in place, and the rules either side of it are decorative.
+
 A labelled divider names the group that follows. `spacing` adds space above and below from the space scale, `strong` uses the stronger line colour, and `decorative` hides the rule from assistive technology when it carries no meaning (it's a `separator` otherwise).
 
 ```tsx
@@ -32,6 +34,33 @@ export function Usage() {
 }
 ```
 
+## Block label
+
+A label can be a block: a few lines set into the rule, like a verdict and a time between two halves of a timetable. It's read in place as ordinary content.
+
+```tsx
+import { Divider, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export function BlockLabel() {
+  return (
+    <Divider
+      labelPosition="center"
+      spacing={4}
+      label={
+        <Stack gap={1} align="center">
+          <Text size="sm" weight="strong">
+            Change at Harbour Square
+          </Text>
+          <Text size="sm" tone="muted">
+            Connection 6 minutes
+          </Text>
+        </Stack>
+      }
+    />
+  )
+}
+```
+
 ## API
 
 `DividerProps`:
@@ -40,7 +69,7 @@ export function Usage() {
 | --- | --- | --- | --- |
 | `orientation` | `'horizontal' \| 'vertical'` | `horizontal` | Default `horizontal`. A vertical rule stretches to its flex/grid row. |
 | `strong` | `boolean` | `false` | Heavier rule in `--color-line-strong` at `--border-width-strong`. |
-| `label` | `ReactNode` |  | Text set into a horizontal rule, e.g. "Earlier this week". It also names the separator. |
+| `label` | `ReactNode` |  | Content set into a horizontal rule, e.g. "Earlier this week". It's real content, read like any text, and may be a block (a `Stack` of lines); the rules either side are decorative. |
 | `labelPosition` | `'start' \| 'center'` | `start` | Where the label sits. Default `start` (left-aligned by default); `center` for a lone break. |
 | `spacing` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12` |  | Margin on both sides of the rule (block axis if horizontal, inline if vertical). |
 | `decorative` | `boolean` | `false` | Purely visual: hide it from assistive tech. Use when the rule only repeats a boundary that headings or landmarks already convey. |

package/skills/layout-composition/references/section.md

@@ -39,9 +39,30 @@ export function Usage() {
 }
 ```
 
+## Categorical band
+
+`surface="cat-1"` to `"cat-8"` paints a band in a categorical colour, one person's or team's colour, matching their `Tag`. Ink and lines flip to stay legible on it.
+
+```tsx
+import { Container, Heading, Section, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export function CategoricalBand() {
+  return (
+    <Section surface="cat-2" space={6}>
+      <Container>
+        <Stack gap={2}>
+          <Heading level={2}>Ada's crew</Heading>
+          <Text tone="muted">Three boats, eleven crossings this week.</Text>
+        </Stack>
+      </Container>
+    </Section>
+  )
+}
+```
+
 ## Surfaces and bands
 
-`surface` is `canvas`, `surface`, `sunken`, `inverse` or `accent`. On `inverse` and `accent`, the colour roles flip for everything inside, so text, links, focus rings and buttons stay legible with no extra props. `divider` adds a rule at the `top`, `bottom` or `both`.
+`surface` is `canvas`, `surface`, `sunken`, `inverse`, `accent`, or a categorical `cat-1` to `cat-8` (a band in one person's or team's colour, matching their `Tag`). On `inverse`, `accent` and the categorical bands, the colour roles flip for everything inside, so text, links, focus rings and buttons stay legible with no extra props. `divider` adds a rule at the `top`, `bottom` or `both`.
 
 ## API
 
@@ -50,7 +71,7 @@ export function Usage() {
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `space` | `Responsive<Space>` | `8` | Block padding (top and bottom), as a step on the space scale. Responsive. Vary it: adjacent sections should not share the same step. Default `8`. |
-| `surface` | `'accent' \| 'surface' \| 'canvas' \| 'sunken' \| 'inverse'` |  | Full-bleed band colour. Omit to stay transparent on the canvas. `inverse` and `accent` re-point the ink, line and focus colours so children stay legible. |
+| `surface` | `'accent' \| 'surface' \| 'canvas' \| 'sunken' \| 'inverse' \| 'cat-6' \| 'cat-3' \| 'cat-5' \| 'cat-1' \| 'cat-2' \| 'cat-4' \| 'cat-7' \| 'cat-8'` |  | Full-bleed band colour. Omit to stay transparent on the canvas. `inverse`, `accent` and the categorical `cat-1` to `cat-8` re-point the ink, line and focus colours so children stay legible. |
 | `divider` | `'top' \| 'bottom' \| 'both'` |  | A hairline across the full bleed at the top, bottom or both edges. |
 | `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer'` | `section` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |

package/skills/setup-and-theming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-and-theming
-description: "Use when installing @mitcsutt/kiln-ui in a React app: loading its stylesheet, wrapping the app in ThemeProvider, choosing Paper or a preset theme (Monograph, Ledger, Fiesta) and a colour mode, setting the theme before first paint with themeScript under SSR or the Next.js App Router, and passing router links through asChild."
+description: "Use when installing @mitcsutt/kiln-ui in a React app: loading its stylesheet, wrapping the app in ThemeProvider, choosing Paper or a preset theme (Monograph, Ledger, Fiesta, Flightdeck, Riso) and a colour mode, setting the theme before first paint with themeScript under SSR or the Next.js App Router, and passing router links through asChild."
 metadata:
   purpose: Install kiln-ui, load its CSS, and apply a built-in theme and colour mode correctly on the client and the server.
   type: lifecycle
@@ -11,6 +11,8 @@ sources:
   - mitcsutt/kiln:apps/docs/content/docs/ui/themes/monograph.mdx
   - mitcsutt/kiln:apps/docs/content/docs/ui/themes/ledger.mdx
   - mitcsutt/kiln:apps/docs/content/docs/ui/themes/fiesta.mdx
+  - mitcsutt/kiln:apps/docs/content/docs/ui/themes/flightdeck.mdx
+  - mitcsutt/kiln:apps/docs/content/docs/ui/themes/riso.mdx
 ---
 
 <!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
@@ -54,14 +56,14 @@ With no `theme`, you get **Paper**, the neutral default. `ThemeProvider` writes
 
 ```tsx
 import '@mitcsutt/kiln-ui/styles.css'
-import '@mitcsutt/kiln-ui/themes/monograph.css'
+import '@mitcsutt/kiln-ui/themes/flightdeck.css'
 
-;<ThemeProvider theme="monograph" defaultMode="dark">
+;<ThemeProvider theme="flightdeck" defaultMode="dark">
   …
 </ThemeProvider>
 ```
 
-Presets are separate files, so an app pays only for the ones it imports. [Themes](references/paper.md) shows all four, and [Theming](https://kiln.mitchellsutton.com/docs/ui/foundations/theming) shows how to write your own.
+Presets are separate files, so an app pays only for the ones it imports. [Themes](references/paper.md) shows all six, and [Theming](https://kiln.mitchellsutton.com/docs/ui/foundations/theming) shows how to write your own.
 
 ## Compose a screen
 
@@ -126,11 +128,11 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 The reader's mode is stored in `localStorage` under `kiln-color-mode`. Every app on one origin shares that key, so a choice made in one carries into the next. Give each app its own key with `storageKey`, or keep a key the app already used so returning readers keep their choice. Pass the same key to `themeScript`:
 
 ```tsx
-;<ThemeProvider theme="ledger" defaultMode="light" storageKey="budget:color-mode">
+;<ThemeProvider theme="ledger" defaultMode="light" storageKey="acme:color-mode">
   …
 </ThemeProvider>
 
-themeScript('ledger', 'light', { storageKey: 'budget:color-mode' })
+themeScript('ledger', 'light', { storageKey: 'acme:color-mode' })
 ```
 
 ### Without server rendering
@@ -150,7 +152,7 @@ export default defineConfig({
       transformIndexHtml: () => [
         {
           tag: 'script',
-          children: themeScript('ledger', 'light', { storageKey: 'budget:color-mode' }),
+          children: themeScript('ledger', 'light', { storageKey: 'acme:color-mode' }),
           injectTo: 'head-prepend',
         },
       ],
@@ -229,7 +231,9 @@ Merges class names, filtering falsy values.
 
 Read a reference when its description matches the task:
 
-- [Paper](references/paper.md): The neutral default. A typeset proof on good uncoated stock, where the ink is the accent.
+- [Paper](references/paper.md): The neutral default. An office that prints for everyone, with white sheets on grey stock, blue-black ink as the accent and Golos Text for type.
 - [Monograph](references/monograph.md): A scholarly monograph read under a desk lamp at night. Blue slate, one ember accent, a big serif display. Dark-first.
-- [Ledger](references/ledger.md): An accountant's ruled book. Green-grey paper, bank-note green, accounting red, and figures set like receipt tape.
+- [Ledger](references/ledger.md): An accountant's columnar pad. A white sheet ruled in green, banknote-green actions, accounting red, and figures set condensed instead of in a monospace.
 - [Fiesta](references/fiesta.md): A screen-printed festival poster. Flat spot inks, hard offsets, condensed signage numerals and springy motion.
+- [Flightdeck](references/flightdeck.md): A glass-cockpit flight display. Cyan for what you set, a reverse-video box for what you select, and green, amber and red for status, set in B612. Dark-first.
+- [Riso](references/riso.md): A two-drum risograph zine. Fluorescent pink and blue on white stock, screen tints instead of borders, and Shantell Sans.

package/skills/setup-and-theming/references/fiesta.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/themes/fiesta
 
 _A screen-printed festival poster and sticker album._ Screen printing can't do gradients, so neither does Fiesta: flat spot inks on apricot poster stock, everything keylined in aubergine, and a hard misregistered offset where other themes have a soft shadow.
 
+Fiesta predates Kiln's [second-order design rules](https://kiln.mitchellsutton.com/docs/ui/foundations/design-rules#second-order-tells) and keeps its original design for compatibility, so it isn't the model for a new theme. Its status inks are kept apart for real use: the gold is only the highlight ("you"), caution is marigold, and critical is a deep brick that never reads as the coral accent.
+
 
 ## Use it
 
@@ -21,7 +23,7 @@ import { ThemeProvider } from '@mitcsutt/kiln-ui'
 </ThemeProvider>
 ```
 
-Fiesta's two faces are declared in its own stylesheet, so they cost nothing unless you import it. It's light-first (the daytime show); dark mode is the floodlit night show.
+Fiesta's faces (Big Shoulders, Bricolage Grotesque and Martian Mono for code) are declared in its own stylesheet, so they cost nothing unless you import it. It's light-first (the daytime show); dark mode is the floodlit night show.
 
 ## The idea, applied
 

package/skills/setup-and-theming/references/flightdeck.md

@@ -0,0 +1,39 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Flightdeck
+
+> A glass-cockpit flight display. Cyan for what you set, a reverse-video box for what you select, and green, amber and red for status, set in B612. Dark-first.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/themes/flightdeck
+
+_A glass-cockpit flight display._ Flightdeck follows the colour convention of electronic flight instruments, where each colour has one fixed meaning, and sets everything in the typefaces designed for Airbus cockpit displays.
+
+
+## Use it
+
+Flightdeck is a preset, so import its stylesheet. It's dark-first, so pair it with `defaultMode="dark"`, and give `themeScript` the same:
+
+```tsx
+import '@mitcsutt/kiln-ui/styles.css'
+import '@mitcsutt/kiln-ui/themes/flightdeck.css'
+import { ThemeProvider, themeScript } from '@mitcsutt/kiln-ui'
+
+;<html lang="en">
+  <head>
+    <script dangerouslySetInnerHTML={{ __html: themeScript('flightdeck', 'dark') }} />
+  </head>
+  <body>
+    <ThemeProvider theme="flightdeck" defaultMode="dark">
+      …
+    </ThemeProvider>
+  </body>
+</html>
+```
+
+## The idea, applied
+
+- **Colour.** The cockpit convention, mapped onto Kiln's roles. Cyan is the accent: what the pilot sets and acts on. What you selected is a neutral reverse-video box, like the selected line of a flight-management display. Green, amber and red are the positive, caution and critical tones, and info is steel blue. Neutrals are dark blue-grey display glass, never black. Light mode is the day mode of an electronic flight bag: pale cool grey with the cyan darkened to pass contrast.
+- **Type.** B612 for text, display and figures (its digits are already equal width), and B612 Mono for code. B612 ships static regular and bold weights and a Latin subset only, so Latin Extended text falls back to a system face. There are no uppercase transforms.
+- **Shape.** Square instrument bezels: small radii on actions, fields and surfaces. Chips are pills, like annunciator capsules.
+- **Depth.** Hairlines, with no shadow on static surfaces. Floating layers add a very subtle dark shadow, with no glow.
+- **Motion.** Instruments move linearly and quickly: a gentle ease-out, a little faster than the default, and no bounce.

package/skills/setup-and-theming/references/ledger.md

@@ -2,11 +2,11 @@
 
 # Ledger
 
-> An accountant's ruled book. Green-grey paper, bank-note green, accounting red, and figures set like receipt tape.
+> An accountant's columnar pad. A white sheet ruled in green, banknote-green actions, accounting red, and figures set condensed instead of in a monospace.
 
 Source: https://kiln.mitchellsutton.com/docs/ui/themes/ledger
 
-_An accountant's ruled book._ Quiet, dense and numeric. In Ledger the numbers are the content, so they get their own face: a condensed monospace, always tabular, like receipt tape.
+_An accountant's columnar pad._ Quiet, dense and numeric. In Ledger the numbers are the content, so they get their own treatment: the same face set condensed, always tabular, so a column of money reads like receipt tape.
 
 
 ## Use it
@@ -25,8 +25,8 @@ Ledger is light-first. It suits screens that are mostly tables and totals: invoi
 
 ## The idea, applied
 
-- **Colour.** Faint green-grey ledger paper, a bank-note green accent, accounting red for negatives and a highlighter-yellow highlight.
-- **Type.** Schibsted Grotesk throughout, and Martian Mono at 80% width for every figure. A 15px base on a 1.2 ratio.
-- **Shape.** 5px radii everywhere, and a compact density of 0.86, so every space step and control is smaller.
-- **Depth.** Hairlines, and a double rule above a table's footer (`--table-foot-rule`), as a ledger totals a column.
-- **Motion.** Brief and flat (`--motion-scale: 0.8`).
+- **Colour.** A white sheet, with the green carried by the rules rather than the paper. Banknote green for actions, accounting red for negatives and a flat highlighter yellow for the highlight. Dark mode is a blue-green carbon-copy night with dim green rules, not a green-screen terminal.
+- **Type.** Archivo throughout. Figures use its width axis to set condensed (`--numeric-stretch`) with tabular numerals, so they get receipt-tape narrowness without a monospace. Atkinson Hyperlegible Mono is for code only. A 15px base on a 1.2 ratio.
+- **Shape.** Tight radii on actions, fields and surfaces, squarer chips, and rounded-square avatars like ledger stamps. A compact density of 0.86, so every space step and control is smaller.
+- **Depth.** Hairlines in the ledger green, with flat surfaces, and a double rule above a table's footer (`--table-foot-rule`), as a ledger totals a column.
+- **Motion.** Brief and flat, with no bounce (`--motion-scale: 0.8`).

package/skills/setup-and-theming/references/monograph.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/themes/monograph
 
 _A scholarly monograph read under a desk lamp at night._ Modern nostalgia: blue slate rather than black, a single ember accent that behaves like phosphor, and a serif display set big and tight over a newsroom grotesk.
 
+Monograph predates Kiln's [second-order design rules](https://kiln.mitchellsutton.com/docs/ui/foundations/design-rules#second-order-tells) and ships unchanged for compatibility, so it isn't the model for a new theme.
+
 
 ## Use it
 
@@ -30,6 +32,8 @@ import { ThemeProvider, themeScript } from '@mitcsutt/kiln-ui'
 </html>
 ```
 
+Its faces (Newsreader, Schibsted Grotesk and Martian Mono) are declared in its own stylesheet, so they cost nothing unless you import it.
+
 ## The idea, applied
 
 - **Colour.** Blue-slate neutrals (hue 255, never black). One ember accent (`oklch(0.72 0.15 52)` in dark, `oklch(0.565 0.158 44)` in light) that marks what's live and current, and never decorates. A cool slate highlight.