shelving 1.237.0 → 1.239.0

package/ui/style/Size.module.css

@@ -0,0 +1,69 @@
+@import "layers.css";
+
+@layer defaults {
+	:root {
+		/* Sizings */
+		--size: 1rem;
+		--size-scale: 1.25;
+		--size-xxsmall: calc(var(--size) * pow(var(--size-scale), -3));
+		--size-xsmall: calc(var(--size) * pow(var(--size-scale), -2));
+		--size-small: calc(var(--size) * pow(var(--size-scale), -1));
+		--size-normal: calc(var(--size) * pow(var(--size-scale), 0));
+		--size-large: calc(var(--size) * pow(var(--size-scale), 1));
+		--size-xlarge: calc(var(--size) * pow(var(--size-scale), 2));
+		--size-xxlarge: calc(var(--size) * pow(var(--size-scale), 3));
+		--size-xxxlarge: calc(var(--size) * pow(var(--size-scale), 4));
+
+		/* Semantic sizes */
+		--size-icon: var(--size-large);
+		--size-label: var(--size-small);
+
+		/* Relative sizes */
+		--size-smaller: 0.875em;
+		--size-larger: 1.5em;
+		--size-xlarger: 2.5em;
+		--size-xxlarger: 5em;
+
+		/* Line heights */
+		--leading: clamp(1.05em, calc(1em + 0.5rem), 1.5em);
+		--leading-normal: 1.5;
+	}
+
+	/* Baseline body size so a page with no `<Layout>` still reads correctly. */
+	body {
+		font-size: var(--size-normal);
+		line-height: var(--leading);
+	}
+}
+
+@layer variants {
+	/* Font-size variants. */
+	.xxsmall {
+		font-size: var(--size-xxsmall);
+		line-height: var(--leading);
+	}
+	.xsmall {
+		font-size: var(--size-xsmall);
+		line-height: var(--leading);
+	}
+	.small {
+		font-size: var(--size-small);
+		line-height: var(--leading);
+	}
+	.normal {
+		font-size: var(--size-normal);
+		line-height: var(--leading);
+	}
+	.large {
+		font-size: var(--size-large);
+		line-height: var(--leading);
+	}
+	.xlarge {
+		font-size: var(--size-xlarge);
+		line-height: var(--leading);
+	}
+	.xxlarge {
+		font-size: var(--size-xxlarge);
+		line-height: var(--leading);
+	}
+}

package/ui/style/Size.tsx

@@ -0,0 +1,31 @@
+import { getModuleClass } from "../util/css.js";
+import SIZE_CSS from "./Size.module.css";
+
+/**
+ * Enumerated font-size scale selectable via the `size` variant prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Size/UISize
+ */
+export type UISize = "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge";
+
+/**
+ * Variant props for the font size of an element, e.g. `size="large"`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Size/SizeVariants
+ */
+export interface SizeVariants {
+	/** Font size of the element. */
+	size?: UISize | undefined;
+}
+
+/**
+ * Get the font-size class for a component from its `size` variant prop.
+ *
+ * @param variants Variant props containing the optional `size` scale.
+ * @returns The size class string, or `undefined` when no `size` is set.
+ * @example getSizeClass({ size: "large" }) // "large"
+ * @see https://dhoulb.github.io/shelving/ui/style/Size/getSizeClass
+ */
+export function getSizeClass({ size }: SizeVariants): string | undefined {
+	return size && getModuleClass(SIZE_CSS, size);
+}

package/ui/style/Space.module.css

