shelving 1.264.0 → 1.264.2

package/ui/layout/Layout.js

@@ -1,3 +1,4 @@
+import { useEffect } from "react";
 /**
  * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
  *
@@ -8,6 +9,9 @@
  * @see https://shelving.cc/ui/useSafeKeyboardArea
  */
 export function useSafeKeyboardArea() {
+    useEffect(_safeKeyboardArea, []);
+}
+function _safeKeyboardArea() {
     const vv = window.visualViewport;
     if (!vv)
         return;

package/ui/layout/Layout.ts

@@ -1,3 +1,5 @@
+import { useEffect } from "react";
+
 /**
  * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
  *
@@ -8,6 +10,10 @@
  * @see https://shelving.cc/ui/useSafeKeyboardArea
  */
 export function useSafeKeyboardArea() {
+	useEffect(_safeKeyboardArea, []);
+}
+
+function _safeKeyboardArea() {
 	const vv = window.visualViewport;
 	if (!vv) return;
 	const onResize = () => {

package/ui/layout/SidebarLayout.js

@@ -1,11 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Bars3Icon, XMarkIcon } from "@heroicons/react/24/solid";
 import { useEffect, useState } from "react";
-import { Button } from "../form/Button.js";
+import { Button } from "../button/Button.js";
 import { requireMetaURL } from "../misc/MetaContext.js";
 import { RouteCache } from "../router/RouteCache.js";
 import { getClass, getModuleClass } from "../util/css.js";
-import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
+import LAYOUT_CSS from "./SidebarLayout.module.css";
+const LAYOUT_SIDEBAR_CLASS = getModuleClass(LAYOUT_CSS, "sidebar");
+const LAYOUT_CONTENT_CLASS = getModuleClass(LAYOUT_CSS, "content");
+const LAYOUT_TOGGLE_CLASS = getModuleClass(LAYOUT_CSS, "toggle");
+const LAYOUT_OVERLAY_CLASS = getModuleClass(LAYOUT_CSS, "overlay");
+const LAYOUT_MAIN_CLASS = getModuleClass(LAYOUT_CSS, "main");
+const LAYOUT_OPEN_CLASS = getModuleClass(LAYOUT_CSS, "open");
 /**
  * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
  * - The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
@@ -25,12 +31,13 @@ export function SidebarLayout({ sidebar, children, right = false }) {
         if (path)
             setOpen(false);
     }, [path]);
-    const sidebarEl = (_jsx("nav", { className: getClass(getModuleClass(SIDEBAR_LAYOUT_CSS, "sidebar"), open && getModuleClass(SIDEBAR_LAYOUT_CSS, "open")), children: sidebar }, "sidebar"));
+    const sidebarEl = (_jsx("nav", { className: getClass(LAYOUT_SIDEBAR_CLASS, //
+        open && LAYOUT_OPEN_CLASS), children: sidebar }, "sidebar"));
     // Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden
     // — keeping the scroll position of this `.content` container (and all page state) intact across
     // back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither
     // duplicated nor remounted as the URL changes.
-    const contentEl = (_jsx(RouteCache, { children: _jsxs("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "content"), children: [_jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle"), children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), _jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner"), children: children })] }) }, "content"));
-    const overlayEl = open && (_jsx("button", { type: "button", className: getModuleClass(SIDEBAR_LAYOUT_CSS, "overlay"), "aria-label": "Close menu", onClick: () => setOpen(false) }, "overlay"));
-    return (_jsx("main", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "main"), children: right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl] }));
+    const contentEl = (_jsx(RouteCache, { children: _jsxs("div", { className: LAYOUT_CONTENT_CLASS, children: [_jsx("div", { className: LAYOUT_TOGGLE_CLASS, children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), children] }) }, "content"));
+    const overlayEl = open && (_jsx("button", { type: "button", className: LAYOUT_OVERLAY_CLASS, "aria-label": "Close menu", onClick: () => setOpen(false) }, "overlay"));
+    return _jsx("main", { className: LAYOUT_MAIN_CLASS, children: right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl] });
 }

package/ui/layout/SidebarLayout.md

@@ -48,11 +48,11 @@ useEffect(useSafeKeyboardArea, []);
 | Variable | Styles | Default |
 |---|---|---|
 | `--sidebar-layout-width` | Width of the side column (and drawer) | `17.5rem` |
-| `--sidebar-layout-background` | Page background while the layout is mounted | `var(--tint-100)` |
-| `--sidebar-layout-sidebar-background` | Sidebar column fill | `var(--tint-90)` |
-| `--sidebar-layout-content-background` | Main content column fill | `var(--tint-100)` |
+| `--sidebar-layout-background` | Page background while the layout is mounted | Unset — the `body` default from `Typography.module.css` shows |
+| `--sidebar-layout-sidebar-background` | Sidebar column fill | Unset — the page background shows |
+| `--sidebar-layout-content-background` | Main content column fill | Unset — the page background shows |
 | `--sidebar-layout-border` | Divider between sidebar and content | `var(--stroke-normal) solid var(--tint-80)` |
 
 The sidebar and content columns own their own scroll behaviour directly (this layout no longer composes a shared `.layout` class). `useSafeKeyboardArea()` still writes `--layout-inset-bottom` for layouts that pad to the safe area.
 
-**Global tokens it reads** — the tint ladder `--tint-80` / `--tint-90` / `--tint-100`, plus `--space-normal`, `--stroke-normal`, `--duration-normal`, and `--color-shadow`.
+**Global tokens it reads** — `--tint-80`, plus `--space-normal`, `--stroke-normal`, `--duration-normal`, and `--color-shadow`.

package/ui/layout/SidebarLayout.module.css

@@ -50,7 +50,8 @@
 		inset: 0;
 
 		/* Style */
-		background: var(--sidebar-layout-background, var(--tint-100));
+		/* Deliberately no fallback: when the hook is unset this declaration fails and the body default from Typography.module.css shows. */
+		background: var(--sidebar-layout-background);
 	}
 
 	.main {
@@ -74,7 +75,8 @@
 		padding: var(--space-normal);
 
 		/* Style */
-		background: var(--sidebar-layout-sidebar-background, var(--tint-90));
+		/* Deliberately no fallback: when the hook is unset this declaration fails and the page background shows. */
+		background: var(--sidebar-layout-sidebar-background);
 	}
 
 	.content {
@@ -91,13 +93,8 @@
 		scroll-behavior: smooth;
 
 		/* Style */
-		background: var(--sidebar-layout-content-background, var(--tint-100));
-	}
-
-	.contentInner {
-		width: 100%;
-		padding: 0;
-		margin: 0 auto;
+		/* Deliberately no fallback: when the hook is unset this declaration fails and the page background shows. */
+		background: var(--sidebar-layout-content-background);
 	}
 
 	/* Wrapper for the menu toggle button — hidden on wide viewports, shown on narrow ones (see media query). */

package/ui/layout/SidebarLayout.tsx

@@ -1,11 +1,18 @@
 import { Bars3Icon, XMarkIcon } from "@heroicons/react/24/solid";
 import { type ReactElement, type ReactNode, useEffect, useState } from "react";
-import { Button } from "../form/Button.js";
+import { Button } from "../button/Button.js";
 import { requireMetaURL } from "../misc/MetaContext.js";
 import { RouteCache } from "../router/RouteCache.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
-import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
+import LAYOUT_CSS from "./SidebarLayout.module.css";
+
+const LAYOUT_SIDEBAR_CLASS = getModuleClass(LAYOUT_CSS, "sidebar");
+const LAYOUT_CONTENT_CLASS = getModuleClass(LAYOUT_CSS, "content");
+const LAYOUT_TOGGLE_CLASS = getModuleClass(LAYOUT_CSS, "toggle");
+const LAYOUT_OVERLAY_CLASS = getModuleClass(LAYOUT_CSS, "overlay");
+const LAYOUT_MAIN_CLASS = getModuleClass(LAYOUT_CSS, "main");
+const LAYOUT_OPEN_CLASS = getModuleClass(LAYOUT_CSS, "open");
 
 /**
  * Props for `<SidebarLayout>` — the `sidebar` column content, main `children`, and a `right` placement flag.
@@ -42,39 +49,35 @@ export function SidebarLayout({ sidebar, children, right = false }: SidebarLayou
 	const sidebarEl = (
 		<nav
 			key="sidebar"
-			className={getClass(getModuleClass(SIDEBAR_LAYOUT_CSS, "sidebar"), open && getModuleClass(SIDEBAR_LAYOUT_CSS, "open"))}
+			className={getClass(
+				LAYOUT_SIDEBAR_CLASS, //
+				open && LAYOUT_OPEN_CLASS,
+			)}
 		>
 			{sidebar}
 		</nav>
 	);
+
 	// Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden
 	// — keeping the scroll position of this `.content` container (and all page state) intact across
 	// back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither
 	// duplicated nor remounted as the URL changes.
 	const contentEl = (
 		<RouteCache key="content">
-			<div className={getModuleClass(SIDEBAR_LAYOUT_CSS, "content")}>
-				<div className={getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle")}>
+			<div className={LAYOUT_CONTENT_CLASS}>
+				<div className={LAYOUT_TOGGLE_CLASS}>
 					<Button title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
 						{open ? <XMarkIcon /> : <Bars3Icon />}
 					</Button>
 				</div>
-				<div className={getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner")}>{children}</div>
+				{children}
 			</div>
 		</RouteCache>
 	);
+
 	const overlayEl = open && (
-		<button
-			key="overlay"
-			type="button"
-			className={getModuleClass(SIDEBAR_LAYOUT_CSS, "overlay")}
-			aria-label="Close menu"
-			onClick={() => setOpen(false)}
-		/>
-	);
-	return (
-		<main className={getModuleClass(SIDEBAR_LAYOUT_CSS, "main")}>
-			{right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl]}
-		</main>
+		<button key="overlay" type="button" className={LAYOUT_OVERLAY_CLASS} aria-label="Close menu" onClick={() => setOpen(false)} />
 	);
+
+	return <main className={LAYOUT_MAIN_CLASS}>{right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl]}</main>;
 }

package/ui/menu/Menu.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import { type ClickableProps } from "../form/Clickable.js";
+import { type ClickableProps } from "../button/Clickable.js";
 import { type BlockVariants } from "../style/Block.js";
 import type { OptionalChildProps } from "../util/props.js";
 /**

package/ui/menu/Menu.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { isArray } from "../../util/array.js";
 import { getLink, isURLActive, isURLProud } from "../../util/index.js";
-import { Clickable } from "../form/Clickable.js";
+import { Clickable } from "../button/Clickable.js";
 import { requireMeta } from "../misc/MetaContext.js";
 import { getBlockClass } from "../style/Block.js";
 import { getClass, getModuleClass } from "../util/css.js";

package/ui/menu/Menu.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import { isArray } from "../../util/array.js";
 import { getLink, isURLActive, isURLProud } from "../../util/index.js";
-import { Clickable, type ClickableProps } from "../form/Clickable.js";
+import { Clickable, type ClickableProps } from "../button/Clickable.js";
 import { requireMeta } from "../misc/MetaContext.js";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { getClass, getModuleClass } from "../util/css.js";

package/ui/misc/Catcher.d.ts

@@ -1,25 +1,8 @@
 import { Component, type ReactElement, type ReactNode } from "react";
 import type { Callback } from "../../util/function.js";
-import { type ButtonVariants } from "../form/Button.js";
-import type { ChildProps, OptionalChildProps } from "../util/props.js";
-/**
- * Props for `<RetryButton>` — `<Button>` variants plus optional `children` to override the default "Retry" label.
- *
- * @see https://shelving.cc/ui/RetryButtonProps
- */
-export interface RetryButtonProps extends ButtonVariants, OptionalChildProps {
-}
-/**
- * Button that retries the nearest `<Catcher>` error boundary when clicked.
- *
- * - Reads the retry callback from `<Catcher>`'s private context, so it renders `null` when there is no boundary above it to retry.
- * - Defaults to an "Retry" label with a refresh icon; pass `children` to override.
- *
- * @kind component
- * @see https://shelving.cc/ui/RetryButton
- */
-export declare function RetryButton({ children, ...props }: RetryButtonProps): ReactElement | null;
+import type { ChildProps } from "../util/props.js";
 /**
+import { RetryButton, RetryContext } from "../button/RetryButton.js";
  * Props for a component that renders a caught error `reason`.
  *
  * @see https://shelving.cc/ui/ErrorProps

package/ui/misc/Catcher.js

@@ -1,30 +1,11 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ArrowPathIcon } from "@heroicons/react/24/solid";
-import { Component, createContext, use } from "react";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component } from "react";
 import { getMessage } from "../../util/error.js";
 import { Paragraph } from "../block/Paragraph.js";
-import { Button } from "../form/Button.js";
+import { RetryButton, RetryContext } from "../button/RetryButton.js";
 import { CenteredLayout } from "../layout/CenteredLayout.js";
 import { Notice } from "../notice/Notice.js";
 import { Page } from "../page/Page.js";
-const RetryContext = createContext(undefined);
-RetryContext.displayName = "RetryContext";
-const RETRY_CHILDREN = (_jsxs(_Fragment, { children: [_jsx(ArrowPathIcon, {}), "Retry"] }));
-/**
- * Button that retries the nearest `<Catcher>` error boundary when clicked.
- *
- * - Reads the retry callback from `<Catcher>`'s private context, so it renders `null` when there is no boundary above it to retry.
- * - Defaults to an "Retry" label with a refresh icon; pass `children` to override.
- *
- * @kind component
- * @see https://shelving.cc/ui/RetryButton
- */
-export function RetryButton({ children = RETRY_CHILDREN, ...props }) {
-    const retry = use(RetryContext);
-    if (!retry)
-        return null;
-    return (_jsx(Button, { onClick: retry, ...props, children: children }));
-}
 /**
  * React error boundary that renders a fallback component when any descendant throws.
  *

package/ui/misc/Catcher.tsx

@@ -1,51 +1,15 @@
-import { ArrowPathIcon } from "@heroicons/react/24/solid";
-import { Component, createContext, type ReactElement, type ReactNode, use } from "react";
+import { Component, type ReactElement, type ReactNode } from "react";
 import { getMessage } from "../../util/error.js";
 import type { Callback } from "../../util/function.js";
 import { Paragraph } from "../block/Paragraph.js";
-import { Button, type ButtonVariants } from "../form/Button.js";
+import { RetryButton, RetryContext } from "../button/RetryButton.js";
 import { CenteredLayout } from "../layout/CenteredLayout.js";
 import { Notice } from "../notice/Notice.js";
 import { Page } from "../page/Page.js";
-import type { ChildProps, OptionalChildProps } from "../util/props.js";
-
-const RetryContext = createContext<Callback | undefined>(undefined);
-RetryContext.displayName = "RetryContext";
-
-/**
- * Props for `<RetryButton>` — `<Button>` variants plus optional `children` to override the default "Retry" label.
- *
- * @see https://shelving.cc/ui/RetryButtonProps
- */
-export interface RetryButtonProps extends ButtonVariants, OptionalChildProps {}
-
-const RETRY_CHILDREN = (
-	<>
-		<ArrowPathIcon />
-		Retry
-	</>
-);
-
-/**
- * Button that retries the nearest `<Catcher>` error boundary when clicked.
- *
- * - Reads the retry callback from `<Catcher>`'s private context, so it renders `null` when there is no boundary above it to retry.
- * - Defaults to an "Retry" label with a refresh icon; pass `children` to override.
- *
- * @kind component
- * @see https://shelving.cc/ui/RetryButton
- */
-export function RetryButton({ children = RETRY_CHILDREN, ...props }: RetryButtonProps): ReactElement | null {
-	const retry = use(RetryContext);
-	if (!retry) return null;
-	return (
-		<Button onClick={retry} {...props}>
-			{children}
-		</Button>
-	);
-}
+import type { ChildProps } from "../util/props.js";
 
 /**
+import { RetryButton, RetryContext } from "../button/RetryButton.js";
  * Props for a component that renders a caught error `reason`.
  *
  * @see https://shelving.cc/ui/ErrorProps

package/ui/misc/MetaContext.test.tsx

@@ -1,9 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import { RequiredError } from "../../error/RequiredError.js";
-import { createMeta } from "../util/meta.js";
-import { MetaContext, requireMetaURL } from "./MetaContext.js";
+import { RequiredError } from "shelving/error";
+import { createMeta, MetaContext, requireMetaURL } from "shelving/ui";
 
 /** Render `requireMetaURL().path` from inside a component so its `use(MetaContext)` call is valid. */
 function Probe(): ReactNode {

package/ui/misc/Tag.d.ts

@@ -1,5 +1,5 @@
 import type { ReactElement } from "react";
-import { type ClickableProps } from "../form/Clickable.js";
+import { type ClickableProps } from "../button/Clickable.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 /**

package/ui/misc/Tag.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Clickable } from "../form/Clickable.js";
+import { Clickable } from "../button/Clickable.js";
 import { getStatusClass } from "../style/Status.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";

package/ui/misc/Tag.md

@@ -20,11 +20,10 @@ import { Tag } from "shelving/ui";
 
 ## Styling
 
-`Tag` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Move `--tag-tint` to recolour the whole tag at once.
+`Tag` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the tag or an ancestor scope) to recolour the whole tag at once.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--tag-tint` | Tint anchor for the tag scope | `inherit` (flows from `color=` / `status=` / parent) |
 | `--tag-background` | Surface fill | `var(--tint-50)` |
 | `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)` |
 | `--tag-color` | Text colour | `var(--tint-100)` |

package/ui/misc/Tag.module.css

@@ -8,9 +8,6 @@
 
 @layer components {
 	.tag {
-		/* Theme */
-		--tint-50: var(--tag-tint, inherit);
-
 		/* Box */
 		display: inline-block;
 		vertical-align: text-bottom;

package/ui/misc/Tag.tsx

@@ -1,5 +1,5 @@
 import type { ReactElement } from "react";
-import { Clickable, type ClickableProps } from "../form/Clickable.js";
+import { Clickable, type ClickableProps } from "../button/Clickable.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";

package/ui/notice/Message.module.css

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

package/ui/notice/Notice.md

@@ -28,11 +28,10 @@ import { LOADING_NOTICE } from "shelving/ui";
 
 ## Styling
 
-`Notice` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Move `--notice-tint` to recolour everything at once.
+`Notice` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Its `status` (or a `color=` / `status=` on an ancestor scope) sets the tint that the surface, border, and text all derive from; reach for a per-property hook for a single change.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--notice-tint` | Tint anchor for the notice scope | `inherit` (flows from `color=` / `status=` / parent) |
 | `--notice-background` | Surface fill | `var(--tint-90)` |
 | `--notice-color` | Text colour | `var(--tint-50)` |
 | `--notice-border` | Border shorthand | `var(--notice-stroke) solid var(--tint-80)` |

