@cueplusplus/ui 0.8.0 → 0.9.0

package/dist/theming/contrast.js

@@ -1,194 +1,2 @@
-import { converter, parse } from "culori";
-//#region src/theming/contrast.ts
-/**
-* WCAG contrast, and the eleven pairs a theme is judged on.
-*
-* A generator that only derived colours would be a colour toy: the reason to
-* compute a palette instead of picking one is that the computer can then *check*
-* it, on every build, against the one part of visual design that is not a matter
-* of taste. So `createTheme()` never hands back a theme without a report, and
-* the report is the deliverable — a failing pair is information, not an error to
-* swallow.
-*
-* The maths is WCAG 2.x relative luminance (sRGB, linearised, 0.2126/0.7152/
-* 0.0722), deliberately not APCA. APCA is better, and it is also not what
-* anyone's compliance checklist says; a theme that has to survive an audit needs
-* the number the audit will compute.
-*/
-const toRgb = converter("rgb");
-/** Non-text and large-text AA: UI components, graphics, status dots. */
-const WCAG_AA_NON_TEXT = 3;
-/** Body-text AA. The floor for anything a reader is expected to read. */
-const WCAG_AA_TEXT = 4.5;
-/** Body-text AAA. What this portfolio holds its primary ink to. */
-const WCAG_AAA_TEXT = 7;
-/** sRGB gamma decode, per WCAG's definition of relative luminance. */
-function linearize(channel) {
-	return channel <= .04045 ? channel / 12.92 : ((channel + .055) / 1.055) ** 2.4;
-}
-/** Parse to sRGB, or say which value could not be read. */
-function toSrgb(input, label = "colour") {
-	const color = toRgb(parse(input));
-	if (color === void 0) throw new TypeError(`${label} is not a colour this can measure: ${JSON.stringify(input)}`);
-	return color;
-}
-/** Source-over composite of `over` onto `under`, in (non-linear) sRGB. */
-function composite(over, under) {
-	const alpha = over.alpha ?? 1;
-	if (alpha >= 1) return over;
-	return {
-		r: over.r * alpha + under.r * (1 - alpha),
-		g: over.g * alpha + under.g * (1 - alpha),
-		b: over.b * alpha + under.b * (1 - alpha)
-	};
-}
-function luminanceOf(color) {
-	return .2126 * linearize(color.r) + .7152 * linearize(color.g) + .0722 * linearize(color.b);
-}
-/**
-* 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…
-*/
-function relativeLuminance(color) {
-	return luminanceOf(toSrgb(color));
-}
-/**
-* 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…
-*/
-function contrastRatio(foreground, background) {
-	const ground = toSrgb(background, "background");
-	const [high, low] = [luminanceOf(composite(toSrgb(foreground, "foreground"), ground)), luminanceOf(ground)].toSorted((a, b) => b - a);
-	return (high + .05) / (low + .05);
-}
-/**
-* The eleven 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
-* and the live hue to the non-text AA floor because they are read as *signals*
-* — a dot, a rim, a bar — never as body copy.
-*
-* `danger` and `warn` each appear twice, and they are the only tones that do.
-* `ok`, `busy`, `info` and `stream` are *only* ever signals, so the non-text
-* floor is the whole truth about them. The red and the amber are also grounds:
-* they are the two tones this system fills a control with, and what they fill is
-* the confirm on something irreversible and the confirm on something merely
-* consequential. Text on either fill is text, so its ink is held to the text
-* floor against the tone it sits on rather than against the page.
-*
-* `stream` is measured for the same reason `ok` is: `createTheme()` darkens it
-* to this floor when it has to invent a light block, and a report that did not
-* check what the derivation targets would be checking the wrong thing.
-*/
-const CONTRAST_REQUIREMENTS = [
-	{
-		id: "fg/bg",
-		foreground: "fg",
-		background: "bg",
-		minimum: 7,
-		reason: "Primary ink carries the prose, and this portfolio holds it to AAA."
-	},
-	{
-		id: "fg-muted/bg",
-		foreground: "fg-muted",
-		background: "bg",
-		minimum: WCAG_AA_TEXT,
-		reason: "Secondary ink is still text: labels, captions, table headers."
-	},
-	{
-		id: "accent-fg/accent",
-		foreground: "accent-fg",
-		background: "accent",
-		minimum: WCAG_AA_TEXT,
-		reason: "The label on a solid accent button has to be readable."
-	},
-	{
-		id: "danger-fg/danger",
-		foreground: "danger-fg",
-		background: "danger",
-		minimum: WCAG_AA_TEXT,
-		reason: "The label on a solid destructive fill is read before something irreversible happens."
-	},
-	{
-		id: "warn-fg/warn",
-		foreground: "warn-fg",
-		background: "warn",
-		minimum: WCAG_AA_TEXT,
-		reason: "The label on a solid warning fill is read before a consequential press lands."
-	},
-	...[
-		"ok",
-		"busy",
-		"warn",
-		"danger",
-		"info",
-		"stream"
-	].map((status) => ({
-		id: `${status}/bg`,
-		foreground: status,
-		background: "bg",
-		minimum: 3,
-		reason: `The ${status} tone is read as a signal — dot, rim, bar — not as body copy.`
-	}))
-];
-/**
-* 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
-*/
-function contrastReport(inputs) {
-	const checks = [];
-	for (const { mode, tokens, provisional = false } of inputs) for (const requirement of CONTRAST_REQUIREMENTS) {
-		const foregroundValue = tokens[requirement.foreground];
-		const backgroundValue = tokens[requirement.background];
-		if (foregroundValue === void 0 || backgroundValue === void 0) continue;
-		const ratio = contrastRatio(foregroundValue, backgroundValue);
-		checks.push({
-			...requirement,
-			mode,
-			foregroundValue,
-			backgroundValue,
-			ratio,
-			passes: ratio >= requirement.minimum,
-			provisional
-		});
-	}
-	const failures = checks.filter((check) => !check.passes);
-	return {
-		passes: failures.length === 0,
-		provisional: checks.some((check) => check.provisional),
-		checks,
-		failures
-	};
-}
-//#endregion
-export { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance };
+import { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, relativeLuminance } from "@cueplusplus/theme-base/contrast";
+export { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, relativeLuminance };

