shelving 1.236.2 → 1.238.0

package/extract/IndexExtractor.js

@@ -62,8 +62,15 @@ function _absorbIndex(element, index) {
     // Recurse first so nested levels absorb their own indexes before we look at this one.
     // Only descend into elements that actually have children — leaving childless leaves (e.g. files) untouched, including their `undefined` children.
     const recursed = Array.from(walkElements(element.props.children)).map(child => notNullish(child.props.children) ? _absorbIndex(child, index) : child);
-    // Find the index child by key.
-    const indexChild = recursed.find(child => anyMatch(child.key, ...index));
+    // Find the index child by pattern priority: the earliest `index` pattern with a matching child wins, so a
+    // README.md is preferred over an index.ts barrel even when the barrel is listed first on disk (a barrel carries
+    // no prose, so absorbing it instead of the README would silently drop the directory's documentation).
+    let indexChild;
+    for (const matcher of index) {
+        indexChild = recursed.find(child => anyMatch(child.key, matcher));
+        if (indexChild)
+            break;
+    }
     if (!indexChild)
         return { ...element, props: { ...element.props, children: recursed } };
     // Fold the index child into the parent, and drop it from children.

package/extract/MergingExtractor.d.ts

@@ -20,9 +20,11 @@ export interface MergingExtractorOptions {
 /**
  * Through extractor that walks a tree of `tree-element` nodes and merges sibling tree elements whose keys match a `merges` template pair.
  * - Purely key-based: it doesn't care whether siblings are directories or files — any element with children is processed, at every level.
+ * - **Token-first:** a secondary (e.g. `Card.md`) is preferentially folded into the same-named documentation token declared by a sibling file (the `Card` symbol inside `Card.tsx`), not the file element. Exported names are unique across the package, so this is unambiguous — and it lands the prose on the published symbol page, which survives the module flatten (file-element content does not).
+ * - **File fallback:** when no same-named token exists, the secondary folds into a sibling *file* whose key matches a `merges` candidate (whole-file prose like `template.md` → `template.ts`).
  * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
- * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
+ * - A secondary with no matching token or file is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
  *
  * @example
  * ```ts

package/extract/MergingExtractor.js

@@ -15,9 +15,11 @@ const DEFAULT_MERGES = {
 /**
  * Through extractor that walks a tree of `tree-element` nodes and merges sibling tree elements whose keys match a `merges` template pair.
  * - Purely key-based: it doesn't care whether siblings are directories or files — any element with children is processed, at every level.
+ * - **Token-first:** a secondary (e.g. `Card.md`) is preferentially folded into the same-named documentation token declared by a sibling file (the `Card` symbol inside `Card.tsx`), not the file element. Exported names are unique across the package, so this is unambiguous — and it lands the prose on the published symbol page, which survives the module flatten (file-element content does not).
+ * - **File fallback:** when no same-named token exists, the secondary folds into a sibling *file* whose key matches a `merges` candidate (whole-file prose like `template.md` → `template.ts`).
  * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
- * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
+ * - A secondary with no matching token or file is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
  *
  * @example
  * ```ts
@@ -70,10 +72,24 @@ function _mergeElement(element, merges) {
 }
 /** Merge same-template siblings at one directory level. */
 function _mergeChildren(children, merges) {
-    // Index children by key so we can look up primary candidates quickly.
+    // Index children by key so we can look up primary file candidates quickly.
     const byKey = new Map();
     for (const child of children)
         byKey.set(child.key, child);
+    // Index exported documentation tokens by name, recording the key of the file element that declares each.
+    // Exported names are unique across the package, so a `Foo.md` can target the symbol `Foo` directly.
+    const tokensByName = new Map();
+    for (const child of children) {
+        if (child.type !== "tree-element")
+            continue;
+        for (const token of walkElements(child.props.children)) {
+            const t = token;
+            if (t.type === "tree-documentation")
+                tokensByName.set(t.props.name, { fileKey: child.key, token: t });
+        }
+    }
+    // Accumulate token replacements per declaring file: fileKey → (tokenKey → merged token).
+    const tokenUpdates = new Map();
     // Walk in original order, deciding for each whether it's a secondary that should fold into a primary.
     const skip = new Set();
     for (const secondary of children) {
@@ -81,6 +97,18 @@ function _mergeChildren(children, merges) {
             const matches = matchTemplate(lhs, secondary.key);
             if (!matches)
                 continue;
+            // Prefer folding a `.md` into the same-named documentation token (e.g. `Card.md` → the `Card` component) so the
+            // prose lands on the published symbol page — the module flatten keeps tokens but discards file-element content.
+            const base = Object.values(matches)[0];
+            const hit = base ? tokensByName.get(base) : undefined;
+            if (hit && hit.token !== secondary) {
+                const fileMap = tokenUpdates.get(hit.fileKey) ?? new Map();
+                fileMap.set(hit.token.key, mergeTreeElements(fileMap.get(hit.token.key) ?? hit.token, secondary));
+                tokenUpdates.set(hit.fileKey, fileMap);
+                skip.add(secondary);
+                break;
+            }
+            // Otherwise fall back to merging into a sibling file (whole-file prose like `template.md` → `template.ts`).
             for (const rhs of candidates) {
                 const primaryKey = renderTemplate(rhs, matches);
                 const primary = byKey.get(primaryKey);
@@ -94,5 +122,15 @@ function _mergeChildren(children, merges) {
                 break;
         }
     }
-    return children.filter(c => !skip.has(c)).map(c => byKey.get(c.key) ?? c);
+    // Rebuild: drop merged `.md` secondaries, apply file-level merges, and fold token updates into their file elements.
+    return children
+        .filter(c => !skip.has(c))
+        .map(c => {
+        const updated = byKey.get(c.key) ?? c;
+        const fileMap = tokenUpdates.get(c.key);
+        if (!fileMap)
+            return updated;
+        const merged = Array.from(walkElements(updated.props.children), child => fileMap.get(child.key) ?? child);
+        return { ...updated, props: { ...updated.props, children: merged } };
+    });
 }

package/extract/TypescriptExtractor.d.ts

@@ -6,6 +6,7 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
  * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
+ * - A `@kind` tag in a symbol's JSDoc overrides the inferred kind — e.g. `@kind component` relabels a React component (otherwise a `function`) so the docs site groups and colours it as a component. The override also drops the trailing `()` from the title, since a non-function kind reads as a bare name.
  * - Top-of-file JSDoc comment becomes the file's `content`.
  * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on the file and every `tree-documentation` child.
  * - Sets `title` on every `tree-documentation` child — `name()` for functions and methods, bare `name` for other kinds. Parent class context comes from the `class` prop ("member of …" affordance), never the title.

package/extract/TypescriptExtractor.js

@@ -7,6 +7,7 @@ import { extractMarkdownProps } from "./MarkupExtractor.js";
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
  * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
+ * - A `@kind` tag in a symbol's JSDoc overrides the inferred kind — e.g. `@kind component` relabels a React component (otherwise a `function`) so the docs site groups and colours it as a component. The override also drops the trailing `()` from the title, since a non-function kind reads as a bare name.
  * - Top-of-file JSDoc comment becomes the file's `content`.
  * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on the file and every `tree-documentation` child.
  * - Sets `title` on every `tree-documentation` child — `name()` for functions and methods, bare `name` for other kinds. Parent class context comes from the `class` prop ("member of …" affordance), never the title.
@@ -127,7 +128,8 @@ function _extractStatement(statement, source) {
     if (name.startsWith("_"))
         return;
     const jsDoc = _getJSDoc(statement, source);
-    const kind = _getKind(statement);
+    // A `@kind` tag overrides the AST-inferred kind (e.g. `@kind component` for a React component declared as a function).
+    const kind = jsDoc?.kind ?? _getKind(statement);
     if (!kind)
         return;
     const signatures = _getSignatures(statement, source, name);
@@ -442,10 +444,11 @@ function _getClassMembers(statement, source, className) {
 }
 /**
  * `@rule` names handled (parsed or deliberately discarded) — everything else is appended to `unhandled` as raw markup.
+ * - `@kind` is parsed by `_parseJSDocKind` to override the AST-inferred kind, so it must not also leak into `unhandled`.
  * - `@see` is recognised here purely to strip it: it's a VS Code hover affordance (a link back to the docs site) and must
  *   never leak into the rendered page content. It has no dedicated parser; it's simply discarded from the `unhandled` bucket.
  */
-const _HANDLED_RULES = new Set(["param", "params", "return", "returns", "throw", "throws", "example", "examples", "see"]);
+const _HANDLED_RULES = new Set(["kind", "param", "params", "return", "returns", "throw", "throws", "example", "examples", "see"]);
 /** Extract JSDoc from a node. */
 function _getJSDoc(node, source) {
     const ranges = ts.getLeadingCommentRanges(source.text, node.pos);
@@ -460,6 +463,7 @@ function _getJSDoc(node, source) {
         if (!text.startsWith("/**"))
             continue;
         const description = _parseJSDocComment(text);
+        const kind = _parseJSDocKind(text);
         const params = _parseJSDocParams(text);
         const returns = _parseJSDocReturns(text);
         const throws = _parseJSDocThrows(text);
@@ -467,6 +471,7 @@ function _getJSDoc(node, source) {
         const unhandled = _parseJSDocUnhandled(text);
         return {
             description: description || undefined,
+            kind,
             params: params.length ? params : undefined,
             returns: returns.length ? returns : undefined,
             throws: throws.length ? throws : undefined,
@@ -529,6 +534,11 @@ function _parseJSDocComment(text) {
     const result = description.join("\n").trim();
     return result || undefined;
 }
+/** Parse a single `@kind` override from a JSDoc comment (e.g. `@kind component`), or `undefined` when absent. */
+function _parseJSDocKind(text) {
+    // `@kind name` — a single identifier-ish token (letters, digits, hyphens).
+    return text.match(/@kind\s+([\w-]+)/)?.[1];
+}
 /** Parse `@param` tags from a JSDoc comment. Duplicates are kept (overloads). */
 function _parseJSDocParams(text) {
     const results = [];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.236.2",
+	"version": "1.238.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/README.md

@@ -8,299 +8,67 @@ The `ui` module exists so an app never hand-rolls the same form field, card, or
 
 ## How components work
 
-A few conventions run through every component (see also the React Components section of `AGENTS.md`):
+A few conventions run through every component:
 
-- **Styling props, not CSS.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`) and boolean props for on/off variants (`<Button strong>`, `<Section narrow>`, `<Flex wrap>`). Each maps to a class in a CSS Module. You never pass `style` or raw `className`.
-- **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like `Card`, `Section`, `Button`, and `Tag` rather than shipping their own styling.
+- **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`) and boolean props for on/off variants (`<Button strong>`, `<Section narrow>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in *one place* — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style` or raw `className`.
+- **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like [`Card`](/ui/Card), [`Section`](/ui/Section), [`Button`](/ui/Button), and [`Tag`](/ui/Tag) rather than shipping their own styling.
 - **Sentence case.** Titles, headings, and button labels capitalise only the first word.
-- **Theming via CSS variables.** Colour and spacing come from CSS custom properties with fallback chains, so a theme is a small set of variable overrides.
+- **Theme with CSS.** An app-wide custom look is a CSS file, not a wall of props. Write a `theme.css` that overrides the base design-token variables (and, where needed, per-component hooks) at `:root`, and import it after the library styles. The recommended workflow is to spend time tuning those variables to match your design — see [Theming](#theming) below.
 
-## Styling system
+## The styling system
 
-The styling system has four moving parts, all defined in [style/](./style/): design tokens, the tint scale, cascade layers, and the styling props. Components compose them in a predictable shape; consumers theme by overriding CSS custom properties at `:root`.
+The styling system lives in `style/` and has four moving parts: design tokens, the tint scale, cascade layers, and the styling props. Components compose them in a predictable shape; consumers theme by overriding CSS custom properties at `:root`.
 
-### Design tokens
+**Design tokens.** Every design-token constant is defined at `:root`, split across the themed token modules in `style/` — each module owns one domain, documents the variables it defines, and is the page a theme author overrides. `style/layers.css` is the cascade-layer anchor; every `*.module.css` `@import`s it plus the specific token modules it references, so the tokens and the layer order reach every component regardless of bundle order. The domains are: colours ([`getColorClass`](/ui/getColorClass)), font sizes ([`getSizeClass`](/ui/getSizeClass)), font weights ([`getWeightClass`](/ui/getWeightClass)), font faces ([`getFontClass`](/ui/getFontClass)), spacing ([`getSpaceClass`](/ui/getSpaceClass)), widths ([`getWidthClass`](/ui/getWidthClass)), radii ([`getRadiusClass`](/ui/getRadiusClass)), strokes ([`getStrokeClass`](/ui/getStrokeClass)), shadows ([`getShadowClass`](/ui/getShadowClass)), and durations ([`getDurationClass`](/ui/getDurationClass)). Each also defines the semantic aliases a theme usually targets (`--color-primary`, `--color-link`, `--space-paragraph`, …). Components read tokens via `var(--token)`.
 
-[`style/base.css`](./style/base.css) defines every design-token constant at `:root` — colours (`--color-*`), font sizes (`--size-*`), spacing (`--space-*`), radii (`--radius-*`), strokes (`--stroke-*`), shadows (`--shadow-*`), durations (`--duration-*`), font weights (`--weight-*`), and font faces (`--font-*`). Components read these via `var(--token)`; themes override them at `:root` in their own CSS file. No class selectors needed.
+**The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and *recomputed* under [`TINT_CLASS`](/ui/TINT_CLASS) — the heart of how `color=` and `status=` retint a whole subtree. The ladder, the recompute trick, the painting conventions, and the theming guide all live on the [`TINT_CLASS`](/ui/TINT_CLASS) page.
 
-`base.css` is `@import`ed at the top of every `*.module.css` in the codebase — that's how the design tokens (and the cascade layer order) reach every component automatically, regardless of bundle order.
+**Cascade layers.** Styles are ordered by `@layer`, lowest to highest priority: `defaults` (`:root` tokens, the tint ladder, body baseline) → `components` (the bulk of the CSS: `.card`, `.button`, …) → `variants` (cross-cutting opt-in modifiers, which always beat components) → `overrides` (top-priority structural fixes like `:first-child` / `:last-child` margin collapses). Unlayered rules beat all layered rules, so a theme should set tokens at `:root` or wrap its rules in `@layer`.
 
-Alongside the raw scales sit semantic aliases that themes usually target instead: `--color-primary` / `--color-secondary` / `--color-tertiary` (brand), `--color-link` / `--color-focus` (interaction), `--color-success` / `--color-warning` / `--color-failure` (status), `--space-paragraph` / `--space-section` (rhythm).
+**Styling props.** The cross-cutting visual options are props, each backed by a helper in `style/` that maps the prop to a class. Colour and status move the tint anchor — [`getColorClass`](/ui/getColorClass) and [`getStatusClass`](/ui/getStatusClass); font size, weight, and family come from [`getSizeClass`](/ui/getSizeClass), [`getWeightClass`](/ui/getWeightClass), and [`getFontClass`](/ui/getFontClass), which [`getTypographyClass`](/ui/getTypographyClass) combines with text alignment and tint; spacing, padding, and gap from [`getSpaceClass`](/ui/getSpaceClass), [`getPaddingClass`](/ui/getPaddingClass), and [`getGapClass`](/ui/getGapClass); width constraints from [`getWidthClass`](/ui/getWidthClass); flex layout from [`getFlexClass`](/ui/getFlexClass); and opt-in scrolling from [`getScrollClass`](/ui/getScrollClass). Each helper's page lists its exact prop values and what they set. A component opts into the props it wants by extending the matching `*Props` interfaces and composing the `getXxxClass(props)` calls.
 
-### The tint scale
+Each painting component also exposes its own theme hooks — a single tint hook (`--card-tint`) to recolour the whole component, plus per-property hooks (`--card-background`, `--card-radius`, …) for surgical overrides. Those are documented in each component's own **Styling** section (see [`Card`](/ui/Card) for the precedent).
 
-All colour in the library flows from a single anchor variable, **`--tint-50`**, defined in [`style/Tint.module.css`](./style/Tint.module.css). From that one hue, a 21-step ladder — `--tint-00`, `--tint-05`, … `--tint-95`, `--tint-100` — is computed with `color-mix()` in OKLCH: `--tint-00` is black, `--tint-50` is the anchor hue itself, `--tint-100` is white, and every step in between mixes the anchor toward one extreme or the other.
+## Theming
 
-The anchor defaults to `--color-gray`, so the default ladder is a neutral grey ramp — grey is just the colour you get when nothing moves the anchor. The page baseline paints from the extremes: `body { color: var(--tint-00); background: var(--tint-100); }`.
-
-The ladder is computed at `:root` and *recomputed* under the `.tint` class (`TINT_CLASS` in [`style/Tint.tsx`](./style/Tint.tsx)). That recomputation is the whole trick: move the anchor at any scope, apply `.tint`, and all 21 shades rebuild from the new hue at that scope. Colour and status classes are exactly that —
+The recommended way to give an app its own look is a **theme stylesheet**, not styling props. Create a `theme.css`, override the base design-token variables at `:root`, and import it after the library styles:
 
 ```css
-/* Color.module.css — a colour variant just moves the anchor. */
-.red {
-	--tint-50: var(--color-red);
-}
-
-/* Status.module.css — a status maps a semantic name onto a palette colour. */
-.success {
-	--tint-50: var(--color-success);
+/* theme.css — imported after shelving/ui styles */
+:root {
+	--color-primary: oklch(58% 0.25 300); /* purple brand */
+	--font-body: "Inter", system-ui;
+	--radius: 0.5rem; /* tighter corners everywhere */
+	--space: 1.125rem; /* roomier spacing scale */
 }
 ```
 
-`getColorClass()` and `getStatusClass()` compose `TINT_CLASS` automatically, so `<Card color="red">` is: move the anchor to red, rebuild the ladder, and let the card paint from the same steps it always paints from. Descendants inherit the rebuilt ladder, which is why a `<Tag>` or `<Preformatted>` nested in a red card tints to match it.
-
-Components paint from the ladder by convention:
-
-| Step | Used for |
-|---|---|
-| `--tint-00` | Body text, headings — maximum contrast |
-| `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `strong` button backgrounds |
-| `--tint-80` | Borders |
-| `--tint-90` | Surfaces — `Card`, `Preformatted`, `Button` backgrounds |
-| `--tint-95` | Hover state of those surfaces |
-| `--tint-100` | The page background; text on `--tint-50` backgrounds |
-
-Pairings follow contrast: long text reads at `00`-on-`90` or `00`-on-`100`; short labels read at `100`-on-`50`.
-
-### Cascade layers
-
-Order, lowest to highest priority:
-
-| Layer | What's in it |
-|---|---|
-| `defaults` | `:root` design tokens, the tint ladder, body baseline typography, low-priority opt-in defaults |
-| `components` | Component-defining CSS — the bulk of the codebase: `.card`, `.button`, `.notice`, `.heading`, etc. |
-| `variants` | Cross-cutting opt-in modifiers (Color, Status, Spacing, Padding, Gap, Width, Typography, Flex, Scroll). Always beat components. |
-| `overrides` | Top-priority structural overrides — `:first-child` / `:last-child` margin collapses, which need to beat variant-set margins |
+Each base token lives in a themed module that documents the variables it defines and which ones a theme usually overrides. Work from broadest (a palette colour or scale root) to narrowest (a single semantic alias):
 
-**Unlayered rules beat all layered rules.** A consumer theme that wraps its overrides in `@layer theme { … }` or just sets tokens at `:root` is fine; one that writes raw class selectors without participating in the layer system will silently dominate variants.
+- [weight](/ui/getWeightClass) · [size](/ui/getSizeClass) · [font](/ui/getFontClass) — typography (`--weight-*`, `--size-*`, `--font-*`, `--case-label`).
+- [color](/ui/getColorClass) — palette, semantic, and brand colours (`--color-*`).
+- [space](/ui/getSpaceClass) · [width](/ui/getWidthClass) — layout spacing and widths (`--space-*`, `--width-*`).
+- [radius](/ui/getRadiusClass) · [stroke](/ui/getStrokeClass) · [shadow](/ui/getShadowClass) · [duration](/ui/getDurationClass) — surface tokens (`--radius-*`, `--stroke-*`, `--shadow-*`, `--duration-*`).
 
-### Styling props
+The **tint ladder** is the one exception that doesn't follow the override-a-variable pattern: its 21 steps are *recomputed* from a single anchor inside every tinted scope, so you move the anchor rather than overriding individual steps. See [`TINT_CLASS`](/ui/TINT_CLASS) for the full theming guide, and each component's **Styling** section for its per-component hooks.
 
-[`style/`](./style/) exports the cross-cutting styling props. Each module has the same shape: a `.module.css` with classes inside `@layer variants`, and a `.tsx` exporting a `getXxxClass(props)` helper plus a props interface that components extend.
+## Finding your way around
 
-Scales — anything with mutually-exclusive options — are enumerated props:
+The components below are listed in the index following this page; this is the short version of where to start reading.
 
-| Prop | Module | Values | Sets |
-|---|---|---|---|
-| `color=` | [`Color`](./style/Color.tsx) | `"primary"`, `"secondary"`, `"tertiary"`, `"red"`, `"orange"`, `"yellow"`, `"green"`, `"aqua"`, `"blue"`, `"purple"`, `"pink"`, `"gray"` | The tint anchor — recolours the whole scope |
-| `status=` | [`Status`](./style/Status.tsx) | `"info"`, `"success"`, `"warning"`, `"danger"`, `"error"`, `"loading"` | The tint anchor, via a semantic name |
-| `size=` | [`Typography`](./style/Typography.tsx) | `"xxsmall"` … `"xxlarge"` | `font-size` |
-| `tint=` | [`Typography`](./style/Typography.tsx) | `"00"`, `"05"`, … `"100"` | Text `color`, as a step of the current ladder |
-| `space=` | [`Spacing`](./style/Spacing.tsx) | `"none"`, `"xxsmall"` … `"xxlarge"` | `margin-block` (top + bottom) |
-| `padding=` | [`Padding`](./style/Padding.tsx) | `"none"`, `"xxsmall"` … `"xxlarge"` | `padding-block` (top + bottom) |
-| `gap=` | [`Gap`](./style/Gap.tsx) | `"none"`, `"xxsmall"` … `"xxlarge"` | `gap` between children |
+**Content.** Block-level structure starts with [`Card`](/ui/Card), [`Section`](/ui/Section), and the [`Heading`](/ui/Heading) / [`Title`](/ui/Title) family, with [`Table`](/ui/Table), [`List`](/ui/List), and [`Figure`](/ui/Figure) for specific shapes; wrap longform copy in [`Prose`](/ui/Prose). Inline pieces — [`Link`](/ui/Link), [`Code`](/ui/Code), [`Strong`](/ui/Strong), [`Mark`](/ui/Mark) — live inside that block content. To render a Markdown string as components, use [`Markup`](/ui/Markup).
 
-On/off options stay boolean props:
-
-| Props | Module | Purpose |
-|---|---|---|
-| `narrow`, `wide`, `full` | [`Width`](./style/Width.tsx) | Constrain (or unconstrain) `max-width` |
-| `body`, `code`, `monospace`, `sans`, `serif` | [`Typography`](./style/Typography.tsx) | Font family |
-| `left`, `center`, `right` | [`Typography`](./style/Typography.tsx) | Text alignment |
-| `wrap`, `column`, `reverse`, justify/align (`left`, `middle`, `between`, …) | [`Flex`](./style/Flex.tsx) | Flex layout (composes `gap=`) |
-| `horizontal`, `vertical` | [`Scroll`](./style/Scroll.tsx) | Opt-in scrolling (combinable) |
-
-Status also keeps boolean aliases (`<Notice error>` ≡ `<Notice status="error">`) because they read naturally at call sites that hard-code one status.
-
-A component using styling props looks like:
-
-```tsx
-export interface CardProps extends ColorProps, StatusProps, PaddingProps, SpacingProps, WidthVariants /* … */ {}
-
-export function Card({ children, ...props }: CardProps): ReactElement {
-  return (
-    <article
-      className={getClass(
-        getModuleClass(CARD_CSS, "card"),
-        getStatusClass(props),
-        getColorClass(props),
-        getPaddingClass(props),
-        getSpacingClass(props),
-        getWidthClass(props),
-      )}
-    >
-      {children}
-    </article>
-  );
-}
-```
-
-```tsx
-// At a call site:
-<Card color="purple" padding="large" space="none">…</Card>
-```
+**Structure.** Mount a client app with [`App`](/ui/App), or render a full server document with [`HTML`](/ui/HTML) and [`Page`](/ui/Page). Arrange the screen with [`CenteredLayout`](/ui/CenteredLayout) or [`SidebarLayout`](/ui/SidebarLayout), and drive URLs with [`Navigation`](/ui/Navigation) and [`Router`](/ui/Router).
 
-### Component theme hooks
-
-Each component exposes per-component CSS custom properties for its overridable values, read with a `var(--component-hook, default)` fallback chain. A consumer overrides the hook at `:root` to retheme that one component without touching the rest of the design system.
-
-Every painting component exposes two kinds of hook:
-
-- **A tint hook** — the component rebinds the scale anchor once, at the top of its rule: `--tint-50: var(--card-tint, inherit);`. Setting `--card-tint: var(--color-purple)` recolours every card (and everything nested inside cards) while leaving the rest of the page alone. The `inherit` fallback is what lets `color=` / `status=` variants and parent scopes flow through when the hook is unset.
-- **Per-property hooks** — `--card-background`, `--card-border`, `--card-padding`, `--card-radius`, `--card-shadow`, and so on, for surgical overrides of a single painted property: `background: var(--card-background, var(--tint-90))`.
-
-Naming follows the file-prefix rule from [AGENTS.md](/AGENTS.md): hooks owned by a module file start with that file's kebab-case name — `Card.module.css` owns `--card-*`, `Button.module.css` owns `--button-*`. Design tokens declared at `:root` in `base.css` and the tint ladder itself are exempt — they're the global palette, not file-owned.
-
-### Theming
-
-A theme is a CSS file of custom-property overrides at `:root`, imported after the base styles. Work from broadest to narrowest:
-
-1. **Move a palette colour.** Overriding `--color-gray` moves the default anchor, retinting every neutral ladder in the app — the broadest possible change. Overriding `--color-red`, `--color-primary`, etc. re-aims every variant and status that maps to it.
-2. **Retint one component family.** Set its tint hook: `--card-tint: var(--color-purple)` makes all cards (and their nested content) purple-tinted, with text, border, surface, and hover shades all derived for free.
-3. **Override one property.** Per-property hooks are the scalpel: `--button-radius: 999px`, `--card-border: none`, `--tag-case: none`.
-
-**Don't override individual ladder steps (`--tint-90`, etc.) at `:root`.** The ladder is *recomputed* from the anchor inside every `.tint` scope — which includes every component that accepts `color=` or `status=` — so a step override at `:root` only reaches untinted regions and produces inconsistent surfaces. Move the anchor (option 1 or 2) instead, and the steps follow.
-
-### How `:first-child` / `:last-child` margin overrides work
-
-Every paragraph-level component zeros its outer margins when it's the first or last child of its container — otherwise a Heading at the top of a Card would leave a strip of unwanted space. These rules live in `@layer overrides`, which beats every other layer including `variants`, so a `<Paragraph space="large">` still collapses its abutting edges correctly.
-
-Pattern:
-
-```css
-@layer components {
-  .paragraph { margin-block: var(--paragraph-space, var(--space-paragraph)); }
-}
-
-@layer overrides {
-  .paragraph {
-    &:first-child { margin-block-start: 0; }
-    &:last-child { margin-block-end: 0; }
-  }
-}
-```
+**Interaction.** Forms start at [`Form`](/ui/Form), which wires [`Field`](/ui/Field) and the typed inputs to a [`FormStore`](/ui/FormStore); [`Button`](/ui/Button) is the standalone action. Overlays are [`Dialog`](/ui/Dialog) and [`Modal`](/ui/Modal); navigation menus are [`Menu`](/ui/Menu) and [`MenuItem`](/ui/MenuItem); transient feedback is [`Notice`](/ui/Notice) (and the global [`Notices`](/ui/Notices) list); animate enter/leave with [`Transition`](/ui/Transition).
 
-### Writing a new component
-
-A typical new block-level component looks like:
-
-```tsx
-// Address.tsx
-import { type ColorProps, getColorClass } from "../style/Color.js";
-import { getSpacingClass, type SpacingProps } from "../style/Spacing.js";
-import { getTypographyClass, type TypographyProps } from "../style/Typography.js";
-
-export interface AddressProps extends ColorProps, SpacingProps, TypographyProps, ChildProps {}
-
-export function Address({ children, ...props }: AddressProps) {
-  return (
-    <address
-      className={getClass(
-        getModuleClass(styles, "address"),
-        getColorClass(props),
-        getSpacingClass(props),
-        getTypographyClass(props),
-      )}
-    >
-      {children}
-    </address>
-  );
-}
-```
-
-```css
-/* Address.module.css */
-@import "../style/base.css";
-
-@layer components {
-  .address {
-    /* Theme — rebind the tint anchor so `--address-tint` (and parent scopes) flow through. */
-    --tint-50: var(--address-tint, inherit);
-
-    /* Box */
-    display: block;
-    margin-inline: 0;
-    margin-block: var(--address-space, var(--space-paragraph));
-
-    /* Text — paint from the ladder, with a per-property hook in front. */
-    color: var(--address-color, var(--tint-00));
-    font-family: var(--address-font, inherit);
-    font-size: var(--address-size, inherit);
-  }
-}
-
-@layer overrides {
-  .address {
-    &:first-child { margin-block-start: 0; }
-    &:last-child { margin-block-end: 0; }
-  }
-}
-```
-
-Checklist:
-
-- [ ] `@import "../style/base.css";` at the top.
-- [ ] All rules inside `@layer components { … }`.
-- [ ] All custom properties owned by this file start with the file name (`--address-*`, etc.), per [AGENTS.md](/AGENTS.md).
-- [ ] If the component paints colour, rebind the tint anchor at the top of the rule (`--tint-50: var(--address-tint, inherit);`) and paint from ladder steps with per-property hooks in front.
-- [ ] `:first-child` / `:last-child` overrides in a separate `@layer overrides { … }` block.
-- [ ] TSX extends the styling-prop interfaces (`ColorProps`, `SpacingProps`, `TypographyProps`, etc.) you want to expose; composes the matching `getXxxClass(props)` calls.
-
-## Module map
-
-### Content
-
-| Folder | What's inside |
-|---|---|
-| [block](/ui/block) | Block-level content — `Card`, `Section`, `Title`, `Heading`, `Table`, `List`, `Prose`, `Figure` |
-| [inline](/ui/inline) | Inline content — `Code`, `Strong`, `Emphasis`, `Link`, `Mark`, `Small` |
-| [misc](/ui/misc) | Cross-cutting pieces — `Markup`, `Tag`, `StatusIcon`, `Loading`, `Catcher`, `Mapper` |
-| [style](./style/) | The styling system — design tokens, the tint scale, styling props, `Flex`, `Scroll` |
-
-### Structure
-
-| Folder | What's inside |
-|---|---|
-| [app](/ui/app) | The `<App>` root component |
-| [page](/ui/page) | Document-level components — `<HTML>`, `<Head>`, `<Page>` |
-| [layout](/ui/layout) | Page layouts — `SidebarLayout`, `CenteredLayout` |
-| [router](/ui/router) | Client-side routing — `<Navigation>`, `<Router>` |
-
-### Interaction
-
-| Folder | What's inside |
-|---|---|
-| [form](/ui/form) | Forms and inputs — `<Form>`, `<Field>`, typed inputs, `<Button>`, `FormStore` |
-| [dialog](/ui/dialog) | `<Dialog>` and `<Modal>` overlays |
-| [menu](/ui/menu) | `<Menu>` and `<MenuItem>` |
-| [notice](/ui/notice) | Inline and global notices |
-| [transition](/ui/transition) | CSS enter / leave transitions |
-
-### Documentation site
-
-| Folder | What's inside |
-|---|---|
-| [tree](/ui/tree) | `<TreeApp>` and the components that turn a tree into a site |
-| [docs](/ui/docs) | Page and card renderers for directories, files, and code symbols |
-| [util](/ui/util) | UI helper functions — context, meta, CSS class composition |
-
-## Quick start
-
-A minimal single-screen app:
-
-```tsx
-import { App, CenteredLayout, Section, Title, Paragraph } from "shelving/ui";
-
-function HelloApp() {
-  return (
-    <App app="My app">
-      <CenteredLayout>
-        <Section narrow>
-          <Title>Hello</Title>
-          <Paragraph>Welcome to the app.</Paragraph>
-        </Section>
-      </CenteredLayout>
-    </App>
-  );
-}
-```
-
-For a routed, multi-page app, wrap the tree in [`<Navigation>` and `<Router>`](/ui/router). For a documentation site, hand an extracted tree to [`<TreeApp>`](/ui/tree) — see the [extract](/extract) guide.
+**Documentation site.** Hand an extracted tree to [`TreeApp`](/ui/TreeApp) and you get a complete site — sidebar, routing, and a rendered page per element — using the renderers in `docs/`.
 
 ## See also
 
 - [extract](/extract) — builds the tree that the documentation components render
-- [markup](/markup) — Markdown rendering used by `<Markup>` and `<Prose>`
-- [store](/store) — reactive state behind `FormStore`, `NavigationStore`, and notices
+- [markup](/markup) — Markdown rendering used by [`Markup`](/ui/Markup) and [`Prose`](/ui/Prose)
+- [store](/store) — reactive state behind [`FormStore`](/ui/FormStore), `NavigationStore`, and notices
 - [react](/react) — store and provider hooks used alongside these components
+
+> Building or extending a component? The contributor walkthrough (file layout, the tint-anchor + per-property-hook pattern, `:first-child` / `:last-child` overrides, and the checklist) lives in the **React Components** section of `AGENTS.md`.

package/ui/app/App.d.ts

@@ -1,5 +1,16 @@
 import type { ReactElement } from "react";
-import "../style/base.css";
+import "../style/layers.css";
+import "../style/Color.module.css";
+import "../style/Duration.module.css";
+import "../style/Font.module.css";
+import "../style/Radius.module.css";
+import "../style/Shadow.module.css";
+import "../style/Size.module.css";
+import "../style/Space.module.css";
+import "../style/Stroke.module.css";
+import "../style/Tint.module.css";
+import "../style/Weight.module.css";
+import "../style/Width.module.css";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
 /**
@@ -12,11 +23,12 @@ export interface AppProps extends PossibleMeta, ChildProps {
 /**
  * Root component for an application, providing the top-level `Meta` context and global styles.
  * - Descendants can read or update metadata via the provided `<Meta>` context.
- * - Design tokens and body baseline typography are set globally via `style/base.css`.
+ * - Design tokens and body baseline typography are set globally via the `style/` token modules (`Color`, `Size`, `Font`, …).
  *
  * @param children The application content.
  * @param meta The root meta (app name, root URL, language, etc.).
  * @returns The app root element wrapping `children`.
+ * @kind component
  * @example <App app="My App" root="https://example.com/"><Navigation>…</Navigation></App>
  * @see https://dhoulb.github.io/shelving/ui/app/App/App
  */

package/ui/app/App.js

@@ -1,14 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
-import "../style/base.css";
+// Load the global design tokens, cascade-layer order, and body baseline. Each module owns its own
+// `:root` tokens (and body rules where relevant); see `modules/ui/README.md` for the styling system.
+import "../style/layers.css";
+import "../style/Color.module.css";
+import "../style/Duration.module.css";
+import "../style/Font.module.css";
+import "../style/Radius.module.css";
+import "../style/Shadow.module.css";
+import "../style/Size.module.css";
+import "../style/Space.module.css";
+import "../style/Stroke.module.css";
+import "../style/Tint.module.css";
+import "../style/Weight.module.css";
+import "../style/Width.module.css";
 /**
  * Root component for an application, providing the top-level `Meta` context and global styles.
  * - Descendants can read or update metadata via the provided `<Meta>` context.
- * - Design tokens and body baseline typography are set globally via `style/base.css`.
+ * - Design tokens and body baseline typography are set globally via the `style/` token modules (`Color`, `Size`, `Font`, …).
  *
  * @param children The application content.
  * @param meta The root meta (app name, root URL, language, etc.).
  * @returns The app root element wrapping `children`.
+ * @kind component
  * @example <App app="My App" root="https://example.com/"><Navigation>…</Navigation></App>
  * @see https://dhoulb.github.io/shelving/ui/app/App/App
  */