shelving 1.228.0 → 1.229.0

package/package.json

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

package/ui/README.md

@@ -15,6 +15,229 @@ A few conventions run through every component (see also the React Components sec
 - **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.
 
+## Styling system
+
+The styling system has four moving parts, all defined in [style/](./style/). Most components compose them in a predictable shape; consumers theme by overriding CSS custom properties at `:root`.
+
+### Design tokens
+
+[`style/base.css`](./style/base.css) defines every design-token constant at `:root` — colours, sizes (`--size-*`), spacing (`--space-*`), radii (`--radius-*`), strokes (`--stroke-*`), shadows (`--shadow-*`), durations (`--duration-*`). Components read these via `var(--token)`; themes override them at `:root` in their own CSS file. No class selectors needed.
+
+`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.
+
+#### The 5-step colour scale
+
+Colours are organised as a **5-step scale**: `--color-black`, `--color-dark`, `--color-vivid`, `--color-light`, `--color-white`. The inner three steps (`dark` / `vivid` / `light`) are saturated tones of the active hue and change per variant scope; the extremes (`black` / `white`) are the page foreground/background and stay put unless the theme deliberately inverts them (e.g. dark mode).
+
+A useful mental model: **step distance encodes contrast strength**.
+
+| Distance | Pairing | Use for |
+|---|---|---|
+| 2 steps | `vivid + white`, `light + dark` | Short text (button labels, tag labels, notices) |
+| 3 steps | `dark + white`, `light + black` | Body text (paragraphs, headings) |
+| 4 steps | `black + white` | Maximum-contrast surfaces (Inputs) |
+
+Components pick whichever pair fits their content; variants only ever set the inner three steps, so a component that renders `bg=light` and `text=dark` automatically inherits the right tint when wrapped in `.red`, `.success`, etc.
+
+The base palette underneath the scale defines three shades per hue: `--vivid-red`, `--light-red`, `--dark-red` (and the same for orange, yellow, green, aqua, blue, purple, pink, plus `--*-gray` for the default neutrals). The default `:root` value of `--color-vivid` is `var(--vivid-gray)` and so on — grey is just the variant you get when no colour variant is applied.
+
+**`--color-black` and `--color-white` are theme-scoped, not literal.** They're the extremes of the active scale. In a dark theme they'd be a deep navy and a soft cream. For literal black or white pixels (neutral hover blends, etc.) use the CSS keywords `black` / `white` directly — they sit outside the scale entirely.
+
+### Cascade layers
+
+Order, lowest to highest priority:
+
+| Layer | What's in it |
+|---|---|
+| `defaults` | `:root` design tokens, body baseline typography, any 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, Align, Spacing, Padding, Gap, Thickness, Width, Typography, Flex). Always beat components. |
+| `overrides` | Top-priority structural overrides — `:first-child` / `:last-child` margin collapses, which need to beat variant-set margins |
+
+**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.
+
+### Variant utilities
+
+[`style/`](./style/) exports a set of opt-in class utilities. Each has the same shape: a `.module.css` with the variant classes inside `@layer variants`, and a `.tsx` exporting `getXxxClass(props)` + a `XxxVariants` interface that components extend.
+
+| Utility | Classes | Purpose |
+|---|---|---|
+| [`Color`](./style/Color.tsx) | `.primary`, `.secondary`, `.red`, `.blue`, `.green`, etc. | Raw colour overrides |
+| [`Status`](./style/Status.tsx) | `.info`, `.success`, `.warning`, `.danger`, `.error`, `.loading` | Semantic status colours |
+| [`Align`](./style/Align.tsx) | `.left`, `.center`, `.right` | `text-align` |
+| [`Spacing`](./style/Spacing.tsx) | `.space-none` … `.space-xxlarge` | `margin-block` (top + bottom) |
+| [`Padding`](./style/Padding.tsx) | `.padding-none` … `.padding-xxlarge` | `padding-block` (top + bottom) |
+| [`Gap`](./style/Gap.tsx) | `.gap-none` … `.gap-xxlarge` | `gap` |
+| [`Thickness`](./style/Thickness.tsx) | `.thickness-none` … `.thickness-xxthick` | Sets `--thickness` for components that paint borders |
+| [`Width`](./style/Width.tsx) | `.narrow`, `.wide`, `.full` | `max-width` |
+| [`Typography`](./style/Typography.tsx) | `.body`, `.monospace`, `.sans`, `.serif`, `.code` + `.size-xxsmall` … `.size-xxlarge` | `font-family` + `font-size` |
+| [`Flex`](./style/Flex.tsx) | `.flex` + `.column`, `.left`, `.wrap`, etc. | Flex layout (composes `Gap`) |
+
+A component using variants looks like:
+
+```tsx
+export interface CardProps extends ColorVariants, PaddingVariants, ThicknessVariants, WidthVariants /* … */ {
+  status?: Status | undefined;
+}
+
+export function Card({ children, status, ...props }: CardProps): ReactElement {
+  return (
+    <article
+      className={getClass(
+        getModuleClass(CARD_CSS, "card"),
+        status && getStatusClass(status),
+        getColorClass(props),
+        getPaddingClass(props),
+        getThicknessClass(props),
+        getWidthClass(props),
+      )}
+    >
+      {children}
+    </article>
+  );
+}
+```
+
+### Component theme hooks
+
+Each component exposes per-component CSS custom properties for its overridable values. These are read with a `var(--component-hook, default)` fallback chain in the component's CSS, so a consumer can override the hook to retheme a single component without touching the rest of the design system.
+
+Naming follows the file-prefix rule from [AGENTS.md](/AGENTS.md): hooks owned by a specific module file start with that file's kebab-case name. So Card owns `--card-color-light`, `--card-color-dark`, `--card-padding`, `--card-radius`, etc. Button owns `--button-color-vivid`, `--button-color-light`, `--button-border`, and so on.
+
+Tokens declared at `:root` (in `base.css`, or in `Color`/`Status`'s token blocks) are exempt — they're the global palette, not file-owned.
+
+### The colour rebind pattern
+
+Any component that paints a `background-color`, `border-color`, or `color` from the 5-step scale (Card, Button, Notice, Panel, Tag, Code, Mark, Modal, Popover, Preformatted, …) **rebinds all five scale steps on its own scope** before painting:
+
+```css
+.card {
+  /* Rebind: per-component theme hook wins; otherwise inherit from variant or page scope. */
+  --color-black: var(--card-color-black, inherit);
+  --color-dark:  var(--card-color-dark, inherit);
+  --color-vivid: var(--card-color-vivid, inherit);
+  --color-light: var(--card-color-light, inherit);
+  --color-white: var(--card-color-white, inherit);
+
+  /* bg=light + text=dark is a 2-step pair, fine for the short text inside a card body. */
+  background-color: var(--color-light);
+  border-color:     var(--color-vivid);
+  color:            var(--color-dark);
+}
+```
+
+The rebind serves three jobs at once:
+
+1. **Per-component theme hook.** A consumer setting `--card-color-light: peachpuff` at `:root` repaints the card surface without touching Buttons or Notices.
+2. **Variant inheritance.** When the card is `.red` (or `.success`, etc.), the variant has already set `--color-dark / --color-vivid / --color-light` at its scope. The rebind's `inherit` fallback picks those up — no explicit `.card.red` rule needed.
+3. **Identity propagation.** Descendants (like a `<Code>` chip inside the card) inherit the rebound values, so they can compute their own surface relative to the card.
+
+For variants on appearance (`.strong`, `.outline`, `.plain` on Button) — just pick a different step pair from the already-rebound scale. No extra hook needed:
+
+```css
+.button { background: var(--color-light); color: var(--color-dark); }
+.button.strong { background: var(--color-vivid); color: var(--color-white); }
+```
+
+**What about components that only paint one colour?** Text-only blocks (Paragraph, Heading, Title, etc.) skip the rebind and read the relevant scale step directly with a single theme-hook fallback:
+
+```css
+.paragraph { color: var(--paragraph-color, var(--color-dark)); }
+.heading   { color: var(--heading-color, var(--color-black)); }
+```
+
+**What about Inputs?** Inputs sit outside the variant scope's middle three steps — they always use `bg=white + text=black` (a 4-step pair, maximum contrast) regardless of the surrounding variant. Variant scope still tints their border and validity states, but never the field surface.
+
+Other tokens (`--*-padding`, `--*-spacing`, `--*-radius`, `--*-font`, `--*-size`, etc.) are **not** rebound:
+
+- `font-*` properties already inherit naturally via CSS, so just setting them is enough — children pick up the value automatically.
+- `padding`, `margin`, `gap`, `border-width`, `border-radius` are non-inheriting CSS properties. Each component sets its own; children should never read a parent's padding.
+
+This split is deliberate. The rebind is the right tool when an identity needs to propagate; for everything else, plain CSS inheritance (or no inheritance at all) is the right tool.
+
+### How `:first-child` / `:last-child` margin overrides work
+
+Every block-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 `<Card space-large>` still collapses its abutting edges correctly.
+
+Pattern:
+
+```css
+@layer components {
+  .card { margin-block: var(--card-spacing, var(--spacing-paragraph)); }
+}
+
+@layer overrides {
+  .card {
+    &:first-child { margin-block-start: 0; }
+    &:last-child { margin-block-end: 0; }
+  }
+}
+```
+
+### Writing a new component
+
+A typical new block-level component looks like:
+
+```tsx
+// Address.tsx
+import { type AlignVariants, getAlignClass } from "../style/Align.js";
+import { getSpacingClass, type SpacingVariants } from "../style/Spacing.js";
+import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+
+export interface AddressProps extends AlignVariants, SpacingVariants, TypographyVariants, ChildProps {}
+
+export function Address({ children, ...variants }: AddressProps) {
+  return (
+    <address
+      className={getClass(
+        getModuleClass(styles, "address"),
+        getAlignClass(variants),
+        getSpacingClass(variants),
+        getTypographyClass(variants),
+      )}
+    >
+      {children}
+    </address>
+  );
+}
+```
+
+```css
+/* Address.module.css */
+@import "../style/base.css";
+
+@layer components {
+  .address {
+    display: block;
+    margin-inline: 0;
+    margin-block: var(--address-spacing, var(--spacing-paragraph));
+
+    /* Single-colour text block — read --color-dark directly with a theme-hook fallback. */
+    color: var(--address-color, var(--color-dark));
+    font-family: var(--address-font, inherit);
+    font-size: var(--address-size, inherit);
+    text-align: var(--address-align, left);
+  }
+}
+
+@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 a surface (background + border + text), rebind all five scale steps at the top of the rule and pick a step pair for the painted properties.
+- [ ] If the component only paints one colour (a text-only block), skip the rebind and read the step directly with a single theme-hook fallback.
+- [ ] `:first-child` / `:last-child` overrides in a separate `@layer overrides { … }` block.
+- [ ] TSX extends the variant interfaces (`SpacingVariants`, `AlignVariants`, etc.) you want to expose; composes the matching `getXxxClass(props)` calls.
+
 ## Module map
 
 ### Content

package/ui/app/App.d.ts

@@ -1,11 +1,11 @@
-import { type ReactElement } from "react";
+import type { ReactElement } from "react";
+import "../style/base.css";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
 export interface AppProps extends PossibleMeta, ChildProps {
 }
 /**
- * Root component for an application.
- * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
- * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ * Root component for an application. Provides a `Meta` context to its children so descendants can read
+ * or update metadata. Design tokens and body baseline typography are set globally via `style/base.css`.
  */
 export declare function App({ children, ...meta }: AppProps): ReactElement;

package/ui/app/App.js

@@ -1,20 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect } from "react";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
-import APP_CSS from "./App.module.css";
-const APP_CLASS = APP_CSS.app;
+import "../style/base.css";
 /**
- * Root component for an application.
- * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
- * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ * Root component for an application. Provides a `Meta` context to its children so descendants can read
+ * or update metadata. Design tokens and body baseline typography are set globally via `style/base.css`.
  */
 export function App({ children, ...meta }) {
-    const merged = requireMeta(meta);
-    useEffect(() => {
-        if (!APP_CLASS)
-            return;
-        document.body.classList.add(APP_CLASS);
-        return () => document.body.classList.remove(APP_CLASS);
-    }, []);
-    return _jsx(MetaContext, { value: merged, children: children });
+    return _jsx(MetaContext, { value: requireMeta(meta), children: children });
 }

