@scattered-light/loomiere 0.0.0-stage → 0.1.1

package/generator/roles.mjs

@@ -0,0 +1,258 @@
+/**
+ * Roles: which palette plays which part, and the emphasis ladder components draw from.
+ *
+ *   roles.chrome    the palette for surfaces, text and borders (a neutral-table palette)
+ *   roles.accent    the palette for links, focus and the loudest actions (any spot palette)
+ *   roles.emphasis  four levels, each a style and a color:
+ *                   { bold: { style: "solid", color: "accent" }, standard: …, subtle: …, quiet: … }
+ *   roles.concepts  optional picks that replace a role's default step for one concept:
+ *                   { "chrome.fg": { light: "primary.1000" } }. A pick is "palette.step",
+ *                   "white" (paper), "black" (ink) or a hex. Modes left out keep the default.
+ *
+ * Every palette also gets a scope: the same slots (solid, soft, border, text…) at fixed
+ * steps, so any palette can stand in for another. That works because spot palettes share a
+ * contrast table, so step 600 has the same contrast in every hue. A page re-colors a part
+ * with data-color="secondary"; data-emphasis="subtle" applies a level.
+ */
+
+/**
+ * Slot → [light step, dark step, other modes?], per contrast table. This table is the only
+ * place that decides which step a concept uses in light, dark and high contrast; semantic
+ * tokens point at slots and never at steps. `on.N` is step N's on-color; `white` and
+ * `black` are the brand's paper and ink.
+ */
+export const SLOTS = {
+  spot: {
+    solid: [600, 400],
+    'solid-hover': [700, 300],
+    'solid-active': [800, 200],
+    'on-solid': ['on.600', 'on.400'],
+    soft: [50, 1000],
+    'soft-hover': [100, 900],
+    'soft-active': [200, 800],
+    'soft-strong': [300, 700],
+    'on-soft': [800, 100],
+    ink: [900, 75],
+    border: [600, 400],
+    'border-subtle': [200, 900],
+    fg: [700, 200],
+    signal: [500, 400],
+    focus: [500, 400],
+  },
+  // Chrome palettes run lighter to darker over more steps; their solid is the inverse surface.
+  // They also carry the page concepts: canvas, raised, overlay, modal and tray surfaces, text levels, dividers, tracks.
+  neutral: {
+    solid: [1100, 100],
+    'solid-hover': [1000, 200],
+    'solid-active': [900, 300],
+    'on-solid': ['on.1100', 'on.100'],
+    soft: [200, 900],
+    'soft-hover': [300, 800],
+    'soft-active': [400, 700],
+    'soft-strong': [500, 600],
+    'on-soft': [1200, 50],
+    border: [800, 600],
+    'border-hover': [900, 400],
+    'border-subtle': [200, 900],
+    'border-strong': [800, 700, { 'contrast-more': 900, 'dark-contrast-more': 200 }],
+    divider: [300, 800, { 'contrast-more': 700, 'dark-contrast-more': 400 }],
+    fg: [1200, 'white'],
+    'fg-secondary': [1000, 300, { 'contrast-more': 1100, 'dark-contrast-more': 100 }],
+    'fg-tertiary': [900, 400, { 'contrast-more': 1000 }],
+    focus: [800, 400],
+    canvas: ['white', 1200],
+    raised: [50, 1100],
+    overlay: [100, 1000],
+    modal: ['white', 1100],
+    tray: [50, 1000],
+    inverse: [1100, 900],
+    'on-inverse': ['on.1100', 'on.900'],
+    // The empty part of a meter or progress bar. Dark mode goes near the page so any palette's fill reads 3:1 on it.
+    track: [200, 1100],
+  },
+};
+
+/** The token a slot step stands for in one palette. */
+export const stepRef = (palette, step) => (step === 'white' || step === 'black' ? `{color.${step}}` : `{color.${palette}.${step}}`);
+
+/**
+ * The concepts the builder shows as rows, by role. `against` is what the color is read on
+ * (text) or sits beside (lines and fills), for the contrast column; `min` is the ratio it
+ * should reach there.
+ */
+export const CONCEPTS = [
+  { role: 'chrome', group: 'Surfaces', slot: 'canvas', label: 'Page', against: 'fg', min: 4.5 },
+  { role: 'chrome', group: 'Surfaces', slot: 'raised', label: 'Cards and panels', against: 'fg', min: 4.5 },
+  { role: 'chrome', group: 'Surfaces', slot: 'overlay', label: 'Menus, popovers, inline code', against: 'fg', min: 4.5 },
+  { role: 'chrome', group: 'Surfaces', slot: 'modal', label: 'Dialogs and drawers', against: 'fg', min: 4.5 },
+  { role: 'chrome', group: 'Surfaces', slot: 'tray', label: 'Toolbars and toggle groups', against: 'fg', min: 4.5 },
+  { role: 'chrome', group: 'Surfaces', slot: 'inverse', label: 'Inverse surface (tooltips)', against: 'on-inverse', min: 4.5 },
+  { role: 'chrome', group: 'Surfaces', slot: 'on-inverse', label: 'Text on the inverse surface', against: 'inverse', min: 4.5 },
+  { role: 'chrome', group: 'Text', slot: 'fg', label: 'Body text and prose', against: 'canvas', min: 4.5 },
+  { role: 'chrome', group: 'Text', slot: 'fg-secondary', label: 'Secondary text', against: 'canvas', min: 4.5 },
+  { role: 'chrome', group: 'Text', slot: 'fg-tertiary', label: 'Tertiary text', against: 'canvas', min: 4.5 },
+  { role: 'chrome', group: 'Text', slot: 'soft-strong', label: 'Disabled text', against: 'canvas' },
+  { role: 'chrome', group: 'Lines', slot: 'border', label: 'Control borders', against: 'canvas', min: 3 },
+  { role: 'chrome', group: 'Lines', slot: 'border-hover', label: 'Control border on hover', against: 'canvas', min: 3 },
+  { role: 'chrome', group: 'Lines', slot: 'border-strong', label: 'Strong borders', against: 'canvas', min: 3 },
+  { role: 'chrome', group: 'Lines', slot: 'divider', label: 'Dividers', against: 'canvas' },
+  { role: 'chrome', group: 'Lines', slot: 'border-subtle', label: 'Hairlines', against: 'canvas' },
+  { role: 'chrome', group: 'Fills', slot: 'soft', label: 'Subtle fill', against: 'canvas' },
+  { role: 'chrome', group: 'Fills', slot: 'soft-hover', label: 'Default fill', against: 'canvas' },
+  { role: 'chrome', group: 'Fills', slot: 'soft-active', label: 'Strong fill, disabled controls', against: 'canvas' },
+  { role: 'chrome', group: 'Fills', slot: 'track', label: 'Meter and progress tracks', against: 'canvas' },
+  { role: 'chrome', group: 'Fills', slot: 'solid', label: 'Solid chip (keycaps)', against: 'on-solid', min: 4.5 },
+  { role: 'chrome', group: 'Fills', slot: 'on-solid', label: 'Text on the solid chip', against: 'solid', min: 4.5 },
+  { role: 'accent', group: 'Accent', slot: 'solid', label: 'Buttons, links, focus ring', against: 'canvas', min: 3 },
+  { role: 'accent', group: 'Accent', slot: 'solid-hover', label: 'Hover', against: 'canvas', min: 3 },
+  { role: 'accent', group: 'Accent', slot: 'solid-active', label: 'Pressed', against: 'canvas', min: 3 },
+  { role: 'accent', group: 'Accent', slot: 'on-solid', label: 'Text on accent', against: 'solid', min: 4.5 },
+  { role: 'accent', group: 'Accent', slot: 'fg', label: 'Accent text, active tab', against: 'canvas', min: 4.5 },
+  { role: 'accent', group: 'Accent', slot: 'focus', label: 'Focus outline', against: 'canvas', min: 3 },
+  { role: 'accent', group: 'Tints', slot: 'soft', label: 'Tint', against: 'canvas' },
+  { role: 'accent', group: 'Tints', slot: 'soft-hover', label: 'Tint hover, selection, mark', against: 'canvas' },
+  { role: 'accent', group: 'Tints', slot: 'soft-active', label: 'Tint pressed', against: 'canvas' },
+  { role: 'accent', group: 'Tints', slot: 'soft-strong', label: 'Strong tint', against: 'canvas' },
+  { role: 'accent', group: 'Tints', slot: 'on-soft', label: 'Text on a tint, inline code', against: 'soft', min: 4.5 },
+  { role: 'accent', group: 'Tints', slot: 'ink', label: 'Text on a strong tint', against: 'soft-strong', min: 4.5 },
+];
+
+/** How each emphasis style reads the scope's slots, part by part. */
+export const STYLES = {
+  solid: { bg: 'solid', 'bg-hover': 'solid-hover', 'bg-active': 'solid-active', fg: 'on-solid', border: 'solid', 'border-hover': 'solid-hover' },
+  soft: { bg: 'soft', 'bg-hover': 'soft-hover', 'bg-active': 'soft-active', fg: 'on-soft', border: 'soft', 'border-hover': 'soft-hover' },
+  outline: { bg: 'transparent', 'bg-hover': 'soft', 'bg-active': 'soft-hover', fg: 'fg', border: 'border', 'border-hover': 'solid-hover' },
+  ghost: { bg: 'transparent', 'bg-hover': 'soft', 'bg-active': 'soft-hover', fg: 'fg', border: 'transparent', 'border-hover': 'transparent' },
+};
+export const PARTS = Object.keys(STYLES.solid);
+export const LEVELS = ['bold', 'standard', 'subtle', 'quiet'];
+
+export const DEFAULT_ROLES = {
+  chrome: 'neutral',
+  accent: 'primary',
+  emphasis: {
+    bold: { style: 'solid', color: 'accent' },
+    standard: { style: 'outline', color: 'accent' },
+    subtle: { style: 'soft', color: 'chrome' },
+    quiet: { style: 'outline', color: 'chrome' },
+  },
+};
+
+const tableOf = (palette) => (palette.contrast === 'neutral' ? 'neutral' : 'spot');
+
+/** The palette name a color choice ("accent", "chrome" or a palette role) stands for. */
+export const paletteFor = (roles, color) => (color === 'accent' ? roles.accent : color === 'chrome' ? roles.chrome : color);
+
+/** A brand's roles with every missing setting taken from the defaults. */
+export const withDefaults = (roles = {}) => ({
+  ...DEFAULT_ROLES,
+  ...roles,
+  emphasis: Object.fromEntries(LEVELS.map((level) => [level, { ...DEFAULT_ROLES.emphasis[level], ...roles.emphasis?.[level] }])),
+});
+
+/**
+ * A concept pick as a token value: "palette.step" and "white"/"black" become references,
+ * a hex stays a hex. Returns undefined for anything else.
+ */
+export function pickRef(pick, palettes) {
+  if (pick === 'white' || pick === 'black') return `{color.${pick}}`;
+  if (/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(pick)) return pick.toLowerCase();
+  const m = /^([\w-]+)\.((?:on\.)?\d+)$/.exec(String(pick));
+  return m && palettes[m[1]] ? `{color.${m[1]}.${m[2]}}` : undefined;
+}
+
+/** A slot's default as a pick, in the same form a brand file writes ("neutral.1200", "white"). */
+export const defaultPick = (palette, step) => (step === 'white' || step === 'black' ? step : `${palette}.${step}`);
+
+/**
+ * One role concept's values in every mode, as token values, with the brand's picks applied.
+ * A pick for light replaces the high-contrast light step too, and dark likewise, since
+ * those were chosen to go with the default.
+ */
+export function conceptModes(brand, roles, role, slot) {
+  const palettes = brand.color.palettes;
+  const name = roles[role];
+  const [light, dark, more = {}] = SLOTS[tableOf(palettes[name])][slot];
+  const pick = roles.concepts?.[`${role}.${slot}`] ?? {};
+  const out = {
+    light: pick.light !== undefined ? pickRef(pick.light, palettes) : stepRef(name, light),
+    dark: pick.dark !== undefined ? pickRef(pick.dark, palettes) : stepRef(name, dark),
+  };
+  if (more['contrast-more'] !== undefined && pick.light === undefined) out['contrast-more'] = stepRef(name, more['contrast-more']);
+  if (more['dark-contrast-more'] !== undefined && pick.dark === undefined) out['dark-contrast-more'] = stepRef(name, more['dark-contrast-more']);
+  return out;
+}
+
+/** Roles with defaults filled in, checked against the brand's palettes. */
+export function resolveRoles(brand) {
+  const roles = withDefaults(brand.roles);
+  const palettes = brand.color.palettes;
+  const problems = [];
+  if (!palettes[roles.chrome]) problems.push(`roles.chrome is "${roles.chrome}", which is not a palette`);
+  if (!palettes[roles.accent]) problems.push(`roles.accent is "${roles.accent}", which is not a palette`);
+  for (const [level, { style, color }] of Object.entries(roles.emphasis)) {
+    if (!STYLES[style]) problems.push(`roles.emphasis.${level}.style "${style}" is not one of ${Object.keys(STYLES).join(', ')}`);
+    if (!palettes[paletteFor(roles, color)]) problems.push(`roles.emphasis.${level}.color "${color}" is not accent, chrome or a palette`);
+  }
+  for (const [key, pick] of Object.entries(roles.concepts ?? {})) {
+    const [role, slot] = key.split('.');
+    const palette = palettes[roles[role]];
+    if (!['chrome', 'accent'].includes(role) || !palette || !SLOTS[tableOf(palette)][slot]) {
+      problems.push(`roles.concepts "${key}" is not a chrome or accent concept`);
+      continue;
+    }
+    for (const [mode, value] of Object.entries(pick)) {
+      if (!['light', 'dark'].includes(mode)) problems.push(`roles.concepts.${key}.${mode}: only light and dark can be picked`);
+      else if (pickRef(value, palettes) === undefined) problems.push(`roles.concepts.${key}.${mode} "${value}" is not palette.step, white, black or a hex`);
+    }
+  }
+  if (problems.length) throw new Error(`Roles: ${problems.join('; ')}`);
+  return roles;
+}
+
+const token = (type, value, description, modes) => ({
+  $type: type,
+  $value: value,
+  ...(description && { $description: description }),
+  ...(modes && { $extensions: { 'sl.modes': modes } }),
+});
+
+/**
+ * tokens/semantic/scope.json and emphasis.json:
+ *   scope.<palette>.<slot>  every palette's slots, plus scope.accent and scope.chrome
+ *   emphasis.<level>.<part> each level's colors at its default palette
+ */
+export function generateRoleTokens(brand) {
+  const roles = resolveRoles(brand);
+  const scope = {};
+  for (const [name, palette] of Object.entries(brand.color.palettes)) {
+    scope[name] = {};
+    for (const [slot, [light, dark, more = {}]] of Object.entries(SLOTS[tableOf(palette)])) {
+      const modes = { dark: stepRef(name, dark), ...Object.fromEntries(Object.entries(more).map(([mode, step]) => [mode, stepRef(name, step)])) };
+      scope[name][slot] = token('color', stepRef(name, light), `${name} ${slot}: ${light} in light, ${dark} in dark`, modes);
+    }
+  }
+  for (const role of ['accent', 'chrome']) {
+    const name = roles[role];
+    scope[role] = Object.fromEntries(
+      Object.keys(scope[name]).map((slot) => {
+        if (!roles.concepts?.[`${role}.${slot}`]) return [slot, token('color', `{scope.${name}.${slot}}`, `The ${role} role is ${name}.`)];
+        // A picked concept no longer follows the palette's slot, so it carries its own modes.
+        const { light, ...modes } = conceptModes(brand, roles, role, slot);
+        return [slot, token('color', light, `${role} ${slot}, picked in the brand file (roles.concepts).`, modes)];
+      }),
+    );
+  }
+
+  const emphasis = {};
+  for (const level of LEVELS) {
+    const { style, color } = roles.emphasis[level];
+    const palette = paletteFor(roles, color);
+    emphasis[level] = {};
+    for (const [part, slot] of Object.entries(STYLES[style])) {
+      const value = slot === 'transparent' ? 'transparent' : `{scope.${color}.${slot}}`;
+      emphasis[level][part] = token('color', value, `${level}: ${style} in ${color === palette ? palette : `${color} (${palette})`}`);
+    }
+  }
+  return { scope: { scope }, emphasis: { emphasis }, roles };
+}

