@scattered-light/loomiere 0.0.0-stage → 0.1.1

package/exporters/tailwind.mjs

@@ -0,0 +1,35 @@
+/**
+ * Tailwind CSS v4 theme. It points Tailwind's theme variables at the --sl- variables
+ * instead of copying values, so dark mode, contrast modes, color vision themes and
+ * data-color/data-emphasis all keep working in utility classes.
+ *   @import "tailwindcss";
+ *   @import "./theme/tokens.css";
+ *   @import "./tailwind.css";
+ */
+export default {
+  id: 'tailwind',
+  name: 'Tailwind CSS v4',
+  file: 'tailwind.css',
+  for: 'Tailwind v4 projects: import after tailwindcss and tokens.css. Utilities like bg-accent-solid, text-fg, border-chrome-border.',
+  build(theme) {
+    const name = new Map(theme.tokens.map((t) => [t.path, t.name]));
+    const line = (twVar, path) => (name.has(path) ? `  ${twVar}: var(${name.get(path)});` : null);
+    const lines = ['  --color-*: initial;'];
+    for (const [palette, steps] of Object.entries(theme.palettes)) for (const step of Object.keys(steps)) lines.push(line(`--color-${palette}-${step}`, `color.${palette}.${step}`));
+    for (const [scope, { light }] of Object.entries(theme.scopes)) for (const slot of Object.keys(light)) lines.push(line(`--color-${scope}-${slot}`, `scope.${scope}.${slot}`));
+    // The scope in effect (accent unless data-color says otherwise) and the emphasis paints.
+    for (const slot of Object.keys(theme.scopes.accent.light)) lines.push(`  --color-scope-${slot}: var(--${theme.prefix}-scope-${slot});`);
+    for (const part of ['bg', 'bg-hover', 'bg-active', 'fg', 'border', 'border-hover']) lines.push(`  --color-e-${part}: var(--${theme.prefix}-e-${part});`);
+    const semantic = { bg: 'surface.canvas', raised: 'surface.raised', overlay: 'surface.overlay', inverse: 'surface.inverse', fg: 'text.primary', 'fg-muted': 'text.secondary', 'fg-subtle': 'text.tertiary', 'fg-disabled': 'text.disabled', border: 'border.default', 'border-subtle': 'border.subtle', 'border-strong': 'border.strong', focus: 'focus.ring', white: 'color.white', black: 'color.black' };
+    for (const [k, path] of Object.entries(semantic)) lines.push(line(`--color-${k}`, path));
+    lines.push('  --color-transparent: transparent;', '  --color-current: currentColor;');
+    for (const role of ['display', 'body', 'mono']) lines.push(line(`--font-${role}`, `font-family.${role}`));
+    lines.push(line('--font-sans', 'font-family.body'));
+    for (const step of Object.keys(theme.fontSizes)) lines.push(line(`--text-${step}`, `font-size.${step}`), line(`--text-${step}--line-height`, `line-height.${step}`));
+    for (const r of Object.keys(theme.radii)) lines.push(line(`--radius-${r}`, `radius.${r}`));
+    for (const s of Object.keys(theme.shadows)) lines.push(line(`--shadow-${s}`, `elevation.${s}`));
+    const unit = name.get('space.1');
+    if (unit) lines.push(`  --spacing: var(${unit});`);
+    return `/* Tailwind CSS v4 theme for "${theme.brand}". Generated by loomiere build; do not edit.\n   @import "tailwindcss";\n   @import "./theme/tokens.css";\n   @import "./tailwind.css";\n   Every value points at a --${theme.prefix}- variable, so modes and data-color keep working. */\n@theme inline {\n${lines.filter(Boolean).join('\n')}\n}\n`;
+  },
+};

package/exporters/theme.mjs

