shelving 1.261.0 → 1.262.1

package/package.json

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

package/react/createAPIContext.d.ts

@@ -1,21 +1,20 @@
-import { type ReactElement, type ReactNode } from "react";
+import { type ReactElement } from "react";
 import type { Endpoint } from "../api/endpoint/Endpoint.js";
 import type { APIProvider } from "../api/provider/APIProvider.js";
 import type { EndpointStore } from "../api/store/EndpointStore.js";
+import type { ChildProps } from "../ui/index.js";
 import type { Nullish } from "../util/null.js";
 /**
- * Bundle of hooks and a provider component returned by `createAPIContext()`.
+ * Bundle of hooks and a provider component returned by `createAPIContext()`
  *
  * @see https://shelving.cc/react/APIContext
  */
 export interface APIContext<P, R> {
-    /** Get an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
+    /** React hook to return an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Endpoint<PP, RR>, payload: PP): EndpointStore<PP, RR>;
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Nullish<Endpoint<PP, RR>>, payload: PP): EndpointStore<PP, RR> | undefined;
     /** The `<APIContext>` wrapper to give your React components access to this API provider. */
-    readonly APIContext: ({ children }: {
-        children: ReactNode;
-    }) => ReactElement;
+    readonly APIContext: (props: ChildProps) => ReactElement;
 }
 /**
  * Create an API context.
@@ -24,8 +23,6 @@ export interface APIContext<P, R> {
  *
  * @param provider `APIProvider` the created context resolves endpoint stores against.
  *
- * @todo Use and integreate our `EndpointCache` functionality and use it in this.
- *
  * @see https://shelving.cc/react/createAPIContext
  */
 export declare function createAPIContext<P, R>(provider: APIProvider<P, R>): APIContext<P, R>;

package/react/createAPIContext.js

@@ -11,8 +11,6 @@ import { useStore } from "./useStore.js";
  *
  * @param provider `APIProvider` the created context resolves endpoint stores against.
  *
- * @todo Use and integreate our `EndpointCache` functionality and use it in this.
- *
  * @see https://shelving.cc/react/createAPIContext
  */
 export function createAPIContext(provider) {

package/ui/README.md

@@ -25,7 +25,7 @@ The styling system lives in `style/` and has four moving parts: design tokens, t
 
 **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`.
 
-**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()`; 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.
+**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).
 

package/ui/block/Definitions.d.ts

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import type { ColorVariants } from "../style/Color.js";
 import type { GapVariants } from "../style/Gap.js";
 import type { SpaceVariants } from "../style/Space.js";
 import type { TypographyVariants } from "../style/Typography.js";
@@ -9,7 +8,7 @@ import type { OptionalChildProps } from "../util/props.js";
  *
  * @see https://shelving.cc/ui/DefinitionsProps
  */
-export interface DefinitionsProps extends ColorVariants, GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {
+export interface DefinitionsProps extends GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {
 }
 /**
  * Description list — a sequence of term/value pairs rendered as a `<dl>`.

package/ui/block/Definitions.tsx

@@ -1,6 +1,5 @@
 import type { ReactElement } from "react";
 import { getBlockClass } from "../style/Block.js";
-import type { ColorVariants } from "../style/Color.js";
 import type { GapVariants } from "../style/Gap.js";
 import type { SpaceVariants } from "../style/Space.js";
 import type { TypographyVariants } from "../style/Typography.js";
@@ -15,7 +14,7 @@ const DEFINITIONS_CLASS = getModuleClass(DEFINITIONS_CSS, "definitions");
  *
  * @see https://shelving.cc/ui/DefinitionsProps
  */
-export interface DefinitionsProps extends ColorVariants, GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {}
+export interface DefinitionsProps extends GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {}
 
 /**
  * Description list — a sequence of term/value pairs rendered as a `<dl>`.

package/ui/form/Button.d.ts

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import { type ColorVariants } from "../style/Color.js";
 import { type FlexVariants } from "../style/Flex.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
@@ -9,7 +8,7 @@ import { type ClickableProps } from "./Clickable.js";
  *
  * @see https://shelving.cc/ui/ButtonVariants
  */
-export interface ButtonVariants extends FlexVariants, ColorVariants, StatusVariants, TypographyVariants {
+export interface ButtonVariants extends FlexVariants, StatusVariants, TypographyVariants {
     /** This is the default button in a form and should be displayed stronger. */
     strong?: boolean | undefined;
     /** Add plain styling (background only appears on hover or focus). */

package/ui/form/Button.js

@@ -1,5 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { getColorClass } from "../style/Color.js";
 import { getFlexClass } from "../style/Flex.js";
 import { getStatusClass } from "../style/Status.js";
 import { getTypographyClass } from "../style/Typography.js";
@@ -14,7 +13,7 @@ import { Clickable } from "./Clickable.js";
  * @see https://shelving.cc/ui/getButtonClass
  */
 export function getButtonClass(variants) {
-    return getClass(getModuleClass(BUTTON_CSS, "button", variants), getFlexClass(variants), getStatusClass(variants), getColorClass(variants), getTypographyClass(variants));
+    return getClass(getModuleClass(BUTTON_CSS, "button", variants), getFlexClass(variants), getStatusClass(variants), getTypographyClass(variants));
 }
 /**
  * Render either a `<button>` or an `<a href="">` styled as a button, based on whether an `onClick` or `href` prop is provided.

package/ui/form/Button.tsx

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { type FlexVariants, getFlexClass } from "../style/Flex.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
@@ -12,7 +11,7 @@ import { Clickable, type ClickableProps } from "./Clickable.js";
  *
  * @see https://shelving.cc/ui/ButtonVariants
  */
-export interface ButtonVariants extends FlexVariants, ColorVariants, StatusVariants, TypographyVariants {
+export interface ButtonVariants extends FlexVariants, StatusVariants, TypographyVariants {
 	/** This is the default button in a form and should be displayed stronger. */
 	strong?: boolean | undefined;
 	/** Add plain styling (background only appears on hover or focus). */
@@ -37,7 +36,6 @@ export function getButtonClass(variants: ButtonVariants): string {
 		getModuleClass(BUTTON_CSS, "button", variants),
 		getFlexClass(variants),
 		getStatusClass(variants),
-		getColorClass(variants),
 		getTypographyClass(variants),
 	);
 }

package/ui/inline/Code.d.ts

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import type { ColorVariants } from "../style/Color.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/index.js";
 /**
@@ -7,7 +6,7 @@ import type { OptionalChildProps } from "../util/index.js";
  *
  * @see https://shelving.cc/ui/CodeProps
  */
-export interface CodeProps extends ColorVariants, TypographyVariants, OptionalChildProps {
+export interface CodeProps extends TypographyVariants, OptionalChildProps {
     plain?: boolean | undefined;
 }
 /**

package/ui/inline/Code.module.css

@@ -19,9 +19,9 @@
 	.prose :is(code, kbd, samp, var):not(pre *) {
 		/* Box */
 		display: inline-block;
-		vertical-align: text-bottom;
 		padding-inline: var(--code-padding, var(--space-xxsmall));
 		border-radius: var(--code-radius, var(--radius-xxsmall));
+		vertical-align: baseline;
 
 		/* Style */
 		background: var(--code-background, var(--tint-90));

package/ui/inline/Code.tsx

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import type { ColorVariants } from "../style/Color.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/index.js";
@@ -14,7 +13,7 @@ const CODE_PLAIN_CLASS = getModuleClass(CODE_CSS, "plain");
  *
  * @see https://shelving.cc/ui/CodeProps
  */
-export interface CodeProps extends ColorVariants, TypographyVariants, OptionalChildProps {
+export interface CodeProps extends TypographyVariants, OptionalChildProps {
 	plain?: boolean | undefined;
 }
 

package/ui/inline/Deleted.d.ts

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import { type ColorVariants } from "../style/Color.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/props.js";
 /**
@@ -7,7 +6,7 @@ import type { OptionalChildProps } from "../util/props.js";
  *
  * @see https://shelving.cc/ui/DeletedProps
  */
-export interface DeletedProps extends OptionalChildProps, ColorVariants, TypographyVariants {
+export interface DeletedProps extends OptionalChildProps, TypographyVariants {
 }
 /**
  * Deleted text — renders a `<del>` element to mark content removed from a document.

package/ui/inline/Deleted.js

@@ -1,5 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { getColorClass } from "../style/Color.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import DELETED_CSS from "./Deleted.module.css";
@@ -13,5 +12,5 @@ const DELETED_CLASS = getModuleClass(DELETED_CSS, "deleted");
  */
 export function Deleted({ children, ...props }) {
     return (_jsx("del", { className: getClass(DELETED_CLASS, //
-        getColorClass(props), getTypographyClass(props)), children: children }));
+        getTypographyClass(props)), children: children }));
 }

package/ui/inline/Deleted.tsx

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
@@ -12,7 +11,7 @@ const DELETED_CLASS = getModuleClass(DELETED_CSS, "deleted");
  *
  * @see https://shelving.cc/ui/DeletedProps
  */
-export interface DeletedProps extends OptionalChildProps, ColorVariants, TypographyVariants {}
+export interface DeletedProps extends OptionalChildProps, TypographyVariants {}
 
 /**
  * Deleted text — renders a `<del>` element to mark content removed from a document.
@@ -26,7 +25,6 @@ export function Deleted({ children, ...props }: DeletedProps): ReactElement {
 		<del
 			className={getClass(
 				DELETED_CLASS, //
-				getColorClass(props),
 				getTypographyClass(props),
 			)}
 		>

package/ui/inline/Inserted.d.ts

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import { type ColorVariants } from "../style/Color.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/props.js";
 /**
@@ -7,7 +6,7 @@ import type { OptionalChildProps } from "../util/props.js";
  *
  * @see https://shelving.cc/ui/InsertedProps
  */
-export interface InsertedProps extends OptionalChildProps, ColorVariants, TypographyVariants {
+export interface InsertedProps extends OptionalChildProps, TypographyVariants {
 }
 /**
  * Inserted text — renders an `<ins>` element to mark content added to a document.

package/ui/inline/Inserted.js

@@ -1,5 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { getColorClass } from "../style/Color.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import INSERTED_CSS from "./Inserted.module.css";
@@ -13,5 +12,5 @@ const INSERTED_CLASS = getModuleClass(INSERTED_CSS, "inserted");
  */
 export function Inserted({ children, ...props }) {
     return (_jsx("ins", { className: getClass(INSERTED_CLASS, //
-        getColorClass(props), getTypographyClass(props)), children: children }));
+        getTypographyClass(props)), children: children }));
 }

package/ui/inline/Inserted.tsx

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
@@ -12,7 +11,7 @@ const INSERTED_CLASS = getModuleClass(INSERTED_CSS, "inserted");
  *
  * @see https://shelving.cc/ui/InsertedProps
  */
