shelving 1.264.1 → 1.265.0

package/package.json

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

package/ui/README.md

@@ -27,7 +27,7 @@ The styling system lives in `style/` and has four moving parts: design tokens, t
 
 **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()` and `getStatusClass()`; font size, weight, family, and case, plus text alignment, tint, and wrapping, all come from `getTypographyClass()`, which extends `ColorVariants` and composes `getColorClass()` so every typographic element also accepts `color` (use `getColorClass()` directly only for colour-without-typography, e.g. `<Icon>`); spacing, block-padding, inline-padding ("indent"), and gap from `getSpaceClass()`, `getPaddingClass()`, `getIndentClass()`, and `getGapClass()`; width constraints from `getWidthClass()`; flex layout from `getFlexClass()`; and opt-in scrolling from `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.
 
-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>` for the precedent).
+Each painting component also exposes per-property theme hooks (`--card-background`, `--card-radius`, …) for surgical overrides. To recolour a component or a whole region, apply `color=` / `status=` — on it or an ancestor scope — rather than a per-component tint hook; components no longer set the tint anchor themselves. Those hooks are documented in each component's own **Styling** section (see `<Card>` for the precedent).
 
 ## Theming
 
@@ -50,7 +50,7 @@ Each base token lives in a themed module that documents the variables it defines
 - `space` · `width` — layout spacing and widths (`--space-*`, `--width-*`).
 - `radius` · `stroke` · `shadow` · `duration` — surface tokens (`--radius-*`, `--stroke-*`, `--shadow-*`, `--duration-*`).
 
-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` for the full theming guide, and each component's **Styling** section for its per-component hooks.
+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 (via `color=` / `status=`) rather than overriding individual steps. See `TINT_CLASS` for the full theming guide, and each component's **Styling** section for its per-property hooks.
 
 ## Finding your way around
 

package/ui/block/Blockquote.module.css