package/dist/theming/create-theme.d.ts

@@ -1,6 +1,6 @@
 import { ContrastReport } from "./contrast.js";
-import { THEME_COLOR_TOKENS, ThemeColorToken } from "./_presets.js";
-import { ThemeName } from "@cueplusplus/tokens";
+import { Density } from "@cueplusplus/tokens";
+import { ColorToken, ThemeManifest } from "@cueplusplus/theme-base";
 //#region src/theming/create-theme.d.ts
 /**
  * `createTheme()` — the typed generator behind the spec's second theming tier.
@@ -25,8 +25,21 @@ import { ThemeName } from "@cueplusplus/tokens";
  *   the report rather than being silently repaired — with one exception, noted
  *   below, where the value was this module's invention in the first place.
  */
-/** The preset a theme starts from when the caller names none. */
-declare const DEFAULT_THEME_BASE: ThemeName;
+/**
+ * The colour tokens every theme block declares, in the order the contract lists
+ * them.
+ *
+ * Not a list this module owns any more, and not a copy of one: it *is*
+ * `COLOR_CONTRACT`, re-exported under the name this package's public API has
+ * always used. The two were byte-identical — twenty-six names, same order —
+ * because the copy was written from the contract in the first place, and a
+ * second list that has to agree with the first is a drift test waiting to be
+ * written. `test/theming/create-theme.test.ts` asserts the identity, so a future
+ * edit that quietly reintroduces a local array fails rather than diverges.
+ */
+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", "warn-fg", "danger", "danger-fg", "info", "stream", "selection", "focus", "data-ground", "scrim"];
+/** One of the colour tokens a theme block owns. */
+type ThemeColorToken = ColorToken;
 /**
  * How far the sunken ground sits below the page, in oklch lightness.
  *
@@ -85,10 +98,22 @@ interface ThemeAnchors {
    */
   name: string;
   /**
-   * The preset to start from. Every token you do not move comes back verbatim.
-   * Defaults to {@link DEFAULT_THEME_BASE}.
+   * The manifest to start from. Every token you do not move comes back verbatim.
+   *
+   * A manifest, not a name: this package holds no table of palettes to look a
+   * name up in, and one is exactly what it stopped holding. Pass the default
+   * export of a theme package — `@cueplusplus/theme-terminal`'s, say — or any
+   * manifest of your own. Absent means the blank base: the neutral ramp
+   * `@cueplusplus/theme-base` ships, which every theme's deltas were diffed
+   * against.
+   *
+   * The package is named in prose rather than shown as an `import` line on
+   * purpose. Every barrel test in this package scrapes imports with a regex
+   * that cannot tell a doc comment from code, and to those tests an example
+   * import reads as `ui` depending on a theme package — which it may not, at
+   * runtime or otherwise.
    */