@@ -0,0 +1,93 @@
+/**
+ * The framework-neutral theme every exporter starts from: the built token catalog
+ * (dist/tokens/tokens.json) read back into the few things frameworks ask for, with each
+ * color resolved in light and dark. Adapters only rename; no exporter does color math.
+ */
+import { SLOTS } from '../generator/roles.mjs';
+
+/**
+ * A token's value in a mode. Aliases carry no modes of their own, so follow them to the
+ * token that does; a value built from references (a color-mix, a shadow) is rebuilt from
+ * each reference's value in that mode.
+ */
+export function valueIn(byPath, path, mode = 'light') {
+  const t = byPath.get(path);
+  if (!t) throw new Error(`Export: no token ${path}`);
+  if (mode === 'light') return t.value;
+  if (t.modes?.[mode] !== undefined) return t.modes[mode];
+  if (typeof t.references !== 'string') return t.value;
+  const alias = t.references.match(/^\{([^}]+)\}$/)?.[1];
+  if (alias) return byPath.has(alias) ? valueIn(byPath, alias, mode) : t.value;
+  return t.references.replace(/\{([^}]+)\}/g, (_, ref) => valueIn(byPath, ref, mode));
+}
+
+export function readTheme(catalog, roles) {
+  const byPath = new Map(catalog.tokens.map((t) => [t.path, t]));
+  const valueOf = (path, mode = 'light') => valueIn(byPath, path, mode);
+  const both = (path) => ({ light: valueOf(path, 'light'), dark: valueOf(path, 'dark') });
+  const group = (prefix) =>
+    Object.fromEntries(catalog.tokens.filter((t) => t.path.startsWith(`${prefix}.`) && !t.path.slice(prefix.length + 1).includes('.')).map((t) => [t.path.slice(prefix.length + 1), t.value]));
+
+  const palettes = {};
+  for (const t of catalog.tokens) {
+    const m = t.path.match(/^color\.([\w-]+)\.(\d+)$/);
+    if (m && !['accent', 'chrome'].includes(m[1])) (palettes[m[1]] ??= {})[m[2]] = t.value;
+  }
+  const scopes = {};
+  for (const name of [...Object.keys(palettes).filter((p) => p !== 'data'), 'accent', 'chrome']) {
+    // Slots both tables share, so every scope has the same shape.
+    const slots = Object.keys(SLOTS.spot).filter((slot) => slot in SLOTS.neutral);
+    if (!byPath.has(`scope.${name}.solid`)) continue;
+    scopes[name] = { light: {}, dark: {} };
+    for (const slot of slots) {
+      const v = both(`scope.${name}.${slot}`);
+      scopes[name].light[slot] = v.light;
+      scopes[name].dark[slot] = v.dark;
+    }
+  }
+
+  const semantic = {
+    bg: 'surface.canvas',
+    raised: 'surface.raised',
+    overlay: 'surface.overlay',
+    inverse: 'surface.inverse',
+    text: 'text.primary',
+    textMuted: 'text.secondary',
+    textSubtle: 'text.tertiary',
+    textDisabled: 'text.disabled',
+    border: 'border.default',
+    borderSubtle: 'border.subtle',
+    borderStrong: 'border.strong',
+    focus: 'focus.ring',
+  };
+  const modes = { light: {}, dark: {} };
+  for (const [key, path] of Object.entries(semantic)) {
+    const v = both(path);
+    modes.light[key] = v.light;
+    modes.dark[key] = v.dark;
+  }
+
+  return {
+    brand: catalog.brand,
+    prefix: catalog.prefix,
+    roles,
+    palettes,
+    data: palettes.data ?? {},
+    scopes,
+    modes,
+    tokens: catalog.tokens,
+    fonts: { display: valueOf('font-family.display'), body: valueOf('font-family.body'), mono: valueOf('font-family.mono') },
+    fontSizes: group('font-size'),
+    fontWeights: group('font-weight'),
+    lineHeights: group('line-height'),
+    radii: group('radius'),
+    space: group('space'),
+    shadows: group('elevation'),
+  };
+}
+
+/** "0.25rem" → 4, "12px" → 12 (16px root). */
+export const px = (v) => {
+  const m = String(v).match(/^(-?[\d.]+)(rem|px)?$/);
+  return m ? Number(m[1]) * (m[2] === 'rem' ? 16 : 1) : undefined;
+};

package/generator/brand.mjs