@@ -7,9 +7,6 @@
 @layer components {
 	.blockquote,
 	.prose blockquote {
-		/* Theme */
-		--tint-50: var(--blockquote-tint, inherit);
-
 		/* Box */
 		margin-block: var(--blockquote-space, var(--space-paragraph));
 		border-inline-start: var(--blockquote-border, var(--blockquote-stroke, var(--stroke-normal)) solid var(--tint-80));

package/ui/block/Card.md

@@ -45,11 +45,10 @@ import { Card, Subheading } from "shelving/ui";
 
 ## Styling
 
-`Card` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Move `--card-tint` to recolour everything at once; reach for a per-property hook for a single surgical change.
+`Card` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the card or an ancestor scope) to recolour everything at once — surface, border, text, and hover shade re-derive together; reach for a per-property hook for a single surgical change.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--card-tint` | Tint anchor for the card scope — recolours surface, border, text and hover together | `inherit` (flows from `color=` / `status=` / parent) |
 | `--card-background` | Surface fill | `var(--tint-90)` |
 | `--card-hover-background` | Surface fill when a navigable card is hovered | `var(--tint-95)` |
 | `--card-color` | Text colour | `var(--tint-00)` |
@@ -71,9 +70,6 @@ import { Card, Subheading } from "shelving/ui";
   --card-shadow: var(--shadow-small);
   --card-radius: var(--radius-small);
 }
-
-/* Retint every card purple — surface, border, text and hover all follow. */
-:root {
-  --card-tint: var(--color-purple);
-}
 ```
+
+To recolour cards, apply `color=` / `status=` to the card (or a tinted ancestor scope) — e.g. `<Card color="purple">` — rather than a per-component tint hook.

package/ui/block/Card.module.css

@@ -19,9 +19,6 @@
 
 @layer components {
 	.card {
-		/* Theme */
-		--tint-50: var(--card-tint, inherit);
-
 		/* Box */
 		position: relative;
 		margin-inline: 0;

package/ui/block/Heading.md

@@ -44,7 +44,6 @@ import { Heading } from "shelving/ui";
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--heading-tint` | Tint anchor for the heading scope | `inherit` (flows from `color=` / parent) |
 | `--heading-color` | Text colour | `inherit` |
 | `--heading-space-before` | Top margin | `var(--space-section)` (2rem) |
 | `--heading-space` | Bottom margin | `var(--space-paragraph)` (16px) |

package/ui/block/Heading.module.css

@@ -6,9 +6,6 @@
 @layer components {
 	.heading,
 	.prose h2 {
-		/* Theme */
-		--tint-50: var(--heading-tint, inherit);
-
 		/* Box */
 		margin-block-start: var(--heading-space-before, var(--space-section));
 		margin-block-end: var(--heading-space, var(--space-paragraph));

package/ui/block/Label.module.css

@@ -5,9 +5,6 @@
 
 @layer components {
 	.label {
-		/* Theme */
-		--tint-50: var(--label-tint, inherit);
-
 		/* Box */
 		margin-block: var(--label-space, var(--space-paragraph));
 

package/ui/block/List.md

@@ -31,11 +31,10 @@ import { List } from "shelving/ui";
 
 ## Styling
 
-`List` paints from the [tint ladder](/ui/TINT_CLASS) for its markers only; rebind `--list-tint` to recolour the scope, or reach for a per-property hook for a single change.
+`List` paints from the [tint ladder](/ui/TINT_CLASS) for its markers only; apply `color=` (on the list or an ancestor scope) to recolour the markers, or reach for a per-property hook for a single change.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--list-tint` | Tint anchor for the list scope | `inherit` (flows from `color=` / parent) |
 | `--list-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
 | `--list-gap` | Space between items | `var(--space-xsmall)` |
 | `--list-indent` | Inline start padding (marker gutter) | `1.125em` unordered / `1.8em` ordered |

package/ui/block/List.module.css

@@ -9,9 +9,6 @@
 	.ordered,
 	.prose ul,
 	.prose ol {
-		/* Theme */
-		--tint-50: var(--list-tint, inherit);
-
 		/* Box */
 		margin-block: var(--list-space, var(--space-paragraph));
 

package/ui/block/Panel.md

@@ -31,11 +31,10 @@ import { Panel, Block, Title, Paragraph } from "shelving/ui";
 
 ## Styling
 
-`Panel` paints from the [tint ladder](/ui/TINT_CLASS); rebind `--panel-tint` to recolour the whole scope at once, or reach for a per-property hook for a single change.
+`Panel` paints from the [tint ladder](/ui/TINT_CLASS); apply `color=` / `status=` (on the panel or an ancestor scope) to recolour the whole scope at once — surface, border, and text re-derive together — or reach for a per-property hook for a single change.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--panel-tint` | Tint anchor for the panel scope — recolours surface, border, and text together | `inherit` (flows from `color=` / `status=` / parent) |
 | `--panel-background` | Surface fill | `var(--tint-90)` |
 | `--panel-color` | Text colour | `var(--tint-00)` |
 | `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |

package/ui/block/Panel.module.css

@@ -14,9 +14,6 @@
  */
 @layer components {
 	.panel {
-		/* Theme */
-		--tint-50: var(--panel-tint, inherit);
-
 		/* Box */
 		position: relative;
 		padding-block: var(--panel-padding, var(--space-section));

package/ui/block/Paragraph.md

@@ -31,11 +31,10 @@ import { Paragraph, Strong, Link } from "shelving/ui";
 
 ## Styling
 
-`Paragraph` exposes a single hook for its own block margin and rebinds the tint anchor for its scope; it paints no colour of its own, so it inherits the surrounding text colour.
+`Paragraph` exposes a single hook for its own block margin; it paints no colour of its own, so it inherits the surrounding text colour. Apply `color=` / `status=` to set the tint scope for any ladder-reading inline content inside it.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--paragraph-tint` | Tint anchor for the paragraph scope | `inherit` (flows from `color=` / parent) |
 | `--paragraph-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
 
 **Global tokens it reads:** `--space-paragraph`.

package/ui/block/Paragraph.module.css

@@ -4,9 +4,6 @@
 @layer components {
 	.prose p,
 	.paragraph {
-		/* Theme */
-		--tint-50: var(--paragraph-tint, inherit);
-
 		/* Box */
 		margin-block: var(--paragraph-space, var(--space-paragraph));
 	}

package/ui/block/Preformatted.module.css

@@ -10,9 +10,6 @@
 @layer components {
 	.preformatted,
 	.prose pre {
-		/* Theme */
-		--tint-50: var(--preformatted-tint, inherit);
-
 		/* Box */
 		position: relative;
 		margin-inline: 0;

package/ui/block/Subheading.md

@@ -39,7 +39,6 @@ import { Title, Heading, Subheading } from "shelving/ui";
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--subheading-tint` | Tint anchor for the subheading scope | `inherit` (flows from `color=` / parent) |
 | `--subheading-color` | Text colour | `inherit` |
 | `--subheading-space-before` | Top margin | `var(--space-section)` (2rem) |
 | `--subheading-space` | Bottom margin | `var(--space-paragraph)` (16px) |

package/ui/block/Subheading.module.css

@@ -6,9 +6,6 @@
 @layer components {
 	.subheading,
 	.prose :is(h3, h4, h5, h6) {
-		/* Theme */
-		--tint-50: var(--subheading-tint, inherit);
-
 		/* Box */
 		margin-block-start: var(--subheading-space-before, var(--space-section));
 		margin-block-end: var(--subheading-space, var(--space-paragraph));

package/ui/block/Title.md

@@ -38,7 +38,6 @@ import { Panel, Block, Title } from "shelving/ui";
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--title-tint` | Tint anchor for the title scope | `inherit` (flows from `color=` / parent) |
 | `--title-color` | Text colour | `inherit` |
 | `--title-space-before` | Top margin | `var(--space-section)` (2rem) |
 | `--title-space` | Bottom margin | `var(--space-paragraph)` (16px) |

package/ui/block/Title.module.css

@@ -6,9 +6,6 @@
 @layer components {
 	.title,
 	.prose h1 {
-		/* Theme */
-		--tint-50: var(--title-tint, inherit);
-
 		/* Box */
 		margin-block-start: var(--title-space-before, var(--space-section));
 		margin-block-end: var(--title-space, var(--space-paragraph));

package/ui/button/Button.md

@@ -46,11 +46,10 @@ import { getButtonClass } from "shelving/ui";
 
 ## Styling
 
-`Button` paints from the [tint ladder](/ui/TINT_CLASS). Override these hooks at `:root` or any ancestor scope; move `--button-tint` to recolour the whole button, or use a per-property hook for one change.
+`Button` paints from the [tint ladder](/ui/TINT_CLASS). Override these hooks at `:root` or any ancestor scope; apply `color=` / `status=` (on the button or an ancestor scope) to recolour the whole button, or use a per-property hook for one change.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--button-tint` | Tint anchor for the button scope | `inherit` (flows from `color=` / `status=` / parent) |
 | `--button-background` | Surface fill | `var(--tint-90)` |
 | `--button-hover-background` | Surface fill on hover / focus | `var(--tint-95)` |
 | `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid var(--tint-90)` |

package/ui/button/Button.module.css

@@ -9,9 +9,6 @@
 
 @layer components {
 	.button {
-		/* Theme */
-		--tint-50: var(--button-tint, inherit);
-
 		/* Box */
 		display: block;
 		box-sizing: border-box;

package/ui/docs/DocumentationPage.test.tsx

@@ -1,10 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import type { DocumentationElement } from "../../util/tree.js";
-import { MetaContext } from "../misc/MetaContext.js";
-import { createMeta } from "../util/meta.js";
-import { DocumentationPage } from "./DocumentationPage.js";
+import { createMeta, DocumentationPage, MetaContext } from "shelving/ui";
+import type { DocumentationElement } from "shelving/util/tree";
 
 /** Make a minimal `tree-documentation` child element of a given kind. */
 function doc(name: string, kind: string): DocumentationElement {

package/ui/docs/DocumentationParams.js

@@ -29,7 +29,7 @@ export function DocumentationParams({ params }) {
     const map = useTreeMap();
     if (!params?.length)
         return null;
-    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Param" }), _jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: params.map(({ name, type = DEFAULT_TYPE, description, default: def, optional }) => {
+    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Param" }), _jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "16x", grow: true })] }) }), _jsx("tbody", { children: params.map(({ name, type = DEFAULT_TYPE, description, default: def, optional }) => {
                             const { members, optional: typeOptional } = splitType(type);
                             // An options-bag param whose (single, concrete) type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
                             const single = members.length === 1 ? members[0] : undefined;

package/ui/docs/DocumentationParams.tsx

@@ -55,7 +55,7 @@ export function DocumentationParams({ params }: DocumentationParamsProps): React
 							<Cell header width="fit">
 								Type
 							</Cell>
-							<Cell header width="xxnarrow" grow />
+							<Cell header width="16x" grow />
 						</tr>
 					</thead>
 					<tbody>

package/ui/docs/DocumentationProperties.js

@@ -24,7 +24,7 @@ export function DocumentationProperties({ properties }) {
     const map = useTreeMap();
     if (!properties?.length)
         return null;
-    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Property" }), _jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: properties.map(({ name, type = DEFAULT_TYPE, description, default: def, optional, readonly }) => {
+    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Property" }), _jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "16x", grow: true })] }) }), _jsx("tbody", { children: properties.map(({ name, type = DEFAULT_TYPE, description, default: def, optional, readonly }) => {
                             const { members, optional: typeOptional } = splitType(type);
                             return (_jsxs("tr", { children: [_jsx(Cell, { nowrap: true, children: _jsx(Code, { nowrap: true, children: `.${name}` }) }), _jsx("td", { children: _jsx(DocumentationType, { members: members }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || getTreeElement(map, members[0] ?? DEFAULT_TYPE)?.props.description, default: def, optional: !!optional || typeOptional, readonly: readonly }) })] }, `${name}-${type}`));
                         }) })] }) }) }));

