@cueplusplus/ui 0.1.0

package/dist/system/use-theme.js

@@ -0,0 +1,25 @@
+"use client";
+import { ThemeContext } from "./theme-provider.js";
+import * as React from "react";
+//#region src/system/use-theme.ts
+/**
+* Read and drive the ambient theme state.
+*
+* Returns `{ theme, density, mode, resolvedMode, setTheme, setDensity, setMode }`.
+* `density` here is the *provider's* level — a nested `<Density>` island does not
+* change it; use `useDensity()` when you want the level that actually applies
+* where you are.
+*
+* @throws If called outside a `<ThemeProvider>`. Theme state is never guessed:
+*   a missing provider is a wiring bug, not a fallback situation.
+* @example
+* const { resolvedMode, setMode } = useTheme();
+* <Switch checked={resolvedMode === "light"} onCheckedChange={(on) => setMode(on ? "light" : "dark")} />
+*/
+function useTheme() {
+	const context = React.useContext(ThemeContext);
+	if (context === null) throw new Error("useTheme() must be called inside a <ThemeProvider>.");
+	return context;
+}
+//#endregion
+export { useTheme };

package/dist/theming/_presets.d.ts

@@ -0,0 +1,11 @@
+import { Density, ThemeName } from "@cueplusplus/tokens";
+//#region src/theming/_presets.d.ts
+/**
+ * The colour tokens every theme block declares, in the order the tokens build
+ * emits them. A generated theme is complete exactly when it covers this list.
+ */
+declare const THEME_COLOR_TOKENS: readonly ["bg", "sunken", "surface-1", "surface-2", "surface-3", "fg", "fg-muted", "fg-subtle", "border", "border-strong", "border-overlay", "accent", "accent-hover", "accent-fg", "ok", "busy", "warn", "danger", "info", "selection", "focus", "data-ground", "scrim"];
+/** One of the colour tokens a theme block owns. */
+type ThemeColorToken = (typeof THEME_COLOR_TOKENS)[number];
+//#endregion
+export { THEME_COLOR_TOKENS, ThemeColorToken };

package/dist/theming/_presets.js