@@ -1,4 +1,22 @@
-@import "base.css";
+@import "layers.css";
+
+@layer defaults {
+	:root {
+		/* Spacings */
+		--space: 1rem;
+		--space-xxsmall: calc(var(--space) * 0.25); /* 4px */
+		--space-xsmall: calc(var(--space) * 0.5); /* 8px */
+		--space-small: calc(var(--space) * 0.75); /* 12px */
+		--space-normal: calc(var(--space) * 1); /* 16px */
+		--space-large: calc(var(--space) * 1.5); /* 24px */
+		--space-xlarge: calc(var(--space) * 2); /* 32px */
+		--space-xxlarge: calc(var(--space) * 3); /* 48px */
+
+		/* Semantic spacings */
+		--space-section: 2rem; /* Default top margin for titles/headings/section blocks. */
+		--space-paragraph: var(--space-normal); /* Default block-space for most prose-level elements. */
+	}
+}
 
 @layer variants {
 	/* Block-space variants — opt-in margin-block modifiers for any block-level component. */

package/ui/style/Status.module.css

@@ -1,4 +1,5 @@
-@import "base.css";
+@import "layers.css";
+@import "Color.module.css";
 @import "Tint.module.css";
 
 /* Status variant classes go in `@layer variants` — always beat component rules.

package/ui/style/Stroke.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Enumerated border-thickness names selectable via the `stroke` variant prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Stroke/UIStroke
+ */
+export type UIStroke = "normal" | "thick";
+/**
+ * Variant props for the border thickness of an element, e.g. `stroke="thick"`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Stroke/StrokeVariants
+ */
+export interface StrokeVariants {
+    /** Border thickness of the element. */
+    stroke?: UIStroke | undefined;
+}
+/**
+ * Get the border-thickness class for a component from its `stroke` variant prop.
+ *
+ * @param variants Variant props containing the optional `stroke` name.
+ * @returns The stroke class string, or `undefined` when no `stroke` is set.
+ * @example getStrokeClass({ stroke: "thick" }) // "stroke-thick"
+ * @see https://dhoulb.github.io/shelving/ui/style/Stroke/getStrokeClass
+ */
+export declare function getStrokeClass({ stroke }: StrokeVariants): string | undefined;

package/ui/style/Stroke.js

@@ -0,0 +1,13 @@
+import { getModuleClass } from "../util/css.js";
+import STROKE_CSS from "./Stroke.module.css";
+/**
+ * Get the border-thickness class for a component from its `stroke` variant prop.
+ *
+ * @param variants Variant props containing the optional `stroke` name.
+ * @returns The stroke class string, or `undefined` when no `stroke` is set.
+ * @example getStrokeClass({ stroke: "thick" }) // "stroke-thick"
+ * @see https://dhoulb.github.io/shelving/ui/style/Stroke/getStrokeClass
+ */
+export function getStrokeClass({ stroke }) {
+    return stroke && getModuleClass(STROKE_CSS, `stroke-${stroke}`);
+}

package/ui/style/Stroke.module.css

@@ -0,0 +1,26 @@
+@import "layers.css";
+
+@layer defaults {
+	:root {
+		/* Strokes — border thicknesses. Components hard-code to these and expose per-component
+		 * `--x-border` / `--x-stroke` hooks to override. */
+		--stroke: 2px;
+		--stroke-normal: calc(var(--stroke) * 1);
+		--stroke-thick: calc(var(--stroke) * 1.5);
+
+		/* Semantic strokes */
+		--stroke-focus: var(--stroke-thick);
+	}
+}
+
+@layer variants {
+	/* Border-thickness variants. */
+	.stroke-normal {
+		border-style: solid;
+		border-width: var(--stroke-normal);
+	}
+	.stroke-thick {
+		border-style: solid;
+		border-width: var(--stroke-thick);
+	}
+}

package/ui/style/Stroke.tsx

@@ -0,0 +1,31 @@
+import { getModuleClass } from "../util/css.js";
+import STROKE_CSS from "./Stroke.module.css";
+
+/**
+ * Enumerated border-thickness names selectable via the `stroke` variant prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Stroke/UIStroke
+ */
+export type UIStroke = "normal" | "thick";
+
+/**
+ * Variant props for the border thickness of an element, e.g. `stroke="thick"`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Stroke/StrokeVariants
+ */
+export interface StrokeVariants {
+	/** Border thickness of the element. */
+	stroke?: UIStroke | undefined;
+}
+
+/**
+ * Get the border-thickness class for a component from its `stroke` variant prop.
+ *
+ * @param variants Variant props containing the optional `stroke` name.
+ * @returns The stroke class string, or `undefined` when no `stroke` is set.
+ * @example getStrokeClass({ stroke: "thick" }) // "stroke-thick"
+ * @see https://dhoulb.github.io/shelving/ui/style/Stroke/getStrokeClass
+ */
+export function getStrokeClass({ stroke }: StrokeVariants): string | undefined {
+	return stroke && getModuleClass(STROKE_CSS, `stroke-${stroke}`);
+}

package/ui/style/Tint.module.css

@@ -1,6 +1,9 @@
+@import "layers.css";
+
 @layer defaults {
 	:root {
-		/* Main tint color — the `50` tint is used to calculate all the other shades. */
+		/* Main tint color — the `50` tint is used to calculate all the other shades.
+		 * Defaults to `--color-gray` (defined in Color.module.css), resolved at use-time. */
 		--tint-50: var(--color-gray);
 	}
 

package/ui/style/Typography.d.ts

@@ -1,21 +1,6 @@
-/**
- * Enumerated font-size scale selectable via the `size` variant prop.
- *
- * @see https://dhoulb.github.io/shelving/ui/style/Typography/UISize
- */
-export type UISize = "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge";
-/**
- * Enumerated font-family names selectable via the `font` variant prop.
- *
- * @see https://dhoulb.github.io/shelving/ui/style/Typography/UIFont
- */
-export type UIFont = "title" | "body" | "label" | "code" | "serif" | "sans" | "monospace";
-/**
- * Enumerated font-weight names selectable via the `weight` variant prop.
- *
- * @see https://dhoulb.github.io/shelving/ui/style/Typography/UIWeight
- */
-export type UIWeight = "title" | "body" | "label" | "code" | "normal" | "strong";
+import { type FontVariants } from "./Font.js";
+import { type SizeVariants } from "./Size.js";
+import { type WeightVariants } from "./Weight.js";
 /**
  * Enumerated tint shades selectable via the `tint` variant prop — shades of the current tint colour from `"00"` (black) through `"50"` (the hue itself) to `"100"` (white).
  *
@@ -38,24 +23,23 @@ export type AlignVariants = {
 /**
  * Typographic variant props — font-family, weight, alignment, size, and tint.
  *
+ * Combines the focused {@link SizeVariants}, {@link WeightVariants}, and {@link FontVariants} interfaces (each backed
+ * by its own CSS module) with text alignment and tint colour.
+ *
  * @see https://dhoulb.github.io/shelving/ui/style/Typography/TypographyVariants
  */
-export interface TypographyVariants extends AlignVariants {
-    /** Font family. */
-    font?: UIFont | undefined;
-    /** Font weight */
-    weight?: UIWeight | undefined;
-    /** Font size of the element. */
-    size?: UISize | undefined;
+export interface TypographyVariants extends AlignVariants, SizeVariants, WeightVariants, FontVariants {
     /** Set CSS text `color:` to one of the shades of the current tint colour (defaults to gray). */
     tint?: UITint | undefined;
 }
 /**
  * Get the typography class for a component from its typographic variant props.
  *
+ * Composes the focused size, weight, and font helpers with text alignment and tint colour.
+ *
  * @param props Typographic variant props (font, weight, size, tint, alignment).
  * @returns The combined typography class string, or `undefined` when no variants apply.
  * @example getTypographyClass({ font: "title", size: "large", center: true })
  * @see https://dhoulb.github.io/shelving/ui/style/Typography/getTypographyClass
  */
-export declare function getTypographyClass({ tint, size, font, weight, ...props }: TypographyVariants): string | undefined;
+export declare function getTypographyClass({ tint, ...props }: TypographyVariants): string | undefined;

package/ui/style/Typography.js

@@ -1,13 +1,18 @@
-import { getModuleClass } from "../util/css.js";
+import { getClass, getModuleClass } from "../util/css.js";
+import { getFontClass } from "./Font.js";
+import { getSizeClass } from "./Size.js";
 import TYPOGRAPHY_CSS from "./Typography.module.css";
+import { getWeightClass } from "./Weight.js";
 /**
  * Get the typography class for a component from its typographic variant props.
  *
+ * Composes the focused size, weight, and font helpers with text alignment and tint colour.
+ *
  * @param props Typographic variant props (font, weight, size, tint, alignment).
  * @returns The combined typography class string, or `undefined` when no variants apply.
  * @example getTypographyClass({ font: "title", size: "large", center: true })
  * @see https://dhoulb.github.io/shelving/ui/style/Typography/getTypographyClass
  */
-export function getTypographyClass({ tint, size, font, weight, ...props }) {
-    return getModuleClass(TYPOGRAPHY_CSS, tint && `tint-${tint}`, weight && `weight-${weight}`, size, font, props);
+export function getTypographyClass({ tint, ...props }) {
+    return getClass(getSizeClass(props), getWeightClass(props), getFontClass(props), getModuleClass(TYPOGRAPHY_CSS, tint && `tint-${tint}`, props));
 }

package/ui/style/Typography.module.css

@@ -1,72 +1,8 @@
-@import "base.css";
+@import "layers.css";
 @import "Tint.module.css";
 
 @layer variants {
-	/* Font-family variants. */
-	.title {
-		font-family: var(--font-heading);
-	}
-	.body {
-		font-family: var(--font-body);
-	}
-	.code {
-		font-family: var(--font-code);
-	}
-	.label {
-		font-family: var(--font-code);
-	}
-
-	/* Font weight variants. */
-	.weight-title {
-		font-weight: var(--weight-heading);
-	}
-	.weight-body {
-		font-weight: var(--weight-body);
-	}
-	.weight-code {
-		font-weight: var(--weight-code);
-	}
-	.weight-label {
-		font-weight: var(--weight-code);
-	}
-	.weight-normal {
-		font-weight: var(--weight-normal);
-	}
-	.weight-strong {
-		font-weight: var(--weight-strong);
-	}
-
-	/* Font-size variants. */
-	.xxsmall {
-		font-size: var(--size-xxsmall);
-		line-height: var(--leading);
-	}
-	.xsmall {
-		font-size: var(--size-xsmall);
-		line-height: var(--leading);
-	}
-	.small {
-		font-size: var(--size-small);
-		line-height: var(--leading);
-	}
-	.normal {
-		font-size: var(--size-normal);
-		line-height: var(--leading);
-	}
-	.large {
-		font-size: var(--size-large);
-		line-height: var(--leading);
-	}
-	.xlarge {
-		font-size: var(--size-xlarge);
-		line-height: var(--leading);
-	}
-	.xxlarge {
-		font-size: var(--size-xxlarge);
-		line-height: var(--leading);
-	}
-
-	/* Text tint variants */
+	/* Text tint variants — set CSS `color:` to a shade of the current tint ladder. */
 	.tint-00 {
 		color: var(--tint-00);
 	}

package/ui/style/Typography.tsx

@@ -1,26 +1,8 @@
-import { getModuleClass } from "../util/css.js";
+import { getClass, getModuleClass } from "../util/css.js";
+import { type FontVariants, getFontClass } from "./Font.js";
+import { getSizeClass, type SizeVariants } from "./Size.js";
 import TYPOGRAPHY_CSS from "./Typography.module.css";
-
-/**
- * Enumerated font-size scale selectable via the `size` variant prop.
- *
- * @see https://dhoulb.github.io/shelving/ui/style/Typography/UISize
- */
-export type UISize = "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge";
-
-/**
- * Enumerated font-family names selectable via the `font` variant prop.
- *
- * @see https://dhoulb.github.io/shelving/ui/style/Typography/UIFont
- */
-export type UIFont = "title" | "body" | "label" | "code" | "serif" | "sans" | "monospace";
-
-/**
- * Enumerated font-weight names selectable via the `weight` variant prop.
- *
- * @see https://dhoulb.github.io/shelving/ui/style/Typography/UIWeight
- */
-export type UIWeight = "title" | "body" | "label" | "code" | "normal" | "strong";
+import { getWeightClass, type WeightVariants } from "./Weight.js";
 
 /**
  * Enumerated tint shades selectable via the `tint` variant prop — shades of the current tint colour from `"00"` (black) through `"50"` (the hue itself) to `"100"` (white).
@@ -67,15 +49,12 @@ export type AlignVariants = {
 /**
  * Typographic variant props — font-family, weight, alignment, size, and tint.
  *
+ * Combines the focused {@link SizeVariants}, {@link WeightVariants}, and {@link FontVariants} interfaces (each backed
+ * by its own CSS module) with text alignment and tint colour.
+ *
  * @see https://dhoulb.github.io/shelving/ui/style/Typography/TypographyVariants
  */
-export interface TypographyVariants extends AlignVariants {
-	/** Font family. */
-	font?: UIFont | undefined;
-	/** Font weight */
-	weight?: UIWeight | undefined;
-	/** Font size of the element. */
-	size?: UISize | undefined;
+export interface TypographyVariants extends AlignVariants, SizeVariants, WeightVariants, FontVariants {
 	/** Set CSS text `color:` to one of the shades of the current tint colour (defaults to gray). */
 	tint?: UITint | undefined;
 }
@@ -83,11 +62,18 @@ export interface TypographyVariants extends AlignVariants {
 /**
  * Get the typography class for a component from its typographic variant props.
  *
+ * Composes the focused size, weight, and font helpers with text alignment and tint colour.
+ *
  * @param props Typographic variant props (font, weight, size, tint, alignment).
  * @returns The combined typography class string, or `undefined` when no variants apply.
  * @example getTypographyClass({ font: "title", size: "large", center: true })
  * @see https://dhoulb.github.io/shelving/ui/style/Typography/getTypographyClass
  */
-export function getTypographyClass({ tint, size, font, weight, ...props }: TypographyVariants): string | undefined {
-	return getModuleClass(TYPOGRAPHY_CSS, tint && `tint-${tint}`, weight && `weight-${weight}`, size, font, props);
+export function getTypographyClass({ tint, ...props }: TypographyVariants): string | undefined {
+	return getClass(
+		getSizeClass(props),
+		getWeightClass(props),
+		getFontClass(props),
+		getModuleClass(TYPOGRAPHY_CSS, tint && `tint-${tint}`, props),
+	);
 }

package/ui/style/Weight.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Enumerated font-weight names selectable via the `weight` variant prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Weight/UIWeight
+ */
+export type UIWeight = "title" | "body" | "label" | "code" | "normal" | "strong";
+/**
+ * Variant props for the font weight of an element, e.g. `weight="strong"`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Weight/WeightVariants
+ */
+export interface WeightVariants {
+    /** Font weight of the element. */
+    weight?: UIWeight | undefined;
+}
+/**
+ * Get the font-weight class for a component from its `weight` variant prop.
+ *
+ * @param variants Variant props containing the optional `weight` name.
+ * @returns The weight class string, or `undefined` when no `weight` is set.
+ * @example getWeightClass({ weight: "strong" }) // "weight-strong"
+ * @see https://dhoulb.github.io/shelving/ui/style/Weight/getWeightClass
+ */
+export declare function getWeightClass({ weight }: WeightVariants): string | undefined;

package/ui/style/Weight.js

@@ -0,0 +1,13 @@
+import { getModuleClass } from "../util/css.js";
+import WEIGHT_CSS from "./Weight.module.css";
+/**
+ * Get the font-weight class for a component from its `weight` variant prop.
+ *
+ * @param variants Variant props containing the optional `weight` name.
+ * @returns The weight class string, or `undefined` when no `weight` is set.
+ * @example getWeightClass({ weight: "strong" }) // "weight-strong"
+ * @see https://dhoulb.github.io/shelving/ui/style/Weight/getWeightClass
+ */
+export function getWeightClass({ weight }) {
+    return weight && getModuleClass(WEIGHT_CSS, `weight-${weight}`);
+}

package/ui/style/Weight.module.css

@@ -0,0 +1,42 @@
+@import "layers.css";
+
+@layer defaults {
+	:root {
+		/* Font weights */
+		--weight-normal: 400;
+		--weight-strong: 700;
+
+		/* Semantic font weights */
+		--weight-title: var(--weight-strong);
+		--weight-body: var(--weight-normal);
+		--weight-label: var(--weight-strong);
+		--weight-code: 500;
+	}
+
+	/* Baseline body weight so a page with no `<Layout>` still reads correctly. */
+	body {
+		font-weight: var(--weight-body);
+	}
+}
+
+@layer variants {
+	/* Font-weight variants. */
+	.weight-title {
+		font-weight: var(--weight-title);
+	}
+	.weight-body {
+		font-weight: var(--weight-body);
+	}
+	.weight-code {
+		font-weight: var(--weight-code);
+	}
+	.weight-label {
+		font-weight: var(--weight-label);
+	}
+	.weight-normal {
+		font-weight: var(--weight-normal);
+	}
+	.weight-strong {
+		font-weight: var(--weight-strong);
+	}
+}

package/ui/style/Weight.tsx

@@ -0,0 +1,31 @@
+import { getModuleClass } from "../util/css.js";
+import WEIGHT_CSS from "./Weight.module.css";
+
+/**
+ * Enumerated font-weight names selectable via the `weight` variant prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Weight/UIWeight
+ */
+export type UIWeight = "title" | "body" | "label" | "code" | "normal" | "strong";
+
+/**
+ * Variant props for the font weight of an element, e.g. `weight="strong"`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/style/Weight/WeightVariants
+ */
+export interface WeightVariants {
+	/** Font weight of the element. */
+	weight?: UIWeight | undefined;
+}
+
+/**
+ * Get the font-weight class for a component from its `weight` variant prop.
+ *
+ * @param variants Variant props containing the optional `weight` name.
+ * @returns The weight class string, or `undefined` when no `weight` is set.
+ * @example getWeightClass({ weight: "strong" }) // "weight-strong"
+ * @see https://dhoulb.github.io/shelving/ui/style/Weight/getWeightClass
+ */
+export function getWeightClass({ weight }: WeightVariants): string | undefined {
+	return weight && getModuleClass(WEIGHT_CSS, `weight-${weight}`);
+}

package/ui/style/Width.module.css

@@ -1,6 +1,12 @@
-@import "base.css";
+@import "layers.css";
 
 @layer defaults {
+	:root {
+		/* Semantic widths */
+		--width-narrow: 22.5rem;
+		--width-wide: 33.75rem;
+	}
+
 	.narrow,
 	.wide,
 	.full,

package/ui/style/getColorClass.md

@@ -0,0 +1,47 @@
+# getColorClass
+
+The `color` variant prop moves the [tint ladder](/ui/TINT_CLASS) anchor to a named palette colour — `<Card color="red">`, `<Tag color="primary">`. It's an **override** for one-off recolouring of a component in a page; for an app-wide look, override the palette variables below in a theme file instead.
+
+`getColorClass({ color })` returns `getClass(TINT_CLASS, "<colour>")` — it moves `--tint-50` to the chosen colour and recomposes the ladder, so the whole subtree retints. See [`TINT_CLASS`](/ui/TINT_CLASS) for how the ladder works.
+
+## Theme variables
+
+The following `:root` variables are defined by this module and can be overridden in a theme file to adjust default styling across the whole app. Override a palette colour to re-aim every variant and status that maps to it.
+
+### Palette
+
+| Variable | Default | Notes |
+|---|---|---|
+| `--color-gray` | `oklch(60% 0.01 240)` | Neutral anchor — also the default tint when nothing moves it. |
+| `--color-red` | `oklch(62% 0.2 30)` | |
+| `--color-orange` | `oklch(74% 0.157 60)` | |
+| `--color-yellow` | `oklch(86% 0.16 92)` | |
+| `--color-green` | `oklch(72% 0.185 130)` | |
+| `--color-aqua` | `oklch(72% 0.121 185)` | |
+| `--color-blue` | `oklch(57% 0.216 260)` | |
+| `--color-purple` | `oklch(58% 0.25 300)` | |
+| `--color-pink` | `oklch(68% 0.239 350)` | |
+
+### Semantic
+
+| Variable | Default | Used for |
+|---|---|---|
+| `--color-link` | `var(--color-blue)` | Link colour. |
+| `--color-focus` | `var(--color-blue)` | Focus outlines. |
+| `--color-success` | `var(--color-green)` | `status="success"`. |
+| `--color-warning` | `var(--color-orange)` | `status="warning"`. |
+| `--color-failure` | `var(--color-red)` | `status="error"` / `status="danger"`. |
+
+### Brand
+
+| Variable | Default | Used for |
+|---|---|---|
+| `--color-primary` | `var(--color-blue)` | `color="primary"`. |
+| `--color-secondary` | `var(--color-purple)` | `color="secondary"`. |
+| `--color-tertiary` | `var(--color-pink)` | `color="tertiary"`. |
+
+## See also
+
+- [`TINT_CLASS`](/ui/TINT_CLASS) — the tint ladder these colours feed, and the full theming guide.
+- [`getStatusClass`](/ui/getStatusClass) — the semantic-status sibling of `color`.
+- [`ui`](/ui) — the styling-system overview and the full list of base token pages.

package/ui/style/getDurationClass.md

@@ -0,0 +1,18 @@
+# getDurationClass
+
+This module's main job is to **define and document the transition/animation timing tokens**. Components and [transitions](/ui/Transition) read these tokens directly; `getDurationClass({ duration })` exists as a utility (e.g. `duration="fast"` → `duration-fast`) and as the home for this documentation.
+
+## Theme variables
+
+The following `:root` variables are defined by this module and can be overridden in a theme file to adjust default styling across the whole app.
+
+| Variable | Default | Used for |
+|---|---|---|
+| `--duration-fast` | `150ms` | Snappy UI feedback — hovers, small toggles. |
+| `--duration-normal` | `300ms` | Default transitions. |
+| `--duration-slow` | `600ms` | Deliberate, large movements. |
+
+## See also
+
+- [`Transition`](/ui/Transition) — the enter/leave animation component that reads these.
+- [`ui`](/ui) — the styling-system overview and the full list of base token pages.