-export interface InsertedProps extends OptionalChildProps, ColorVariants, TypographyVariants {}
+export interface InsertedProps extends OptionalChildProps, TypographyVariants {}
 
 /**
  * Inserted text — renders an `<ins>` element to mark content added to a document.
@@ -26,7 +25,6 @@ export function Inserted({ children, ...props }: InsertedProps): ReactElement {
 		<ins
 			className={getClass(
 				INSERTED_CLASS, //
-				getColorClass(props),
 				getTypographyClass(props),
 			)}
 		>

package/ui/inline/Link.d.ts

@@ -1,13 +1,12 @@
 import type { ReactElement } from "react";
 import { type ClickableProps } from "../form/Clickable.js";
-import { type ColorVariants } from "../style/Color.js";
 import { type TypographyVariants } from "../style/Typography.js";
 /**
  * Props for `Link` — `ClickableProps` (`href` for navigation or `onClick` for actions) plus colour and typography variants.
  *
  * @see https://shelving.cc/ui/LinkProps
  */
-export interface LinkProps extends ClickableProps, ColorVariants, TypographyVariants {
+export interface LinkProps extends ClickableProps, TypographyVariants {
 }
 /**
  * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).

package/ui/inline/Link.js

@@ -1,6 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Clickable } from "../form/Clickable.js";
-import { getColorClass } from "../style/Color.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import LINK_CSS from "./Link.module.css";
@@ -13,5 +12,5 @@ const LINK_CLASS = getModuleClass(LINK_CSS, "link");
  */
 export function Link(props) {
     return (_jsx(Clickable, { ...props, className: getClass(LINK_CLASS, //
-        getColorClass(props), getTypographyClass(props)) }));
+        getTypographyClass(props)) }));
 }

package/ui/inline/Link.tsx

@@ -1,6 +1,5 @@
 import type { ReactElement } from "react";
 import { Clickable, type ClickableProps } from "../form/Clickable.js";
-import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import LINK_CSS from "./Link.module.css";
@@ -12,7 +11,7 @@ const LINK_CLASS = getModuleClass(LINK_CSS, "link");
  *
  * @see https://shelving.cc/ui/LinkProps
  */
-export interface LinkProps extends ClickableProps, ColorVariants, TypographyVariants {}
+export interface LinkProps extends ClickableProps, TypographyVariants {}
 
 /**
  * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
@@ -26,7 +25,6 @@ export function Link(props: LinkProps): ReactElement {
 			{...props}
 			className={getClass(
 				LINK_CLASS, //
-				getColorClass(props),
 				getTypographyClass(props),
 			)}
 		/>

package/ui/inline/Mark.module.css

@@ -12,10 +12,10 @@
 		display: inline-block;
 		padding-inline: var(--mark-padding, var(--space-xxsmall));
 		border-radius: var(--mark-radius, var(--radius-xxsmall));
-		vertical-align: text-bottom;
+		vertical-align: baseline;
 
 		/* Style */
-		background-color: var(--mark-background, var(--tint-50));
+		background: var(--mark-background, var(--tint-80));
 		color: var(--mark-color, var(--tint-00));
 
 		/* Text */

package/ui/inline/Span.d.ts

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import { type TypographyVariants } from "../style/Typography.js";
+import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `Span` — colour and typography variants, plus optional `children`.
+ *
+ * @see https://shelving.cc/ui/SpanProps
+ */
+export interface SpanProps extends OptionalChildProps, TypographyVariants {
+}
+/**
+ * Styled inline text — renders a `<span>` carrying only the colour and typography variant classes, with no styling of its own.
+ * - Reach for it to apply variants (`size`, `weight`, `tint`, `color`, …) to a run of text that has no semantic meaning of its own.
+ *
+ * @kind component
+ * @example <Span weight="strong" tint="30">label</Span>
+ * @see https://shelving.cc/ui/Span
+ */
+export declare function Span({ children, ...props }: SpanProps): ReactElement;

package/ui/inline/Span.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getTypographyClass } from "../style/Typography.js";
+/**
+ * Styled inline text — renders a `<span>` carrying only the colour and typography variant classes, with no styling of its own.
+ * - Reach for it to apply variants (`size`, `weight`, `tint`, `color`, …) to a run of text that has no semantic meaning of its own.
+ *
+ * @kind component
+ * @example <Span weight="strong" tint="30">label</Span>
+ * @see https://shelving.cc/ui/Span
+ */
+export function Span({ children, ...props }) {
+    return _jsx("span", { className: getTypographyClass(props), children: children });
+}

package/ui/inline/Span.md

@@ -0,0 +1,33 @@
+# Span
+
+Styled inline text — renders a `<span>` element that carries only the colour and typography variant classes you pass it, with no styling of its own. Reach for it when you need to apply variants to a run of text that has no semantic meaning, the inline counterpart to a styled `<div>`.
+
+**Things to know:**
+
+- It is purely presentational: use `<Strong>` for importance, `<Emphasis>` for stress emphasis, `<Mark>` for highlighting, and `<Small>` for fine print — `Span` is for everything that is _only_ a visual tweak.
+- With no props it is an inert wrapper — it renders a bare `<span>` and changes nothing.
+- It accepts the full [typography variants](/ui/TypographyVariants) (`size`, `weight`, `font`, `case`, `tint`, `left` / `center` / `right`, `wrap` / `nowrap`) and the [colour variant](/ui/ColorVariants) (`color`).
+- `color` sets the [tint ladder](/ui/TINT_CLASS) for the span and its descendants; pair it with `tint` to actually paint the span's own text from a ladder step (e.g. `color="purple" tint="40"`).
+
+## Usage
+
+### Applying typography variants
+
+```tsx
+import { Span } from "shelving/ui";
+
+<p>Total <Span weight="strong">$35.00</Span> due today.</p>
+<p><Span case="upper" size="xsmall">New</Span></p>
+```
+
+### Colouring a run of text
+
+```tsx
+import { Span } from "shelving/ui";
+
+<Span color="purple" tint="40">on-brand accent</Span>
+```
+
+## Styling
+
+`Span` declares no CSS of its own — there are no theming hooks. All appearance comes from the colour and typography variant props, which apply shared variant classes from the design system.

package/ui/inline/Span.tsx