-  base?: ThemeName;
+  base?: ThemeManifest;
   /**
    * The ground. Moving it re-derives the sunken well, the three raised surfaces
    * and the three border weights.
@@ -156,14 +181,15 @@ interface CreatedTheme {
  * configurator's export dialog — never in a render path, because there is
  * nothing here a stylesheet is not already doing faster.
  *
- * @param anchors - The name, the preset to start from, and whatever you moved.
+ * @param anchors - The name, the manifest to start from, and whatever you moved.
  * @returns The stylesheet, the resolved tokens for both modes, and the report.
  * @throws TypeError if the name is not a CSS identifier, an anchor is not a
- *   colour, a font stack carries CSS punctuation, or the base preset is unknown.
+ *   colour, a font stack carries CSS punctuation, or `base` is a theme *name*
+ *   rather than a manifest.
  * @example
- * const { css, report } = createTheme({ name: "acme", base: "terminal", accent: "#ff8800" });
+ * const { css, report } = createTheme({ name: "acme", accent: "#ff8800" });
  * if (!report.passes) console.warn(report.failures);
  */
 declare function createTheme(anchors: ThemeAnchors): CreatedTheme;
 //#endregion
-export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CreatedTheme, DEFAULT_THEME_BASE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, ThemeAnchors, type ThemeColorToken, createTheme };
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CreatedTheme, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, ThemeAnchors, ThemeColorToken, createTheme };

package/dist/theming/create-theme.js

@@ -1,8 +1,9 @@
 import { formatColorString } from "../color/_convert.js";