package/generator/vision.mjs

@@ -0,0 +1,167 @@
+/**
+ * Color vision themes: versions of the alert and data colors designed for each kind of
+ * color blindness, generated from the brand's own colors (so every brand gets its own).
+ *
+ * Every spot palette (brand colors and alerts; the neutral stays) moves until the colors
+ * that stand for them are as far apart as possible as seen with that kind of vision,
+ * without wandering further from the brand than they need to; brand colors cost more to
+ * move than alerts. For the three color blindnesses they turn hue and keep lightness and
+ * chroma; with no color vision at all hue means nothing, so they move lightness instead. Either way each
+ * ramp is rebuilt on the same contrast table, so every step keeps its contrast. Data
+ * colors are nudged, in series order, until each is distinct from the two before and
+ * after it as seen with that vision, and never lose contrast on paper.
+ *
+ * A brand can pin any generated color: color.vision.deuteranopia.keys.primary = "#…" or
+ * color.vision.deuteranopia.data.coral = "#…"; the others move to make room.
+ */
+import { differenceCiede2000, formatHex, oklch, wcagContrast } from 'culori';
+
+import { dataColorPasses, nudgeDataColor, VISIONS } from './data-colors.mjs';
+
+const turnHue = {
+  cost: 0.05,
+  amounts: range(-60, 60, 5),
+  // An alert turned further than this stops reading as its kind (a green success turned yellow).
+  alertLimit: 40,
+  move: (c, dh) => ({ ...c, h: ((c.h ?? 0) + dh + 360) % 360 }),
+  between: (from, to) => ((((to.h ?? 0) - (from.h ?? 0)) % 360) + 540) % 360 - 180,
+};
+// Lightness only darkens, so no color loses contrast on paper.
+const shiftLightness = {
+  cost: 5,
+  amounts: range(-0.4, 0, 0.02),
+  move: (c, dl) => ({ ...c, l: Math.min(0.97, Math.max(0.2, c.l + dl)) }),
+  between: (from, to) => to.l - from.l,
+};
+
+/** Most common first. `sees` is the simulation the theme is designed against. */
+export const VISION_THEMES = {
+  deuteranopia: { name: 'Deuteranopia', label: 'green-blind, the most common', sees: 'deutan', moves: turnHue },
+  protanopia: { name: 'Protanopia', label: 'red-blind', sees: 'protan', moves: turnHue },
+  tritanopia: { name: 'Tritanopia', label: 'blue-blind, rare', sees: 'tritan', moves: turnHue },
+  achromatopsia: { name: 'Achromatopsia', label: 'no color vision, or a grayscale screen', sees: 'achromat', moves: shiftLightness },
+};
+export const ALERT_ROLES = ['success', 'warning', 'error', 'info'];
+/** Brand colors carry identity, so they cost four times as much to move as alerts. */
+const BRAND_WEIGHT = 4;
+
+/** ΔE neighbors need in a vision theme: more than the everyday check, since it is the point. */
+const THEME_DISTINCT = 15;
+/** ΔE at which two colors are plainly different; further apart gains nothing. */
+const ENOUGH = 25;
+/** ΔE of lost difference past which a pair counts as blurred together. */
+const BLURRED = 8;
+function range(from, to, step) {
+  const out = [];
+  for (let x = from; x <= to + 1e-9; x += step) out.push(Math.round(x * 1000) / 1000);
+  return out;
+}
+
+const ΔE = differenceCiede2000();
+const moveHex = (moves, hex, amount) => formatHex(moves.move(oklch(hex), amount));
+
+/**
+ * What a vision loses: for each pair of colors, how much of the difference typical vision
+ * sees (up to ENOUGH) is gone when seen with `sees`. Pairs that look alike to everyone
+ * (an ember brand color and an error red) lose nothing, so nothing pushes them apart.
+ */
+function losses(hexes, sees) {
+  const seen = hexes.map((h) => VISIONS[sees].see(h));
+  const out = [];
+  for (let a = 0; a < hexes.length; a++) for (let b = a + 1; b < hexes.length; b++) {
+    const wanted = Math.min(ΔE(hexes[a], hexes[b]), ENOUGH);
+    out.push(Math.max(0, wanted - ΔE(seen[a], seen[b])));
+  }
+  return out;
+}
+
+/** Pairs that blur together: they lose more than BLURRED of their difference. */
+const blurred = (hexes, sees) => losses(hexes, sees).filter((l) => l > BLURRED).length;
+
+/**
+ * How far to move each palette (degrees of hue, or lightness). Coordinate search: move one
+ * role at a time to the amount that most reduces what the vision loses (squared, so the
+ * worst pair counts most), plus the cost of moving, until nothing moves. Pinned roles sit
+ * where they were pinned.
+ */
+function paletteMoves(keys, sees, moves, pinned) {
+  const roles = Object.keys(keys);
+  const amount = Object.fromEntries(roles.map((r) => [r, 0]));
+  const weight = (r) => (ALERT_ROLES.includes(r) ? 1 : BRAND_WEIGHT);
+  const hexes = () => roles.map((r) => pinned[r] ?? moveHex(moves, keys[r], amount[r]));
+  const score = () =>
+    -losses(hexes(), sees).reduce((sum, l) => sum + l * l, 0) / ENOUGH -
+    moves.cost * roles.reduce((total, r) => total + weight(r) * Math.abs(amount[r]), 0);
+  for (let round = 0; round < 6; round++) {
+    let moved = false;
+    for (const r of roles) {
+      if (pinned[r]) continue;
+      let best = amount[r], bestScore = score();
+      for (const a of moves.amounts) {
+        if (moves.alertLimit && ALERT_ROLES.includes(r) && Math.abs(a) > moves.alertLimit) continue;
+        amount[r] = a;
+        const s = score();
+        if (s > bestScore + 1e-6) [best, bestScore] = [a, s];
+      }
+      if (best !== amount[r]) moved = true;
+      amount[r] = best;
+    }
+    if (!moved) break;
+  }
+  return amount;
+}
+
+/** The key that stands for a palette: its most colorful one. */
+const representative = (keys) => keys.reduce((a, b) => ((oklch(b).c ?? 0) > (oklch(a).c ?? 0) ? b : a));
+
+/**
+ * Per theme: every spot palette with moved keys (the neutral stays), the data colors, the
+ * color that stands for each palette, and how many pairs of those blur together for that
+ * vision before and after. Pins come from color.vision.<theme>: keys.<role> (that palette's
+ * representative color) and data.<name>.
+ */
+let last = { key: '', value: null };
+
+export function visionColors(color) {
+  // The builder recomputes on every keystroke; only the palettes, data and paper matter here.
+  const key = JSON.stringify([color.paper, color.data, color.vision, color.palettes]);
+  if (key === last.key) return last.value;
+  const out = {};
+  const roles = Object.keys(color.palettes).filter((r) => color.palettes[r].keys?.length && color.palettes[r].contrast !== 'neutral');
+  const reps = Object.fromEntries(roles.map((r) => [r, representative(color.palettes[r].keys)]));
+  for (const [theme, { sees, moves }] of Object.entries(VISION_THEMES)) {
+    const pinned = color.vision?.[theme]?.keys ?? {};
+    const amounts = paletteMoves(reps, sees, moves, pinned);
+    const palettes = {};
+    const keys = {};
+    for (const r of roles) {
+      const p = color.palettes[r];
+      // A pin moves the whole palette by as much as its representative moved.
+      const amount = pinned[r] ? moves.between(oklch(reps[r]), oklch(pinned[r])) : amounts[r];
+      const move = (k) => (k === reps[r] && pinned[r] ? pinned[r] : moveHex(moves, k, amount));
+      palettes[r] = { ...p, keys: p.keys.map(move), ...(p.darkest && { darkest: moveHex(moves, p.darkest, amount) }) };
+      keys[r] = move(reps[r]);
+    }
+
+    const dataPins = color.vision?.[theme]?.data ?? {};
+    const data = color.data.map(([name, hex]) => [name, dataPins[name] ?? hex]);
+    const rules = { visions: [sees], distinct: THEME_DISTINCT, reach: 2 };
+    for (let i = 0; i < data.length; i++) {
+      if (dataPins[data[i][0]]) continue;
+      // Never lose contrast on paper: a light color may darken, never the other way.
+      const goal = wcagContrast(data[i][1], color.paper);
+      if (dataColorPasses(data, i, color.paper, goal, rules)) continue;
+      data[i][1] = nudgeDataColor(data, i, color.paper, goal, rules) ?? data[i][1];
+    }
+
+    out[theme] = {
+      palettes,
+      keys,
+      brandKeys: reps,
+      data,
+      blurred: { before: blurred(Object.values(reps), sees), after: blurred(Object.values(keys), sees) },
+    };
+  }
+  last = { key, value: out };
+  return out;
+}