package/ui/docs/DocumentationProperties.tsx

@@ -49,7 +49,7 @@ export function DocumentationProperties({ properties }: DocumentationPropertiesP
 							<Cell header width="fit">
 								Type
 							</Cell>
-							<Cell header width="xxnarrow" grow />
+							<Cell header width="16x" grow />
 						</tr>
 					</thead>
 					<tbody>

package/ui/docs/DocumentationReferences.js

@@ -19,5 +19,5 @@ export function DocumentationReferences({ types }) {
     const map = useTreeMap();
     if (!types?.length)
         return null;
-    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: types.map(type => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: getTreeElement(map, type)?.props.description }) })] }, type))) })] }) }) }));
+    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "16x", grow: true })] }) }), _jsx("tbody", { children: types.map(type => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: getTreeElement(map, type)?.props.description }) })] }, type))) })] }) }) }));
 }

package/ui/docs/DocumentationReferences.tsx

@@ -39,7 +39,7 @@ export function DocumentationReferences({ types }: DocumentationReferencesProps)
 							<Cell header width="fit">
 								Type
 							</Cell>
-							<Cell header width="xxnarrow" grow />
+							<Cell header width="16x" grow />
 						</tr>
 					</thead>
 					<tbody>

package/ui/docs/DocumentationReturns.js

