@mlola-ui/engine 1.0.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mlola-ui/engine",
+  "version": "1.0.0",
+  "description": "Framework-free CSS, spring easings, and the machine-readable contract for Mlola UI",
+  "type": "module",
+  "sideEffects": [
+    "*.css",
+    "generated/*.css"
+  ],
+  "files": [
+    "generated",
+    "src",
+    "build.mjs"
+  ],
+  "exports": {
+    ".": "./generated/mlola.css",
+    "./tokens.css": "./generated/tokens.css",
+    "./foundations.css": "./generated/foundations.css",
+    "./materials.css": "./generated/materials.css",
+    "./recipes.css": "./generated/recipes.css",
+    "./motion.css": "./generated/motion.css",
+    "./tokens.json": "./generated/tokens.json",
+    "./manifest.json": "./generated/manifest.json"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "check": "node build.mjs --check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Mlola",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mlolahq/mlola-ui.git",
+    "directory": "packages/engine"
+  },
+  "homepage": "https://ui.mlola.com",
+  "bugs": {
+    "url": "https://github.com/mlolahq/mlola-ui/issues"
+  },
+  "keywords": [
+    "mlola",
+    "ui",
+    "design-system",
+    "css",
+    "design-tokens",
+    "theme",
+    "oklch",
+    "accessibility"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/behavior-spec.mjs

@@ -0,0 +1,291 @@
+/**
+ * What a renderer must *do*, as data.
+ *
+ * The stylesheet says what an attribute looks like; this says when to set it.
+ * Kept as plain data so it can be read by a human implementing the library in
+ * Svelte, Vue, Rails or a Go template, by the framework-free runtime in
+ * packages/behavior, and by the audit that proves the two agree.
+ *
+ * Components built on native form controls are deliberately absent: checkbox
+ * and radio are real inputs, so the browser already owns their behaviour and
+ * nothing here can rot. Only the indeterminate flag on a checkbox needs script,
+ * because HTML exposes it as a property rather than an attribute.
+ */
+export const behaviors = {
+  accordion: {
+    summary: "Disclosure list. One panel open at a time, or several.",
+    root: "ml-accordion",
+    parts: {
+      item: "ml-accordion-item",
+      trigger: "ml-accordion-trigger",
+      panel: "ml-accordion-panel",
+    },
+    state: { "data-state": ["open", "closed"] },
+    aria: {
+      trigger: {
+        role: "button (a real <button> is preferred)",
+        "aria-expanded": "true when the item is open",
+        "aria-controls": "id of the panel",
+      },
+      panel: { role: "region", "aria-labelledby": "id of the trigger" },
+    },
+    keyboard: [
+      { keys: ["Enter", "Space"], does: "Toggle the focused item." },
+      { keys: ["ArrowDown", "ArrowUp"], does: "Move focus between triggers." },
+      { keys: ["Home", "End"], does: "Focus the first or last trigger." },
+    ],
+    transitions: [
+      {
+        on: "click or activate a trigger",
+        set: "data-state on the item, trigger and panel",
+        to: "open, or closed when it was open and collapsing is allowed",
+        also: "hide the closed panel from the accessibility tree",
+      },
+    ],
+    options: {
+      multiple: "Allow more than one open item.",
+      collapsible: "Allow closing the last open item. Default true.",
+    },
+  },
+
+  tabs: {
+    summary: "One panel visible at a time, selected by a tab strip.",
+    root: "ml-tabs",
+    parts: {
+      list: "ml-tabs-list",
+      trigger: "ml-tabs-trigger",
+      content: "ml-tabs-content",
+    },
+    state: { "data-state": ["active", "inactive"], "data-orientation": ["horizontal", "vertical"] },
+    aria: {
+      list: { role: "tablist", "aria-orientation": "matches data-orientation" },
+      trigger: {
+        role: "tab",
+        "aria-selected": "true on the active tab",
+        "aria-controls": "id of the panel",
+        tabindex: "0 on the active tab, -1 on the rest",
+      },
+      content: { role: "tabpanel", "aria-labelledby": "id of the tab" },
+    },
+    keyboard: [
+      {
+        keys: ["ArrowRight", "ArrowLeft"],
+        does: "Move to the next or previous enabled tab when horizontal, wrapping around.",
+      },
+      { keys: ["ArrowDown", "ArrowUp"], does: "The same when vertical." },
+      { keys: ["Home", "End"], does: "Move to the first or last enabled tab." },
+    ],
+    transitions: [
+      {
+        on: "select a tab by pointer or key",
+        set: "data-state and aria-selected on triggers, data-state on panels",
+        to: "active for the chosen pair, inactive for the rest",
+        also: "move focus to the newly selected tab",
+      },
+    ],
+    notes: "Selection follows focus. Disabled tabs are skipped, never focused.",
+  },
+
+  "dropdown-menu": {
+    summary: "A menu anchored to a trigger.",
+    root: "ml-dropdown",
+    parts: {
+      trigger: "ml-dropdown-trigger",
+      menu: "ml-dropdown-menu",
+      item: "ml-dropdown-item",
+    },
+    state: { "data-align": ["start", "end"] },
+    signals: { "data-state": ["open", "closed"], "data-highlighted": ["present on the active item"] },
+    aria: {
+      trigger: { "aria-haspopup": "menu", "aria-expanded": "true while open" },
+      menu: { role: "menu" },
+      item: { role: "menuitem", "data-highlighted": "present on the active item" },
+    },
+    keyboard: [
+      { keys: ["ArrowDown", "ArrowUp"], does: "Open the menu, then move the highlight." },
+      { keys: ["Enter", "Space"], does: "Activate the highlighted item." },
+      { keys: ["Escape"], does: "Close and return focus to the trigger." },
+      { keys: ["Tab"], does: "Close without activating." },
+    ],
+    transitions: [
+      { on: "click the trigger", set: "data-state", to: "open or closed" },
+      { on: "pointer over an item", set: "data-highlighted", to: "that item only" },
+      { on: "pointer down outside the root", set: "data-state", to: "closed" },
+    ],
+    notes: "Disabled items are skipped by the highlight and cannot be activated.",
+  },
+
+  select: {
+    summary: "A listbox behind a combobox trigger.",
+    root: "ml-select-root",
+    parts: {
+      trigger: "ml-select",
+      popover: "ml-select-popover",
+      list: "ml-select-list",
+      option: "ml-select-option",
+      search: "ml-select-search",
+    },
+    state: { "data-state": ["open", "closed", "checked", "unchecked"] },
+    aria: {
+      trigger: {
+        role: "combobox",
+        "aria-expanded": "true while open",
+        "aria-controls": "id of the listbox",
+        "aria-activedescendant": "id of the highlighted option while open",
+      },
+      list: { role: "listbox", "aria-multiselectable": "true when multiple" },
+      option: {
+        role: "option",
+        "aria-selected": "true when chosen",
+        "data-highlighted": "present on the active option",
+      },
+    },
+    keyboard: [
+      { keys: ["ArrowDown", "ArrowUp"], does: "Open, then move the highlight past disabled options." },
+      { keys: ["Enter", "Space"], does: "Choose the highlighted option. Space types when a search field has focus." },
+      { keys: ["Home", "End"], does: "Highlight the first or last enabled option." },
+      { keys: ["Escape"], does: "Close and return focus to the trigger." },
+      { keys: ["Tab"], does: "Close without choosing." },
+    ],
+    transitions: [
+      {
+        on: "choose an option",
+        set: "aria-selected and data-state on options",
+        to: "checked for the chosen option",
+        also: "single select closes and restores focus; multiple select stays open",
+      },
+    ],
+    options: { multiple: "Toggle several values and keep the list open." },
+  },
+
+  modal: {
+    summary: "A dialog over the page that owns focus while open.",
+    root: "ml-modal",
+    parts: { overlay: "ml-modal-overlay", close: "ml-modal-close" },
+    state: { "data-size": ["sm", "md", "lg", "xl", "full"] },
+    signals: { "data-state": ["open", "closed"] },
+    aria: {
+      root: {
+        role: "dialog",
+        "aria-modal": "true",
+        "aria-labelledby": "id of the title, or aria-label",
+      },
+    },
+    keyboard: [
+      { keys: ["Escape"], does: "Close, unless closing on Escape is disabled." },
+      { keys: ["Tab", "Shift+Tab"], does: "Cycle focus inside the dialog and never leave it." },
+    ],
+    transitions: [
+      { on: "open", set: "focus", to: "the first focusable element inside", also: "lock page scroll" },
+      { on: "close", set: "focus", to: "the element that opened the dialog", also: "release page scroll" },
+      { on: "pointer down on the backdrop", set: "closed", to: "unless closing on backdrop is disabled" },
+    ],
+  },
+
+  sheet: {
+    summary: "A dialog anchored to one edge of the viewport.",
+    root: "ml-sheet-panel",
+    parts: { overlay: "ml-sheet-overlay", close: "ml-sheet-close" },
+    state: {
+      "data-side": ["left", "right", "top", "bottom"],
+      "data-size": ["sm", "md", "lg"],
+    },
+    signals: { "data-state": ["open", "closed"] },
+    aria: { root: { role: "dialog", "aria-modal": "true" } },
+    keyboard: [
+      { keys: ["Escape"], does: "Close, unless closing on Escape is disabled." },
+      { keys: ["Tab", "Shift+Tab"], does: "Cycle focus inside the panel." },
+    ],
+    transitions: [
+      { on: "open", set: "focus", to: "inside the panel", also: "lock page scroll" },
+      { on: "close", set: "focus", to: "the trigger", also: "release page scroll" },
+    ],
+    notes: "Identical to modal apart from which edge it is anchored to.",
+  },
+
+  tooltip: {
+    summary: "A short label shown on hover or focus.",
+    root: "ml-tooltip-root",
+    parts: { tooltip: "ml-tooltip", arrow: "ml-tooltip-arrow" },
+    state: { "data-side": ["top", "right", "bottom", "left"] },
+    signals: { "data-state": ["open"] },
+    aria: {
+      tooltip: { role: "tooltip" },
+      trigger: { "aria-describedby": "id of the tooltip while it is open" },
+    },
+    keyboard: [{ keys: ["Escape"], does: "Hide the tooltip." }],
+    transitions: [
+      { on: "pointer enter or focus the trigger", set: "visible", to: "after the delay" },
+      { on: "pointer leave or blur", set: "hidden", to: "immediately, cancelling any pending delay" },
+    ],
+    notes: "Never put essential information or interactive content in a tooltip.",
+  },
+
+  toast: {
+    summary: "Transient messages in a live region.",
+    root: "ml-toaster",
+    parts: { toast: "ml-toast", action: "ml-toast-action", close: "ml-toast-close" },
+    state: {
+      "data-tone": ["neutral", "info", "success", "warning", "danger"],
+      "data-position": ["top-right", "top-center", "bottom-right", "bottom-center"],
+    },
+    aria: {
+      root: { role: "region", "aria-label": "distinct per region, so several are distinguishable" },
+      toast: {
+        role: "status for ordinary messages, alert for danger and warning",
+        "aria-live": "polite, or assertive for danger and warning",
+        "aria-busy": "true while it waits on work (a loading toast)",
+      },
+    },
+    keyboard: [{ keys: ["Tab"], does: "Reach the action and dismiss controls." }],
+    transitions: [
+      { on: "push", set: "a toast into the region matching its position", to: "visible" },
+      { on: "duration elapsed", set: "removed", to: "unless the duration is zero" },
+    ],
+  },
+
+  switch: {
+    summary: "An on/off control that is not a native checkbox.",
+    root: "ml-toggle",
+    parts: { thumb: "ml-toggle-thumb" },
+    state: { "data-state": ["checked", "unchecked"], "data-size": ["sm", "md", "lg"] },
+    aria: { root: { role: "switch", "aria-checked": "true or false" } },
+    keyboard: [{ keys: ["Enter", "Space"], does: "Toggle." }],
+    transitions: [{ on: "activate", set: "aria-checked and data-state", to: "the opposite value" }],
+    notes: "Prefer a native checkbox unless the control genuinely reads as a switch.",
+  },
+
+  slider: {
+    summary: "A single value chosen from a range.",
+    root: "ml-slider-field",
+    parts: {
+      control: "ml-slider",
+      track: "ml-slider-track",
+      range: "ml-slider-range",
+      thumb: "ml-slider-thumb",
+    },
+    state: { "data-size": ["sm", "md"] },
+    aria: {
+      thumb: {
+        role: "slider",
+        "aria-valuenow": "current value",
+        "aria-valuemin": "minimum",
+        "aria-valuemax": "maximum",
+        tabindex: "0 unless disabled",
+      },
+    },
+    keyboard: [
+      { keys: ["ArrowRight", "ArrowUp"], does: "Increase by one step." },
+      { keys: ["ArrowLeft", "ArrowDown"], does: "Decrease by one step." },
+      { keys: ["Home", "End"], does: "Jump to the minimum or maximum." },
+      { keys: ["PageUp", "PageDown"], does: "Move by a larger step." },
+    ],
+    transitions: [
+      {
+        on: "pointer down on the track, or drag the thumb",
+        set: "the value from the pointer position, snapped to the step",
+        to: "within min and max",
+      },
+    ],
+  },
+};

package/src/color.mjs

@@ -0,0 +1,150 @@
+/**
+ * Colour math the engine can rely on, in the browser or in Node.
+ *
+ * Everything is OKLCH in and OKLCH out. A colour outside sRGB is brought into
+ * gamut by reducing chroma at a fixed lightness and hue, the same strategy CSS
+ * Color 4 uses, so the value the engine measures is the value the browser
+ * paints. Contrast follows WCAG 2.2.
+ */
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const round = (value, places) => Number(value.toFixed(places));
+
+/** Parse `oklch(L C H / A)` or `#rgb`, `#rrggbb`. Returns null when unreadable. */
+export function parseColor(value) {
+  const text = String(value ?? "").trim();
+  const oklch = text.match(
+    /^oklch\(\s*([\d.]+%?)\s+([\d.]+%?)\s+([\d.]+)(?:deg)?\s*(?:\/\s*([\d.]+%?))?\s*\)$/i,
+  );
+  if (oklch) {
+    const read = (raw, scale) =>
+      raw.endsWith("%") ? (Number.parseFloat(raw) / 100) * scale : Number.parseFloat(raw);
+    return {
+      L: clamp(read(oklch[1], 1), 0, 1),
+      C: Math.max(0, read(oklch[2], 0.4)),
+      H: ((Number.parseFloat(oklch[3]) % 360) + 360) % 360,
+      alpha: oklch[4] === undefined ? 1 : clamp(read(oklch[4], 1), 0, 1),
+    };
+  }
+  const hex = text.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (hex) {
+    const digits = hex[1].length === 3 ? [...hex[1]].map((digit) => digit + digit).join("") : hex[1];
+    const channels = [0, 2, 4].map((offset) => Number.parseInt(digits.slice(offset, offset + 2), 16) / 255);
+    return { ...srgbToOklch(channels), alpha: 1 };
+  }
+  return null;
+}
+
+const decode = (channel) =>
+  channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+const encode = (channel) =>
+  channel <= 0.0031308 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055;
+
+function srgbToOklch([r, g, b]) {
+  const [lr, lg, lb] = [r, g, b].map(decode);
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const bb = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  const C = Math.hypot(a, bb);
+  const H = C < 1e-6 ? 0 : ((Math.atan2(bb, a) * 180) / Math.PI + 360) % 360;
+  return { L, C, H };
+}
+
+/** Linear sRGB for an OKLCH colour, not clamped. */
+function toLinear({ L, C, H }) {
+  const radians = (H * Math.PI) / 180;
+  const a = C * Math.cos(radians);
+  const b = C * Math.sin(radians);
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+const EPSILON = 1e-5;
+const inGamut = (color) => toLinear(color).every((channel) => channel >= -EPSILON && channel <= 1 + EPSILON);
+
+/** Reduce chroma until the colour fits sRGB. Lightness and hue are kept. */
+export function toGamut(color) {
+  const L = clamp(color.L, 0, 1);
+  const candidate = { ...color, L };
+  if (inGamut(candidate)) return candidate;
+  let low = 0;
+  let high = candidate.C;
+  for (let step = 0; step < 24; step += 1) {
+    const middle = (low + high) / 2;
+    if (inGamut({ ...candidate, C: middle })) low = middle;
+    else high = middle;
+  }
+  return { ...candidate, C: low };
+}
+
+/** Gamma-encoded sRGB in 0..1, for an in-gamut colour. */
+export function toSrgb(color) {
+  return toLinear(toGamut(color)).map((channel) => clamp(encode(clamp(channel, 0, 1)), 0, 1));
+}
+
+/** WCAG relative luminance. */
+export function luminance(color) {
+  const [r, g, b] = toLinear(toGamut(color)).map((channel) => clamp(channel, 0, 1));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function composite(top, bottom) {
+  const alpha = top.alpha ?? 1;
+  if (alpha >= 1) return top;
+  const over = toSrgb(top);
+  const under = toSrgb(bottom);
+  const mixed = over.map((channel, index) => channel * alpha + under[index] * (1 - alpha));
+  return { ...srgbToOklch(mixed), alpha: 1 };
+}
+
+/** WCAG 2.2 contrast ratio. Accepts colour strings or parsed colours. */
+export function contrast(foreground, background) {
+  const fg = typeof foreground === "string" ? parseColor(foreground) : foreground;
+  const bg = typeof background === "string" ? parseColor(background) : background;
+  if (!fg || !bg) return null;
+  const top = composite(fg, bg);
+  const a = luminance(top);
+  const b = luminance(bg);
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+
+/** Serialise an OKLCH colour, gamut-mapped, at stable precision. */
+export function formatColor(color) {
+  const mapped = toGamut(color);
+  const chroma = round(mapped.C, 3);
+  const hue = chroma === 0 ? 0 : round(mapped.H, 1);
+  const alpha = mapped.alpha ?? 1;
+  const body = `${round(mapped.L, 3)} ${chroma} ${hue}`;
+  return alpha < 1 ? `oklch(${body} / ${round(alpha, 3)})` : `oklch(${body})`;
+}
+
+/**
+ * Find the lightness closest to `color.L` that reaches `target` contrast
+ * against `against`, moving only in `direction`. Hue and requested chroma are
+ * kept; chroma is reduced only where the gamut demands it. Returns the
+ * extreme when even that cannot reach the target, so callers can detect it.
+ */
+export function solveLightness(color, against, target, direction) {
+  const meets = (L) => contrast({ ...color, L, alpha: 1 }, against) >= target;
+  const start = clamp(color.L, 0, 1);
+  if (meets(start)) return { ...color, L: start };
+  const limit = direction === "darker" ? 0 : 1;
+  if (!meets(limit)) return { ...color, L: limit };
+  let near = start;
+  let far = limit;
+  for (let step = 0; step < 32; step += 1) {
+    const middle = (near + far) / 2;
+    if (meets(middle)) far = middle;
+    else near = middle;
+  }
+  return { ...color, L: far };
+}

package/src/config.mjs

@@ -0,0 +1,170 @@
+import { CHANNELS, normalizeSpec } from "./spec.mjs";
+
+export const dimensions = [
+  ["type", "utilitarian", "editorial"],
+  ["geometry", "rectilinear", "organic"],
+  ["density", "compact", "spacious"],
+  ["depth", "flat", "layered"],
+  ["motion", "still", "kinetic"],
+  ["texture", "polished", "tactile"],
+  ["rhythm", "regular", "syncopated"],
+  ["icon", "systematic", "expressive"],
+];
+
+/**
+ * The theme a page gets when it names none. Every consumer (the `:root`
+ * selector, `normalizeSpec` inheritance, the CLI, the registry, the preview)
+ * reads this instead of hard-coding a name.
+ */
+export const DEFAULT_THEME = "graphite";
+
+/**
+ * The canonical themes, as specs.
+ *
+ * None of them carries a palette. Each is a handful of decisions — eight
+ * channels, a primary seed, the tint of the neutrals, a material and a font
+ * set — and the engine derives every token from those, exactly as it does for
+ * a project theme or one generated from a prompt. There is one path, so the
+ * canonical themes are also the proof that the path works.
+ */
+export const canonicalSpecs = {
+  graphite: {
+    id: "graphite",
+    label: "Graphite",
+    vector: { type: 0.34, geometry: 0.4, density: 0.44, depth: 0.36, motion: 0.36, texture: 0, rhythm: 0.32, icon: 0.36 },
+    color: { primary: "oklch(0.21 0.006 286)", neutral: { hue: 286, chroma: 0.004 } },
+    material: "solid",
+    fonts: "neutral",
+  },
+  atelier: {
+    id: "atelier",
+    label: "Atelier Umami",
+    vector: { type: 0.82, geometry: 0.68, density: 0.58, depth: 0.62, motion: 0.48, texture: 0.78, rhythm: 0.7, icon: 0.82 },
+    color: {
+      primary: "oklch(0.55 0.16 58)",
+      primaryDark: "oklch(0.75 0.16 68)",
+      neutral: { hue: 80, chroma: 0.016 },
+      ink: { hue: 260, chroma: 0.018 },
+    },
+    material: "paper",
+    fonts: "editorial",
+  },
+  machined: {
+    id: "machined",
+    label: "Machined Titanium",
+    vector: { type: 0.22, geometry: 0.05, density: 0.3, depth: 0.34, motion: 0.22, texture: 0.18, rhythm: 0.24, icon: 0.3 },
+    color: {
+      primary: "oklch(0.22 0.01 240)",
+      primaryDark: "oklch(0.78 0.15 210)",
+      neutral: { hue: 240, chroma: 0.004 },
+      ink: { hue: 240, chroma: 0.01 },
+    },
+    material: "anodized",
+    fonts: "technical",
+  },
+  aerogel: {
+    id: "aerogel",
+    label: "Aerogel Glass",
+    vector: { type: 0.54, geometry: 0.92, density: 0.76, depth: 0.94, motion: 0.82, texture: 0.38, rhythm: 0.76, icon: 0.68 },
+    color: {
+      primary: "oklch(0.55 0.24 285)",
+      primaryDark: "oklch(0.75 0.2 285)",
+      neutral: { hue: 260, chroma: 0.018 },
+      ink: { hue: 270, chroma: 0.028 },
+    },
+    material: "glass",
+    fonts: "neutral",
+  },
+  nordic: {
+    id: "nordic",
+    label: "Nordic Earth",
+    vector: { type: 0.62, geometry: 0.74, density: 0.66, depth: 0.46, motion: 0.34, texture: 0.86, rhythm: 0.62, icon: 0.54 },
+    color: {
+      primary: "oklch(0.5 0.14 150)",
+      primaryDark: "oklch(0.72 0.15 150)",
+      neutral: { hue: 135, chroma: 0.018 },
+      ink: { hue: 145, chroma: 0.024 },
+    },
+    material: "solid",
+    fonts: "neutral",
+  },
+};
+
+/** Descriptive copy for the docs and the theme menu. Not read by the engine. */
+const canonicalMeta = {
+  graphite: { genre: "Product & AI", flavor: "Neutral graphite, crisp hairlines, and ink that stays out of the way.", bone: "Tight corners", typography: "Neutral sans throughout" },
+  atelier: { genre: "Editorial & Craft", flavor: "Warm cotton paper, artisanal ink, and an amber signal.", bone: "Soft corners", typography: "Serif display + sans body" },
+  machined: { genre: "Industrial & Telemetry", flavor: "Aerospace telemetry, compact precision, and high contrast.", bone: "Hard corners", typography: "Monospace throughout" },
+  aerogel: { genre: "Liquid AI & Optics", flavor: "Optical luminescence, liquid refraction, and specular depth.", bone: "Fluid radius", typography: "Airy sans" },
+  nordic: { genre: "Organic & Minimal", flavor: "Forest moss, fjord stone, terracotta, and organic calm.", bone: "Organic radius", typography: "Even sans rhythm" },
+};
+
+/**
+ * Canonical themes in the shape the rest of the build reads: the normalised
+ * spec, its vector as an ordered array, and the descriptive copy.
+ */
+export const profiles = Object.fromEntries(
+  Object.entries(canonicalSpecs).map(([id, input]) => {
+    const spec = normalizeSpec(input);
+    return [id, { ...canonicalMeta[id], aliases: [], label: spec.label, spec, vector: CHANNELS.map((channel) => spec.vector[channel]) }];
+  }),
+);
+
+export const coupling = {
+  "type×rhythm": 0.14,
+  "geometry×texture": 0.18,
+  "density×rhythm": -0.1,
+  "depth×texture": 0.2,
+  "depth×motion": 0.16,
+  "motion×rhythm": 0.12,
+  "icon×type": 0.08,
+};
+
+/** Accepts a vector as the ordered array or as an object keyed by channel. */
+function vectorOf(input) {
+  const vector = input.vector ?? input;
+  return Array.isArray(vector) ? vector : CHANNELS.map((channel) => vector[channel] ?? 0);
+}
+
+export function derive(profile) {
+  const [type, geometry, density, depth, motion, texture, rhythm, icon] = vectorOf(profile);
+  const gt = geometry * texture;
+  const dt = depth * texture;
+  const dm = depth * motion;
+  const mr = motion * rhythm;
+  const tr = type * rhythm;
+  const durationNormal = 180 + 140 * motion + 35 * mr;
+
+  // The damped oscillator behind every spatial transition. The motion axis
+  // sets the damping ratio (still ↔ kinetic becomes damped ↔ springy) and the
+  // natural frequency is chosen so the spring settles inside the normal
+  // duration, which keeps CSS transitions and pointer kinetics in step.
+  const springDamping = 0.95 - 0.5 * motion;
+  const springOmega = 4 / (Math.max(0.2, springDamping) * (durationNormal / 1000));
+
+  return {
+    spacing: 3.5 + 1.5 * density - 0.3 * density * rhythm,
+    radius: 2 + 12 * geometry + 4 * gt,
+    border: 1 + 0.45 * (1 - geometry) + 0.2 * texture,
+    shadowY: 2 + 12 * depth + 4 * dm,
+    shadowBlur: 4 + 30 * depth + 10 * dt,
+    shadowAlpha: 0.04 + 0.1 * depth + 0.04 * dt,
+    durationFast: 110 + 80 * motion + 20 * mr,
+    durationNormal,
+    durationSlow: 300 + 260 * motion + 60 * dm,
+    // Entrances that draw something in (a chart, a bar filling): twice the slow step.
+    durationReveal: 2 * (300 + 260 * motion + 60 * dm),
+    springOmega,
+    springDamping,
+    springBounceDamping: Math.max(0.22, springDamping * 0.55),
+    displayWeight: Math.round(690 + 140 * type + 40 * tr),
+    bodyLeading: 1.42 + 0.16 * density + 0.04 * tr,
+    tracking: -0.006 - 0.014 * type + 0.006 * rhythm,
+    iconStroke: 2.1 - 0.55 * icon + 0.12 * (1 - geometry),
+    textureOpacity: 0.01 + 0.055 * texture + 0.02 * dt,
+    // Density sets how much room a control and a panel take. The spacing scale
+    // stays theme-invariant so composed pages still line up.
+    controlHeight: 2 + 0.5 * density - 0.06 * density * rhythm,
+    panelPadding: 1 + 0.75 * density,
+  };
+}