package/ui/app/App.tsx

@@ -1,24 +1,15 @@
-import { type ReactElement, useEffect } from "react";
+import type { ReactElement } from "react";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
+import "../style/base.css";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
-import APP_CSS from "./App.module.css";
 
 export interface AppProps extends PossibleMeta, ChildProps {}
 
-const APP_CLASS = APP_CSS.app;
-
 /**
- * Root component for an application.
- * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
- * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ * Root component for an application. Provides a `Meta` context to its children so descendants can read
+ * or update metadata. Design tokens and body baseline typography are set globally via `style/base.css`.
  */
 export function App({ children, ...meta }: AppProps): ReactElement {
-	const merged = requireMeta(meta);
-	useEffect(() => {
-		if (!APP_CLASS) return;
-		document.body.classList.add(APP_CLASS);
-		return () => document.body.classList.remove(APP_CLASS);
-	}, []);
-	return <MetaContext value={merged}>{children}</MetaContext>;
+	return <MetaContext value={requireMeta(meta)}>{children}</MetaContext>;
 }

package/ui/block/Address.d.ts

@@ -1,8 +1,12 @@
 import type { ReactElement } from "react";
 import { type AddressData } from "../../schema/AddressSchema.js";
 import type { Nullish } from "../../util/null.js";
+import { type AlignVariants } from "../style/Align.js";
+import { type ColorVariants } from "../style/Color.js";
+import { type SpacingVariants } from "../style/Spacing.js";
+import { type TypographyVariants } from "../style/Typography.js";
 import type { ChildProps } from "../util/props.js";