-import { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, RESOLVED_MONO, THEME_COLOR_TOKENS, THEME_PRESETS } from "./_presets.js";
-import { WCAG_AA_TEXT, contrastRatio, contrastReport } from "./contrast.js";
-import { assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+import { WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport } from "./contrast.js";
+import { RESOLVED_MONO, assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+import { COLOR_CONTRACT, resolve } from "@cueplusplus/theme-base";
 import { clampChroma, converter, formatHex, inGamut, parse } from "culori";
+import tokensBase from "@cueplusplus/tokens/base.json" with { type: "json" };
 //#region src/theming/create-theme.ts
 /**
 * `createTheme()` — the typed generator behind the spec's second theming tier.
@@ -27,8 +28,36 @@ import { clampChroma, converter, formatHex, inGamut, parse } from "culori";
 *   the report rather than being silently repaired — with one exception, noted
 *   below, where the value was this module's invention in the first place.
 */
-/** The preset a theme starts from when the caller names none. */
-const DEFAULT_THEME_BASE = "cue";
+/**
+* The colour tokens every theme block declares, in the order the contract lists
+* them.
+*
+* Not a list this module owns any more, and not a copy of one: it *is*
+* `COLOR_CONTRACT`, re-exported under the name this package's public API has
+* always used. The two were byte-identical — twenty-six names, same order —
+* because the copy was written from the contract in the first place, and a
+* second list that has to agree with the first is a drift test waiting to be
+* written. `test/theming/create-theme.test.ts` asserts the identity, so a future
+* edit that quietly reintroduces a local array fails rather than diverges.
+*/
+const THEME_COLOR_TOKENS = COLOR_CONTRACT;
+/**
+* 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.
+*
+* `Number(…)` because `base.json` is DTCG, where every value is text: the scale
+* arrives as `"0.75"` and what happens to it next is arithmetic. Keyed by the
+* base five alone, because those are the rungs a build-time generator can know
+* the geometry of; a rung a theme adds carries its own radius in its manifest.
+*/
+const DENSITY_RADIUS_SCALE = Object.fromEntries(Object.keys(tokensBase.densities).map((rung) => [rung, Number(tokensBase.densities[rung]["radius-scale"])]));
+/** The default density, whose radius scale the uncrossed theme block carries. */
+const DEFAULT_DENSITY_LEVEL = tokensBase.defaults.density;
 /**
 * How far the sunken ground sits below the page, in oklch lightness.
 *
@@ -333,7 +362,7 @@ function resolveLight(dark, preset) {
 	const accent = colors["accent"];
 	define("accent-hover", () => shift(readColor(accent, "accent"), ACCENT_HOVER_LIGHTNESS_STEP));
 	define("accent-fg", () => pickInk(accent, [colors["bg"], colors["fg"]]));
-	for (const tone of TINTED) define(tone, () => darkenToContrast(dark.colors[tone], paperGround, 3, tone));
+	for (const tone of TINTED) define(tone, () => darkenToContrast(dark.colors[tone], paperGround, WCAG_AA_NON_TEXT, tone));
 	for (const tone of INKED) define(`${tone}-fg`, () => pickInk(colors[tone], [
 		colors["bg"],
 		colors["sunken"],
@@ -358,11 +387,11 @@ function resolveLight(dark, preset) {
 * ancestor, purely by sitting nearer to the text, and a consumer's own preset
 * would be the one preset in the system the typeface picker could not move.
 */
-function resolveFonts(anchors, preset) {
+function resolveFonts$1(anchors, preset) {
 	const fonts = anchors.fonts ?? {};
 	const declared = [];
 	if (fonts.sans !== void 0) declared.push(["font-sans", fonts.sans]);
-	declared.push(["font-theme-mono", fonts.mono ?? lookup(preset, "font-mono") ?? BASE_FONT_STACKS["font-mono"]]);
+	declared.push(["font-theme-mono", fonts.mono ?? lookup(preset, "font-mono") ?? tokensBase.base["font-mono"]]);
 	if (fonts.display !== void 0) declared.push(["font-display", fonts.display]);
 	return [...declared.map(([name, value]) => [tokenProperty(name), assertCssValue(name, value)]), [tokenProperty("font-mono"), RESOLVED_MONO]];
 }
@@ -385,7 +414,10 @@ function radiusBlocks(name, radiusScale) {
 	for (const [level, scale] of Object.entries(DENSITY_RADIUS_SCALE)) {
 		if (scale === fallback) continue;
 		blocks.push({
-			selector: themeSelector(name, { density: level }),
+			selector: themeSelector(name, {
+				density: level,
+				pair: true
+			}),
 			sections: [{ declarations: [[property, scaled(radiusScale, scale)]] }]
 		});
 	}
@@ -408,24 +440,29 @@ const SHAPE_COMMENT = "shape — crossed with the density ladder below, never fl
 * configurator's export dialog — never in a render path, because there is
 * nothing here a stylesheet is not already doing faster.
 *
-* @param anchors - The name, the preset to start from, and whatever you moved.
+* @param anchors - The name, the manifest to start from, and whatever you moved.
 * @returns The stylesheet, the resolved tokens for both modes, and the report.
 * @throws TypeError if the name is not a CSS identifier, an anchor is not a
-*   colour, a font stack carries CSS punctuation, or the base preset is unknown.
+*   colour, a font stack carries CSS punctuation, or `base` is a theme *name*
+*   rather than a manifest.
 * @example
-* const { css, report } = createTheme({ name: "acme", base: "terminal", accent: "#ff8800" });
+* const { css, report } = createTheme({ name: "acme", accent: "#ff8800" });
 * if (!report.passes) console.warn(report.failures);
 */
 function createTheme(anchors) {
 	const name = assertThemeName(anchors.name);
-	const baseName = anchors.base ?? "cue";
-	const preset = THEME_PRESETS[baseName];
-	if (preset === void 0) throw new TypeError(`unknown base theme: ${JSON.stringify(baseName)}`);
+	if (typeof anchors.base === "string") throw new TypeError(`base is a manifest, not a name — import it from @cueplusplus/theme-${anchors.base}`);
+	const base = anchors.base ?? null;
+	const preset = {
+		dark: resolve(base, { mode: "dark" }).colors,
+		light: base === null || base.supportsLight ? resolve(base, { mode: "light" }).colors : null,
+		fonts: base?.fonts ?? {}
+	};
 	if (anchors.radiusScale !== void 0 && !(anchors.radiusScale > 0)) throw new TypeError(`radiusScale must be a positive number, got ${anchors.radiusScale}`);
 	const dark = resolveDark(anchors, preset.dark);
 	const light = anchors.supportsLight ?? preset.light !== null ? resolveLight(dark, preset.light) : null;
 	const derived = Object.entries(derivedTokens());
-	const fonts = resolveFonts(anchors, preset.fonts);
+	const fonts = resolveFonts$1(anchors, preset.fonts);
 	const radius = anchors.radiusScale === void 0 ? null : radiusBlocks(name, anchors.radiusScale);
 	const darkPaletteSections = [
 		{ declarations: colorDeclarations(dark.colors) },
@@ -484,4 +521,4 @@ function createTheme(anchors) {
 	};
 }
 //#endregion
-export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, DEFAULT_THEME_BASE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, createTheme };
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, createTheme };

package/dist/theming/index.d.ts

@@ -1,5 +1,4 @@
 import { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance } from "./contrast.js";
-import { THEME_COLOR_TOKENS, ThemeColorToken } from "./_presets.js";
-import { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CreatedTheme, DEFAULT_THEME_BASE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, ThemeAnchors, createTheme } from "./create-theme.js";
-import { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, SerializeThemeCssOptions, THEME_NAME_PATTERN, ThemeBlock, ThemeBlockSection, ThemeSelectorOptions, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
-export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CONTRAST_REQUIREMENTS, CUE_TOKEN_PREFIX, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, type CreatedTheme, DEFAULT_THEME_BASE, DERIVED_TOKEN_TEMPLATES, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, type SerializeThemeCssOptions, THEME_COLOR_TOKENS, THEME_NAME_PATTERN, type ThemeAnchors, type ThemeBlock, type ThemeBlockSection, type ThemeColorToken, type ThemeSelectorOptions, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, assertCssValue, assertThemeName, contrastRatio, contrastReport, createTheme, derivedTokens, relativeLuminance, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };
+import { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CreatedTheme, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, ThemeAnchors, ThemeColorToken, createTheme } from "./create-theme.js";
+import { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, RESOLVED_MONO, SerializeThemeCssOptions, THEME_NAME_PATTERN, ThemeBlock, ThemeBlockSection, ThemeSelectorOptions, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CONTRAST_REQUIREMENTS, CUE_TOKEN_PREFIX, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, type CreatedTheme, DERIVED_TOKEN_TEMPLATES, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, RESOLVED_MONO, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, type SerializeThemeCssOptions, THEME_COLOR_TOKENS, THEME_NAME_PATTERN, type ThemeAnchors, type ThemeBlock, type ThemeBlockSection, type ThemeColorToken, type ThemeSelectorOptions, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, assertCssValue, assertThemeName, contrastRatio, contrastReport, createTheme, derivedTokens, relativeLuminance, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/dist/theming/index.js

@@ -1,5 +1,4 @@
-import { THEME_COLOR_TOKENS } from "./_presets.js";
 import { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance } from "./contrast.js";
-import { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
-import { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, DEFAULT_THEME_BASE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, createTheme } from "./create-theme.js";
-export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CONTRAST_REQUIREMENTS, CUE_TOKEN_PREFIX, DEFAULT_THEME_BASE, DERIVED_TOKEN_TEMPLATES, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, THEME_NAME_PATTERN, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, assertCssValue, assertThemeName, contrastRatio, contrastReport, createTheme, derivedTokens, relativeLuminance, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };
+import { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, RESOLVED_MONO, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+import { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, createTheme } from "./create-theme.js";
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CONTRAST_REQUIREMENTS, CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, RESOLVED_MONO, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, THEME_NAME_PATTERN, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, assertCssValue, assertThemeName, contrastRatio, contrastReport, createTheme, derivedTokens, relativeLuminance, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/dist/theming/serialize.d.ts

@@ -1,4 +1,5 @@
 import { Density } from "@cueplusplus/tokens";
+import { RESOLVED_MONO, THEME_NAME_PATTERN as THEME_NAME_PATTERN$1 } from "@cueplusplus/theme-base";
 //#region src/theming/serialize.d.ts
 /**
  * Turning a resolved token map back into the stylesheet the tokens build would
@@ -10,7 +11,10 @@ import { Density } from "@cueplusplus/tokens";
  * `[data-theme]` block, or a consumer ends up with two vocabularies and the
  * generator becomes a toy. So the shapes below mirror `build.mjs` deliberately,
  * comments included: same selector form, same declaration order, same section
- * breaks. `test/theming/presets.test.ts` diffs the two.
+ * breaks. The generator-versus-build parity that `test/theming/presets.test.ts`
+ * used to diff is unguarded for this plan — the shipped preset copy that test
+ * compared against was deleted with it — and Plan 4 restores the comparison
+ * once `@cueplusplus/tokens` stops emitting presets of its own.
  *
  * It is also the only place that touches raw strings, which makes it the place
  * to stop injection. A theme name lands inside an attribute selector and a font
@@ -18,15 +22,6 @@ import { Density } from "@cueplusplus/tokens";
  */
 /** The one custom-property prefix this design system emits. */
 declare const CUE_TOKEN_PREFIX = "--cue-";
-/**
- * What a theme may be called.
- *
- * The name is interpolated into `[data-theme="…"]`, so the pattern is a
- * whitelist rather than an escape: a CSS identifier, which is also what a
- * `data-theme` attribute is expected to hold and what a file called
- * `<name>.css` can be named.
- */
-declare const THEME_NAME_PATTERN: RegExp;
 /**
  * Check a theme name and hand it back.
  *
@@ -65,6 +60,22 @@ interface ThemeSelectorOptions {
   mode?: "dark" | "light";
   /** Cross with the density axis. Used only for the radius multiplier. */
   density?: Density;
+  /**
+   * Emit the descendant form beside the compound one, as `"A, B"`.
+   *
+   * Only meaningful together with `density`, and it exists because the two axes
+   * do **not** always land on the same element. The compound
+   * `[data-theme="x"][data-density="y"]` matches only a node carrying both
+   * attributes — the provider root, and nothing else. A `<Density>` island
+   * stamps `data-density` on a `<div>` *inside* that root, and
+   * `useControlHeight`'s measuring probe hangs off `document.body`, outside it
+   * entirely; both therefore carry a density with no theme beside it, and both
+   * were silently missing the crossed value. The descendant form
+   * `[data-theme="x"] [data-density="y"]` covers exactly those, and the pair is
+   * emitted rather than the descendant alone because the descendant does not
+   * match the root itself.
+   */
+  pair?: boolean;
 }
 /**
  * The selector a theme's declarations live under.
@@ -78,6 +89,8 @@ interface ThemeSelectorOptions {
  * @returns The CSS selector.
  * @example
  * themeSelector("acme", { mode: "light" }); // → '[data-theme="acme"][data-mode="light"]'
+ * themeSelector("acme", { density: "compact", pair: true });
+ * // → '[data-theme="acme"] [data-density="compact"]:where([data-cue-theme="acme"]), [data-theme="acme"] [data-density="compact"]:where(:not([data-cue-theme]):not([data-theme]:not([data-theme="acme"])):not([data-theme="acme"] [data-theme]:not([data-theme="acme"]) *)), [data-theme="acme"][data-density="compact"]'
  */
 declare function themeSelector(name: string, options?: ThemeSelectorOptions): string;
 /**
@@ -151,4 +164,4 @@ interface SerializeThemeCssOptions {
  */
 declare function serializeThemeCss(blocks: readonly ThemeBlock[], options?: SerializeThemeCssOptions): string;
 //#endregion
-export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, SerializeThemeCssOptions, THEME_NAME_PATTERN, ThemeBlock, ThemeBlockSection, ThemeSelectorOptions, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };
+export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, RESOLVED_MONO, SerializeThemeCssOptions, THEME_NAME_PATTERN$1 as THEME_NAME_PATTERN, ThemeBlock, ThemeBlockSection, ThemeSelectorOptions, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/dist/theming/serialize.js

@@ -1,3 +1,4 @@
+import { RESOLVED_MONO, THEME_NAME_PATTERN as THEME_NAME_PATTERN$1 } from "@cueplusplus/theme-base";
 //#region src/theming/serialize.ts
 /**
 * Turning a resolved token map back into the stylesheet the tokens build would
@@ -9,7 +10,10 @@
 * `[data-theme]` block, or a consumer ends up with two vocabularies and the
 * generator becomes a toy. So the shapes below mirror `build.mjs` deliberately,
 * comments included: same selector form, same declaration order, same section
-* breaks. `test/theming/presets.test.ts` diffs the two.
+* breaks. The generator-versus-build parity that `test/theming/presets.test.ts`
+* used to diff is unguarded for this plan — the shipped preset copy that test
+* compared against was deleted with it — and Plan 4 restores the comparison
+* once `@cueplusplus/tokens` stops emitting presets of its own.
 *
 * It is also the only place that touches raw strings, which makes it the place
 * to stop injection. A theme name lands inside an attribute selector and a font
@@ -18,15 +22,6 @@
 /** The one custom-property prefix this design system emits. */
 const CUE_TOKEN_PREFIX = "--cue-";
 /**
-* What a theme may be called.
-*
-* The name is interpolated into `[data-theme="…"]`, so the pattern is a
-* whitelist rather than an escape: a CSS identifier, which is also what a
-* `data-theme` attribute is expected to hold and what a file called
-* `<name>.css` can be named.
-*/
-const THEME_NAME_PATTERN = /^[a-z][a-z0-9-]*$/i;
-/**
 * Characters a value may never contain: the ones that end a declaration, end a
 * block, or open a comment.
 *
@@ -45,7 +40,7 @@ const UNSAFE_VALUE = /[;{}]|\/\*/;
 * assertThemeName("acme-dark"); // → "acme-dark"
 */
 function assertThemeName(name) {
-	if (!THEME_NAME_PATTERN.test(name)) throw new TypeError(`theme name must be a CSS identifier (letters, digits and dashes, starting with a letter), got ${JSON.stringify(name)}`);
+	if (!THEME_NAME_PATTERN$1.test(name)) throw new TypeError(`theme name must be a CSS identifier (letters, digits and dashes, starting with a letter), got ${JSON.stringify(name)}`);
 	return name;
 }
 /**
@@ -88,14 +83,17 @@ function tokenProperty(name) {
 * @returns The CSS selector.
 * @example
 * themeSelector("acme", { mode: "light" }); // → '[data-theme="acme"][data-mode="light"]'
+* themeSelector("acme", { density: "compact", pair: true });
+* // → '[data-theme="acme"] [data-density="compact"]:where([data-cue-theme="acme"]), [data-theme="acme"] [data-density="compact"]:where(:not([data-cue-theme]):not([data-theme]:not([data-theme="acme"])):not([data-theme="acme"] [data-theme]:not([data-theme="acme"]) *)), [data-theme="acme"][data-density="compact"]'
 */
 function themeSelector(name, options = {}) {
-	const { mode, density } = options;
-	return [
-		`[data-theme="${name}"]`,
-		mode === "light" ? "[data-mode=\"light\"]" : "",
-		density === void 0 ? "" : `[data-density="${density}"]`
-	].join("");
+	const { mode, density, pair } = options;
+	const themeAttr = `[data-theme="${name}"]`;
+	const theme = `${themeAttr}${mode === "light" ? "[data-mode=\"light\"]" : ""}`;
+	if (density === void 0) return theme;
+	const crossed = `[data-density="${density}"]`;
+	if (pair !== true) return `${theme}${crossed}`;
+	return `${`${theme} ${crossed}:where([data-cue-theme="${name}"])`}, ${`${theme} ${crossed}:where(:not([data-cue-theme]):not([data-theme]:not(${themeAttr})):not(${themeAttr} [data-theme]:not(${themeAttr}) *))`}, ${theme}${crossed}`;
 }
 /** The tone vocabulary that gets a soft fill and a soft border in every theme. */
 const STATUSES = [
@@ -240,4 +238,4 @@ function serializeThemeCss(blocks, options = {}) {
 	return `${[...options.banner === void 0 ? [] : [`/*! ${options.banner}\n * Generated by createTheme(). Do not edit by hand.\n */`], ...rules].join("\n\n")}\n`;
 }
 //#endregion
-export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };
+export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, RESOLVED_MONO, THEME_NAME_PATTERN$1 as THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeSystemModeAliases, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/manifest/components/colors-section.json

@@ -38,17 +38,16 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-radius-control",
     "--cue-radius-scale",
     "--cue-space-1",
     "--cue-space-2",
     "--cue-space-4",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-text-ui"
   ],
   "summary": "Section 2 — every colour the active theme declares, one row each.",
   "examples": [

package/manifest/components/cue-portal-frame.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "Inline version of the portal contract, for portals whose container cannot be\nchosen (a third-party overlay, or content already portaled by something else).\n\nWraps `children` in a `display: contents` element carrying the same\n`data-theme` / `data-density` / `data-font` / `data-mode` / `data-cue-skin` /\n`data-cue-fidelity` stamp and `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one\nelement per overlay instead of one per render tree — and reach for this only\nwhen the container prop is not available.",
+  "description": "Inline version of the portal contract, for portals whose container cannot be\nchosen (a third-party overlay, or content already portaled by something else).\n\nWraps `children` in a `display: contents` element carrying the same\n`data-theme` / `data-density` / `data-font` / `data-mode` / `data-cue-skin` /\n`data-cue-fidelity` stamp, `--cue-font-scale` and `overrides` properties as\n{@link useCuePortalProps}. Prefer the hook — a stamped container costs one\nelement per overlay instead of one per render tree — and reach for this only\nwhen the container prop is not available.",
   "props": [
     {
       "name": "children",

package/manifest/components/density.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "Re-scope any subtree to a different density level.\n\nRenders a plain `<div data-density=\"…\">`: the geometry custom properties are\nre-declared by the attribute selector and inherit down, so nesting is free and\nneeds no JS. The matching React context is published alongside for the rare\nJS reads (`useDensity()`, `useControlHeight()`, portal stamping) — the DOM\nattribute, not the context, is what actually restyles the tree.\n\nTheme and mode are deliberately *not* re-scoped here: density is the only axis\nan island may override (spec §6).",
+  "description": "Re-scope any subtree to a different density level.\n\nRenders a plain `<div data-density=\"…\" data-cue-theme=\"…\">`: the geometry\ncustom properties are re-declared by the attribute selector and inherit\ndown, so nesting is free and needs no JS. The matching React context is\npublished alongside for the rare JS reads (`useDensity()`,\n`useControlHeight()`, portal stamping) — the DOM attributes, not the\ncontext, are what actually restyle the tree.\n\n`data-cue-theme` carries the nearest `<ThemeProvider>`'s name, or is\nomitted where there is none. It is read by nothing this island does —\ntheme and mode are deliberately *not* re-scoped here, density is the only\naxis an island may override (spec §6) — it exists so a theme's own\ngenerated CSS can address exactly this island regardless of how many\n*other* themed providers sit between it and the one it belongs to. A CSS\nancestor selector can only ask \"does some ancestor carry theme `x`\", never\n\"is `x` the *nearest* one\"; this stamp answers that question the way\n`useContext` already does, at render time, and hands the answer to CSS as\nan attribute rather than leaving it unanswerable there.",
   "props": [
     {
       "name": "density",

package/manifest/components/export-dialog.json

@@ -55,12 +55,9 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-radius-control",
-    "--cue-radius-scale",
     "--cue-space-1",
     "--cue-space-3",
     "--cue-space-4",