@@ -0,0 +1,487 @@
+//#region src/theming/_presets.ts
+/**
+* The colour tokens every theme block declares, in the order the tokens build
+* emits them. A generated theme is complete exactly when it covers this list.
+*/
+const THEME_COLOR_TOKENS = [
+	"bg",
+	"sunken",
+	"surface-1",
+	"surface-2",
+	"surface-3",
+	"fg",
+	"fg-muted",
+	"fg-subtle",
+	"border",
+	"border-strong",
+	"border-overlay",
+	"accent",
+	"accent-hover",
+	"accent-fg",
+	"ok",
+	"busy",
+	"warn",
+	"danger",
+	"info",
+	"selection",
+	"focus",
+	"data-ground",
+	"scrim"
+];
+/** The shipped presets, keyed by name. */
+const THEME_PRESETS = {
+	cue: {
+		dark: {
+			"bg": "#0a0a0a",
+			"sunken": "#000000",
+			"surface-1": "#121212",
+			"surface-2": "#1a1a1a",
+			"surface-3": "#242424",
+			"fg": "#f5f5f7",
+			"fg-muted": "rgba(255,255,255,0.55)",
+			"fg-subtle": "rgba(255,255,255,0.35)",
+			"border": "rgba(255,255,255,0.10)",
+			"border-strong": "rgba(255,255,255,0.25)",
+			"border-overlay": "rgba(255,255,255,0.25)",
+			"accent": "#ffffff",
+			"accent-hover": "rgba(255,255,255,0.85)",
+			"accent-fg": "#0a0a0a",
+			"ok": "#ffffff",
+			"busy": "#ffffff",
+			"warn": "#ffffff",
+			"danger": "#ff5f57",
+			"info": "#ffffff",
+			"selection": "rgba(255,255,255,0.20)",
+			"focus": "#ffffff",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		light: {
+			"bg": "#fcfcfc",
+			"sunken": "#f0f0f0",
+			"surface-1": "#ffffff",
+			"surface-2": "#f6f6f6",
+			"surface-3": "#ededed",
+			"fg": "#0a0a0a",
+			"fg-muted": "rgba(0,0,0,0.55)",
+			"fg-subtle": "rgba(0,0,0,0.35)",
+			"border": "rgba(0,0,0,0.10)",
+			"border-strong": "rgba(0,0,0,0.25)",
+			"border-overlay": "rgba(0,0,0,0.25)",
+			"accent": "#0a0a0a",
+			"accent-hover": "rgba(0,0,0,0.85)",
+			"accent-fg": "#fcfcfc",
+			"ok": "#0a0a0a",
+			"busy": "#0a0a0a",
+			"warn": "#0a0a0a",
+			"danger": "#d03030",
+			"info": "#0a0a0a",
+			"selection": "rgba(0,0,0,0.20)",
+			"focus": "#0a0a0a",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		fonts: { "font-mono": "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
+	},
+	terminal: {
+		dark: {
+			"bg": "hsl(240 10% 6%)",
+			"sunken": "hsl(240 12% 4%)",
+			"surface-1": "hsl(240 8% 9%)",
+			"surface-2": "hsl(240 6% 14%)",
+			"surface-3": "hsl(240 6% 16%)",
+			"fg": "hsl(240 5% 96%)",
+			"fg-muted": "hsl(240 4% 56%)",
+			"fg-subtle": "hsl(240 4% 40%)",
+			"border": "hsl(240 6% 18%)",
+			"border-strong": "hsl(240 6% 26%)",
+			"border-overlay": "hsl(240 6% 26%)",
+			"accent": "hsl(180 100% 50%)",
+			"accent-hover": "hsl(180 100% 42%)",
+			"accent-fg": "hsl(240 10% 6%)",
+			"ok": "hsl(142 76% 50%)",
+			"busy": "hsl(180 100% 50%)",
+			"warn": "hsl(38 100% 55%)",
+			"danger": "hsl(0 72% 51%)",
+			"info": "hsl(180 100% 50%)",
+			"selection": "hsl(180 100% 50% / 0.25)",
+			"focus": "hsl(180 100% 50%)",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		light: {
+			"bg": "hsl(0 0% 99%)",
+			"sunken": "hsl(240 5% 92%)",
+			"surface-1": "#ffffff",
+			"surface-2": "hsl(240 5% 96%)",
+			"surface-3": "hsl(240 5% 94%)",
+			"fg": "hsl(240 6% 10%)",
+			"fg-muted": "hsl(240 4% 46%)",
+			"fg-subtle": "hsl(240 4% 60%)",
+			"border": "hsl(240 6% 90%)",
+			"border-strong": "hsl(240 6% 80%)",
+			"border-overlay": "hsl(240 6% 80%)",
+			"accent": "hsl(240 6% 10%)",
+			"accent-hover": "hsl(240 6% 22%)",
+			"accent-fg": "hsl(0 0% 98%)",
+			"ok": "hsl(142 71% 45%)",
+			"busy": "hsl(187 100% 33%)",
+			"warn": "hsl(38 92% 50%)",
+			"danger": "hsl(0 72% 45%)",
+			"info": "hsl(187 100% 33%)",
+			"selection": "hsl(187 100% 33% / 0.18)",
+			"focus": "hsl(240 6% 10%)",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		fonts: {}
+	},
+	signal: {
+		dark: {
+			"bg": "#1a1a1a",
+			"sunken": "#141414",
+			"surface-1": "#222222",
+			"surface-2": "#2a2a2a",
+			"surface-3": "#333333",
+			"fg": "#cccccc",
+			"fg-muted": "#888888",
+			"fg-subtle": "#666666",
+			"border": "#333333",
+			"border-strong": "#3e3e3e",
+			"border-overlay": "#555555",
+			"accent": "#ff6a2e",
+			"accent-hover": "#ff8552",
+			"accent-fg": "#1a1a1a",
+			"ok": "#00cc66",
+			"busy": "#ff6a2e",
+			"warn": "#ff9500",
+			"danger": "#ff3333",
+			"info": "#3b82f6",
+			"selection": "rgba(255,106,46,0.16)",
+			"focus": "#ff6a2e",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		light: {
+			"bg": "#f5f5f5",
+			"sunken": "#ececec",
+			"surface-1": "#ffffff",
+			"surface-2": "#f0f0f0",
+			"surface-3": "#e8e8e8",
+			"fg": "#1f1f1f",
+			"fg-muted": "#5c5c5c",
+			"fg-subtle": "#8a8a8a",
+			"border": "#e0e0e0",
+			"border-strong": "#cfcfcf",
+			"border-overlay": "#b5b5b5",
+			"accent": "#d9541a",
+			"accent-hover": "#c04a17",
+			"accent-fg": "#ffffff",
+			"ok": "#009e50",
+			"busy": "#d9541a",
+			"warn": "#cc7700",
+			"danger": "#d42020",
+			"info": "#1a6fd4",
+			"selection": "rgba(217,84,26,0.18)",
+			"focus": "#d9541a",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.35)"
+		},
+		fonts: { "font-mono": "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
+	},
+	venu: {
+		dark: {
+			"bg": "hsl(0 0% 9%)",
+			"sunken": "hsl(0 0% 7%)",
+			"surface-1": "hsl(0 0% 11%)",
+			"surface-2": "hsl(0 0% 13%)",
+			"surface-3": "hsl(0 0% 15%)",
+			"fg": "hsl(240 4% 87%)",
+			"fg-muted": "hsl(0 0% 65%)",
+			"fg-subtle": "hsl(0 0% 33%)",
+			"border": "hsl(0 0% 22%)",
+			"border-strong": "hsl(0 0% 31%)",
+			"border-overlay": "hsl(0 0% 13%)",
+			"accent": "hsl(27 94% 53%)",
+			"accent-hover": "hsl(27 94% 48%)",
+			"accent-fg": "#ffffff",
+			"ok": "hsl(166 79% 38%)",
+			"busy": "hsl(27 94% 53%)",
+			"warn": "hsl(27 88% 52%)",
+			"danger": "hsl(0 87% 62%)",
+			"info": "hsl(209 89% 54%)",
+			"selection": "hsl(212 63% 23%)",
+			"focus": "hsl(27 94% 53%)",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		light: {
+			"bg": "#f5f5f5",
+			"sunken": "#e8e8e8",
+			"surface-1": "#ffffff",
+			"surface-2": "#f0f0f0",
+			"surface-3": "#e4e4e4",
+			"fg": "#17171a",
+			"fg-muted": "#555555",
+			"fg-subtle": "#999999",
+			"border": "#dcdcdc",
+			"border-strong": "#c4c4c4",
+			"border-overlay": "#e4e4e4",
+			"accent": "#e06510",
+			"accent-hover": "#c85a0e",
+			"accent-fg": "#ffffff",
+			"ok": "#0e8c70",
+			"busy": "#e06510",
+			"warn": "#c05e10",
+			"danger": "#cc2f2f",
+			"info": "#1a75d2",
+			"selection": "#cce0ff",
+			"focus": "#e06510",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.35)"
+		},
+		fonts: { "font-mono": "\"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
+	},
+	hivehub: {
+		dark: {
+			"bg": "hsl(222 47% 5%)",
+			"sunken": "hsl(222 47% 4%)",
+			"surface-1": "hsl(222 47% 8%)",
+			"surface-2": "hsl(222 47% 11%)",
+			"surface-3": "hsl(222 47% 13%)",
+			"fg": "hsl(0 0% 98%)",
+			"fg-muted": "hsl(0 0% 65%)",
+			"fg-subtle": "hsl(0 0% 45%)",
+			"border": "hsl(222 47% 15%)",
+			"border-strong": "hsl(222 47% 20%)",
+			"border-overlay": "hsl(222 47% 20%)",
+			"accent": "hsl(27 94% 53%)",
+			"accent-hover": "hsl(27 94% 48%)",
+			"accent-fg": "#ffffff",
+			"ok": "hsl(142 76% 36%)",
+			"busy": "hsl(38 92% 50%)",
+			"warn": "hsl(38 92% 50%)",
+			"danger": "hsl(0 72% 51%)",
+			"info": "hsl(221 83% 62%)",
+			"selection": "hsl(27 94% 53% / 0.2)",
+			"focus": "hsl(27 94% 53%)",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.8)"
+		},
+		light: {
+			"bg": "hsl(222 30% 97%)",
+			"sunken": "hsl(222 28% 94%)",
+			"surface-1": "#ffffff",
+			"surface-2": "hsl(222 30% 95%)",
+			"surface-3": "hsl(222 25% 92%)",
+			"fg": "hsl(222 30% 12%)",
+			"fg-muted": "hsl(222 12% 38%)",
+			"fg-subtle": "hsl(222 10% 55%)",
+			"border": "hsl(222 25% 88%)",
+			"border-strong": "hsl(222 20% 78%)",
+			"border-overlay": "hsl(222 20% 78%)",
+			"accent": "#e06510",
+			"accent-hover": "#c85a0e",
+			"accent-fg": "#ffffff",
+			"ok": "hsl(142 70% 30%)",
+			"busy": "hsl(38 92% 40%)",
+			"warn": "hsl(38 92% 40%)",
+			"danger": "#c62828",
+			"info": "#2f6fd0",
+			"selection": "rgba(224,101,16,0.15)",
+			"focus": "#e06510",
+			"data-ground": "#000000",
+			"scrim": "rgba(15,23,42,0.45)"
+		},
+		fonts: {}
+	},
+	dusk: {
+		dark: {
+			"bg": "#0C1411",
+			"sunken": "#08100D",
+			"surface-1": "#101C17",
+			"surface-2": "#15241E",
+			"surface-3": "#1a2c24",
+			"fg": "#E9EFEA",
+			"fg-muted": "#A7B3AC",
+			"fg-subtle": "#6E7D75",
+			"border": "#1E2A25",
+			"border-strong": "#2C3A33",
+			"border-overlay": "#2C3A33",
+			"accent": "#E8A33D",
+			"accent-hover": "#F2B85A",
+			"accent-fg": "#20160A",
+			"ok": "#6BBF95",
+			"busy": "#D98E4B",
+			"warn": "#D98E4B",
+			"danger": "#D9694B",
+			"info": "#5B8DEF",
+			"selection": "#1B1F16",
+			"focus": "#E8A33D",
+			"data-ground": "#000000",
+			"scrim": "rgba(4,8,6,0.62)"
+		},
+		light: {
+			"bg": "#F4F5F1",
+			"sunken": "#E9EBE3",
+			"surface-1": "#FAF8F0",
+			"surface-2": "#EDEFE8",
+			"surface-3": "#E4E7DD",
+			"fg": "#14201B",
+			"fg-muted": "#46554D",
+			"fg-subtle": "#76837B",
+			"border": "#DEE1D7",
+			"border-strong": "#C3CABD",
+			"border-overlay": "#C3CABD",
+			"accent": "#9A6516",
+			"accent-hover": "#7E5210",
+			"accent-fg": "#FFFDF7",
+			"ok": "#2C7D55",
+			"busy": "#96591D",
+			"warn": "#96591D",
+			"danger": "#A23C22",
+			"info": "#2563EB",
+			"selection": "rgba(154,101,22,0.18)",
+			"focus": "#9A6516",
+			"data-ground": "#000000",
+			"scrim": "rgba(4,8,6,0.62)"
+		},
+		fonts: { "font-mono": "\"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
+	},
+	luma: {
+		dark: {
+			"bg": "#181818",
+			"sunken": "#111111",
+			"surface-1": "#1d1d1d",
+			"surface-2": "#212121",
+			"surface-3": "#2a2a2a",
+			"fg": "#d6d6dd",
+			"fg-muted": "#a6a6a6",
+			"fg-subtle": "#535353",
+			"border": "#2a2a2a",
+			"border-strong": "#383838",
+			"border-overlay": "#383838",
+			"accent": "#edbd6a",
+			"accent-hover": "#d9a850",
+			"accent-fg": "#181818",
+			"ok": "#15ac91",
+			"busy": "#edbd6a",
+			"warn": "#ea7620",
+			"danger": "#f14c4c",
+			"info": "#228df2",
+			"selection": "rgba(237,189,106,0.22)",
+			"focus": "#edbd6a",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		light: {
+			"bg": "#f5f5f5",
+			"sunken": "#e0e0e0",
+			"surface-1": "#ffffff",
+			"surface-2": "#f0f0f0",
+			"surface-3": "#e8e8e8",
+			"fg": "#1a1a1a",
+			"fg-muted": "#555555",
+			"fg-subtle": "#999999",
+			"border": "#e0e0e0",
+			"border-strong": "#cccccc",
+			"border-overlay": "#999999",
+			"accent": "#b8862f",
+			"accent-hover": "#9c7226",
+			"accent-fg": "#ffffff",
+			"ok": "#0e8c70",
+			"busy": "#b8862f",
+			"warn": "#d06a10",
+			"danger": "#d03030",
+			"info": "#1a75d2",
+			"selection": "rgba(184,134,47,0.20)",
+			"focus": "#b8862f",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		fonts: { "font-mono": "\"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
+	},
+	snuffle: {
+		dark: {
+			"bg": "#1a1a1a",
+			"sunken": "#141414",
+			"surface-1": "#202020",
+			"surface-2": "#262626",
+			"surface-3": "#2b2b2b",
+			"fg": "#cccccc",
+			"fg-muted": "#8a8a8a",
+			"fg-subtle": "#6f6f6f",
+			"border": "#333333",
+			"border-strong": "#8a8a8a",
+			"border-overlay": "#333333",
+			"accent": "#e0568a",
+			"accent-hover": "#e97aa2",
+			"accent-fg": "#1a1a1a",
+			"ok": "#7bc47f",
+			"busy": "#e6c53a",
+			"warn": "#e6c53a",
+			"danger": "#e0563b",
+			"info": "#5ac8fa",
+			"selection": "#e0568a",
+			"focus": "#e0568a",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.55)"
+		},
+		light: {
+			"bg": "#f6f6f6",
+			"sunken": "#ededed",
+			"surface-1": "#ffffff",
+			"surface-2": "#f0f0f0",
+			"surface-3": "#e9e9e9",
+			"fg": "#262626",
+			"fg-muted": "#6b6b6b",
+			"fg-subtle": "#999999",
+			"border": "#dddddd",
+			"border-strong": "#bdbdbd",
+			"border-overlay": "#dddddd",
+			"accent": "#b83560",
+			"accent-hover": "#9c2c51",
+			"accent-fg": "#ffffff",
+			"ok": "#3d8b41",
+			"busy": "#8f7a14",
+			"warn": "#8f7a14",
+			"danger": "#b8402b",
+			"info": "#157fb3",
+			"selection": "rgba(184,53,96,0.18)",
+			"focus": "#b83560",
+			"data-ground": "#000000",
+			"scrim": "rgba(0,0,0,0.35)"
+		},
+		fonts: { "font-mono": "\"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" }
+	}
+};
+/**
+* The base type stacks, restated by a theme block when the preset overrides
+* nothing — a theme block has no more specificity than the `:root` defaults it
+* has to beat, and `:root` carries the *default* theme's font override. A silent
+* theme would inherit cue's JetBrains Mono instead of the base stack, so every
+* block says what it owns. Mirrors `build.mjs`'s `THEME_FONTS` handling.
+*/
+const BASE_FONT_STACKS = {
+	"font-sans": "Geist, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", \"Helvetica Neue\", sans-serif",
+	"font-mono": "ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
+	"font-display": "Geist, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif"
+};
+/**
+* The radius multiplier each density level contributes.
+*
+* Geometry belongs to the density axis, so a theme that wants rounder corners
+* cannot simply declare `--cue-radius-scale`: its block would outrank the density
+* block and freeze ultra-compact's 0.75 at 1. {@link createTheme} instead
+* multiplies the two and emits one crossed rule per density that differs from the
+* default — which is why this ladder has to be known here.
+*/
+const DENSITY_RADIUS_SCALE = {
+	"ultra-compact": .75,
+	"normal": 1,
+	"large": 1
+};
+/** The default density, whose radius scale the uncrossed theme block carries. */
+const DEFAULT_DENSITY_LEVEL = "normal";
+//#endregion
+export { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, THEME_COLOR_TOKENS, THEME_PRESETS };

package/dist/theming/contrast.d.ts

@@ -0,0 +1,110 @@
+//#region src/theming/contrast.d.ts
+/** Non-text and large-text AA: UI components, graphics, status dots. */
+declare const WCAG_AA_NON_TEXT = 3;
+/** Body-text AA. The floor for anything a reader is expected to read. */
+declare const WCAG_AA_TEXT = 4.5;
+/** Body-text AAA. What this portfolio holds its primary ink to. */
+declare const WCAG_AAA_TEXT = 7;
+/**
+ * WCAG relative luminance: 0 for black, 1 for white.
+ *
+ * Alpha is ignored — a translucent colour has no luminance of its own, only one
+ * in front of something. {@link contrastRatio} is where that composite happens.
+ *
+ * @param color - Any CSS colour string.
+ * @returns Relative luminance in `[0, 1]`.
+ * @throws TypeError if the value is not a colour.
+ * @example
+ * relativeLuminance("#767676"); // → 0.1845…
+ */
+declare function relativeLuminance(color: string): number;
+/**
+ * WCAG contrast ratio between two colours, from 1:1 to 21:1.
+ *
+ * Symmetric, because a ratio has no direction — the arguments are named for
+ * readability, not for order. A **translucent foreground is composited over the
+ * background first**, which is not decoration: half this system's `fg-muted`
+ * tokens are white-alpha ink, and measuring them raw would report the ratio of
+ * pure white and pass everything.
+ *
+ * @param foreground - The ink. Composited over `background` if it has alpha.
+ * @param background - The ground. Its own alpha is ignored — nothing is behind it.
+ * @returns The ratio, `>= 1`.
+ * @throws TypeError naming whichever value could not be read.
+ * @example
+ * contrastRatio("#767676", "#ffffff"); // → 4.5422…
+ */
+declare function contrastRatio(foreground: string, background: string): number;
+/** One pair a theme is checked on. */
+interface ContrastRequirement {
+  /** `"<foreground>/<background>"` — stable, and readable in a failure message. */
+  id: string;
+  /** Bare token name of the ink. */
+  foreground: string;
+  /** Bare token name of the ground. */
+  background: string;
+  /** The ratio the pair has to reach. */
+  minimum: number;
+  /** Why this minimum, in one line — the configurator surfaces it. */
+  reason: string;
+}
+/**
+ * The eight pairs that decide whether a theme is usable.
+ *
+ * Not every pair in the palette: the ones a reader's comprehension actually
+ * depends on. Primary ink is held to AAA because it carries the prose; secondary
+ * ink and accent ink to AA because they carry labels; the five status colours to
+ * the non-text AA floor because they are read as *signals* — a dot, a rim, a bar
+ * — never as body copy.
+ */
+declare const CONTRAST_REQUIREMENTS: readonly ContrastRequirement[];
+/** One measured pair. */
+interface ContrastCheck extends ContrastRequirement {
+  /** Which block the pair was measured in. */
+  mode: "dark" | "light";
+  /** The colour the foreground token resolved to. */
+  foregroundValue: string;
+  /** The colour the background token resolved to. */
+  backgroundValue: string;
+  /** The measured ratio. */
+  ratio: number;
+  /** Whether {@link ContrastRequirement.minimum} was reached. */
+  passes: boolean;
+  /** Whether the values were derived rather than authored — see the light variant. */
+  provisional: boolean;
+}
+/** One block's worth of resolved colours. */
+interface ContrastInput {
+  /** Which block these are. */
+  mode: "dark" | "light";
+  /** Bare token name → resolved CSS colour. Pairs with a missing token are skipped. */
+  tokens: Readonly<Record<string, string>>;
+  /** Mark the resulting checks provisional. Defaults to `false`. */
+  provisional?: boolean;
+}
+/** Every pair, measured, plus the verdict. */
+interface ContrastReport {
+  /** True when nothing failed. */
+  passes: boolean;
+  /** True when any measured block was derived rather than authored. */
+  provisional: boolean;
+  /** Every pair that could be measured, in requirement order, dark block first. */
+  checks: readonly ContrastCheck[];
+  /** The subset that failed. Empty when {@link ContrastReport.passes}. */
+  failures: readonly ContrastCheck[];
+}
+/**
+ * Measure every requirement against every block handed in.
+ *
+ * A pair whose tokens are missing is **skipped**, not failed: the report says
+ * what it measured, and a caller checking a partial palette should not be told
+ * that a colour it never supplied is unreadable.
+ *
+ * @param inputs - One entry per block, dark first by convention.
+ * @returns The report.
+ * @example
+ * contrastReport([{ mode: "dark", tokens: { fg: "#fff", bg: "#000" } }]).passes; // → true
+ */
+declare function contrastReport(inputs: readonly ContrastInput[]): ContrastReport;
+//#endregion
+export { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance };