@cueplusplus/ui 0.1.0

package/dist/theming/contrast.js

@@ -0,0 +1,167 @@
+import { converter, parse } from "culori";
+//#region src/theming/contrast.ts
+/**
+* WCAG contrast, and the eight 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 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.
+*/
+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."
+	},
+	...[
+		"ok",
+		"busy",
+		"warn",
+		"danger",
+		"info"
+	].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 };

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

@@ -0,0 +1,165 @@
+import { ContrastReport } from "./contrast.js";
+import { THEME_COLOR_TOKENS, ThemeColorToken } from "./_presets.js";
+import { ThemeName } from "@cueplusplus/tokens";
+//#region src/theming/create-theme.d.ts
+/**
+ * `createTheme()` — the typed generator behind the spec's second theming tier.
+ *
+ * Three things it is not, because each of them is a trap this deliberately
+ * avoids:
+ *
+ * - **Not a runtime engine.** It is a pure function of its arguments, called at
+ *   build time (or once, in the configurator's export dialog), and what comes
+ *   out is a plain `[data-theme]` stylesheet — tier 1, the guaranteed contract.
+ *   Nothing about a shipped app depends on this module existing.
+ * - **Not a palette generator.** Handed a preset and nothing else it returns the
+ *   preset, byte for byte. Derivation is what happens to the tokens hanging off
+ *   an anchor you actually moved, and only those: swap the accent and the hover,
+ *   the ink on it, the focus ring and the selection wash follow; the ground, the
+ *   ink and the five status tones do not. That rule is the whole reason
+ *   "start from `terminal`, make it orange" is a two-line call rather than a
+ *   fork of a palette.
+ * - **Not a colour opinion.** Every derivation happens in oklch, where a
+ *   lightness step is a step the eye agrees with, and every result is measured
+ *   against WCAG before you are told it is fine. A failing pair comes back in
+ *   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;
+/**
+ * How far the sunken ground sits below the page, in oklch lightness.
+ *
+ * Small on purpose: sunken is a well, not a second theme. Across the eight
+ * shipped presets the authored gap runs −0.011 to −0.031.
+ */
+declare const SUNKEN_LIGHTNESS_STEP = -0.02;
+/**
+ * The three raised surfaces, as lightness above the ground.
+ *
+ * Even spacing, because the ladder encodes *elevation* and a reader counts
+ * rungs. The shipped presets cluster around these three values.
+ */
+declare const SURFACE_LIGHTNESS_STEPS: readonly number[];
+/**
+ * The hairline and its stronger sibling, as lightness above the ground.
+ *
+ * Above the top surface, so a border still reads as a line when it is drawn on
+ * `surface-3`. `border-overlay` reuses the strong value: an overlay floats over
+ * everything, so its rim has to hold against the brightest thing under it.
+ */
+declare const BORDER_LIGHTNESS_STEPS: readonly number[];
+/** How far secondary ink recedes from primary ink. */
+declare const FG_MUTED_LIGHTNESS_STEP = -0.25;
+/** How far tertiary ink recedes from primary ink. */
+declare const FG_SUBTLE_LIGHTNESS_STEP = -0.45;
+/**
+ * Chroma each rung of the ink ramp keeps from the rung above.
+ *
+ * Ink greys as it recedes rather than staying saturated: a muted label that held
+ * full chroma would read as a *coloured* label — a status, a link — instead of a
+ * quiet one. The hue is preserved throughout, so the ramp still belongs to the
+ * theme. `fg-subtle` takes the square, being two rungs down.
+ */
+declare const INK_RAMP_CHROMA_SCALE = 0.6;
+/** How far the accent darkens on hover. */
+declare const ACCENT_HOVER_LIGHTNESS_STEP = -0.05;
+/** How much accent a derived selection wash carries. */
+declare const SELECTION_ACCENT_PERCENT = 22;
+/** What a label on a solid accent has to reach before this module accepts it. */
+declare const ACCENT_FG_MINIMUM = 4.5;
+/**
+ * How much of the dark ground's lightness survives the flip to paper.
+ *
+ * A ground's job is to be the extreme, so inverting it means going to the *other*
+ * extreme rather than to the arithmetic mirror: `1 − L` of a 0.16 near-black is a
+ * 0.84 mid-grey, which is not a page. Compressing instead maps the ladder of
+ * dark grounds onto a narrow paper band — a deeper dark theme gets a cleaner
+ * white page — and lands within 0.01 of all eight authored light presets.
+ */
+declare const LIGHT_GROUND_COMPRESSION = 0.1;
+interface ThemeAnchors {
+  /**
+   * The theme's name. Lands in `[data-theme="…"]`, so it must be a CSS
+   * identifier: letters, digits and dashes, starting with a letter.
+   */
+  name: string;
+  /**
+   * The preset to start from. Every token you do not move comes back verbatim.
+   * Defaults to {@link DEFAULT_THEME_BASE}.
+   */
+  base?: ThemeName;
+  /**
+   * The ground. Moving it re-derives the sunken well, the three raised surfaces
+   * and the three border weights.
+   */
+  bg?: string;
+  /** Primary ink. Moving it re-derives `fg-muted` and `fg-subtle`. */
+  fg?: string;
+  /**
+   * The accent. Moving it re-derives `accent-hover`, `accent-fg`, `focus` and
+   * `selection`.
+   */
+  accent?: string;
+  /** Individual rungs of the surface ladder, overriding whatever would be derived. */
+  surfaces?: Partial<Record<"sunken" | "surface-1" | "surface-2" | "surface-3", string>>;
+  /** Individual status tones. Never derived — a signal colour is a decision. */
+  status?: Partial<Record<"ok" | "busy" | "warn" | "danger" | "info", string>>;
+  /**
+   * Font stacks. `mono` is the one the presets themselves override; `sans` and
+   * `display` are emitted only when given. Values pass through verbatim, so they
+   * are checked for CSS punctuation rather than parsed.
+   */
+  fonts?: Partial<{
+    sans: string;
+    mono: string;
+    display: string;
+  }>;
+  /**
+   * Multiplier on every corner radius. Crossed with the density ladder rather
+   * than declared flat, so `ultra-compact` keeps its tighter corners.
+   */
+  radiusScale?: number;
+  /**
+   * Whether to emit a light block. Defaults to whether the base preset has one.
+   * Setting it `true` on a dark-only preset derives one, and marks the report
+   * provisional.
+   */
+  supportsLight?: boolean;
+}
+interface CreatedTheme {
+  /** The name that was asked for, once validated. */
+  name: string;
+  /**
+   * The stylesheet: the dark block, the light block if there is one, and one
+   * crossed density rule per radius scale that differs from the default's.
+   */
+  css: string;
+  /**
+   * The dark block as a map, keyed by the exact `--cue-*` property names the
+   * tokens build emits. Says the same thing as the dark block of {@link css}.
+   */
+  tokens: Record<string, string>;
+  /** The light block as a map, or `null` when the theme is dark-only. */
+  light: Record<string, string> | null;
+  /** Every WCAG pair, measured. Read it — a failing theme still returns. */
+  report: ContrastReport;
+}
+/**
+ * Generate a theme: a stylesheet, its token map, and a contrast report.
+ *
+ * Pure and synchronous. Call it in a build script, in a test, or in the
+ * 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.
+ * @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.
+ * @example
+ * const { css, report } = createTheme({ name: "acme", base: "terminal", 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 };