@mitcsutt/kiln-ui 0.2.1 → 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/layout-composition/SKILL.md

@@ -7,18 +7,18 @@ metadata:
   library: "@mitcsutt/kiln-ui"
 sources:
   - mitcsutt/kiln:apps/docs/content/docs/ui/foundations/spacing.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/stack.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/inline.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/grid.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/split.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/section.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/container.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/box.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/app-shell.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/action-bar.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/divider.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/aspect-ratio.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/visually-hidden.mdx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Stack/Stack.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Inline/Inline.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Grid/Grid.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Split/Split.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Section/Section.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Container/Container.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Box/Box.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/AppShell/AppShell.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/ActionBar/ActionBar.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Divider/Divider.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/AspectRatio/AspectRatio.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/VisuallyHidden/VisuallyHidden.tsx
   - mitcsutt/kiln:apps/docs/content/docs/ui/patterns/dashboard.mdx
   - mitcsutt/kiln:apps/docs/content/docs/ui/patterns/settings.mdx
   - mitcsutt/kiln:apps/docs/content/docs/ui/patterns/checkout.mdx
@@ -121,6 +121,8 @@ A column of things with consistent space between them. The layout you'll reach f
 
 `Stack` lays its children out vertically with a gap from the space scale. Most screens are stacks of stacks, so most spacing in a Kiln app is a `gap` prop rather than a margin.
 
+`align` sets the cross-axis alignment (`stretch` by default, so children fill the width). Use `align="start"` when a child like a button should keep its own width.
+
 ```tsx
 import { Button, Heading, Stack, Text } from '@mitcsutt/kiln-ui'
 
@@ -137,8 +139,6 @@ export function Usage() {
 }
 ```
 
-`align` sets the cross-axis alignment (`stretch` by default, so children fill the width). Use `align="start"` when a child like a button should keep its own width.
-
 ### Rules between items
 
 `dividers` draws a hairline between every child, centred in the gap. It's usually better than a card per item: lists, settings rows and timelines read as one document.