@@ -0,0 +1,328 @@
+/**
+ * Brand → Primitive, without touching the file system, so the same math runs in the build
+ * (generator/generate.mjs) and in the browser (the brand builder, loomiere studio).
+ */
+import { parse } from 'culori';
+
+import { palette as buildPalette } from './color.mjs';
+import { PAIR_PARTS, describePart, onColor, resolvePair } from './pairs.mjs';
+import { generateRoleTokens } from './roles.mjs';
+import { visionColors } from './vision.mjs';
+
+const ROOT_FONT_SIZE = 16;
+
+const round = (n, places = 4) => Number(n.toFixed(places));
+const rem = (px) => (px === 0 ? '0' : `${round(px / ROOT_FONT_SIZE)}rem`);
+const stepName = (n) => String(n).replace('.', '-');
+const token = (type, value, description) => ({ $type: type, $value: value, ...(description && { $description: description }) });
+
+/** Mojave's shadow shapes. Brand supplies the color and how strong it is. */
+const SHADOW_RECIPES = {
+  xs: [{ x: 0, y: 0, blur: 0, spread: 1, alpha: 0.05 }],
+  sm: [{ x: 0, y: 1, blur: 2, spread: 0, alpha: 0.05 }],
+  base: [
+    { x: 0, y: 1, blur: 3, spread: 0, alpha: 0.1 },
+    { x: 0, y: 1, blur: 2, spread: 0, alpha: 0.06 },
+  ],
+  md: [
+    { x: 0, y: 4, blur: 6, spread: -1, alpha: 0.1 },
+    { x: 0, y: 2, blur: 4, spread: -1, alpha: 0.06 },
+  ],
+  lg: [
+    { x: 0, y: 10, blur: 15, spread: -3, alpha: 0.1 },
+    { x: 0, y: 4, blur: 6, spread: -2, alpha: 0.05 },
+  ],
+  xl: [
+    { x: 0, y: 20, blur: 25, spread: -5, alpha: 0.1 },
+    { x: 0, y: 10, blur: 10, spread: -5, alpha: 0.04 },
+  ],
+  '2xl': [{ x: 0, y: 25, blur: 50, spread: -12, alpha: 0.25 }],
+  inner: [{ x: 0, y: 2, blur: 4, spread: 0, alpha: 0.06, inset: true }],
+};
+
+function generateSpace({ unit, steps }) {
+  const space = {};
+  for (const step of steps) {
+    space[stepName(step)] = token('dimension', rem(unit * step), `${step} × ${unit}px unit = ${round(unit * step, 2)}px`);
+  }
+  return { space };
+}
+
+function generateColor({ paper, ink, contrast, palettes, data }) {
+  const color = {
+    white: token('color', paper, 'Paper: the lightest color in the system. Every palette step is measured against it.'),
+    black: token('color', ink, 'Ink: the darkest color in the system. Palettes end here unless they name their own darkest color.'),
+  };
+  for (const [role, p] of Object.entries(palettes)) {
+    const table = contrast[p.contrast ?? 'spot'];
+    if (!table) throw new Error(`Palette "${role}" uses unknown contrast table "${p.contrast}"`);
+    const label = p.label ? ` (${p.label})` : '';
+    const steps = buildPalette({
+      keys: p.keys,
+      exact: p.exact,
+      tone: p.tone,
+      paper,
+      ink: p.darkest ?? ink,
+      targets: table.targets,
+      locked: table.locked ?? [],
+    });
+    color[role] = {};
+    for (const { step, hex, ratio, key } of steps) {
+      const why = key
+        ? `brand color ${key}, placed at its own contrast (${round(ratio, 2)}:1)`
+        : `${round(ratio, 2)}:1 against paper${table.locked?.includes(Number(step)) ? ', locked so it always passes' : ''}`;
+      color[role][step] = token('color', hex, `${role}${label} ${step}: ${why}`);
+    }
+    // Text that passes AA on each step, so pairing is never guesswork.
+    const on = {};
+    for (const step of Object.keys(color[role])) {
+      const { ref, ratio } = onColor(role, step, color[role], paper, ink);
+      on[step] = token('color', ref, `Text on ${role} ${step}: ${round(ratio, 2)}:1`);
+    }
+    color[role].on = on;
+  }
+  color.data = {};
+  data.forEach(([name, hex], i) => {
+    color.data[i + 1] = token('color', hex, `Data series ${i + 1} (${name}). Categorical; use in order.`);
+  });
+  return { color };
+}
+
+/** Height of a font's own line box (ascent + descent) in em; 1.2 when its metrics are unknown. */
+const contentHeight = (m) => (m ? m.ascent + m.descent : 1.2);
+
+function generateType({ families, metrics = {}, base, ratio, viewport, steps, baseStep, stepDown, displayFrom, lineHeight, small }) {
+  const baseIndex = steps.indexOf(baseStep);
+  const sizeAt = (step) => {
+    const n = steps.indexOf(step) - baseIndex;
+    const max = base.max * ratio.max ** n;
+    // Step down: on small screens a size above the base starts where the step below ends
+    // on large screens, so headings drop one step rather than shrink by the base's ratio.
+    if (stepDown && n > 0) return { min: base.max * ratio.max ** (n - 1), max };
+    return { min: base.min * ratio.min ** n, max };
+  };
+
+  // Below the base, sizes are fixed px: small text has little room to shrink before it
+  // stops being readable, so it should not scale with the viewport.
+  const fixedSmall = small?.fixed !== false;
+  const smallPx = (step) => Math.max(small?.floor ?? 0, Math.round(sizeAt(step).min));
+
+  const fontSize = {};
+  for (const step of steps) {
+    if (fixedSmall && steps.indexOf(step) < baseIndex) {
+      const px = smallPx(step);
+      fontSize[step] = token('dimension', rem(px), `${px}px at every width. Below the base, sizes stay fixed (floor ${small?.floor ?? 0}px).`);
+      continue;
+    }
+    const { min, max } = sizeAt(step);
+    const slope = (max - min) / (viewport.max - viewport.min);
+    const intercept = min - slope * viewport.min;
+    const preferred = `${rem(intercept)} + ${round(slope * 100, 4)}vw`;
+    fontSize[step] = token(
+      'dimension',
+      min === max ? rem(max) : `clamp(${rem(min)}, ${preferred}, ${rem(max)})`,
+      `${round(min, 2)}px at ${viewport.min}px wide → ${round(max, 2)}px at ${viewport.max}px wide`,
+    );
+  }
+
+  // Line height is the font's own height (ascent + descent, from its metrics) plus leading.
+  // Leading eases on a log scale of the size from `text` at textStep to `heading` at
+  // headingStep: small text needs air between lines, big headings sit tight. From
+  // solidFrom up, display sizes are set solid (line height 1).
+  const displayIndex = displayFrom ? steps.indexOf(displayFrom) : Infinity;
+  const fontFor = (step) => (steps.indexOf(step) >= displayIndex ? 'display' : 'body');
+  const solidIndex = lineHeight.solidFrom ? steps.indexOf(lineHeight.solidFrom) : Infinity;
+  // The size each step renders at on large screens (fixed small steps use their px).
+  const shown = (step) => (fixedSmall && steps.indexOf(step) < baseIndex ? smallPx(step) : sizeAt(step).max);
+  const logText = Math.log(shown(lineHeight.textStep));
+  const logHeading = Math.log(shown(lineHeight.headingStep));
+  const lineHeightTokens = {};
+  for (const step of steps) {
+    const font = fontFor(step);
+    if (steps.indexOf(step) >= solidIndex) {
+      lineHeightTokens[step] = token('number', 1, `Line height paired with font-size-${step}: set solid, for display sizes.`);
+      continue;
+    }
+    const t = Math.min(1, Math.max(0, (Math.log(shown(step)) - logText) / (logHeading - logText)));
+    const leading = lineHeight.text + (lineHeight.heading - lineHeight.text) * t;
+    const own = contentHeight(metrics[font]);
+    lineHeightTokens[step] = token(
+      'number',
+      round(own + leading, 3),
+      `Line height paired with font-size-${step}: the ${font} font's own height (${round(own, 3)}) plus ${round(leading, 3)}em of leading.`,
+    );
+  }
+
+  const fontFamily = {};
+  for (const [role, stack] of Object.entries(families)) {
+    fontFamily[role] = token('fontFamily', stack, `${role} typeface`);
+  }
+
+  return { 'font-family': fontFamily, 'font-size': fontSize, 'line-height': lineHeightTokens };
+}
+
+function generateScale(group, type, { base, steps }) {
+  const out = {};
+  for (const [name, multiplier] of Object.entries(steps)) {
+    const px = base * multiplier;
+    out[name] = token(type, type === 'dimension' && group === 'radius' ? rem(px) : `${px}px`, `${multiplier} × ${base}px base`);
+  }
+  return { [group]: out };
+}
+
+function generateShadow({ shadowColor, strength }) {
+  const { r, g, b } = parse(shadowColor);
+  const rgb = [r, g, b].map((c) => Math.round(c * 255)).join(', ');
+  const shadow = {};
+  for (const [name, layers] of Object.entries(SHADOW_RECIPES)) {
+    const value = layers
+      .map(({ x, y, blur, spread, alpha, inset }) => {
+        const a = round(Math.min(1, alpha * strength), 3);
+        const len = (n) => (n === 0 ? '0' : `${n}px`);
+        return `${inset ? 'inset ' : ''}${len(x)} ${len(y)} ${len(blur)} ${len(spread)} rgba(${rgb}, ${a})`;
+      })
+      .join(', ');
+    shadow[name] = token('shadow', value, `Elevation ${name}`);
+  }
+  shadow.none = token('shadow', 'none', 'No elevation');
+  // The same heights as a flat 1px outline, in the shadow color, for when blur should go.
+  shadow.flat = {};
+  Object.keys(SHADOW_RECIPES)
+    .filter((name) => name !== 'inner')
+    .forEach((name, i) => {
+      const a = round(Math.min(1, 0.05 * (i + 1) * strength), 3);
+      shadow.flat[name] = token('shadow', `0 0 0 1px rgba(${rgb}, ${a})`, `Elevation ${name} as a 1px outline`);
+    });
+  return { shadow };
+}
+
+function generateMotion({ speed, durations }) {
+  const duration = {};
+  for (const [name, ms] of Object.entries(durations)) {
+    duration[name] = token('duration', `${Math.round(ms * speed)}ms`, `${ms}ms × speed ${speed}`);
+  }
+  return { duration };
+}
+
+/**
+ * Brand pairs → pair.<name>.<part> tokens. A pair may name a `dark` variant (any of bg,
+ * fg, accent); parts it leaves out carry over from the light pair. A pair whose text would
+ * fall short of AA in either mode is left out and reported in `problems`.
+ */
+function generatePairs(pairs = {}, color) {
+  const hexOf = (tokenPath) => {
+    const t = tokenPath.split('.').slice(1).reduce((group, key) => group?.[key], color);
+    return typeof t?.$value === 'string' && t.$value.startsWith('#') ? t.$value : null;
+  };
+  const expr = (name, source) =>
+    Array.isArray(source)
+      ? `color-mix(in oklab, {pair.${name}.${source[0]}} ${source[1]}%, {pair.${name}.${source[2]}})`
+      : PAIR_PARTS[source]
+        ? `{pair.${name}.${source}}`
+        : `{${source}}`;
+  const pair = {};
+  const problems = [];
+  for (const [name, spec] of Object.entries(pairs)) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+      problems.push(`"${name}": names use a-z, 0-9 and dashes, starting with a letter`);
+      continue;
+    }
+    const { dark: darkSpec, description, ...lightSpec } = spec;
+    const light = resolvePair(lightSpec, hexOf);
+    const dark = darkSpec ? resolvePair({ ...lightSpec, ...darkSpec }, hexOf) : null;
+    problems.push(...light.problems.map((m) => `"${name}": ${m}`));
+    if (dark) problems.push(...dark.problems.map((m) => `"${name}" in dark mode: ${m}`));
+    if (light.problems.length || dark?.problems.length) continue;
+
+    pair[name] = { ...(description && { $description: description }) };
+    for (const part of Object.keys(PAIR_PARTS)) {
+      const t = token('color', expr(name, light.sources[part]), describePart(part, light, lightSpec));
+      const darkValue = dark && expr(name, dark.sources[part]);
+      if (darkValue && darkValue !== t.$value) t.$extensions = { 'sl.modes': { dark: darkValue } };
+      pair[name][part] = t;
+    }
+  }
+  return { tokens: { pair }, problems };
+}
+
+/** Overrides are flat: { "color.primary.600": "#883ac3" }. Each replaces one generated value. */
+export function applyOverrides(files, overrides) {
+  const applied = [];
+  for (const [tokenPath, value] of Object.entries(overrides)) {
+    if (tokenPath.startsWith('$')) continue; // $comment
+    const keys = tokenPath.split('.');
+    let node;
+    for (const file of Object.values(files)) {
+      let cursor = file;
+      for (const key of keys) cursor = cursor?.[key];
+      if (cursor?.$value !== undefined) node = cursor;
+    }
+    if (!node) throw new Error(`Override "${tokenPath}" does not match a generated token`);
+    applied.push({ path: tokenPath, generated: node.$value, pinned: value });
+    node.$value = value;
+    node.$extensions = { 'sl.override': { generated: applied.at(-1).generated } };
+  }
+  return applied;
+}
+
+/**
+ * Every primitive file for a brand, with overrides pinned on top. Pairs read the palettes
+ * after overrides, so they check the colors that actually ship. Returns { files, applied,
+ * pairs, problems }: `pairs` holds the pair tokens, `problems` the pairs that fell short.
+ */
+/**
+ * vision.<theme>.color.<role>.<step> and .data: the spot palettes (brand colors and alerts)
+ * and data colors redesigned for each kind of color blindness, built with the same contrast tables so every step keeps
+ * its contrast. Semantic status colors point at the alert palettes, so they follow.
+ * The build re-declares the brand's variables with these under [data-vision="<theme>"].
+ */
+function generateVision(color) {
+  const vision = {};
+  for (const [theme, { palettes, data }] of Object.entries(visionColors(color))) {
+    const roles = new Set(Object.keys(palettes));
+    const { color: built } = generateColor({ ...color, palettes, data });
+    // On-colors point at the brand palette; point them at this theme's palette instead.
+    const retarget = (v) => (typeof v === 'object' && v !== null
+      ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, retarget(x)]))
+      : typeof v === 'string' ? v.replace(/\{color\.([\w-]+)\./g, (m, role) => (roles.has(role) ? `{vision.${theme}.color.${role}.` : m)) : v);
+    const themed = {};
+    for (const role of [...roles, 'data']) themed[role] = retarget(built[role]);
+    vision[theme] = { color: themed };
+  }
+  return { vision };
+}
+
+/**
+ * color.accent.* and color.chrome.*: every step (and on-color) of the palettes the roles
+ * name, as references, so semantic and component tokens say "accent" and follow the brand.
+ */
+function generateRoleAliases(color, roles) {
+  const alias = (name) => {
+    const out = {};
+    for (const [step, t] of Object.entries(color[name])) {
+      if (step === 'on') {
+        out.on = Object.fromEntries(Object.keys(t).map((s) => [s, token('color', `{color.${name}.on.${s}}`)]));
+      } else out[step] = token('color', `{color.${name}.${step}}`);
+    }
+    return out;
+  };
+  return { color: { accent: alias(roles.accent), chrome: alias(roles.chrome) } };
+}
+
+export function buildPrimitives(brand, overrides = {}) {
+  const files = {
+    color: generateColor(brand.color),
+    space: generateSpace(brand.space),
+    type: generateType(brand.type),
+    radius: generateScale('radius', 'dimension', brand.radius),
+    stroke: generateScale('stroke', 'dimension', brand.stroke),
+    shadow: generateShadow(brand.elevation),
+    motion: generateMotion(brand.motion),
+    vision: generateVision(brand.color),
+  };
+  const applied = applyOverrides(files, overrides);
+  const roleTokens = generateRoleTokens(brand);
+  files.role = generateRoleAliases(files.color.color, roleTokens.roles);
+  const { tokens: pairs, problems } = generatePairs(brand.color.pairs, files.color.color);
+  return { files, applied, pairs, problems, roleTokens };
+}