package/lib/config.mjs

@@ -0,0 +1,71 @@
+/**
+ * Where a project's brand lives and where its theme goes. Read from loomiere.config.json in
+ * the project folder, with command-line flags on top:
+ *
+ *   {
+ *     "brand": "brand/portfolio.json",   the brand file (default: the only one in brand/)
+ *     "out": "src/theme",                where the theme is written (default: theme)
+ *     "prefix": "sl",                    CSS variable prefix; loomiere-base-ui reads --sl-
+ *     "exports": ["ag-grid", "tailwind"] which framework files to write (default: all)
+ *   }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { overridesFileFor } from '../generator/generate.mjs';
+
+export const CONFIG_FILE = 'loomiere.config.json';
+
+const ownSchema = fileURLToPath(new URL('../generator/brand.schema.json', import.meta.url));
+
+/**
+ * The $schema path a brand file in `brandDir` should use: through the project's
+ * node_modules when the engine is installed there, so the path survives reinstalls.
+ */
+export function schemaPathFor(brandDir, cwd) {
+  const installed = path.join(cwd, 'node_modules', '@scattered-light', 'loomiere', 'generator', 'brand.schema.json');
+  const target = fs.existsSync(installed) ? installed : ownSchema;
+  return path.relative(brandDir, target).split(path.sep).join('/');
+}
+
+/** The project's brand files (not their .overrides.json), relative to cwd. */
+export function brandFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.json') && !f.endsWith('.overrides.json'))
+    .map((f) => path.join(dir, f));
+}
+
+export function resolveConfig(flags = {}, cwd = process.cwd()) {
+  const file = path.join(cwd, CONFIG_FILE);
+  const saved = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+  const pick = (key, fallback) => flags[key] ?? saved[key] ?? fallback;
+
+  let brand = pick('brand');
+  if (!brand) {
+    const found = brandFiles(path.join(cwd, 'brand'));
+    if (found.length !== 1) {
+      throw new Error(
+        found.length
+          ? `Found ${found.length} brand files in brand/. Say which one with --brand or "brand" in ${CONFIG_FILE}.`
+          : `No brand file yet. Run loomiere init <name> to make one, or set "brand" in ${CONFIG_FILE}.`,
+      );
+    }
+    brand = found[0];
+  }
+  const brandFile = path.resolve(cwd, brand);
+  if (!fs.existsSync(brandFile)) throw new Error(`No brand file at ${path.relative(cwd, brandFile)}.`);
+  const outDir = path.resolve(cwd, pick('out', 'theme'));
+  const exports = pick('exports', 'all');
+  return {
+    cwd,
+    brandFile,
+    overridesFile: overridesFileFor(brandFile),
+    outDir,
+    generatedDir: path.join(outDir, 'generated'),
+    prefix: pick('prefix', 'sl'),
+    exports: exports === 'all' ? 'all' : [].concat(exports),
+  };
+}

package/lib/contrast.mjs

@@ -0,0 +1,134 @@
+/**
+ * Checks the semantic color pairs in every mode against WCAG.
+ *
+ * Palettes are the same in every mode, but semantic tokens point at different steps in
+ * dark and high-contrast mode, so each pair is resolved per mode from the theme's tokens.json.
+ * Brand pairs (color.pairs in the brand file) are checked too, in light and dark: the
+ * text, the accent, the button label on hover and press, and text on the tinted parts.
+ * loomiere build runs it after every build and fails if anything falls short; loomiere check
+ * runs it on its own.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { wcagContrast } from 'culori';
+
+import { resolvePair } from '../generator/pairs.mjs';
+
+export const MODES = ['light', 'dark', 'contrast-more', 'dark-contrast-more'];
+const fallback = { dark: 'light', 'contrast-more': 'light', 'dark-contrast-more': 'dark' };
+
+/**
+ * A token's value in a mode. Dark + contrast falls back to dark, then light. A plain alias
+ * ({other.token}) follows the other token into the same mode, the way var() does in CSS.
+ */
+function valueIn(byPath, tokenPath, mode) {
+  const t = byPath.get(tokenPath);
+  if (!t) throw new Error(`Unknown token ${tokenPath}`);
+  for (let m = mode; m && m !== 'light'; m = fallback[m]) {
+    if (t.modes?.[m] === undefined) continue;
+    const modeAlias = typeof t.modeReferences?.[m] === 'string' && t.modeReferences[m].match(/^\{([^}]+)\}$/);
+    return modeAlias ? valueIn(byPath, modeAlias[1], mode) : t.modes[m];
+  }
+  const alias = typeof t.references === 'string' && t.references.match(/^\{([^}]+)\}$/);
+  return alias ? valueIn(byPath, alias[1], mode) : t.value;
+}
+
+const SURFACES = ['surface.canvas', 'surface.raised', 'surface.overlay', 'surface.modal', 'surface.tray'];
+const TEXT = 4.5;
+const UI = 3;
+
+/** [foreground, background, minimum ratio, what it is] */
+const PAIRS = [
+  ...['text.primary', 'text.secondary', 'text.tertiary', 'text.accent'].flatMap((fg) =>
+    SURFACES.map((bg) => [fg, bg, TEXT, 'text']),
+  ),
+  ...['interactive.default', 'interactive.hover', 'interactive.active'].map((bg) => ['text.on-primary', bg, TEXT, 'text on a button']),
+  ['content.link-color', 'surface.canvas', TEXT, 'link text'],
+  ['content.link-hover-color', 'surface.canvas', TEXT, 'link text'],
+  ['content.code-text', 'content.code-background', TEXT, 'code text'],
+  ['content.kbd-text', 'content.kbd-background', TEXT, 'keycap text'],
+  ['content.selection-text', 'content.selection-background', TEXT, 'selected text'],
+  ['content.prose-color', 'content.page-background', TEXT, 'prose'],
+  ['content.prose-color', 'content.mark-background', TEXT, 'marked text'],
+  ['text.on-inverse-surface', 'surface.inverse', TEXT, 'tooltip text'],
+  ['text.on-inverse', 'fill.inverse', TEXT, 'keycap text'],
+  ['text.on-tint', 'interactive.tint', TEXT, 'text on a tint'],
+  ['text.on-tint-strong', 'interactive.tint-strong', TEXT, 'text on a strong tint'],
+  ...['error', 'warning', 'success', 'info'].map((s) => [`status.${s}-dark`, `status.${s}-light`, TEXT, 'alert text']),
+  ...['error', 'warning', 'success', 'info'].map((s) => [`scope.${s}.on-soft`, `scope.${s}.soft`, TEXT, 'tinted toast text']),
+  ...['accent', 'primary', 'secondary', 'tertiary', 'quaternary', 'error', 'warning', 'success', 'info'].map((s) => [`scope.${s}.solid`, 'gauge.track-color', UI, 'meter fill on its track']),
+  ['table.color', 'table.background', TEXT, 'grid cell text'],
+  ['table.subtle-color', 'table.background', TEXT, 'grid secondary text'],
+  ['table.header-color', 'table.header-background', TEXT, 'grid header text'],
+  ['table.subtle-color', 'table.header-background', TEXT, 'grid side bar text'],
+  ['table.color', 'table.row-hover', TEXT, 'grid text on a hovered row'],
+  ['table.color', 'table.row-selected', TEXT, 'grid text on a selected row'],
+  ['table.color', 'table.range-background', TEXT, 'grid text in a range selection'],
+  ['table.range-border', 'table.background', UI, 'focused cell edge'],
+  ['table.range-border', 'table.row-selected', UI, 'focused cell edge on a selected row'],
+  ['interactive.default', 'surface.canvas', UI, 'control fill'],
+  ['border.strong', 'surface.canvas', UI, 'control border'],
+  ['border.control', 'surface.canvas', UI, 'control border'],
+  ['border.control-hover', 'surface.canvas', UI, 'control border'],
+  ['focus.ring', 'surface.canvas', UI, 'focus ring'],
+  ['focus.ring', 'surface.raised', UI, 'focus ring'],
+  ['scope.chrome.focus', 'surface.canvas', UI, 'neutral focus ring'],
+  ['scope.accent.focus', 'surface.canvas', UI, 'accent focus ring'],
+];
+
+/** Checks a built theme: { rows, failures }, one row per pair and mode. */
+export function checkContrast(outDir, brandFile) {
+const { tokens } = JSON.parse(fs.readFileSync(path.join(outDir, 'tokens.json'), 'utf8'));
+const byPath = new Map(tokens.map((t) => [t.path, t]));
+const failures = [];
+const rows = [];
+for (const mode of MODES) {
+  for (const [fg, bg, min, kind] of PAIRS) {
+    const a = valueIn(byPath, fg, mode);
+    const b = valueIn(byPath, bg, mode);
+    const ratio = wcagContrast(a, b);
+    const row = { mode, fg, bg, kind, min, ratio: Number(ratio.toFixed(2)), a, b };
+    rows.push(row);
+    if (ratio < min) failures.push(row);
+  }
+}
+
+// Palettes are the same in every mode, so a pair resolves from the light palette values.
+const brandPairs = JSON.parse(fs.readFileSync(brandFile, 'utf8')).color.pairs ?? {};
+const hexOf = (tokenPath) => byPath.get(tokenPath)?.value;
+for (const [name, { dark, ...spec }] of Object.entries(brandPairs)) {
+  for (const [mode, modeSpec] of [['light', spec], ...(dark ? [['dark', { ...spec, ...dark }]] : [])]) {
+    const { parts } = resolvePair(modeSpec, hexOf);
+    const checks = [
+      ['fg', 'bg', 'text'],
+      ['accent', 'bg', 'accent text'],
+      ['bg', 'hover', 'button label on hover'],
+      ['bg', 'active', 'button label pressed'],
+      ['fg', 'subtle', 'text on a highlight'],
+      ['fg', 'emphasis', 'text on a selection'],
+      ['fg', 'muted', 'code text'],
+    ];
+    for (const [fg, bg, kind] of checks) {
+      const ratio = wcagContrast(parts[fg], parts[bg]);
+      const row = { mode, fg: `pair.${name}.${fg}`, bg: `pair.${name}.${bg}`, kind: `pair ${kind}`, min: TEXT, ratio: Number(ratio.toFixed(2)), a: parts[fg], b: parts[bg] };
+      rows.push(row);
+      if (ratio < TEXT) failures.push(row);
+    }
+  }
+}
+
+return { rows, failures };
+}
+
+/** Prints a check's result; returns false when something falls short. */
+export function reportContrast({ rows, failures }) {
+  if (failures.length) {
+    console.error(`Contrast check: ${failures.length} of ${rows.length} pairs fall short.`);
+    for (const f of failures) {
+      console.error(`  ${f.mode.padEnd(18)} ${f.fg} on ${f.bg}: ${f.ratio}:1, needs ${f.min}:1 (${f.kind})`);
+    }
+    return false;
+  }
+  console.log(`Contrast check passed: ${rows.length} pairs across ${MODES.length} modes, brand pairs included.`);
+  return true;
+}