@@ -21,5 +21,5 @@ export function DocumentationReturns({ returns }) {
     const map = useTreeMap();
     if (!returns?.length)
         return null;
-    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Return" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || getTreeElement(map, type)?.props.description }) })] }, `${type}-${description}`))) })] }) }) }));
+    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Return" }), _jsx(Cell, { header: true, width: "16x", grow: true })] }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || getTreeElement(map, type)?.props.description }) })] }, `${type}-${description}`))) })] }) }) }));
 }

package/ui/docs/DocumentationReturns.tsx

@@ -43,7 +43,7 @@ export function DocumentationReturns({ returns }: DocumentationReturnsProps): Re
 							<Cell header width="fit">
 								Return
 							</Cell>
-							<Cell header width="xxnarrow" grow />
+							<Cell header width="16x" grow />
 						</tr>
 					</thead>
 					<tbody>

package/ui/docs/DocumentationThrows.js

@@ -21,5 +21,5 @@ export function DocumentationThrows({ throws }) {
     const map = useTreeMap();
     if (!throws?.length)
         return null;
-    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Throws" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || getTreeElement(map, type)?.props.description }) })] }, `${type}-${description}`))) })] }) }) }));
+    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Throws" }), _jsx(Cell, { header: true, width: "16x", grow: true })] }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || getTreeElement(map, type)?.props.description }) })] }, `${type}-${description}`))) })] }) }) }));
 }

package/ui/docs/DocumentationThrows.tsx

@@ -43,7 +43,7 @@ export function DocumentationThrows({ throws }: DocumentationThrowsProps): React
 							<Cell header width="fit">
 								Throws
 							</Cell>
-							<Cell header width="xxnarrow" grow />
+							<Cell header width="16x" grow />
 						</tr>
 					</thead>
 					<tbody>