@@ -180,8 +180,8 @@ export function Dividers() {
 | --- | --- | --- | --- |
 | `gap` | `Responsive<Space>` |  | Space between children, as a step on the theme's space scale. Responsive. |
 | `align` | `Responsive<Align>` | `stretch` | Cross-axis alignment. Responsive. Default `stretch`. |
-| `dividers` | `boolean` |  | Draw a hairline rule between children (the rule sits in the middle of the gap). |
-| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'main' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'form' \| 'fieldset'` |  | Render as a different element. Lists get `role="list"` semantics preserved. |
+| `dividers` | `boolean` | `false` | Draw a hairline rule between children (the rule sits in the middle of the gap). |
+| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'main' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'form' \| 'fieldset'` | `div` | Render as a different element. Lists get `role="list"` semantics preserved. |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 
@@ -193,6 +193,8 @@ Things in a row that wrap when they run out of room. Button rows, tag lists, too
 
 `Inline` lays its children out horizontally with a gap, vertically centred, wrapping onto new lines when they don't fit.
 
+`justify` spreads the row (`between` pushes the groups to either end) and takes responsive values, so a header can stack its groups on a phone and spread them from `md` up. `wrap={false}` keeps everything on one line; children then shrink instead. `rowGap` sets the space between wrapped lines when it should differ from `gap`.
+
 ```tsx
 import { Badge, Button, Inline, Text } from '@mitcsutt/kiln-ui'
 
@@ -214,8 +216,6 @@ export function Usage() {
 }
 ```
 
-`justify` spreads the row (`between` pushes the groups to either end) and takes responsive values, so a header can stack its groups on a phone and spread them from `md` up. `wrap={false}` keeps everything on one line; children then shrink instead. `rowGap` sets the space between wrapped lines when it should differ from `gap`.
-
 ### API
 
 `InlineProps`:
@@ -227,7 +227,7 @@ export function Usage() {
 | `align` | `Responsive<Align>` | `center` | Cross-axis alignment. Default `center`. Responsive. |
 | `justify` | `Responsive<Justify>` | `start` | Main-axis distribution. Default `start`. Responsive. |
 | `wrap` | `boolean` | `true` | Wrap onto new lines. Default `true`. |
-| `as` | `'div' \| 'header' \| 'footer' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'span' \| 'p'` |  |  |
+| `as` | `'div' \| 'header' \| 'footer' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'span' \| 'p'` | `div` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 
@@ -239,6 +239,8 @@ Two-dimensional layout, either with a column count per breakpoint or as an auto-
 
 `Grid` has two modes. With `columns`, you choose how many equal columns there are, per breakpoint. With `minItemWidth`, the grid fits as many columns as there's room for, each at least that wide, so it adapts to its container without a single breakpoint.
 
+One column on a phone, two from `sm` and four from `lg`.
+
 ```tsx
 import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
@@ -318,7 +320,7 @@ export function Items() {
 | `gap` | `Responsive<Space>` |  | Space between cells (both axes). Responsive. |
 | `rowGap` | `Responsive<Space>` |  | Row gap, if different from `gap`. Responsive. |
 | `align` | `Responsive<Align>` | `stretch` | Cell alignment on the block axis. Default `stretch`. Responsive. |
-| `as` | `'div' \| 'section' \| 'ul' \| 'ol' \| 'dl'` |  |  |
+| `as` | `'div' \| 'section' \| 'ul' \| 'ol' \| 'dl'` | `div` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 
@@ -348,6 +350,8 @@ An asymmetric two-column layout that stacks on small screens. A heading beside i
 
 `Split` takes exactly two children and puts them side by side in a ratio. Asymmetric splits read as designed; a 50/50 split of a heading and a list rarely does. Below `collapseBelow` (`md` by default) the two stack, first child on top.
 
+A heading and a list of changes in a 5/7 split, stacked on a phone.
+
 ```tsx
 import { Heading, Split, Stack, Text } from '@mitcsutt/kiln-ui'
 
@@ -410,82 +414,17 @@ export function Ratios() {
 | `collapseBelow` | `'sm' \| 'md' \| 'lg'` | `md` | Stack the two children vertically below this breakpoint. Default `md`. |
 | `gap` | `Responsive<Space>` |  | Space between the two sides (and between them when stacked). Responsive. |
 | `align` | `Responsive<Align>` | `start` | Block-axis alignment of the two sides. Default `start`. Responsive. |
-| `reverse` | `boolean` |  | Put the second child first *visually* when split. DOM (and stacked) order is unchanged. |
+| `reverse` | `boolean` | `false` | Put the second child first *visually* when split. DOM (and stacked) order is unchanged. |
 | `children` (required) | `[ReactNode, ReactNode]` |  | Exactly two children: the first and second side. |
-| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer'` |  |  |
+| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer'` | `div` |  |
 
 Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
-## Section
-
-A full-bleed band of vertical space, with an optional surface and rules. Put a Container inside it for width.
-
-`Section` is how a page gets its rhythm: each band pads itself top and bottom with a step from the space scale, and can paint a surface across the full width. Width is the `Container`'s job, so a section is almost always `Section` then `Container`.
-
-```tsx
-import { Button, Container, Heading, Section, Stack, Text } from '@mitcsutt/kiln-ui'
-
-export function Usage() {
-  return (
-    <>
-      <Section space={7}>
-        <Container width="text">
-          <Stack gap={3}>
-            <Heading level={3} size="2xl">
-              Ride the coast for less
-            </Heading>
-            <Text tone="muted">An annual pass covers every ferry and bus in the bay.</Text>
-          </Stack>
-        </Container>
-      </Section>
-      <Section space={6} surface="inverse" divider="top">
-        <Container width="text">
-          <Stack gap={4} align="start">
-            <Text>Commuting every day? The pass pays for itself in five weeks.</Text>
-            <Button>Buy an annual pass</Button>
-          </Stack>
-        </Container>
-      </Section>
-    </>
-  )
-}
-```
-
-Vary `space` between neighbours. The scale is non-linear for this reason: a page of `space={8}` everywhere has no rhythm at all.
-
-### 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`.
-
-### API
-
-`SectionProps`:
-
-| 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. |
-| `divider` | `'top' \| 'bottom' \| 'both'` |  | A hairline across the full bleed at the top, bottom or both edges. |
-| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer'` |  |  |
-| `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
-| `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
-
-Also accepts every prop of `HTMLAttributes<HTMLElement>`.
-
-#### Component tokens
-
-Set these in a theme, or on one element, to change this component without touching the rest.
-
-| Token | Default and use |
-| --- | --- |
-| `--section-fill` | / --section-on   (read-only) the band's fill and ink on inverse/accent |
-| `--section-space-default` | block padding when `space` is unset (default var(--space-8)) |
-| `--section-divider-color` | hairline colour for `divider` (default var(--color-line)) |
-
 ## References
 
 Read a reference when its description matches the task:
 
+- [Section](references/section.md): A full-bleed band of vertical space, with an optional surface and rules. Put a Container inside it for width.
 - [Container](references/container.md): Centres content at a readable maximum width, with a fluid gutter outside it.
 - [Box](references/box.md): Padding, a surface and an edge, and nothing else. The escape hatch when no other layout fits.
 - [AppShell](references/app-shell.md): The frame of an app screen. A header, an optional sidebar, the main region, a footer and a phone-only bottom bar.

package/skills/layout-composition/references/action-bar.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/action-bar
 
 `ActionBar` is a row of buttons with consistent spacing and alignment: `end` by default, `between` to push a destructive action to the other side, `start` to follow a form's left edge.
 
+`sticky` keeps the bar at the bottom of the viewport while a long form scrolls, so save is always in reach.
+
 ```tsx
 import { ActionBar, Button, Stack, TextField } from '@mitcsutt/kiln-ui'
 
@@ -32,8 +34,6 @@ export function Usage() {
 }
 ```
 
-`sticky` keeps the bar at the bottom of the viewport while a long form scrolls, so save is always in reach.
-
 ## API
 
 `ActionBarProps`:
@@ -41,7 +41,7 @@ export function Usage() {
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `align` | `'start' \| 'end' \| 'between'` | `end` | Where the actions sit on the row. Default `end`. |
-| `sticky` | `boolean` |  | Pins the bar to the bottom of its scroll container — a canvas surface above a top hairline, at `--z-sticky`. Use inside a scrolling form/dialog body so the primary action stays reachable. |
+| `sticky` | `boolean` | `false` | Pins the bar to the bottom of its scroll container — a canvas surface above a top hairline, at `--z-sticky`. Use inside a scrolling form/dialog body so the primary action stays reachable. |
 | `gap` | `Responsive<Space>` | `3` | Space between actions. Responsive. Default `3`. |
 | `as` | `'div' \| 'footer'` | `div` | Render as `footer` when the bar is the form's own closing landmark. Default `div`. |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |

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

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/app-shell
 
 `AppShell` is the outermost frame of an app: landmarks in the right order, a skip link, a sticky header, and a hand-over between a phone's bottom bar and a desktop's sidebar or header nav. These docs are an `AppShell`.
 
+The window above scrolls; narrow it below `md` and the header links give way to the bottom bar.
+
 ```tsx
 import {
   AppShell,
@@ -86,8 +88,6 @@ export function Usage() {
 }
 ```
 
-The window above scrolls; narrow it below `md` and the header links give way to the bottom bar.
-
 ## Slots
 
 `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.
@@ -108,7 +108,7 @@ The window above scrolls; narrow it below `md` and the header links give way to
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `skipLinkLabel` | `string` | `"Skip to content"` | Text of the skip link rendered before everything else. Default "Skip to content". |
-| `navBreakpoint` | `'md' \| 'lg'` |  | Where navigation hands over from phone to desktop: from this breakpoint up the `Sidebar` appears and the `BottomBar` is removed, so there is never a width with neither. `md` (48em) or `lg` (64em, default). Pair it with the same value on `BottomNav hideAbove` and header `NavLinks hideBelow`. |
+| `navBreakpoint` | `'md' \| 'lg'` | `lg` | Where navigation hands over from phone to desktop: from this breakpoint up the `Sidebar` appears and the `BottomBar` is removed, so there is never a width with neither. `md` (48em) or `lg` (64em, default). Pair it with the same value on `BottomNav hideAbove` and header `NavLinks hideBelow`. |
 | `mainId` | `string` |  | Id given to `AppShell.Main` (the skip link target). Generated when omitted. |
 
 Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.
@@ -121,6 +121,9 @@ Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.
 
 Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
+
+Accepts every prop of `HTMLAttributes<HTMLElement>`.
+
 `AppShellSidebarProps`:
 
 | Prop | Type | Default | Description |
@@ -129,6 +132,10 @@ Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
 Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
+
+
+
+
 ### Component tokens
 
 Set these in a theme, or on one element, to change this component without touching the rest.

package/skills/layout-composition/references/aspect-ratio.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/aspect-ratio
 
 `AspectRatio` holds a ratio as its width changes. Its child (an image, a video, an iframe, an SVG) fills it and is cropped with `object-fit: cover`. It has no edge or radius of its own: wrap it in `Media` or a `Card` for those.
 
+The same chart framed at 16/9, 4/3 and 1/1.
+
 ```tsx
 import { AspectRatio, Grid } from '@mitcsutt/kiln-ui'
 

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

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/box
 
 `Box` adds padding, a background surface, a border and a radius to its content. Reach for `Stack`, `Inline` or `Grid` to arrange things, and for `Card` when something is a self-contained object. `Box` is for the wells and frames left over.
 
+`surface="inverse"` flips the colour roles inside, like an inverse `Section`.
+
 ```tsx
 import { Box, Stack, Text } from '@mitcsutt/kiln-ui'
 
@@ -28,8 +30,6 @@ export function Usage() {
 }
 ```
 
-`surface="inverse"` flips the colour roles inside, like an inverse `Section`.
-
 ## API
 
 `BoxProps`:
@@ -39,10 +39,10 @@ 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'` |  | Background fill. `inverse` also re-points ink and line colours for its children. |
-| `border` | `boolean` |  | Hairline border in `--color-line`. One edge treatment per element — a border *or* a fill. |
-| `radius` | `'none' \| 'surface' \| 'field' \| 'media'` |  | Corner radius, by role. |
-| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'li' \| 'span'` |  |  |
+| `surface` | `'none' \| 'surface' \| 'canvas' \| 'sunken' \| 'raised' \| 'inverse'` | `none` | Background fill. `inverse` also re-points 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` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |