@mitcsutt/kiln-ui 0.2.2 → 0.3.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 are kept unchanged for compatibility. 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,7 +34,7 @@ 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
 
@@ -44,6 +44,34 @@ Generated UI converges on the statistical median: indigo buttons, Inter, gradien
 - 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 ship unchanged 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,7 +83,7 @@ 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.
+- **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 ~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.
 - **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.

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
 
@@ -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 ships unchanged for compatibility, so it isn't the model for a new theme.
+
 
 ## 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.

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

@@ -2,11 +2,11 @@
 
 # Paper
 
-> The neutral default. A typeset proof on good uncoated stock, where the ink is the accent.
+> 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.
 
 Source: https://kiln.mitchellsutton.com/docs/ui/themes/paper
 
-_A typeset proof on good uncoated stock._ Paper is the theme you get when you set none. It's in the base stylesheet, and it's built to sit under any brand without arguing with it: graphite ink on warm-neutral paper, with the ink itself as the accent.
+_An office that prints for everyone._ Paper is the theme you get when you set none. It's in the base stylesheet, and it's built to sit under any brand without arguing with it: white sheets on grey recycled stock, blue-black ink as the accent, and a typeface drawn for public services, so that everyone can read it.
 
 
 ## Use it
@@ -24,12 +24,12 @@ Paper is also declared on the document root at zero specificity, so a preset or
 
 ## The idea, applied
 
-- **Colour.** Warm-neutral paper (hue 85, chroma no more than 0.008) and graphite ink. The primary action, the current item and live state are solid ink, and links are ink told apart by their underline. The one other hue is the editor's non-photo blue, kept for "you", the selected row and text selection. Tones are the only saturated colour on the page.
-- **Type.** Schibsted Grotesk for everything you scan (text, headings, and display at weight 640 with −0.04em tracking), Newsreader for long reading and for figures, whose tabular punctuation sits tighter, and Martian Mono for code. A 16px base on a 1.25 ratio.
-- **Shape.** Square-shouldered: 6px actions, fields and chips, 8px surfaces, round avatars.
-- **Depth.** Hairlines only. Soft graphite shadows for floating layers.
+- **Colour.** Cool grey stock for the canvas and near-white sheets for surfaces, so a surface reads against the page by fill alone. The primary action, the current item and live state are solid blue-black ink, and links are ink told apart by their underline. The one other hue is the proofreader's non-photo blue, kept for "you", the selected row and text selection. Tones are the only saturated colour on the page.
+- **Type.** Golos Text for everything: text, headings, display, prose and figures. Atkinson Hyperlegible Mono for code. Paratype drew Golos for a national public-services website, so it has a plain zero, true tabular figures and distinct I, l and 1, and that is why it is here. The bundle has no italic file, so italics are synthesised. There is no serif. A 16px base on a 1.25 ratio.
+- **Shape.** Square-shouldered actions and fields, slightly rounder surfaces, and pill chips as the one deliberate contrast. Round avatars.
+- **Depth.** A fill change rather than a border: a sheet on stock needs no edge. Soft blue-black shadows for floating layers.
 - **Motion.** A quart ease-out, brisk, with no bounce.
 
-## All four themes
+## All six themes
 
 The same screen in each built-in theme, in the page's current mode:

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

@@ -0,0 +1,32 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Riso
+
+> A two-drum risograph zine. Fluorescent pink and blue on white stock, screen tints instead of borders, and Shantell Sans.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/themes/riso
+
+_A two-drum risograph zine._ A riso print can't do gradients or soft shadows. It does flat spot ink, screen tints and the occasional misregistration, so that is all Riso uses: two inks on bright white stock, set in a typeface drawn from handwriting.
+
+
+## Use it
+
+```tsx
+import '@mitcsutt/kiln-ui/styles.css'
+import '@mitcsutt/kiln-ui/themes/riso.css'
+import { ThemeProvider } from '@mitcsutt/kiln-ui'
+
+;<ThemeProvider theme="riso" defaultMode="light">
+  …
+</ThemeProvider>
+```
+
+Riso's face is declared in its own stylesheet, so it costs nothing unless you import it. It's light-first, and dark mode is the deep-blue-stock edition.
+
+## The idea, applied
+
+- **Colour.** Two drums: fluorescent pink is the accent and blue is the text colour, on bright white stock. Surfaces are screen tints (a percentage of an ink) rather than borders. The highlight is an overprint: a pink tint under blue ink. Night mode is the same two inks printed on deep blue stock, not black.
+- **Type.** Shantell Sans for every role except code, drawn from the artist Shantell Martin's own handwriting. It has no tabular figures, so numerals are not column-aligned. Atkinson Hyperlegible Mono is for code. A 1.25 ratio.
+- **Shape.** Hand-cut and mixed: generous radii on actions and surfaces, smaller radii on fields, and pill chips.
+- **Depth.** A fill change, with no shadow on static surfaces. The one misregistered moment is a hard pink offset on floating layers, as if the second drum printed slightly off.
+- **Motion.** A mild spring: things land with a small overshoot.