package/ui/form/Field.test.tsx

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
-import { Field } from "./Field.js";
+import { Field } from "shelving/ui";
 
 describe("Field", () => {
 	test("does not render a message container when there is no message", () => {

package/ui/form/Progress.d.ts

@@ -1,24 +1,27 @@
 import type { ReactElement } from "react";
+import { type ColorVariants } from "../style/Color.js";
+import { type StatusVariants } from "../style/Status.js";
 /**
  * Props for `Progress`, a continuous horizontal progress bar.
  *
  * @see https://shelving.cc/ui/ProgressProps
  */
-export interface ProgressProps {
+export interface ProgressProps extends ColorVariants, StatusVariants {
     value: number;
     min?: number;
     max?: number;
-    success?: boolean;
-    warning?: boolean;
-    danger?: boolean;
 }
 /**
  * Show progress as a single continuous horizontal bar, filled to `value` within the `min`–`max` range (matches `getPercent()` and `formatPercent()`).
- * - The fill is allowed to overspill; CSS clamps it to the `0%`–`100%` range via `min-width`/`max-width`.
+ * - Renders a native `<progress>` element, so `role="progressbar"` and the value/max semantics come from the browser.
+ * - `<progress>` has no `min` attribute (its implicit minimum is `0`), so the range is normalised to `value - min` / `max - min` before it's handed to the element.
+ * - The browser clamps `value` to the `0`–`max` range, so an out-of-range `value` shows an empty or full bar rather than overspilling.
+ * - Paints from the tint ladder, so `color=` / `status=` recolour the fill (and track) by moving the tint anchor.
  *
  * @returns A progress bar element.
  * @kind component
  * @example <Progress value={3} max={4} />
+ * @example <Progress value={90} status="success" />
  * @see https://shelving.cc/ui/Progress
  */
-export declare function Progress({ value, min, max, success, warning, danger }: ProgressProps): ReactElement | null;
+export declare function Progress({ value, min, max, ...props }: ProgressProps): ReactElement;

package/ui/form/Progress.js

@@ -1,19 +1,25 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { formatPercent } from "../../util/format.js";
-import { getPercent } from "../../util/number.js";
+import { getColorClass } from "../style/Color.js";
+import { getStatusClass } from "../style/Status.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import styles from "./Progress.module.css";
 /**
  * Show progress as a single continuous horizontal bar, filled to `value` within the `min`–`max` range (matches `getPercent()` and `formatPercent()`).
- * - The fill is allowed to overspill; CSS clamps it to the `0%`–`100%` range via `min-width`/`max-width`.
+ * - Renders a native `<progress>` element, so `role="progressbar"` and the value/max semantics come from the browser.
+ * - `<progress>` has no `min` attribute (its implicit minimum is `0`), so the range is normalised to `value - min` / `max - min` before it's handed to the element.
+ * - The browser clamps `value` to the `0`–`max` range, so an out-of-range `value` shows an empty or full bar rather than overspilling.
+ * - Paints from the tint ladder, so `color=` / `status=` recolour the fill (and track) by moving the tint anchor.
  *
  * @returns A progress bar element.
  * @kind component
  * @example <Progress value={3} max={4} />
+ * @example <Progress value={90} status="success" />
  * @see https://shelving.cc/ui/Progress
  */
-export function Progress({ value, min = 0, max = 100, success, warning, danger }) {
-    const percent = getPercent(value - min, max - min);
-    const fillStyle = { width: `${Number.isFinite(percent) ? percent : 0}%` };
-    return (_jsx("figure", { className: getClass(getModuleClass(styles, "track"), success && getModuleClass(styles, "success"), warning && getModuleClass(styles, "warning"), danger && getModuleClass(styles, "danger")), role: "progressbar", "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": value, "aria-valuetext": formatPercent(value - min, max - min), children: _jsx("span", { className: getModuleClass(styles, "fill"), style: fillStyle }) }));
+export function Progress({ value, min = 0, max = 100, ...props }) {
+    // `<progress>` has no `min`, so shift the range to a `0`-based one. A non-positive span would make `<progress>` indeterminate, so fall back to an empty determinate bar.
+    const span = max - min;
+    return (_jsx("progress", { className: getClass(getModuleClass(styles, "progress"), //
+        getColorClass(props), getStatusClass(props)), value: span > 0 ? value - min : 0, max: span > 0 ? span : 1, "aria-valuetext": formatPercent(value - min, max - min) }));
 }

package/ui/form/Progress.md

@@ -0,0 +1,62 @@
+# Progress
+
+A continuous horizontal progress bar for the completion of a task. Rendered as a native `<progress>` element, so the `progressbar` role and value/max semantics come from the browser rather than hand-written ARIA.
+
+**Things to know:**
+
+- Use `Progress` for **task completion** — a value heading toward "done" (an upload, a multi-step form, a load). For a static reading within a range that can move up and down (disk usage, a score), a gauge is the right model, not a progress bar.
+- `value` is filled within the `min`–`max` range (defaults `0`–`100`), matching `getPercent()` and `formatPercent()`. `<progress>` has no `min` attribute, so the range is normalised to `value - min` / `max - min` before it reaches the element.
+- The browser clamps `value` to the `0`–`max` range, so an out-of-range `value` renders an empty or full bar rather than overspilling. A non-positive range (`min === max`) falls back to an empty bar rather than the indeterminate state.
+- `aria-valuetext` carries the formatted percentage, so assistive tech announces e.g. "75%".
+- Paints from the [tint ladder](/ui/TINT_CLASS): `color=` and `status=` move the tint anchor for the bar, so the fill (and track) re-derive together — `status="success"` gives a green bar, `color="purple"` a purple one. Without either, the bar takes the ambient tint (`--tint-50`, gray by default).
+
+## Usage
+
+### Basic
+
+```tsx
+import { Progress } from "shelving/ui";
+
+// 75% full.
+<Progress value={3} max={4} />
+```
+
+### Custom range
+
+```tsx
+import { Progress } from "shelving/ui";
+
+// 50% full — value 15 within the 10–20 range.
+<Progress value={15} min={10} max={20} />
+```
+
+### Status and colour
+
+```tsx
+import { Progress } from "shelving/ui";
+
+<Progress value={90} status="success" />
+<Progress value={20} status="danger" />
+<Progress value={60} color="purple" />
+```
+
+## Styling
+
+`Progress` paints a track (the element / `::-webkit-progress-bar`) and a fill (`::-webkit-progress-value` / `::-moz-progress-bar`) from the [tint ladder](/ui/TINT_CLASS). Apply `color=` / `status=` (on the bar or a tinted ancestor scope) to recolour the fill and track together — reach for a per-property hook only for a single surgical change. Override these hooks at `:root` (or any ancestor scope) to retheme.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--progress-height` | Bar thickness | `0.375rem` (6px) |
+| `--progress-radius` | Corner radius | `999px` (pill) |
+| `--progress-background` | Track fill | `var(--tint-90)` |
+| `--progress-color` | Fill colour | `var(--tint-50)` |
+
+**Global tokens it reads** — move these to retheme broadly rather than overriding the hooks directly: the tint-ladder steps `--tint-50` (fill) and `--tint-90` (track), plus `--duration-fast` (the fill's grow transition). To recolour a bar, prefer `color=` / `status=` (or a tinted ancestor scope) over the per-component hooks.
+
+```css
+/* Theme: a chunkier, square-cornered bar. */
+:root {
+  --progress-height: 0.75rem;
+  --progress-radius: var(--radius-small);
+}
+```

package/ui/form/Progress.module.css

@@ -4,35 +4,32 @@
 @import "../style/Tint.module.css";
 
 @layer components {
-	/* Continuous progress bar — a single track that fills horizontally. */
-	.track {
-		position: relative;
+	/* Continuous progress bar — a native `<progress>` styled as a single track that fills horizontally. */
+	.progress {
+		/* Strip the native rendering so the track/fill can be painted from tokens. */
+		appearance: none;
+		display: block;
 		margin: 0;
+		border: none;
 		inline-size: 100%;
-		height: var(--progress-height, 0.375rem);
+		block-size: var(--progress-height, 0.375rem);
 		border-radius: var(--progress-radius, 999px);
-		background: var(--progress-background, var(--tint-90));
 		overflow: hidden;
+		/* Track colour — Firefox uses the element itself as the track; WebKit/Blink repaints it on the pseudo-element below. */
+		background: var(--progress-background, var(--tint-90));
 	}
 
-	.fill {
-		display: block;
-		block-size: 100%;
-		/* Width is set inline; clamp overspill to the track here. */
-		min-width: 0px;
-		max-width: 100%;
-		background: var(--progress-color, var(--color-blue));
-		transition: all var(--duration-fast);
+	/* Track (WebKit/Blink) — Firefox has no track pseudo-element. */
+	.progress::-webkit-progress-bar {
+		background: var(--progress-background, var(--tint-90));
 	}
 
-	/* Status variants applied at the container level. */
-	.success .fill {
-		background: var(--progress-success, var(--color-green));
-	}
-	.warning .fill {
-		background: var(--progress-warning, var(--color-orange));
+	/* Fill — WebKit/Blink and Firefox expose the fill under different pseudo-elements, so both repeat the same paint. Painted from the tint ladder, so `color=` / `status=` recolour it. */
+	.progress::-webkit-progress-value {
+		background: var(--progress-color, var(--tint-50));
+		transition: inline-size var(--duration-fast);
 	}
-	.danger .fill {
-		background: var(--progress-danger, var(--color-red));
+	.progress::-moz-progress-bar {
+		background: var(--progress-color, var(--tint-50));
 	}
 }