@dowel-ui/themes 0.4.0 → 0.7.0

package/src/colour.ts

@@ -0,0 +1,182 @@
+/**
+ * OKLCH → sRGB, and WCAG contrast.
+ *
+ * The design tokens are authored in OKLCH because its lightness is
+ * perceptually even. WCAG contrast, however, is defined on sRGB relative
+ * luminance — so checking the palette means actually converting it rather than
+ * eyeballing the lightness numbers, which are not the same thing.
+ */
+
+export interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/** Parses `oklch(L C H)` or `oklch(L C H / A)`. L may be a percentage. */
+export function parseOklch(
+  value: string,
+): { l: number; c: number; h: number; alpha: number } | undefined {
+  const match = /^oklch\(\s*([\d.%]+)\s+([\d.]+)\s+([\d.]+)\s*(?:\/\s*([\d.]+)\s*)?\)$/.exec(
+    value.trim(),
+  );
+  if (!match) return undefined;
+
+  const rawL = match[1] ?? "0";
+  const l = rawL.endsWith("%") ? Number.parseFloat(rawL) / 100 : Number.parseFloat(rawL);
+
+  return {
+    l,
+    c: Number.parseFloat(match[2] ?? "0"),
+    h: Number.parseFloat(match[3] ?? "0"),
+    alpha: match[4] === undefined ? 1 : Number.parseFloat(match[4]),
+  };
+}
+
+/** Linear-light sRGB, before gamma encoding. Luminance is defined on these. */
+export function oklchToLinearRgb(l: number, c: number, h: number): Rgb {
+  const hRad = (h * Math.PI) / 180;
+  const a = c * Math.cos(hRad);
+  const bb = c * Math.sin(hRad);
+
+  const lCube = (l + 0.3963377774 * a + 0.2158037573 * bb) ** 3;
+  const mCube = (l - 0.1055613458 * a - 0.0638541728 * bb) ** 3;
+  const sCube = (l - 0.0894841775 * a - 1.291485548 * bb) ** 3;
+
+  return {
+    r: 4.0767416621 * lCube - 3.3077115913 * mCube + 0.2309699292 * sCube,
+    g: -1.2684380046 * lCube + 2.6097574011 * mCube - 0.3413193965 * sCube,
+    b: -0.0041960863 * lCube - 0.7034186147 * mCube + 1.707614701 * sCube,
+  };
+}
+
+function clamp(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+/** WCAG 2.x relative luminance. */
+export function luminance(rgb: Rgb): number {
+  return 0.2126 * clamp(rgb.r) + 0.7152 * clamp(rgb.g) + 0.0722 * clamp(rgb.b);
+}
+
+/**
+ * Composites a translucent colour over an opaque one.
+ *
+ * Several tokens are alpha values over a surface — an overlay, a tinted alert
+ * background. Measuring them without compositing would report the contrast of a
+ * colour nobody ever sees.
+ */
+export function composite(foreground: Rgb, alpha: number, background: Rgb): Rgb {
+  return {
+    r: foreground.r * alpha + background.r * (1 - alpha),
+    g: foreground.g * alpha + background.g * (1 - alpha),
+    b: foreground.b * alpha + background.b * (1 - alpha),
+  };
+}
+
+export function contrastRatio(a: Rgb, b: Rgb): number {
+  const la = luminance(a);
+  const lb = luminance(b);
+  const lighter = Math.max(la, lb);
+  const darker = Math.min(la, lb);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/** `oklch(...)` string to linear RGB, composited over `over` if translucent. */
+export function resolveColour(value: string, over?: Rgb): Rgb | undefined {
+  const parsed = parseOklch(value);
+  if (!parsed) return undefined;
+
+  const rgb = oklchToLinearRgb(parsed.l, parsed.c, parsed.h);
+  if (parsed.alpha >= 1 || !over) return rgb;
+  return composite(rgb, parsed.alpha, over);
+}
+
+/** Gamma-encoded sRGB, 0–255, from linear-light sRGB. */
+export function encodeSrgb(rgb: Rgb): { r: number; g: number; b: number } {
+  const encode = (channel: number) => {
+    const value = clamp(channel);
+    const encoded = value <= 0.0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055;
+    return Math.round(encoded * 255);
+  };
+
+  return { r: encode(rgb.r), g: encode(rgb.g), b: encode(rgb.b) };
+}
+
+/** Linear-light sRGB from gamma-encoded channels, each 0–255. */
+export function decodeSrgb(r: number, g: number, b: number): Rgb {
+  const decode = (channel: number) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  };
+
+  return { r: decode(r), g: decode(g), b: decode(b) };
+}
+
+export interface Oklch {
+  l: number;
+  c: number;
+  h: number;
+}
+
+/**
+ * Linear-light sRGB to OKLCH.
+ *
+ * The inverse of `oklchToLinearRgb`, needed because people pick colours as hex
+ * and the tokens are authored in OKLCH. Round-tripping through this is lossy
+ * only where the input is outside the OKLCH gamut the tokens use, which a hex
+ * value from a colour input never is.
+ */
+export function linearRgbToOklch(rgb: Rgb): Oklch {
+  const lCube = 0.4122214708 * rgb.r + 0.5363325363 * rgb.g + 0.0514459929 * rgb.b;
+  const mCube = 0.2119034982 * rgb.r + 0.6806995451 * rgb.g + 0.1073969566 * rgb.b;
+  const sCube = 0.0883024619 * rgb.r + 0.2817188376 * rgb.g + 0.6299787005 * rgb.b;
+
+  const l_ = Math.cbrt(lCube);
+  const m_ = Math.cbrt(mCube);
+  const s_ = Math.cbrt(sCube);
+
+  const l = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+  const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  const b = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+
+  const c = Math.sqrt(a * a + b * b);
+  // atan2 returns (-180, 180]; hues are conventionally [0, 360).
+  const h = c < 1e-6 ? 0 : ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360;
+
+  return { l, c, h };
+}
+
+/** `#rrggbb` (or `#rgb`) to OKLCH. Undefined for anything else. */
+export function hexToOklch(hex: string): Oklch | undefined {
+  const value = hex.trim().replace(/^#/, "");
+  const full =
+    value.length === 3
+      ? value
+          .split("")
+          .map((digit) => digit + digit)
+          .join("")
+      : value;
+
+  if (!/^[0-9a-f]{6}$/i.test(full)) return undefined;
+
+  return linearRgbToOklch(
+    decodeSrgb(
+      Number.parseInt(full.slice(0, 2), 16),
+      Number.parseInt(full.slice(2, 4), 16),
+      Number.parseInt(full.slice(4, 6), 16),
+    ),
+  );
+}
+
+export function oklchToHex({ l, c, h }: Oklch): string {
+  const { r, g, b } = encodeSrgb(oklchToLinearRgb(l, c, h));
+  const pair = (channel: number) => channel.toString(16).padStart(2, "0");
+  return `#${pair(r)}${pair(g)}${pair(b)}`;
+}
+
+/** An OKLCH triple as the tokens write it. */
+export function formatOklch({ l, c, h }: Oklch): string {
+  const round = (value: number, places: number) => Number(value.toFixed(places)).toString();
+  return `oklch(${round(l, 3)} ${round(c, 3)} ${round(h, 1)})`;
+}

package/src/figma.ts

@@ -0,0 +1,287 @@
+import { encodeSrgb, oklchToLinearRgb, parseOklch, formatOklch } from "./colour";
+import type { DerivedPreset, PresetMode } from "./preset";
+
+/**
+ * The tokens, in the shape a design tool reads.
+ *
+ * The CSS is the source of truth and stays that way — nothing here is a second
+ * palette to keep in step. This reads the same `tokens.css`, `base.css` and
+ * preset files the components consume, resolves every `var()` the way a
+ * browser would, and writes the result as W3C Design Tokens (DTCG): the format
+ * Tokens Studio for Figma imports directly, and the one every other design
+ * tool is converging on.
+ *
+ * Colours come out as sRGB hex. Figma has no OKLCH; converting here, with the
+ * same maths the contrast audit uses, means the swatch a designer sees is the
+ * colour a user gets — rather than whatever a tool makes of an `oklch()` string
+ * it cannot parse.
+ */
+
+/** A flat map of custom property name (without the leading `--`) to raw value. */
+export type Declarations = Record<string, string>;
+
+/** A W3C Design Tokens document: nested groups whose leaves carry `$type` and `$value`. */
+export interface DesignToken {
+  $type: "color" | "dimension" | "fontFamily" | "number";
+  $value: string | number | string[];
+  $description?: string;
+}
+
+export interface DesignTokenGroup {
+  [key: string]: DesignToken | DesignTokenGroup | string | undefined;
+  $description?: string;
+}
+
+/** Strips block comments, which otherwise hide `--x: y;` pairs inside them from the parser. */
+function stripComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/**
+ * The declarations inside the first block whose selector is exactly `selector`.
+ *
+ * Exact, not substring: `.dark` must not match `.dark[data-theme="ocean"]`, and
+ * `:root` must not match `:root[dir="rtl"]`. Whitespace inside a value is
+ * collapsed, because a font stack written over four lines is one value.
+ */
+export function parseTokenCss(css: string, selector: string): Declarations {
+  const clean = stripComments(css);
+  const declarations: Declarations = {};
+
+  let searchFrom = 0;
+  for (;;) {
+    const brace = clean.indexOf("{", searchFrom);
+    if (brace === -1) break;
+
+    // The selector is whatever sits between the previous `}` (or `;`, or the
+    // start) and this `{`.
+    const start = Math.max(
+      clean.lastIndexOf("}", brace),
+      clean.lastIndexOf(";", brace),
+      clean.lastIndexOf("{", brace - 1),
+    );
+    const candidate = clean.slice(start + 1, brace).trim();
+    const end = clean.indexOf("}", brace);
+    if (end === -1) break;
+
+    if (candidate === selector) {
+      const body = clean.slice(brace + 1, end);
+      for (const match of body.matchAll(/--([\w-]+)\s*:\s*([^;]+);/g)) {
+        const name = match[1];
+        const value = match[2];
+        if (name && value) declarations[name] = value.replace(/\s+/g, " ").trim();
+      }
+      return declarations;
+    }
+
+    searchFrom = end + 1;
+  }
+
+  return declarations;
+}
+
+/**
+ * Resolves `var(--x)` references the way the cascade would.
+ *
+ * `scopes` are searched in order, so a mode's own declarations shadow the root's
+ * and the root's shadow the raw scale — which is exactly what `.dark { --x }`
+ * over `:root { --x }` over `@theme { --x }` means. A fallback inside the
+ * `var()` is used when nothing defines the name, and an unresolvable reference
+ * is left as written rather than silently dropped.
+ */
+export function resolveReferences(value: string, scopes: Declarations[]): string {
+  let current = value;
+  // Bounded, so a cycle terminates with the reference left in place rather
+  // than hanging the build.
+  for (let depth = 0; depth < 16; depth += 1) {
+    const next = current.replace(
+      /var\(\s*--([\w-]+)\s*(?:,\s*([^()]*(?:\([^()]*\))?[^()]*))?\)/g,
+      (whole, name: string, fallback: string | undefined) => {
+        for (const scope of scopes) {
+          const found = scope[name];
+          if (found !== undefined) return found;
+        }
+        return fallback?.trim() ?? whole;
+      },
+    );
+    if (next === current) return current;
+    current = next;
+  }
+  return current;
+}
+
+/** `oklch(...)` to `#rrggbb`, or `#rrggbbaa` when it carries alpha. */
+export function cssColourToHex(value: string): string | undefined {
+  const parsed = parseOklch(value.trim());
+  if (!parsed) return undefined;
+
+  const { r, g, b } = encodeSrgb(oklchToLinearRgb(parsed.l, parsed.c, parsed.h));
+  const pair = (channel: number) => channel.toString(16).padStart(2, "0");
+  const rgb = `#${pair(r)}${pair(g)}${pair(b)}`;
+  return parsed.alpha >= 1 ? rgb : `${rgb}${pair(Math.round(parsed.alpha * 255))}`;
+}
+
+const ROOT_FONT_PX = 16;
+
+/**
+ * A length in px, for the values the scale is written in.
+ *
+ * Handles the two shapes the tokens use: a plain `rem`/`px`, and the radius
+ * ladder's `calc(<rem> * var(--radius-scale, 1))`, which is resolved with the
+ * given scale so an exported theme carries the corner radius it was designed
+ * with rather than a formula Figma cannot evaluate.
+ */
+export function cssLengthToPx(value: string, radiusScale = 1): number | undefined {
+  const trimmed = value.trim();
+
+  const calc = /^calc\(\s*([\d.]+)rem\s*\*\s*var\(--radius-scale(?:,\s*[\d.]+)?\)\s*\)$/.exec(
+    trimmed,
+  );
+  if (calc?.[1]) return round(Number.parseFloat(calc[1]) * ROOT_FONT_PX * radiusScale);
+
+  const rem = /^([\d.]+)rem$/.exec(trimmed);
+  if (rem?.[1]) return round(Number.parseFloat(rem[1]) * ROOT_FONT_PX);
+
+  const px = /^([\d.]+)px$/.exec(trimmed);
+  if (px?.[1]) return round(Number.parseFloat(px[1]));
+
+  return undefined;
+}
+
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function px(value: number): string {
+  return `${String(value)}px`;
+}
+
+/** The four tokens a derived preset owns, as declarations, per mode. */
+export function presetDeclarations(preset: DerivedPreset): {
+  light: Declarations;
+  dark: Declarations;
+} {
+  const mode = (entry: PresetMode): Declarations => ({
+    primary: formatOklch(entry.primary),
+    "primary-hover": formatOklch(entry.primaryHover),
+    "primary-active": formatOklch(entry.primaryActive),
+    "primary-foreground": formatOklch(entry.primaryForeground),
+  });
+  return { light: mode(preset.light), dark: mode(preset.dark) };
+}
+
+export interface DesignTokensInput {
+  /** Named in the document, e.g. "ocean" or a studio preset's slug. */
+  name: string;
+  /** The `@theme` block of tokens.css: the raw scales. */
+  scale: Declarations;
+  /** The `:root` block of base.css. */
+  light: Declarations;
+  /** The `.dark` block of base.css. */
+  dark: Declarations;
+  /** A preset's overrides, layered over `light` and `dark`. */
+  preset?: { light: Declarations; dark: Declarations };
+  /** The `--radius-scale` the theme was designed at. */
+  radiusScale?: number;
+}
+
+function colourGroup(
+  declarations: Declarations,
+  scopes: Declarations[],
+  filter: (name: string) => boolean,
+): DesignTokenGroup {
+  const group: DesignTokenGroup = {};
+  for (const [name, raw] of Object.entries(declarations)) {
+    if (!filter(name)) continue;
+    const hex = cssColourToHex(resolveReferences(raw, scopes));
+    if (hex) group[name] = { $type: "color", $value: hex };
+  }
+  return group;
+}
+
+/** `--color-neutral-500` → `neutral.500`, nested. */
+function scaleColours(scale: Declarations): DesignTokenGroup {
+  const group: DesignTokenGroup = {};
+  for (const [name, raw] of Object.entries(scale)) {
+    const match = /^color-([a-z]+)-(\d+)$/.exec(name);
+    if (!match) continue;
+    const [, family, step] = match;
+    if (!family || !step) continue;
+    const hex = cssColourToHex(raw);
+    if (!hex) continue;
+    const familyGroup = (group[family] ??= {}) as DesignTokenGroup;
+    familyGroup[step] = { $type: "color", $value: hex };
+  }
+  return group;
+}
+
+function radii(scale: Declarations, radiusScale: number): DesignTokenGroup {
+  const group: DesignTokenGroup = {};
+  for (const [name, raw] of Object.entries(scale)) {
+    const match = /^radius-([\w]+)$/.exec(name);
+    if (!match?.[1]) continue;
+    const length = cssLengthToPx(raw, radiusScale);
+    if (length !== undefined) group[match[1]] = { $type: "dimension", $value: px(length) };
+  }
+  return group;
+}
+
+function typography(scale: Declarations): DesignTokenGroup {
+  const family: DesignTokenGroup = {};
+  for (const [name, raw] of Object.entries(scale)) {
+    const match = /^font-([a-z]+)$/.exec(name);
+    if (!match?.[1]) continue;
+    family[match[1]] = {
+      $type: "fontFamily",
+      $value: raw.split(",").map((entry) => entry.trim().replace(/^["']|["']$/g, "")),
+    };
+  }
+
+  const size: DesignTokenGroup = {};
+  for (const [name, raw] of Object.entries(scale)) {
+    const step = /^text-([\w]+)$/.exec(name)?.[1];
+    if (!step) continue;
+    const fontSize = cssLengthToPx(raw);
+    if (fontSize === undefined) continue;
+    const entry: DesignTokenGroup = { size: { $type: "dimension", $value: px(fontSize) } };
+    const lineHeight = scale[`text-${step}--line-height`];
+    const lineHeightPx = lineHeight === undefined ? undefined : cssLengthToPx(lineHeight);
+    if (lineHeightPx !== undefined) {
+      entry.lineHeight = { $type: "dimension", $value: px(lineHeightPx) };
+    }
+    size[step] = entry;
+  }
+
+  return { family, text: size };
+}
+
+/**
+ * The whole theme, as a design-tokens document.
+ *
+ * Three sets: `core` (the raw scales, the same in both modes), `light` and
+ * `dark` (the semantic colours, resolved). A designer enables `core` plus one
+ * mode, which mirrors exactly how the CSS composes.
+ */
+export function toDesignTokens(input: DesignTokensInput): DesignTokenGroup {
+  const radiusScale = input.radiusScale ?? 1;
+  const light: Declarations = { ...input.light, ...input.preset?.light };
+  const dark: Declarations = { ...input.dark, ...input.preset?.dark };
+
+  const semantic = (name: string) => name !== "radius-scale" && !name.startsWith("color-");
+
+  return {
+    $description: `Dowel design tokens, preset "${input.name}". Generated from the CSS the components use; colours are sRGB hex converted from OKLCH.`,
+    core: {
+      color: scaleColours(input.scale),
+      radius: radii(input.scale, radiusScale),
+      font: typography(input.scale),
+    },
+    light: {
+      color: colourGroup(light, [light, input.scale], semantic),
+    },
+    dark: {
+      // Dark declares only what differs; the rest inherits from the root.
+      color: colourGroup({ ...light, ...dark }, [dark, light, input.scale], semantic),
+    },
+  };
+}

package/src/index.ts

@@ -1,3 +1,46 @@
+export {
+  checkPreset,
+  derivePreset,
+  foregroundFor,
+  formatPreset,
+  slugify,
+  TEXT_MINIMUM,
+  type ContrastCheck,
+  type DerivedPreset,
+  type DeriveOptions,
+  type PresetMode,
+} from "./preset";
+
+export {
+  cssColourToHex,
+  cssLengthToPx,
+  parseTokenCss,
+  presetDeclarations,
+  resolveReferences,
+  toDesignTokens,
+  type Declarations,
+  type DesignToken,
+  type DesignTokenGroup,
+  type DesignTokensInput,
+} from "./figma";
+
+export {
+  composite,
+  contrastRatio,
+  decodeSrgb,
+  encodeSrgb,
+  formatOklch,
+  hexToOklch,
+  linearRgbToOklch,
+  luminance,
+  oklchToHex,
+  oklchToLinearRgb,
+  parseOklch,
+  resolveColour,
+  type Oklch,
+  type Rgb,
+} from "./colour";
+
 /**
  * Typed surface of the theme layer. The CSS is the implementation; these
  * constants exist so theme switchers, the docs playground and the future CLI

package/src/preset.ts

@@ -0,0 +1,191 @@
+import { contrastRatio, formatOklch, oklchToLinearRgb, type Oklch } from "./colour";
+
+/**
+ * Deriving a theme preset from a single colour.
+ *
+ * A preset in this system reassigns four tokens per mode and inherits
+ * everything else, so building one is not a palette exercise — it is picking a
+ * primary and then answering three questions the shipped presets already
+ * answer: what it looks like pressed, what it looks like in dark mode, and what
+ * text can be read on it.
+ *
+ * The deltas below are read off the presets that ship. They are not arbitrary:
+ * every one of those passes the contrast audit in both modes, so starting from
+ * the same relationships means a derived preset starts somewhere that works.
+ */
+
+/** Lightness step from the base colour to its hover state, in light mode. */
+const LIGHT_HOVER_DELTA = -0.045;
+/** And to its active state, which is a press and reads as further down. */
+const LIGHT_ACTIVE_DELTA = -0.083;
+
+/**
+ * Dark mode raises lightness and drops chroma.
+ *
+ * A colour that reads as saturated on white reads as glaring on near-black, and
+ * one dark enough to sit on white disappears into the background.
+ */
+const DARK_LIGHTNESS_DELTA = 0.115;
+const DARK_CHROMA_DELTA = -0.015;
+const DARK_HOVER_DELTA = 0.045;
+const DARK_ACTIVE_DELTA = -0.045;
+
+/** The near-white the shipped presets use for text on a saturated colour. */
+const LIGHT_FOREGROUND: Oklch = { l: 0.985, c: 0.002, h: 265 };
+
+/** WCAG 2.2 AA for normal text; a button label is normal text. */
+export const TEXT_MINIMUM = 4.5;
+
+function clampLightness(value: number): number {
+  return Math.min(0.99, Math.max(0.01, value));
+}
+
+function ratio(a: Oklch, b: Oklch): number {
+  return contrastRatio(oklchToLinearRgb(a.l, a.c, a.h), oklchToLinearRgb(b.l, b.c, b.h));
+}
+
+/**
+ * Text for a saturated background: near-white, or a dark tint of its own hue.
+ *
+ * Whichever reads better, rather than always white. A light primary — amber,
+ * lime — cannot carry white text at 4.5:1 no matter how it is nudged, and the
+ * shipped `amber` preset is dark-on-light for exactly this reason.
+ */
+export function foregroundFor(background: Oklch): Oklch {
+  const dark: Oklch = { l: 0.155, c: 0.03, h: background.h };
+  return ratio(LIGHT_FOREGROUND, background) >= ratio(dark, background)
+    ? LIGHT_FOREGROUND
+    : dark;
+}
+
+export interface PresetMode {
+  primary: Oklch;
+  primaryHover: Oklch;
+  primaryActive: Oklch;
+  primaryForeground: Oklch;
+}
+
+export interface DerivedPreset {
+  light: PresetMode;
+  dark: PresetMode;
+}
+
+export interface DeriveOptions {
+  /**
+   * Lightness of the dark-mode primary.
+   *
+   * Overridable because it is the one derived value with no single right
+   * answer: how bright a brand reads on near-black is a judgement about the
+   * brand, not about contrast.
+   */
+  darkLightness?: number;
+}
+
+export function derivePreset(input: Oklch, options: DeriveOptions = {}): DerivedPreset {
+  // Clamped on the way in as well as on the way out. Every value this returns
+  // is one it is responsible for, including the one it was handed: a preset
+  // built on pure black is not a preset anyone can use, and passing it through
+  // untouched would mean the only unusable value in the output is the one that
+  // was never checked.
+  const primary: Oklch = { ...input, l: clampLightness(input.l), c: Math.max(0, input.c) };
+
+  const light: PresetMode = {
+    primary,
+    primaryHover: { ...primary, l: clampLightness(primary.l + LIGHT_HOVER_DELTA) },
+    primaryActive: { ...primary, l: clampLightness(primary.l + LIGHT_ACTIVE_DELTA) },
+    primaryForeground: foregroundFor(primary),
+  };
+
+  const darkPrimary: Oklch = {
+    l: clampLightness(options.darkLightness ?? primary.l + DARK_LIGHTNESS_DELTA),
+    c: Math.max(0, primary.c + DARK_CHROMA_DELTA),
+    h: primary.h,
+  };
+
+  const dark: PresetMode = {
+    primary: darkPrimary,
+    primaryHover: { ...darkPrimary, l: clampLightness(darkPrimary.l + DARK_HOVER_DELTA) },
+    primaryActive: { ...darkPrimary, l: clampLightness(darkPrimary.l + DARK_ACTIVE_DELTA) },
+    primaryForeground: foregroundFor(darkPrimary),
+  };
+
+  return { light, dark };
+}
+
+export interface ContrastCheck {
+  label: string;
+  ratio: number;
+  minimum: number;
+  passes: boolean;
+}
+
+/**
+ * The pairs a derived preset is responsible for.
+ *
+ * Only these four per mode: every other pair in the system is inherited from
+ * the base tokens, which the audit already covers. Reporting the inherited ones
+ * would be reporting on something the person cannot change from here.
+ */
+export function checkPreset(preset: DerivedPreset): ContrastCheck[] {
+  const checks: ContrastCheck[] = [];
+
+  for (const [mode, values] of [
+    ["Light", preset.light],
+    ["Dark", preset.dark],
+  ] as const) {
+    for (const [state, background] of [
+      ["primary", values.primary],
+      ["primary-hover", values.primaryHover],
+      ["primary-active", values.primaryActive],
+    ] as const) {
+      checks.push({
+        label: `${mode}: primary-foreground on ${state}`,
+        ratio: ratio(values.primaryForeground, background),
+        minimum: TEXT_MINIMUM,
+        passes: ratio(values.primaryForeground, background) >= TEXT_MINIMUM,
+      });
+    }
+  }
+
+  return checks;
+}
+
+function block(selector: string, mode: PresetMode): string {
+  return [
+    `${selector} {`,
+    `  --primary: ${formatOklch(mode.primary)};`,
+    `  --primary-hover: ${formatOklch(mode.primaryHover)};`,
+    `  --primary-active: ${formatOklch(mode.primaryActive)};`,
+    `  --primary-foreground: ${formatOklch(mode.primaryForeground)};`,
+    `}`,
+  ].join("\n");
+}
+
+/**
+ * The preset as a stylesheet, in the same shape as the ones that ship.
+ *
+ * Deliberately the same file format rather than a bespoke export: what comes
+ * out of here can be dropped into `packages/themes/src/presets/` unchanged, and
+ * is then covered by the same audit as everything else.
+ */
+export function formatPreset(name: string, preset: DerivedPreset): string {
+  return [
+    `/* Theme preset: ${name}.`,
+    ` * Apply with data-theme="${name}" on the <html> element. Only the brand-carrying`,
+    ` * tokens are reassigned; every neutral, radius and motion token is inherited. */`,
+    "",
+    block(`[data-theme="${name}"]`, preset.light),
+    "",
+    block(`.dark[data-theme="${name}"]`, preset.dark),
+    "",
+  ].join("\n");
+}
+
+/** A name usable as a `data-theme` value. */
+export function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "custom";
+}