-export interface AddressProps extends ChildProps {
+export interface AddressProps extends AlignVariants, ColorVariants, SpacingVariants, TypographyVariants, ChildProps {
 }
 export interface PhysicalAddressProps {
     name?: Nullish<string>;
@@ -13,7 +17,7 @@ export interface EmailAddressProps {
     email: Nullish<string>;
 }
 /** Show any kind of contact data. */
-export declare function Address({ children }: AddressProps): import("react/jsx-runtime").JSX.Element;
+export declare function Address({ children, ...variants }: AddressProps): import("react/jsx-runtime").JSX.Element;
 /** Show an optional `AddressData` object correctly on screen. */
 export declare function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement;
 /** Show an optional email address string correctly on screen. */

package/ui/block/Address.js

@@ -2,10 +2,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { formatAddress } from "../../schema/AddressSchema.js";
 import { Small } from "../inline/Small.js";
 import { Strong } from "../inline/Strong.js";
+import { getAlignClass } from "../style/Align.js";
+import { getColorClass } from "../style/Color.js";
+import { getSpacingClass } from "../style/Spacing.js";
+import { getTypographyClass } from "../style/Typography.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import styles from "./Address.module.css";
 /** Show any kind of contact data. */
-export function Address({ children }) {
-    return _jsx("address", { className: styles.address, children: children });
+export function Address({ children, ...variants }) {
+    return (_jsx("address", { className: getClass(getModuleClass(styles, "address"), getColorClass(variants), getAlignClass(variants), getSpacingClass(variants), getTypographyClass(variants)), children: children }));
 }
 /** Show an optional `AddressData` object correctly on screen. */
 export function PhysicalAddress({ name, address }) {

package/ui/block/Address.module.css

@@ -1,20 +1,28 @@
-.address,
-.prose address {
-	/* Box */
-	display: block;
-	margin-inline: 0;
-	margin-block: var(--address-spacing, var(--space-normal));
+@import "../style/base.css";
 
-	/* Contents */
-	white-space: pre-line;
-	font-style: normal;
-	text-align: left;
+@layer components {
+	.address,
+	.prose address {
+		display: block;
+		margin-inline: 0;
+		margin-block: var(--address-spacing, var(--spacing-paragraph));
 
-	/* Styles */
-	&:first-child {
-		margin-block-start: 0;
+		white-space: pre-line;
+		font-style: normal;
+		font-family: var(--address-font, inherit);
+		font-size: var(--address-size, inherit);
+		text-align: var(--address-align, left);
 	}
-	&:last-child {
-		margin-block-end: 0;
+}
+
+@layer overrides {
+	.address,
+	.prose address {
+		&:first-child {
+			margin-block-start: 0;
+		}
+		&:last-child {
+			margin-block-end: 0;
+		}
 	}
 }

package/ui/block/Address.tsx

@@ -3,10 +3,15 @@ import { type AddressData, formatAddress } from "../../schema/AddressSchema.js";
 import type { Nullish } from "../../util/null.js";
 import { Small } from "../inline/Small.js";
 import { Strong } from "../inline/Strong.js";
+import { type AlignVariants, getAlignClass } from "../style/Align.js";
+import { type ColorVariants, getColorClass } from "../style/Color.js";
+import { getSpacingClass, type SpacingVariants } from "../style/Spacing.js";
+import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import type { ChildProps } from "../util/props.js";
 import styles from "./Address.module.css";
 
-export interface AddressProps extends ChildProps {}
+export interface AddressProps extends AlignVariants, ColorVariants, SpacingVariants, TypographyVariants, ChildProps {}
 
 export interface PhysicalAddressProps {
 	name?: Nullish<string>;
@@ -19,8 +24,20 @@ export interface EmailAddressProps {
 }
 
 /** Show any kind of contact data. */
-export function Address({ children }: AddressProps) {
-	return <address className={styles.address}>{children}</address>;
+export function Address({ children, ...variants }: AddressProps) {
+	return (
+		<address
+			className={getClass(
+				getModuleClass(styles, "address"),
+				getColorClass(variants),
+				getAlignClass(variants),
+				getSpacingClass(variants),
+				getTypographyClass(variants),
+			)}
+		>
+			{children}
+		</address>
+	);
 }
 
 /** Show an optional `AddressData` object correctly on screen. */

package/ui/block/Block.d.ts

@@ -1,12 +1,12 @@
 import type { ReactElement } from "react";
+import { type AlignVariants } from "../style/Align.js";
+import { type ColorVariants } from "../style/Color.js";
+import { type SpacingVariants } from "../style/Spacing.js";
+import { type TypographyVariants } from "../style/Typography.js";
+import { type WidthVariants } from "../style/Width.js";
 import type { OptionalChildProps } from "../util/props.js";
-import { type SpacingVariants } from "../variant/Spacing.js";
 export declare const BLOCK_CLASS: string | undefined;
-export interface BlockProps extends SpacingVariants, OptionalChildProps {
-    /** Constrain the block to narrow width. */
-    narrow?: boolean | undefined;
-    /** Constrain the block to wide width. */
-    wide?: boolean | undefined;
+export interface BlockProps extends ColorVariants, SpacingVariants, TypographyVariants, WidthVariants, OptionalChildProps {
     /** Mark as a keyboard-focusable horizontal scroll region — adds `tabindex="0"`, `role="region"`, an `aria-label`, and `overflow-x: auto`. */
     scrollable?: boolean | undefined;
 }
@@ -24,7 +24,7 @@ export declare function Nav(props: BlockProps): ReactElement;
 export declare function Aside(props: BlockProps): ReactElement;
 /** `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content. */
 export declare function Figure(props: BlockProps): ReactElement;
-export interface CaptionProps extends OptionalChildProps {
+export interface CaptionProps extends AlignVariants, ColorVariants, TypographyVariants, OptionalChildProps {
 }
 /** `<figcaption>` block — caption text for a `<Figure>`. */
-export declare function Caption({ children }: CaptionProps): ReactElement;
+export declare function Caption({ children, ...variants }: CaptionProps): ReactElement;

package/ui/block/Block.js

@@ -1,11 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { getAlignClass } from "../style/Align.js";
+import { getColorClass } from "../style/Color.js";
+import { getSpacingClass } from "../style/Spacing.js";
+import { getTypographyClass } from "../style/Typography.js";
+import { getWidthClass } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
-import { getSpacingClass } from "../variant/Spacing.js";
 import styles from "./Block.module.css";
 export const BLOCK_CLASS = getModuleClass(styles, "block");
 function renderBlock(Component, { children, ...variants }) {
-    const className = getClass(getModuleClass(styles, "block", variants), //
-    getSpacingClass(variants));
+    const className = getClass(getModuleClass(styles, "block", variants), variants.scrollable && getModuleClass(styles, "scrollable"), getColorClass(variants), getSpacingClass(variants), getTypographyClass(variants), getWidthClass(variants));
     return variants.scrollable ? (_jsx(Component, { className: className, tabIndex: 0, role: "region", "aria-label": "Scrollable region", children: children })) : (_jsx(Component, { className: className, children: children }));
 }
 /** Plain `<div>` block with block-level spacing. Base building block; use a semantic variant (`<Section>`, `<Figure>`, etc.) when the element matters. */
@@ -37,6 +40,6 @@ export function Figure(props) {
     return renderBlock("figure", props);
 }
 /** `<figcaption>` block — caption text for a `<Figure>`. */
-export function Caption({ children }) {
-    return _jsx("figcaption", { className: getModuleClass(styles, "caption"), children: children });
+export function Caption({ children, ...variants }) {
+    return (_jsx("figcaption", { className: getClass(getModuleClass(styles, "caption"), getColorClass(variants), getAlignClass(variants), getTypographyClass(variants)), children: children }));
 }

package/ui/block/Block.module.css

@@ -1,93 +1,80 @@
-.block {
-	/* Box */
-	position: relative;
-	display: block;
-	margin-inline: 0;
-	margin-block: var(--block-spacing, var(--spacing-section));
+@import "../style/base.css";
 
-	/* Psuedo-classes */
-	&:first-child {
-		margin-block-start: 0;
-	}
-	&:last-child {
-		margin-block-end: 0;
+@layer components {
+	.block {
+		position: relative;
+		display: block;
+		margin-inline: 0;
+		margin-block: var(--block-spacing, var(--spacing-section));
 	}
 
-	/* Variants */
-	&.narrow {
-		margin-inline: auto;
-		max-width: var(--block-width-narrow, var(--width-narrow));
+	/* Plain semantic blocks inside prose pick up the same spacing as a <Block>. */
+	.prose :where(section, article, aside, nav, header, footer, figure) {
+		margin-inline: 0;
+		margin-block: var(--block-spacing, var(--spacing-section));
 	}
-	&.wide {
-		margin-inline: auto;
-		max-width: var(--block-width-wide, var(--width-wide));
-	}
-}
 
-/* Plain semantic blocks inside prose pick up the same spacing as a <Block>. */
-.prose :where(section, article, aside, nav, header, footer, figure) {
-	margin-inline: 0;
-	margin-block: var(--block-spacing, var(--spacing-section));
+	/* Scrollable region — keyboard-focusable horizontal scroll container. */
+	.scrollable,
+	.prose [role="region"][tabindex="0"] {
+		overflow-x: auto;
+		overscroll-behavior-x: contain;
 
-	&:first-child {
-		margin-block-start: 0;
-	}
-	&:last-child {
-		margin-block-end: 0;
-	}
-}
-
-/* Scrollable region — keyboard-focusable horizontal scroll container. Targets both the .scrollable variant and any prose element marked `role="region" tabindex="0"` (e.g. Markdown fenced/table output). */
-.scrollable,
-.prose [role="region"][tabindex="0"] {
-	overflow-x: auto;
-	overscroll-behavior-x: contain;
+		&:focus-visible {
+			outline: var(--focus-stroke, var(--stroke-thick)) solid var(--focus-color, var(--color-focus));
+			outline-offset: var(--focus-offset, var(--space-xxsmall));
+		}
 
-	&:focus-visible {
-		outline: var(--focus-stroke, var(--stroke-thick)) solid var(--focus-color, var(--color-accent));
-		outline-offset: var(--focus-offset, var(--space-xxsmall));
-	}
+		/* Stretch the inner block to fill the scroll container so short content still spans the width. */
+		> :is(table, pre) {
+			min-width: 100%;
+		}
 
-	/* Stretch the inner block to fill the scroll container so short content still spans the width. */
-	> :is(table, pre) {
-		min-width: 100%;
-	}
+		/* Force long lines so they trigger horizontal scroll instead of wrapping. */
+		> pre {
+			width: max-content;
+			white-space: pre;
+			overflow-wrap: normal;
+		}
 
-	/* Force long lines so they trigger horizontal scroll instead of wrapping; grow the box with the content (`width: max-content`) so the pre's own right-side padding survives at scroll-end. */
-	> pre {
-		width: max-content;
-		white-space: pre;
-		overflow-wrap: normal;
+		/* Caption stays pinned to the left during horizontal scroll. */
+		> :is(.caption, figcaption) {
+			position: sticky;
+			left: 0;
+		}
 	}
 
-	/* Caption stays pinned to the left during horizontal scroll. Spacing/typography come from the shared figcaption rule below. */
-	> :is(.caption, figcaption) {
-		position: sticky;
-		left: 0;
+	.caption,
+	.prose figcaption {
+		display: block;
+		margin-block: var(--caption-gap, var(--space-xsmall));
+		font-size: var(--caption-size, var(--size-small));
+		text-align: var(--caption-align, left);
 	}
-}
-
-.caption,
-.prose figcaption {
-	display: block;
-	margin-block: var(--caption-gap, var(--space-xsmall));
-	font-size: var(--caption-font-size, var(--size-small));
-	color: var(--caption-color, var(--color-quiet));
 
-	&:first-child {
+	/* Captions have tighter margins than most block elements, so zero the abutting margin of any */
+	/* neighbouring sibling — otherwise margin collapse would let the bigger neighbour margin win, */
+	/* drifting the caption away from its content. */
+	.caption + *,
+	.prose figcaption + * {
 		margin-block-start: 0;
 	}
-	&:last-child {
+	:has(+ .caption),
+	.prose :has(+ figcaption) {
 		margin-block-end: 0;
 	}
 }
 
-/* Captions have tighter margins than most block elements, so zero the abutting margin of any neighbouring sibling — otherwise margin collapse would let the bigger neighbour margin win, drifting the caption away from its content. */
-.caption + *,
-.prose figcaption + * {
-	margin-block-start: 0;
-}
-:has(+ .caption),
-.prose :has(+ figcaption) {
-	margin-block-end: 0;
+@layer overrides {
+	.block,
+	.prose :where(section, article, aside, nav, header, footer, figure),
+	.caption,
+	.prose figcaption {
+		&:first-child {
+			margin-block-start: 0;
+		}
+		&:last-child {
+			margin-block-end: 0;
+		}
+	}
 }