@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+import type { OptionalChildProps } from "../util/props.js";
+
+/**
+ * Props for `Span` — colour and typography variants, plus optional `children`.
+ *
+ * @see https://shelving.cc/ui/SpanProps
+ */
+export interface SpanProps extends OptionalChildProps, TypographyVariants {}
+
+/**
+ * Styled inline text — renders a `<span>` carrying only the colour and typography variant classes, with no styling of its own.
+ * - Reach for it to apply variants (`size`, `weight`, `tint`, `color`, …) to a run of text that has no semantic meaning of its own.
+ *
+ * @kind component
+ * @example <Span weight="strong" tint="30">label</Span>
+ * @see https://shelving.cc/ui/Span
+ */
+export function Span({ children, ...props }: SpanProps): ReactElement {
+	return <span className={getTypographyClass(props)}>{children}</span>;
+}

package/ui/inline/index.d.ts

@@ -5,6 +5,7 @@ export * from "./Inserted.js";
 export * from "./Link.js";
 export * from "./Mark.js";
 export * from "./Small.js";
+export * from "./Span.js";
 export * from "./Strong.js";
 export * from "./Subscript.js";
 export * from "./Superscript.js";

package/ui/inline/index.js

@@ -5,6 +5,7 @@ export * from "./Inserted.js";
 export * from "./Link.js";
 export * from "./Mark.js";
 export * from "./Small.js";
+export * from "./Span.js";
 export * from "./Strong.js";
 export * from "./Subscript.js";
 export * from "./Superscript.js";

package/ui/inline/index.ts

@@ -5,6 +5,7 @@ export * from "./Inserted.js";
 export * from "./Link.js";
 export * from "./Mark.js";
 export * from "./Small.js";
+export * from "./Span.js";
 export * from "./Strong.js";
 export * from "./Subscript.js";
 export * from "./Superscript.js";

package/ui/misc/Catcher.d.ts

@@ -22,9 +22,9 @@ export declare function RetryButton({ children, ...props }: RetryButtonProps): R
 /**
  * Props for a component that renders a caught error `reason`.
  *
- * @see https://shelving.cc/ui/ErrorComponentProps
+ * @see https://shelving.cc/ui/ErrorProps
  */
-export interface ErrorComponentProps {
+export interface ErrorProps {
     reason: unknown;
 }
 /**
@@ -34,7 +34,7 @@ export interface ErrorComponentProps {
  */
 export interface CatcherProps extends ChildProps {
     /** Component to render an error (defaults to `<ErrorNotice />`) */
-    as: (props: ErrorComponentProps) => ReactElement;
+    as: (props: ErrorProps) => ReactElement;
 }
 type CatcherState = {
     /** The error that was caught. */
@@ -56,27 +56,6 @@ export declare class Catcher extends Component<CatcherProps, CatcherState> {
     static getDerivedStateFromError(reason: unknown): CatcherState;
     render(): ReactNode;
 }
-/**
- * Props for `<PageCatcher>` — the page `children` to guard.
- *
- * @see https://shelving.cc/ui/PageCatcherProps
- */
-export interface PageCatcherProps extends ChildProps {
-}
-/**
- * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
- *
- * @kind component
- * @see https://shelving.cc/ui/PageCatcher
- */
-export declare function PageCatcher({ children }: PageCatcherProps): ReactElement;
-/**
- * Props for `<ErrorNotice>` — the caught error `reason`.
- *
- * @see https://shelving.cc/ui/ErrorNoticeProps
- */
-export interface ErrorNoticeProps extends ErrorComponentProps {
-}
 /**
  * Render a caught error as an inline `<Notice>` with a retry button.
  *
@@ -85,14 +64,14 @@ export interface ErrorNoticeProps extends ErrorComponentProps {
  * @kind component
  * @see https://shelving.cc/ui/ErrorNotice
  */
-export declare function ErrorNotice({ reason }: ErrorNoticeProps): ReactElement;
+export declare function ErrorNotice({ reason }: ErrorProps): ReactElement;
 /**
- * Props for `<ErrorPage>` — the caught error `reason`.
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
  *
- * @see https://shelving.cc/ui/ErrorPageProps
+ * @kind component
+ * @see https://shelving.cc/ui/PageCatcher
  */
-export interface ErrorPageProps extends ErrorComponentProps {
-}
+export declare function PageCatcher({ children }: ChildProps): ReactElement;
 /**
  * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
  *
@@ -101,5 +80,5 @@ export interface ErrorPageProps extends ErrorComponentProps {
  * @kind component
  * @see https://shelving.cc/ui/ErrorPage
  */
-export declare function ErrorPage({ reason }: ErrorPageProps): ReactElement;
+export declare function ErrorPage({ reason }: ErrorProps): ReactElement;
 export {};

package/ui/misc/Catcher.js

@@ -3,6 +3,7 @@ import { ArrowPathIcon } from "@heroicons/react/24/solid";
 import { Component, createContext, use } from "react";
 import { getMessage } from "../../util/error.js";
 import { Card } from "../block/Card.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Row } from "../block/Row.js";
 import { Subheading } from "../block/Subheading.js";
 import { Button } from "../form/Button.js";
@@ -59,15 +60,6 @@ export class Catcher extends Component {
         return (_jsx(RetryContext, { value: retry, children: _jsx(ErrorComponent, { reason: reason }) }));
     }
 }
-/**
- * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
- *
- * @kind component
- * @see https://shelving.cc/ui/PageCatcher
- */
-export function PageCatcher({ children }) {
-    return _jsx(Catcher, { as: ErrorPage, children: children });
-}
 /**
  * Render a caught error as an inline `<Notice>` with a retry button.
  *
@@ -78,7 +70,16 @@ export function PageCatcher({ children }) {
  */
 export function ErrorNotice({ reason }) {
     const message = getMessage(reason) ?? "Unknown error";
-    return (_jsxs(Notice, { status: "error", children: [_jsx("p", { children: message }), _jsx(RetryButton, { small: true })] }));
+    return (_jsxs(Notice, { status: "error", children: [_jsx(Paragraph, { children: message }), _jsx(RetryButton, { small: true })] }));
+}
+/**
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageCatcher
+ */
+export function PageCatcher({ children }) {
+    return _jsx(Catcher, { as: ErrorPage, children: children });
 }
 /**
  * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.

package/ui/misc/Catcher.tsx

@@ -3,6 +3,7 @@ import { Component, createContext, type ReactElement, type ReactNode, use } from
 import { getMessage } from "../../util/error.js";
 import type { Callback } from "../../util/function.js";
 import { Card } from "../block/Card.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Row } from "../block/Row.js";
 import { Subheading } from "../block/Subheading.js";
 import { Button, type ButtonVariants } from "../form/Button.js";
@@ -51,9 +52,9 @@ export function RetryButton({ children = RETRY_CHILDREN, ...props }: RetryButton
 /**
  * Props for a component that renders a caught error `reason`.
  *
- * @see https://shelving.cc/ui/ErrorComponentProps
+ * @see https://shelving.cc/ui/ErrorProps
  */
-export interface ErrorComponentProps {
+export interface ErrorProps {
 	reason: unknown;
 }
 
@@ -64,7 +65,7 @@ export interface ErrorComponentProps {
  */
 export interface CatcherProps extends ChildProps {
 	/** Component to render an error (defaults to `<ErrorNotice />`) */
-	as: (props: ErrorComponentProps) => ReactElement;
+	as: (props: ErrorProps) => ReactElement;
 }
 
 type CatcherState = {
@@ -107,30 +108,6 @@ export class Catcher extends Component<CatcherProps, CatcherState> {
 	}
 }
 
-/**
- * Props for `<PageCatcher>` — the page `children` to guard.
- *
- * @see https://shelving.cc/ui/PageCatcherProps
- */
-export interface PageCatcherProps extends ChildProps {}
-
-/**
- * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
- *
- * @kind component
- * @see https://shelving.cc/ui/PageCatcher
- */
-export function PageCatcher({ children }: PageCatcherProps): ReactElement {
-	return <Catcher as={ErrorPage}>{children}</Catcher>;
-}
-
-/**
- * Props for `<ErrorNotice>` — the caught error `reason`.
- *
- * @see https://shelving.cc/ui/ErrorNoticeProps
- */
-export interface ErrorNoticeProps extends ErrorComponentProps {}
-
 /**
  * Render a caught error as an inline `<Notice>` with a retry button.
  *
@@ -139,22 +116,25 @@ export interface ErrorNoticeProps extends ErrorComponentProps {}
  * @kind component
  * @see https://shelving.cc/ui/ErrorNotice
  */
-export function ErrorNotice({ reason }: ErrorNoticeProps): ReactElement {
+export function ErrorNotice({ reason }: ErrorProps): ReactElement {
 	const message = getMessage(reason) ?? "Unknown error";
 	return (
 		<Notice status="error">
-			<p>{message}</p>
+			<Paragraph>{message}</Paragraph>
 			<RetryButton small />
 		</Notice>
 	);
 }
 
 /**
- * Props for `<ErrorPage>` — the caught error `reason`.
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
  *
- * @see https://shelving.cc/ui/ErrorPageProps
+ * @kind component
+ * @see https://shelving.cc/ui/PageCatcher
  */
-export interface ErrorPageProps extends ErrorComponentProps {}
+export function PageCatcher({ children }: ChildProps): ReactElement {
+	return <Catcher as={ErrorPage}>{children}</Catcher>;
+}
 
 /**
  * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
@@ -164,7 +144,7 @@ export interface ErrorPageProps extends ErrorComponentProps {}
  * @kind component
  * @see https://shelving.cc/ui/ErrorPage
  */
-export function ErrorPage({ reason }: ErrorPageProps): ReactElement {
+export function ErrorPage({ reason }: ErrorProps): ReactElement {
 	const message = getMessage(reason) ?? "Unknown error";
 	return (
 		<Page title="Error">

package/ui/misc/Icon.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactElement } from "react";
-import { type ColorVariants } from "../style/Color.js";
+import type { ColorVariants } from "../style/Color.js";
 import type { SpaceVariants } from "../style/Space.js";
 import { type StatusVariants } from "../style/Status.js";
 import type { TintVariant } from "../style/Tint.js";

package/ui/misc/Icon.js

@@ -1,6 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { CheckCircleIcon, ExclamationTriangleIcon, InformationCircleIcon, XCircleIcon } from "@heroicons/react/24/solid";
-import { getColorClass } from "../style/Color.js";
 import { getStatusClass } from "../style/Status.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
@@ -24,5 +23,5 @@ const STATUS_ICONS = {
 export function Icon(props) {
     const { status = "info", icon: Element = STATUS_ICONS[status] ?? InformationCircleIcon } = props;
     return (_jsx(Element, { className: getClass(getModuleClass(ICON_CSS, "icon"), //
-        getColorClass(props), getStatusClass(props), getTypographyClass(props)) }));
+        getStatusClass(props), getTypographyClass(props)) }));
 }

package/ui/misc/Icon.tsx

@@ -1,6 +1,6 @@
 import { CheckCircleIcon, ExclamationTriangleIcon, InformationCircleIcon, XCircleIcon } from "@heroicons/react/24/solid";
 import type { ComponentType, ReactElement } from "react";
-import { type ColorVariants, getColorClass } from "../style/Color.js";
+import type { ColorVariants } from "../style/Color.js";
 import type { SpaceVariants } from "../style/Space.js";
 import { getStatusClass, type Status, type StatusVariants } from "../style/Status.js";
 import type { TintVariant } from "../style/Tint.js";
@@ -55,9 +55,8 @@ export function Icon(props: IconProps): ReactElement {
 		<Element
 			className={getClass(
 				getModuleClass(ICON_CSS, "icon"), //
-				getColorClass(props),
 				getStatusClass(props),
-				getTypographyClass(props), // Used for size and tint.
+				getTypographyClass(props), // Used for colour, size, and tint.
 			)}
 		/>
 	);

package/ui/misc/Loader.d.ts

@@ -0,0 +1,31 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `<Loader>` and `<PageLoader>` — the `children` to load plus an optional `fallback` shown while they suspend.
+ *
+ * @see https://shelving.cc/ui/LoaderProps
+ */
+export interface LoaderProps extends ChildProps {
+    /** Element rendered while `children` suspend (defaults to `LOADING`). */
+    readonly fallback?: ReactNode | undefined;
+}
+/**
+ * Load a component.
+ *
+ * - Wrapped in `<Catcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/Loader
+ */
+export declare function Loader({ children, fallback }: LoaderProps): ReactElement;
+/**
+ * Load a page.
+ *
+ * - Wrapped in `<PageCatcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageLoader
+ */
+export declare function PageLoader({ children, fallback }: LoaderProps): ReactElement;

package/ui/misc/Loader.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense } from "react";
+import { CenteredLayout } from "../layout/CenteredLayout.js";
+import { Catcher, PageCatcher } from "./Catcher.js";
+import { LOADING } from "./Loading.js";
+/**
+ * Load a component.
+ *
+ * - Wrapped in `<Catcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/Loader
+ */
+export function Loader({ children, fallback = LOADING }) {
+    return (_jsx(Catcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
+}
+/**
+ * Load a page.
+ *
+ * - Wrapped in `<PageCatcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageLoader
+ */
+export function PageLoader({ children, fallback = _jsx(CenteredLayout, { children: LOADING }) }) {
+    return (_jsx(PageCatcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
+}

package/ui/misc/Loader.tsx

@@ -0,0 +1,49 @@
+import { type ReactElement, type ReactNode, Suspense } from "react";
+import { CenteredLayout } from "../layout/CenteredLayout.js";
+import type { ChildProps } from "../util/props.js";
+import { Catcher, PageCatcher } from "./Catcher.js";
+import { LOADING } from "./Loading.js";
+
+/**
+ * Props for `<Loader>` and `<PageLoader>` — the `children` to load plus an optional `fallback` shown while they suspend.
+ *
+ * @see https://shelving.cc/ui/LoaderProps
+ */
+export interface LoaderProps extends ChildProps {
+	/** Element rendered while `children` suspend (defaults to `LOADING`). */
+	readonly fallback?: ReactNode | undefined;
+}
+
+/**
+ * Load a component.
+ *
+ * - Wrapped in `<Catcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/Loader
+ */
+export function Loader({ children, fallback = LOADING }: LoaderProps): ReactElement {
+	return (
+		<Catcher>
+			<Suspense fallback={fallback}>{children}</Suspense>
+		</Catcher>
+	);
+}
+
+/**
+ * Load a page.
+ *
+ * - Wrapped in `<PageCatcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageLoader
+ */
+export function PageLoader({ children, fallback = <CenteredLayout>{LOADING}</CenteredLayout> }: LoaderProps): ReactElement {
+	return (
+		<PageCatcher>
+			<Suspense fallback={fallback}>{children}</Suspense>
+		</PageCatcher>
+	);
+}

package/ui/misc/Tag.d.ts

@@ -1,6 +1,5 @@
 import type { ReactElement } from "react";
 import { type ClickableProps } from "../form/Clickable.js";
-import { type ColorVariants } from "../style/Color.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 /**
@@ -8,7 +7,7 @@ import { type TypographyVariants } from "../style/Typography.js";
  *
  * @see https://shelving.cc/ui/TagVariants
  */
-export interface TagVariants extends StatusVariants, ColorVariants, TypographyVariants {
+export interface TagVariants extends StatusVariants, TypographyVariants {
 }
 /**
  * Build the combined `className` string for a `<Tag>` from its styling variants.

package/ui/misc/Tag.js

@@ -1,6 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Clickable } from "../form/Clickable.js";
-import { getColorClass } from "../style/Color.js";
 import { getStatusClass } from "../style/Status.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
@@ -16,7 +15,7 @@ const TAG_CLASS = getModuleClass(TAG_CSS, "tag");
  */
 export function getTagClass(variants) {
     return getClass(TAG_CLASS, //
-    getStatusClass(variants), getColorClass(variants), getTypographyClass(variants));
+    getStatusClass(variants), getTypographyClass(variants));
 }
 /**
  * Small inline label used to annotate other content.

package/ui/misc/Tag.tsx

@@ -1,6 +1,5 @@
 import type { ReactElement } from "react";
 import { Clickable, type ClickableProps } from "../form/Clickable.js";
-import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
@@ -13,7 +12,7 @@ const TAG_CLASS = getModuleClass(TAG_CSS, "tag");
  *
  * @see https://shelving.cc/ui/TagVariants
  */
-export interface TagVariants extends StatusVariants, ColorVariants, TypographyVariants {}
+export interface TagVariants extends StatusVariants, TypographyVariants {}
 
 /**
  * Build the combined `className` string for a `<Tag>` from its styling variants.
@@ -27,7 +26,6 @@ export function getTagClass(variants: TagVariants) {
 	return getClass(
 		TAG_CLASS, //
 		getStatusClass(variants),
-		getColorClass(variants),
 		getTypographyClass(variants),
 	);
 }

package/ui/misc/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./Catcher.js";
 export * from "./Icon.js";
+export * from "./Loader.js";
 export * from "./Loading.js";
 export * from "./Mapper.js";
 export * from "./Markup.js";

package/ui/misc/index.js

@@ -1,5 +1,6 @@
 export * from "./Catcher.js";
 export * from "./Icon.js";
+export * from "./Loader.js";
 export * from "./Loading.js";
 export * from "./Mapper.js";
 export * from "./Markup.js";

package/ui/misc/index.tsx

@@ -1,5 +1,6 @@
 export * from "./Catcher.js";
 export * from "./Icon.js";
+export * from "./Loader.js";
 export * from "./Loading.js";
 export * from "./Mapper.js";
 export * from "./Markup.js";

package/ui/style/Block.d.ts

@@ -1,4 +1,3 @@
-import { type ColorVariants } from "./Color.js";
 import { type IndentVariants } from "./Indent.js";
 import { type PaddingVariants } from "./Padding.js";
 import { type SpaceVariants } from "./Space.js";
@@ -9,7 +8,7 @@ import { type WidthVariants } from "./Width.js";
  *
  * @see https://shelving.cc/ui/BlockVariants
  */
-export interface BlockVariants extends ColorVariants, IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants {
+export interface BlockVariants extends IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants {
 }
 /**
  * Get the combined `className` string for a block from its styling variants.

package/ui/style/Block.js

@@ -1,6 +1,5 @@
 import { getClass, getModuleClass } from "../util/css.js";
 import BLOCK_CSS from "./Block.module.css";
-import { getColorClass } from "./Color.js";
 import { getIndentClass } from "./Indent.js";
 import { getPaddingClass } from "./Padding.js";
 import { getSpaceClass } from "./Space.js";
@@ -18,5 +17,5 @@ const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
  */
 export function getBlockClass(variants) {
     return getClass(BLOCK_CLASS, //
-    getColorClass(variants), getIndentClass(variants), getPaddingClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
+    getIndentClass(variants), getPaddingClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
 }

package/ui/style/Block.tsx

@@ -1,6 +1,5 @@
 import { getClass, getModuleClass } from "../util/css.js";
 import BLOCK_CSS from "./Block.module.css";
-import { type ColorVariants, getColorClass } from "./Color.js";
 import { getIndentClass, type IndentVariants } from "./Indent.js";
 import { getPaddingClass, type PaddingVariants } from "./Padding.js";
 import { getSpaceClass, type SpaceVariants } from "./Space.js";
@@ -14,7 +13,7 @@ const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
  *
  * @see https://shelving.cc/ui/BlockVariants
  */
-export interface BlockVariants extends ColorVariants, IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants {}
+export interface BlockVariants extends IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants {}
 
 /**
  * Get the combined `className` string for a block from its styling variants.
@@ -28,7 +27,6 @@ export interface BlockVariants extends ColorVariants, IndentVariants, SpaceVaria
 export function getBlockClass(variants: BlockVariants): string {
 	return getClass(
 		BLOCK_CLASS, //
-		getColorClass(variants),
 		getIndentClass(variants),
 		getPaddingClass(variants),
 		getSpaceClass(variants),

package/ui/style/Typography.d.ts

@@ -1,3 +1,4 @@
+import { type ColorVariants } from "./Color.js";
 import type { TintVariant } from "./Tint.js";
 /**
  * Allowed values for font size for components that support `TypographyVariants`
@@ -24,11 +25,13 @@ export type CaseVariant = "title" | "body" | "label" | "code" | "upper" | "lower
  */
 export type FontVariant = "title" | "body" | "label" | "code" | "serif" | "sans" | "monospace";
 /**
- * Typographic variant props — font-family, weight, case, size, tint, alignment, and wrap, applied via `getTypographyClass()`
+ * Typographic variant props — colour, font-family, weight, case, size, tint, alignment, and wrap, applied via `getTypographyClass()`
+ *
+ * - Extends `ColorVariants`, so anything that accepts typography also accepts the `color` variant.
  *
  * @see https://shelving.cc/ui/TypographyVariants
  */
-export interface TypographyVariants {
+export interface TypographyVariants extends ColorVariants {
     /** Font size of the element. */
     size?: SizeVariant | undefined;
     /** Set CSS text `color:` to one of the shades of the current tint ladder. */
@@ -53,10 +56,11 @@ export interface TypographyVariants {
 /**
  * Get the typography class for a component from its typographic variant props.
  *
- * Maps the size, weight, font, case, tint, alignment, and wrap variant props to their CSS classes.
+ * Maps the colour, size, weight, font, case, tint, alignment, and wrap variant props to their CSS classes — the `color` variant is composed in via `getColorClass()`.
  *
- * @returns The combined typography class string, or `undefined` when no variants apply.
+ * @returns The combined typography class string (empty when no variants apply).
  * @example getTypographyClass({ font: "title", size: "large", center: true })
+ * @example getTypographyClass({ color: "purple", tint: "40" })
  * @see https://shelving.cc/ui/getTypographyClass
  */
-export declare function getTypographyClass({ tint, weight, font, case: caseValue, size, ...props }: TypographyVariants): string | undefined;
+export declare function getTypographyClass({ tint, weight, font, case: caseValue, size, ...props }: TypographyVariants): string;

package/ui/style/Typography.js

@@ -1,14 +1,16 @@
-import { getModuleClass } from "../util/css.js";
+import { getClass, getModuleClass } from "../util/css.js";
+import { getColorClass } from "./Color.js";
 import TYPOGRAPHY_CSS from "./Typography.module.css";
 /**
  * Get the typography class for a component from its typographic variant props.
  *
- * Maps the size, weight, font, case, tint, alignment, and wrap variant props to their CSS classes.
+ * Maps the colour, size, weight, font, case, tint, alignment, and wrap variant props to their CSS classes — the `color` variant is composed in via `getColorClass()`.
  *
- * @returns The combined typography class string, or `undefined` when no variants apply.
+ * @returns The combined typography class string (empty when no variants apply).
  * @example getTypographyClass({ font: "title", size: "large", center: true })
+ * @example getTypographyClass({ color: "purple", tint: "40" })
  * @see https://shelving.cc/ui/getTypographyClass
  */
 export function getTypographyClass({ tint, weight, font, case: caseValue, size, ...props }) {
-    return getModuleClass(TYPOGRAPHY_CSS, caseValue && `case-${caseValue}`, tint && `tint-${tint}`, weight && `weight-${weight}`, font && `font-${font}`, size && `size-${size}`, props);
+    return getClass(getColorClass(props), getModuleClass(TYPOGRAPHY_CSS, caseValue && `case-${caseValue}`, tint && `tint-${tint}`, weight && `weight-${weight}`, font && `font-${font}`, size && `size-${size}`, props));
 }

package/ui/style/Typography.tsx

@@ -1,4 +1,5 @@
-import { getModuleClass } from "../util/css.js";
+import { getClass, getModuleClass } from "../util/css.js";
+import { type ColorVariants, getColorClass } from "./Color.js";
 import type { TintVariant } from "./Tint.js";
 import TYPOGRAPHY_CSS from "./Typography.module.css";
 
@@ -49,11 +50,13 @@ export type CaseVariant = "title" | "body" | "label" | "code" | "upper" | "lower
 export type FontVariant = "title" | "body" | "label" | "code" | "serif" | "sans" | "monospace";
 
 /**
- * Typographic variant props — font-family, weight, case, size, tint, alignment, and wrap, applied via `getTypographyClass()`
+ * Typographic variant props — colour, font-family, weight, case, size, tint, alignment, and wrap, applied via `getTypographyClass()`
+ *
+ * - Extends `ColorVariants`, so anything that accepts typography also accepts the `color` variant.
  *
  * @see https://shelving.cc/ui/TypographyVariants
  */
-export interface TypographyVariants {
+export interface TypographyVariants extends ColorVariants {
 	/** Font size of the element. */
 	size?: SizeVariant | undefined;
 	/** Set CSS text `color:` to one of the shades of the current tint ladder. */
@@ -79,20 +82,24 @@ export interface TypographyVariants {
 /**
  * Get the typography class for a component from its typographic variant props.
  *
- * Maps the size, weight, font, case, tint, alignment, and wrap variant props to their CSS classes.
+ * Maps the colour, size, weight, font, case, tint, alignment, and wrap variant props to their CSS classes — the `color` variant is composed in via `getColorClass()`.
  *
- * @returns The combined typography class string, or `undefined` when no variants apply.
+ * @returns The combined typography class string (empty when no variants apply).
  * @example getTypographyClass({ font: "title", size: "large", center: true })
+ * @example getTypographyClass({ color: "purple", tint: "40" })
  * @see https://shelving.cc/ui/getTypographyClass
  */
-export function getTypographyClass({ tint, weight, font, case: caseValue, size, ...props }: TypographyVariants): string | undefined {
-	return getModuleClass(
-		TYPOGRAPHY_CSS,
-		caseValue && `case-${caseValue}`,
-		tint && `tint-${tint}`,
-		weight && `weight-${weight}`,
-		font && `font-${font}`,
-		size && `size-${size}`,
-		props,
+export function getTypographyClass({ tint, weight, font, case: caseValue, size, ...props }: TypographyVariants): string {
+	return getClass(
+		getColorClass(props),
+		getModuleClass(
+			TYPOGRAPHY_CSS,
+			caseValue && `case-${caseValue}`,
+			tint && `tint-${tint}`,
+			weight && `weight-${weight}`,
+			font && `font-${font}`,
+			size && `size-${size}`,
+			props,
+		),
 	);
 }

package/ui/style/getTypographyClass.md

@@ -2,7 +2,7 @@
 
 The typography variant props set an element's text styling from a single helper — `<Heading font="title" size="large">`, `<Paragraph weight="strong" center>`, `<Small case="upper">`. They're **overrides** for one-off changes; for an app-wide change, retune the variables below in a theme file.
 
-`getTypographyClass({ size, weight, font, case, tint, left, center, right, wrap, nowrap })` maps each prop to a class (e.g. `size="large"` → `size-large`, `font="title"` → `font-title`, `weight="strong"` → `weight-strong`, `case="upper"` → `case-upper`), and combines them with text alignment, tint colour, and wrapping. It supersedes the former `getFontClass()`, `getSizeClass()`, and `getWeightClass()` helpers, which were merged into this module.
+`getTypographyClass({ color, size, weight, font, case, tint, left, center, right, wrap, nowrap })` maps each prop to a class (e.g. `size="large"` → `size-large`, `font="title"` → `font-title`, `weight="strong"` → `weight-strong`, `case="upper"` → `case-upper`), and combines them with text alignment, tint colour, and wrapping. `TypographyVariants` extends `ColorVariants`, so it also accepts `color` and composes [`getColorClass()`](/ui/getColorClass) internally — anything that opts into typography gets the `color` variant for free and no longer needs to extend `ColorVariants` or call `getColorClass()` separately. (`getColorClass()` stays exported for the rare element that wants colour without typography, such as `<Icon>`.) It also supersedes the former `getFontClass()`, `getSizeClass()`, and `getWeightClass()` helpers, which were merged into this module.
 
 The semantic faces, weights, sizes, and cases are aliases of the base values, so a theme usually only needs to move the small set of base variables.