package/ui/notice/Notice.module.css

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

package/ui/router/Router.test.tsx

@@ -1,9 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
-import { MetaContext } from "../misc/MetaContext.js";
-import { createMeta } from "../util/meta.js";
-import { Router } from "./Router.js";
-import type { RouteProps } from "./Routes.js";
+import { createMeta, MetaContext, type RouteProps, Router } from "shelving/ui";
 
 const ROUTES = {
 	"/": () => <main>Home</main>,

package/ui/style/TINT_CLASS.md

@@ -42,7 +42,7 @@ Pairings follow contrast: long text reads at `00`-on-`90` or `00`-on-`100`; shor
 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.
+2. **Retint a region.** Apply `color=` / `status=` to a container — `<Card color="purple">`, or a `<Panel color="purple">` wrapping a whole section — and everything inside re-tints, with text, border, surface, and hover shades all derived for free. Components don't expose a per-component `--x-tint` hook; the variant moves the anchor, not a bespoke variable.
 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_CLASS` 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.

package/ui/style/Width.d.ts

@@ -3,10 +3,11 @@
  * - `narrow` / `normal` / `wide` — fixed widths from the `--width-*` tokens (capped at 100%).
  * - `full` — take the full available width.
  * - `fit` — shrink to fit the content's intrinsic width (`fit-content`).
+ * - `1x`–`32x` — fixed multiples of `--space-normal` (1x–8x at 1x intervals, then 10x/12x, then 16x–32x at 4x intervals).
  *
  * @see https://shelving.cc/ui/WidthVariant
  */
-export type WidthVariant = "xxnarrow" | "xnarrow" | "narrow" | "normal" | "wide" | "xwide" | "xxwide" | "full" | "fit";
+export type WidthVariant = "narrow" | "normal" | "wide" | "full" | "fit" | "1x" | "2x" | "3x" | "4x" | "5x" | "6x" | "7x" | "8x" | "10x" | "12x" | "16x" | "20x" | "24x" | "28x" | "32x";
 /**
  * Variant props that set (or unconstrain) a component's width, e.g. `width="narrow"` or `width="12x"`.
  *

package/ui/style/Width.module.css

@@ -4,14 +4,9 @@
 @layer defaults {
 	:root {
 		/* Semantic widths */
-		--width-xxnarrow: 16rem;
-		--width-xnarrow: 24rem;
 		--width-narrow: 36rem;
 		--width-normal: 48rem;
 		--width-wide: 80rem;
-		--width-xwide: 96rem;
-		--width-xxwide: 112rem;
-		--width-xxxwide: 128rem;
 	}
 
 	/* Frame shared by every width value (weak default — a component's own margin can still beat the centering). */
@@ -28,12 +23,6 @@
 	}
 
 	/* Semantic widths. */
-	.width-xxnarrow {
-		--width: var(--width-xxnarrow);
-	}
-	.width-xnarrow {
-		--width: var(--width-xnarrow);
-	}
 	.width-narrow {
 		--width: var(--width-narrow);
 	}
@@ -43,12 +32,6 @@
 	.width-wide {
 		--width: var(--width-wide);
 	}
-	.width-xwide {
-		--width: var(--width-xwide);
-	}
-	.width-xxwide {
-		--width: var(--width-xxwide);
-	}
 	.width-full {
 		--width: 100%;
 	}
@@ -56,6 +39,53 @@
 		--width: fit-content;
 	}
 
+	/* Numeric widths — multiples of `--space-normal` (no `--width-*` tokens; calculated directly). */
+	.width-1x {
+		--width: calc(1 * var(--space-normal));
+	}
+	.width-2x {
+		--width: calc(2 * var(--space-normal));
+	}
+	.width-3x {
+		--width: calc(3 * var(--space-normal));
+	}
+	.width-4x {
+		--width: calc(4 * var(--space-normal));
+	}
+	.width-5x {
+		--width: calc(5 * var(--space-normal));
+	}
+	.width-6x {
+		--width: calc(6 * var(--space-normal));
+	}
+	.width-7x {
+		--width: calc(7 * var(--space-normal));
+	}
+	.width-8x {
+		--width: calc(8 * var(--space-normal));
+	}
+	.width-10x {
+		--width: calc(10 * var(--space-normal));
+	}
+	.width-12x {
+		--width: calc(12 * var(--space-normal));
+	}
+	.width-16x {
+		--width: calc(16 * var(--space-normal));
+	}
+	.width-20x {
+		--width: calc(20 * var(--space-normal));
+	}
+	.width-24x {
+		--width: calc(24 * var(--space-normal));
+	}
+	.width-28x {
+		--width: calc(28 * var(--space-normal));
+	}
+	.width-32x {
+		--width: calc(32 * var(--space-normal));
+	}
+
 	/* Grow modifier — turn the chosen width into a floor and expand to fill (flex items + table columns). */
 	.grow {
 		flex-grow: 1;

package/ui/style/Width.tsx

@@ -6,10 +6,31 @@ import WIDTH_CSS from "./Width.module.css";
  * - `narrow` / `normal` / `wide` — fixed widths from the `--width-*` tokens (capped at 100%).
  * - `full` — take the full available width.
  * - `fit` — shrink to fit the content's intrinsic width (`fit-content`).
+ * - `1x`–`32x` — fixed multiples of `--space-normal` (1x–8x at 1x intervals, then 10x/12x, then 16x–32x at 4x intervals).
  *
  * @see https://shelving.cc/ui/WidthVariant
  */
-export type WidthVariant = "xxnarrow" | "xnarrow" | "narrow" | "normal" | "wide" | "xwide" | "xxwide" | "full" | "fit";
+export type WidthVariant =
+	| "narrow"
+	| "normal"
+	| "wide"
+	| "full"
+	| "fit"
+	| "1x"
+	| "2x"
+	| "3x"
+	| "4x"
+	| "5x"
+	| "6x"
+	| "7x"
+	| "8x"
+	| "10x"
+	| "12x"
+	| "16x"
+	| "20x"
+	| "24x"
+	| "28x"
+	| "32x";
 
 /**
  * Variant props that set (or unconstrain) a component's width, e.g. `width="narrow"` or `width="12x"`.

package/ui/style/getWidthClass.md

@@ -1,14 +1,15 @@
 # getWidthClass
 
-The `width` variant prop sets a component's inline-size — `<Card width="narrow">`, `<Block width="wide">`, `<Cell width="xxnarrow">`. It's an **override** for one-off layout; for an app-wide change, retune the width variables below in a theme file. `<Section>` already defaults to the `--width-normal` width, so most pages never set `width` at all.
+The `width` variant prop sets a component's inline-size — `<Card width="narrow">`, `<Block width="wide">`, `<Cell width="narrow">`. It's an **override** for one-off layout; for an app-wide change, retune the width variables below in a theme file. `<Section>` already defaults to the `--width-normal` width, so most pages never set `width` at all.
 
 `getWidthClass({ width, grow })` maps the props to a width class. Every value is capped at 100% of the container.
 
 **Values:**
 
-- `xxnarrow` / `xnarrow` / `narrow` / `normal` / `wide` / `xwide` / `xxwide` — fixed widths from the variables below.
+- `narrow` / `normal` / `wide` — fixed widths from the variables below.
 - `full` — the full available width.
 - `fit` — shrink to the content's intrinsic width (`fit-content`).
+- `1x` / `2x` / `3x` / `4x` / `5x` / `6x` / `7x` / `8x` / `10x` / `12x` / `16x` / `20x` / `24x` / `28x` / `32x` — fixed multiples of `--space-normal` (no per-step variables; calculated directly).
 
 **The `grow` flag** turns the chosen `width` into a floor rather than an exact size: it applies the value as `min-inline-size` and adds `flex-grow: 1`, so the element expands to fill the available space when it's a flex item. Set it on a `<Cell>` (`width="12x" grow`) to give that column a 192px minimum that absorbs the remaining width and keeps the table from collapsing the column on a narrow viewport — cells honour `min-width`, so the table scrolls instead.
 
@@ -18,11 +19,6 @@ The following `:root` variables are defined by this module and can be overridden
 
 | Variable | Default | Used for |
 |---|---|---
-| `--width-xxnarrow` | `16rem` |
-| `--width-xnarrow` | `24rem` |
-| `--width-narrow` | `36rem` |
+| `--width-narrow` | `36rem` | Focused single-purpose column, e.g. forms and login pages. |
 | `--width-normal` | `48rem` | Standard content column. |
-| `--width-wide` | `80rem` |
-| `--width-xwide` | `96rem` |
-| `--width-xxwide` | `112rem` |
-| `--width-xxxwide` | `128rem` |
+| `--width-wide` | `80rem` | Full dashboard-style content. |