synabun 1.3.0 → 2.0.0

package/neural-interface/lib/style-guide/color.js

@@ -0,0 +1,352 @@
+// ═══════════════════════════════════════════
+// SynaBun — Style Guide color math
+// ═══════════════════════════════════════════
+//
+// Pure functions, no I/O: parse any CSS color the editor is likely to be handed
+// (hex, rgb(), hsl(), oklch(), a few names) into hex, convert sRGB ↔ OKLCH,
+// build the 11-step scale a palette holds, and measure contrast (WCAG 2.x ratio
+// and APCA Lc). Every exporter, the renderer and the contrast route read these.
+
+export const PALETTE_STEPS = Object.freeze(['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950']);
+
+const NAMED = Object.freeze({
+  black: '#000000', white: '#ffffff', red: '#ff0000', green: '#008000', blue: '#0000ff', yellow: '#ffff00',
+  orange: '#ffa500', purple: '#800080', pink: '#ffc0cb', gray: '#808080', grey: '#808080', silver: '#c0c0c0',
+  navy: '#000080', teal: '#008080', maroon: '#800000', olive: '#808000', lime: '#00ff00', aqua: '#00ffff',
+  cyan: '#00ffff', fuchsia: '#ff00ff', magenta: '#ff00ff', transparent: '#00000000',
+});
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const round = (value, digits = 0) => { const f = 10 ** digits; return Math.round(value * f) / f; };
+
+// Match the entire CSS number, rather than accepting a numeric prefix ("12oops").
+const CSS_NUMBER = '[+-]?(?:\\d+\\.?\\d*|\\.\\d+)(?:e[+-]?\\d+)?';
+const CHANNEL_RE = new RegExp(`^(${CSS_NUMBER})(%?)$`);
+const HUE_RE = new RegExp(`^(${CSS_NUMBER})(deg|rad|grad|turn)?$`);
+
+function numberOf(text, percentScale = 1) {
+  const match = CHANNEL_RE.exec(text);
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n)) return null;
+  return match[2] ? (n / 100) * percentScale : n;
+}
+
+function channel(text, scale = 255) {
+  const n = numberOf(text, scale);
+  return n === null ? null : clamp(n, 0, scale);
+}
+
+function alphaOf(text) {
+  if (text === undefined) return 1;
+  const n = numberOf(text);
+  return n === null ? null : clamp(n, 0, 1);
+}
+
+/** "a, b, c / d" or "a b c d" → the arguments of a color function. */
+function splitArgs(body) {
+  const parts = body.trim().split('/');
+  if (parts.length > 2) return null;
+  const args = parts[0].includes(',') ? parts[0].split(',').map((arg) => arg.trim()) : parts[0].trim().split(/\s+/);
+  if (parts.length === 2) {
+    if (args.length !== 3 || !parts[1].trim()) return null;
+    args.push(parts[1].trim());
+  }
+  return args.length >= 3 && args.length <= 4 && args.every(Boolean) ? args : null;
+}
+
+function hueOf(text) {
+  const match = HUE_RE.exec(text);
+  if (!match) return null;
+  const factor = { deg: 1, rad: 180 / Math.PI, grad: 0.9, turn: 360 }[match[2] || 'deg'];
+  const deg = Number(match[1]) * factor;
+  if (!Number.isFinite(deg)) return null;
+  return ((deg % 360) + 360) % 360;
+}
+
+function hslToRgb(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return { r: f(0) * 255, g: f(8) * 255, b: f(4) * 255 };
+}
+
+/**
+ * Any supported CSS color → { r, g, b, a } (r/g/b 0..255, a 0..1), or null.
+ * Supported: #rgb #rgba #rrggbb #rrggbbaa, rgb()/rgba(), hsl()/hsla(), oklch(), basic names,
+ * and a bare "H S% L%" triple (the shadcn custom-property form).
+ */
+export function parseColor(input) {
+  if (input && typeof input === 'object') {
+    if (![input.r, input.g, input.b].every(Number.isFinite) || (input.a !== undefined && !Number.isFinite(input.a))) return null;
+    return { r: clamp(input.r, 0, 255), g: clamp(input.g, 0, 255), b: clamp(input.b, 0, 255), a: input.a === undefined ? 1 : clamp(input.a, 0, 1) };
+  }
+  if (typeof input !== 'string') return null;
+  const text = input.trim().toLowerCase();
+  if (!text) return null;
+  if (NAMED[text]) return parseColor(NAMED[text]);
+  const hex = /^#([0-9a-f]{3,8})$/.exec(text);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('');
+    if (h.length !== 6 && h.length !== 8) return null;
+    return {
+      r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16),
+      a: h.length === 8 ? round(parseInt(h.slice(6, 8), 16) / 255, 3) : 1,
+    };
+  }
+  const fn = /^([a-z]+)\(([^()]*)\)$/.exec(text);
+  if (fn) {
+    const args = splitArgs(fn[2]);
+    if (!args) return null;
+    const a = alphaOf(args[3]);
+    if (a === null) return null;
+    if (fn[1] === 'rgb' || fn[1] === 'rgba') {
+      const [r, g, b] = args.slice(0, 3).map((arg) => channel(arg));
+      return [r, g, b].includes(null) ? null : { r, g, b, a };
+    }
+    if (fn[1] === 'hsl' || fn[1] === 'hsla') {
+      // Saturation and lightness are percentages; the modern syntax also allows bare numbers 0..100.
+      const unit = (arg) => { const n = numberOf(arg); return n === null ? null : clamp(!arg.endsWith('%') && n > 1 ? n / 100 : n, 0, 1); };
+      const h = hueOf(args[0]), s = unit(args[1]), l = unit(args[2]);
+      return [h, s, l].includes(null) ? null : { ...hslToRgb(h, s, l), a };
+    }
+    if (fn[1] === 'oklch') {
+      const l = numberOf(args[0]), c = numberOf(args[1], 0.4), h = hueOf(args[2]);
+      if ([l, c, h].includes(null)) return null;
+      const rgb = oklchToSrgb({ l: clamp(l, 0, 1), c: Math.max(0, c), h });
+      return { ...rgb, a };
+    }
+    return null;
+  }
+  // "222.2 84% 4.9%": an HSL triple without the function (shadcn / Tailwind v3 custom properties).
+  const triple = /^(-?[\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%(?:\s*\/\s*([\d.]+%?))?$/.exec(text);
+  if (triple) {
+    return parseColor(`hsl(${triple[1]} ${triple[2]}% ${triple[3]}%${triple[4] === undefined ? '' : ` / ${triple[4]}`})`);
+  }
+  return null;
+}
+
+const hex2 = (value) => Math.round(clamp(value, 0, 255)).toString(16).padStart(2, '0');
+
+/** { r, g, b, a? } → "#rrggbb" (or "#rrggbbaa" when translucent). */
+export function rgbToHex(rgb) {
+  const base = `#${hex2(rgb.r)}${hex2(rgb.g)}${hex2(rgb.b)}`;
+  return Number.isFinite(rgb.a) && rgb.a < 1 ? `${base}${hex2(rgb.a * 255)}` : base;
+}
+
+/** Any supported CSS color → lower-case hex, or null when it is not a color. */
+export function toHex(input) {
+  const rgb = parseColor(input);
+  return rgb ? rgbToHex(rgb) : null;
+}
+
+export function isColor(input) {
+  return parseColor(input) !== null;
+}
+
+// ── sRGB ↔ OKLCH (Björn Ottosson's OKLab) ───────────────────────────────────
+
+const toLinear = (c) => { const v = c / 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; };
+const fromLinear = (v) => (v <= 0.0031308 ? 12.92 * v : 1.055 * (Math.max(v, 0) ** (1 / 2.4)) - 0.055) * 255;
+
+/** { r, g, b } (0..255) → { l (0..1), c (≈0..0.4), h (0..360) }. */
+export function srgbToOklch(rgb) {
+  const r = toLinear(rgb.r); const g = toLinear(rgb.g); const b = toLinear(rgb.b);
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  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);
+  const h = c < 1e-7 ? 0 : ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360;
+  return { l: L, c, h };
+}
+
+function oklchToLinear({ l, c, h }) {
+  const a = c * Math.cos((h * Math.PI) / 180);
+  const b = c * Math.sin((h * Math.PI) / 180);
+  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 inGamut = (linear) => linear.every((v) => v >= -0.0005 && v <= 1.0005);
+
+/** { l, c, h } → { r, g, b } (0..255). Out-of-gamut colors lose chroma until they fit (hue and lightness kept). */
+export function oklchToSrgb(lch) {
+  const l = clamp(lch.l, 0, 1);
+  let c = Math.max(0, lch.c);
+  let linear = oklchToLinear({ l, c, h: lch.h });
+  if (!inGamut(linear)) {
+    let lo = 0; let hi = c;
+    for (let i = 0; i < 24; i++) {
+      const mid = (lo + hi) / 2;
+      if (inGamut(oklchToLinear({ l, c: mid, h: lch.h }))) lo = mid; else hi = mid;
+    }
+    c = lo;
+    linear = oklchToLinear({ l, c, h: lch.h });
+  }
+  return { r: clamp(fromLinear(linear[0]), 0, 255), g: clamp(fromLinear(linear[1]), 0, 255), b: clamp(fromLinear(linear[2]), 0, 255) };
+}
+
+export function hexToOklch(input) {
+  const rgb = parseColor(input);
+  return rgb ? srgbToOklch(rgb) : null;
+}
+
+export function oklchToHex(lch) {
+  return rgbToHex(oklchToSrgb(lch));
+}
+
+// ── Scales ──────────────────────────────────────────────────────────────────
+
+// How far each step travels from the base toward the light end (50…400) or the dark end (600…950),
+// and how much of the base's chroma it keeps.
+const LIGHT_T = { 50: 0.95, 100: 0.87, 200: 0.72, 300: 0.52, 400: 0.27 };
+const DARK_T = { 600: 0.18, 700: 0.37, 800: 0.56, 900: 0.73, 950: 0.88 };
+const CHROMA_T = { 50: 0.14, 100: 0.28, 200: 0.48, 300: 0.7, 400: 0.9, 600: 0.96, 700: 0.86, 800: 0.72, 900: 0.6, 950: 0.46 };
+
+/**
+ * An 11-step scale (50…950) around `base`, built in OKLCH so the steps are evenly spaced to the eye.
+ * The base is step 500, byte for byte. `hueShift` (degrees) drifts the hue toward the light end
+ * (negative half) and the dark end (positive half); `chroma` scales every generated step's saturation.
+ * Returns null when `base` is not a color.
+ */
+export function scaleFromBase(base, { hueShift = 0, chroma = 1 } = {}) {
+  const rgb = parseColor(base);
+  if (!rgb) return null;
+  const baseHex = rgbToHex({ r: rgb.r, g: rgb.g, b: rgb.b });
+  const lch = srgbToOklch(rgb);
+  const top = lch.l >= 0.985 ? lch.l + (1 - lch.l) * 0.9 : 0.985;
+  const bottom = Math.min(0.14, lch.l * 0.6);
+  const shift = Number.isFinite(Number(hueShift)) ? Number(hueShift) : 0;
+  const factor = Number.isFinite(Number(chroma)) ? Math.max(0, Number(chroma)) : 1;
+  const out = {};
+  for (const step of PALETTE_STEPS) {
+    if (step === '500') { out[step] = baseHex; continue; }
+    const light = LIGHT_T[step];
+    const t = light ?? DARK_T[step];
+    const l = light !== undefined ? lch.l + (top - lch.l) * t : lch.l - (lch.l - bottom) * t;
+    const h = (lch.h + (light !== undefined ? -shift * t : shift * t) + 360) % 360;
+    out[step] = oklchToHex({ l, c: lch.c * CHROMA_T[step] * factor, h });
+  }
+  return out;
+}
+
+// ── Contrast ────────────────────────────────────────────────────────────────
+
+/** A translucent foreground painted over an opaque background. */
+function flatten(fg, bg) {
+  if (!(fg.a < 1)) return fg;
+  return { r: fg.r * fg.a + bg.r * (1 - fg.a), g: fg.g * fg.a + bg.g * (1 - fg.a), b: fg.b * fg.a + bg.b * (1 - fg.a), a: 1 };
+}
+
+export function relativeLuminance(input) {
+  const rgb = parseColor(input);
+  if (!rgb) return null;
+  return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b);
+}
+
+/** WCAG 2.x contrast ratio (1…21), or null when either side is not a color. */
+export function wcagContrast(fg, bg) {
+  const back = parseColor(bg);
+  const front = parseColor(fg);
+  if (!back || !front) return null;
+  const a = relativeLuminance(flatten(front, back));
+  const b = relativeLuminance(back);
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+
+/**
+ * APCA lightness contrast Lc (APCA-W3 0.1.9): positive for dark text on a light background,
+ * negative for light text on a dark one, 0 below the noise floor. Advisory only.
+ */
+export function apcaContrast(text, background) {
+  const back = parseColor(background);
+  const front = parseColor(text);
+  if (!back || !front) return null;
+  const y = (rgb) => {
+    const value = 0.2126729 * (rgb.r / 255) ** 2.4 + 0.7151522 * (rgb.g / 255) ** 2.4 + 0.072175 * (rgb.b / 255) ** 2.4;
+    return value > 0.022 ? value : value + (0.022 - value) ** 1.414;
+  };
+  const yText = y(flatten(front, back));
+  const yBg = y(back);
+  if (Math.abs(yBg - yText) < 0.0005) return 0;
+  if (yBg > yText) {
+    const sapc = (yBg ** 0.56 - yText ** 0.57) * 1.14;
+    return sapc < 0.1 ? 0 : (sapc - 0.027) * 100;
+  }
+  const sapc = (yBg ** 0.65 - yText ** 0.62) * 1.14;
+  return sapc > -0.1 ? 0 : (sapc + 0.027) * 100;
+}
+
+/** What the contrast route and the tool return: { ratio, aa, aaa, aaLarge, aaaLarge, apca }. */
+export function contrastReport(fg, bg, { size = 'normal' } = {}) {
+  const ratio = wcagContrast(fg, bg);
+  if (ratio === null) return null;
+  const large = String(size) === 'large';
+  return {
+    ratio: round(ratio, 2),
+    aa: ratio >= (large ? 3 : 4.5),
+    aaa: ratio >= (large ? 4.5 : 7),
+    aaLarge: ratio >= 3,
+    aaaLarge: ratio >= 4.5,
+    apca: round(apcaContrast(fg, bg), 1),
+  };
+}
+
+// ── Harmony and dark theme ──────────────────────────────────────────────────
+
+/** Hue rotations of `base` in OKLCH: { complementary: [hex], analogous: [hex, hex], triadic: [hex, hex], splitComplementary: [hex, hex] }. */
+export function harmony(base) {
+  const lch = hexToOklch(base);
+  if (!lch) return null;
+  const turn = (deg) => oklchToHex({ l: lch.l, c: lch.c, h: (lch.h + deg + 360) % 360 });
+  return {
+    complementary: [turn(180)],
+    analogous: [turn(-30), turn(30)],
+    triadic: [turn(120), turn(240)],
+    splitComplementary: [turn(150), turn(210)],
+  };
+}
+
+const MIRROR = Object.freeze({ 50: '950', 100: '900', 200: '800', 300: '700', 400: '600', 500: '500', 600: '400', 700: '300', 800: '200', 900: '100', 950: '50' });
+// A brand color on a dark surface wants to be lighter, never darker.
+const BRAND_DARK = Object.freeze({ 50: '900', 100: '800', 200: '700', 300: '600', 400: '500', 500: '400', 600: '300', 700: '300', 800: '200', 900: '200', 950: '100' });
+const ALIAS_RE = /^\{([a-z0-9-]+)\.([a-z0-9-]+)\}$/i;
+
+/**
+ * A dark semantic map derived from a light one. Aliases to a palette step are mirrored
+ * ({neutral.50} → {neutral.950}; brand palettes step lighter: {primary.500} → {primary.400});
+ * literal colors get their OKLCH lightness inverted. `neutral` names the palette that mirrors exactly.
+ */
+export function deriveDarkSemantic(light = {}, { neutral = 'neutral' } = {}) {
+  const dark = {};
+  for (const [role, value] of Object.entries(light || {})) {
+    const text = String(value ?? '');
+    const alias = ALIAS_RE.exec(text);
+    if (alias && PALETTE_STEPS.includes(alias[2])) {
+      const onColor = /^on[A-Z]/.test(role);
+      const table = alias[1] === neutral || onColor ? MIRROR : BRAND_DARK;
+      dark[role] = `{${alias[1]}.${table[alias[2]]}}`;
+      continue;
+    }
+    const lch = hexToOklch(text);
+    if (lch) {
+      // White surfaces become the darkest neutral, white-on-color text the darkest neutral too.
+      if (lch.c < 0.02 && lch.l > 0.97) { dark[role] = `{${neutral}.950}`; continue; }
+      if (lch.c < 0.02 && lch.l < 0.2) { dark[role] = `{${neutral}.50}`; continue; }
+      dark[role] = oklchToHex({ l: clamp(1 - lch.l, 0.12, 0.96), c: lch.c * 0.9, h: lch.h });
+      continue;
+    }
+    dark[role] = text;
+  }
+  return dark;
+}

package/neural-interface/lib/style-guide/export-css.js

@@ -0,0 +1,99 @@
+// ═══════════════════════════════════════════
+// SynaBun — Style Guide → CSS custom properties
+// ═══════════════════════════════════════════
+//
+// tokens.css: every token as a custom property under the configured selector
+// (`:root`), the other theme's semantic colors under `[data-theme="dark"]`, `.dark`
+// or `@media (prefers-color-scheme: dark)`, and a reduced-motion block. Semantic
+// colors point at palette steps with var(), so one override re-themes the page.
+// Pure and deterministic.
+
+import { normalizeStyleGuide, resolveText } from './schema.js';
+import { fontKeyOf, fontStack, px, rem, roleName, semanticEntries, themesOf } from './tokens.js';
+
+/** The custom property a semantic or component alias points at, when it names a palette step or a status. */
+function colorVar(entry) {
+  if (!entry.alias || !entry.value) return entry.value;
+  if (entry.alias.group === 'status') return `var(--color-${entry.alias.key})`;
+  if (entry.alias.group === 'semantic') return `var(--color-${roleName(entry.alias.key)})`;
+  return `var(--color-${entry.alias.group}-${entry.alias.key})`;
+}
+
+/** [name, value] pairs for one theme's semantic roles. */
+export function semanticDeclarations(config, theme, { vars = true } = {}) {
+  return semanticEntries(config, theme).filter((entry) => entry.value).map((entry) => [`--color-${entry.name}`, vars ? colorVar(entry) : entry.value]);
+}
+
+/** [name, value] pairs for everything that does not change with the theme. */
+export function baseDeclarations(config, theme) {
+  const out = [];
+  for (const [key, palette] of Object.entries(config.colors.palettes)) {
+    for (const [step, hex] of Object.entries(palette.steps)) out.push([`--color-${key}-${step}`, hex]);
+  }
+  for (const [key, hex] of Object.entries(config.colors.status)) out.push([`--color-${key}`, hex]);
+  for (const gradient of config.colors.gradients) out.push([`--gradient-${gradient.name}`, resolveText(config, gradient.css, { theme }).text]);
+  for (const [key, font] of Object.entries(config.typography.fonts)) if (font) out.push([`--font-${key}`, fontStack(font)]);
+  for (const [id, style] of Object.entries(config.typography.styles)) {
+    out.push([`--text-${id}-size`, rem(style.size)]);
+    if (style.mobileSize && style.mobileSize !== style.size) out.push([`--text-${id}-size-mobile`, rem(style.mobileSize)]);
+    out.push([`--text-${id}-weight`, String(style.weight)]);
+    out.push([`--text-${id}-line-height`, String(style.lineHeight)]);
+    out.push([`--text-${id}-letter-spacing`, style.letterSpacing === 0 ? '0' : `${style.letterSpacing}em`]);
+    out.push([`--text-${id}-font`, `var(--font-${fontKeyOf(config, style)})`]);
+  }
+  for (const [key, value] of Object.entries(config.layout.spacing.scale)) out.push([`--space-${key}`, px(value)]);
+  for (const [key, value] of Object.entries(config.shape.radius)) out.push([`--radius-${key}`, px(value)]);
+  for (const [role, key] of Object.entries(config.shape.radiusRoles)) if (!(role in config.shape.radius)) out.push([`--radius-${role}`, `var(--radius-${key})`]);
+  for (const [key, value] of Object.entries(config.shape.borders)) out.push([`--border-${key}`, px(value)]);
+  for (const [key, level] of Object.entries(config.shape.elevation)) out.push([`--shadow-${key}`, level.shadow]);
+  for (const [key, value] of Object.entries(config.motion.durations)) out.push([`--duration-${key}`, `${value}ms`]);
+  for (const [key, value] of Object.entries(config.motion.easings)) out.push([`--ease-${key}`, value]);
+  for (const [key, value] of Object.entries(config.layout.breakpoints)) out.push([`--breakpoint-${key}`, px(value)]);
+  for (const [key, value] of Object.entries(config.layout.zIndex)) out.push([`--z-${key}`, String(value)]);
+  out.push(['--container-max', px(config.layout.container.maxWidth)], ['--container-padding', px(config.layout.container.padding)]);
+  out.push(['--grid-columns', String(config.layout.grid.columns)], ['--grid-gutter', px(config.layout.grid.gutter)]);
+  return out;
+}
+
+function block(selector, declarations, indent = '') {
+  return [`${indent}${selector} {`, ...declarations.map(([name, value]) => `${indent}  ${name}: ${value};`), `${indent}}`];
+}
+
+/** Where the non-default theme's colors go: { selector } or { media, selector }. */
+export function themeScope(config, theme) {
+  const root = config.exports.cssSelector || ':root';
+  if (config.exports.darkMode === 'media') return { media: `(prefers-color-scheme: ${theme})`, selector: root };
+  const selector = config.exports.darkMode === 'class' ? `.${theme}` : `[data-theme="${theme}"]`;
+  // A custom root (especially #app) outranks a bare theme selector. Cover a theme
+  // on the root itself and on an ancestor, with enough specificity to override it.
+  return { selector: root === ':root' ? selector : `${root}${selector}, ${selector} ${root}` };
+}
+
+/**
+ * tokens.css. `theme` (light | dark) flattens the output to that one theme: no second block,
+ * semantic colors as literal hexes. Without it both themes are written.
+ */
+export function exportCss(input, { theme = null } = {}) {
+  const config = normalizeStyleGuide(input);
+  const themes = themesOf(config);
+  const root = config.exports.cssSelector || ':root';
+  const single = themes.includes(theme) ? theme : null;
+  const first = single || themes[0];
+  const lines = [
+    `/* SynaBun Style Guide rev ${config.revision}: design tokens. Generated, do not edit by hand. */`,
+    ...block(root, [['color-scheme', first], ...baseDeclarations(config, first), ...semanticDeclarations(config, first, { vars: !single })]),
+  ];
+  if (!single) {
+    for (const other of themes.slice(1)) {
+      const scope = themeScope(config, other);
+      const declarations = [['color-scheme', other], ...semanticDeclarations(config, other)];
+      lines.push('');
+      if (scope.media) lines.push(`@media ${scope.media} {`, ...block(scope.selector, declarations, '  '), '}');
+      else lines.push(...block(scope.selector, declarations));
+    }
+  }
+  if (config.motion.reducedMotion === 'respect') {
+    lines.push('', '@media (prefers-reduced-motion: reduce) {', ...block(root, Object.keys(config.motion.durations).map((key) => [`--duration-${key}`, '0ms']), '  '), '}');
+  }
+  return `${lines.join('\n')}\n`;
+}

package/neural-interface/lib/style-guide/export-dtcg.js

@@ -0,0 +1,209 @@
+// ═══════════════════════════════════════════
+// SynaBun — Style Guide → W3C design tokens (DTCG 2025.10)
+// ═══════════════════════════════════════════
+//
+// tokens.json in the Design Tokens Community Group format: a token is an object
+// with `$value`; groups are objects without one; `$type` is inherited from the
+// closest group; an alias is "{group.token}". Value shapes follow the 2025.10
+// module: color { colorSpace, components, alpha, hex }, dimension { value, unit },
+// duration { value, unit }, cubicBezier [x1, y1, x2, y2], shadow, typography.
+// Pure: `generatedAt` is passed in, never read from the clock.
+
+import { parseColor, rgbToHex } from './color.js';
+import { isAlias, normalizeStyleGuide, resolveAlias } from './schema.js';
+import { fontKeyOf, fontList, parseEasing, parseShadow, themesOf, tidy } from './tokens.js';
+
+export const DTCG_MIME = 'application/design-tokens+json';
+export const DTCG_EXTENSION_KEY = 'dev.synabun';
+
+/** A token or group name: DTCG forbids `{`, `}`, `.` and a leading `$`. */
+export function dtcgName(value) {
+  return String(value).replace(/[{}.]/g, '-').replace(/^\$+/, '') || 'token';
+}
+
+/** Any CSS color → the DTCG color value, or null. */
+export function dtcgColor(input) {
+  const rgb = parseColor(input);
+  if (!rgb) return null;
+  return {
+    colorSpace: 'srgb',
+    components: [tidy(rgb.r / 255), tidy(rgb.g / 255), tidy(rgb.b / 255)],
+    alpha: tidy(rgb.a ?? 1, 3),
+    hex: rgbToHex({ r: rgb.r, g: rgb.g, b: rgb.b }),
+  };
+}
+
+const dim = (value, unit = 'px') => ({ value: tidy(value), unit });
+
+/** `extension`: what DTCG has no field for (a mobile size, the CSS a shadow was written as), under $extensions["dev.synabun"]. */
+function token(value, description, extension = null) {
+  const out = { $value: value };
+  if (description) out.$description = String(description);
+  if (extension && Object.keys(extension).length) out.$extensions = { [DTCG_EXTENSION_KEY]: extension };
+  return out;
+}
+
+/** A color field of the config as a DTCG value: an alias to the token it names, or the color itself. */
+function colorRef(config, raw, theme) {
+  if (isAlias(raw)) {
+    const hit = resolveAlias(config, raw, { theme });
+    if (!hit.ok || hit.kind !== 'color') return null;
+    if (hit.group === 'status') return `{color.status.${dtcgName(hit.key)}}`;
+    if (hit.group === 'semantic') return `{color.semantic.${theme}.${dtcgName(hit.key)}}`;
+    return `{color.${dtcgName(hit.group)}.${dtcgName(hit.key)}}`;
+  }
+  return dtcgColor(raw);
+}
+
+function shadowValue(css) {
+  const layers = parseShadow(css);
+  if (layers === null) return null;
+  if (!layers.length) return { color: dtcgColor('#00000000'), offsetX: dim(0), offsetY: dim(0), blur: dim(0), spread: dim(0) };
+  const values = layers.map((layer) => ({
+    color: dtcgColor(layer.color) || dtcgColor('#000000'),
+    offsetX: dim(layer.offsetX), offsetY: dim(layer.offsetY), blur: dim(layer.blur), spread: dim(layer.spread),
+    ...(layer.inset ? { inset: true } : {}),
+  }));
+  return values.length === 1 ? values[0] : values;
+}
+
+/**
+ * The guide as a DTCG document (a plain object). Tokens whose CSS cannot be expressed in DTCG
+ * (an unreadable shadow, a steps() easing) are left out and listed under
+ * `$extensions["dev.synabun"].skipped`.
+ */
+export function exportDtcg(input, { generatedAt = null } = {}) {
+  const config = normalizeStyleGuide(input);
+  const themes = themesOf(config);
+  const skipped = [];
+  const doc = {
+    $description: 'Design tokens generated by SynaBun Style Guide. Do not edit by hand.',
+    $extensions: { [DTCG_EXTENSION_KEY]: { revision: config.revision, generatedAt: generatedAt || config.updatedAt || null, projectPath: config.projectPath, skipped } },
+  };
+
+  // ── color ──
+  const color = { $type: 'color' };
+  for (const [key, palette] of Object.entries(config.colors.palettes)) {
+    const group = palette.usage ? { $description: palette.usage } : {};
+    for (const [step, hex] of Object.entries(palette.steps)) group[dtcgName(step)] = token(dtcgColor(hex));
+    color[dtcgName(key)] = group;
+  }
+  color.status = {};
+  for (const [key, hex] of Object.entries(config.colors.status)) color.status[dtcgName(key)] = token(dtcgColor(hex));
+  color.semantic = {};
+  for (const theme of themes) {
+    const group = {};
+    for (const [role, raw] of Object.entries(config.colors.semantic[theme])) {
+      const value = colorRef(config, raw, theme);
+      if (value) group[dtcgName(role)] = token(value);
+      else skipped.push(`color.semantic.${theme}.${role}`);
+    }
+    color.semantic[theme] = group;
+  }
+  doc.color = color;
+
+  // ── typography ──
+  const fontFamily = { $type: 'fontFamily' };
+  for (const [key, font] of Object.entries(config.typography.fonts)) {
+    if (font) fontFamily[key] = token(fontList(font), `${font.source} · weights ${font.weights.join(', ')}`, { source: font.source, weights: font.weights, ...(font.features ? { features: font.features } : {}) });
+  }
+  doc.fontFamily = fontFamily;
+  const typography = { $type: 'typography' };
+  const lineHeight = { $type: 'number' };
+  for (const [id, style] of Object.entries(config.typography.styles)) {
+    typography[dtcgName(id)] = token({
+      fontFamily: `{fontFamily.${fontKeyOf(config, style)}}`,
+      fontSize: dim(style.size),
+      fontWeight: style.weight,
+      letterSpacing: dim(style.letterSpacing * style.size),
+      lineHeight: style.lineHeight,
+    }, style.usage, { ...(style.mobileSize !== style.size ? { mobileSize: style.mobileSize } : {}), ...(style.transform !== 'none' ? { transform: style.transform } : {}) });
+    lineHeight[dtcgName(id)] = token(style.lineHeight);
+  }
+  doc.typography = typography;
+  doc.lineHeight = lineHeight;
+
+  // ── dimensions ──
+  const dims = (map, describe = null) => {
+    const group = { $type: 'dimension' };
+    for (const [key, value] of Object.entries(map)) group[dtcgName(key)] = token(dim(value), describe?.(key));
+    return group;
+  };
+  doc.spacing = dims(config.layout.spacing.scale);
+  doc.radius = dims(config.shape.radius);
+  doc.radiusRole = { $type: 'dimension' };
+  for (const [role, key] of Object.entries(config.shape.radiusRoles)) doc.radiusRole[dtcgName(role)] = token(`{radius.${dtcgName(key)}}`);
+  doc.breakpoint = dims(config.layout.breakpoints);
+  doc.border = dims(config.shape.borders);
+
+  // ── shadow, motion, numbers ──
+  const shadow = { $type: 'shadow' };
+  for (const [key, level] of Object.entries(config.shape.elevation)) {
+    const value = shadowValue(level.shadow);
+    if (value) shadow[dtcgName(key)] = token(value, level.usage, { css: level.shadow });
+    else skipped.push(`shadow.${key}`);
+  }
+  doc.shadow = shadow;
+  const duration = { $type: 'duration' };
+  for (const [key, ms] of Object.entries(config.motion.durations)) duration[dtcgName(key)] = token(dim(ms, 'ms'));
+  doc.duration = duration;
+  const cubicBezier = { $type: 'cubicBezier' };
+  for (const [key, css] of Object.entries(config.motion.easings)) {
+    const value = parseEasing(css);
+    if (value) cubicBezier[dtcgName(key)] = token(value);
+    else skipped.push(`cubicBezier.${key}`);
+  }
+  doc.cubicBezier = cubicBezier;
+  const zIndex = { $type: 'number' };
+  for (const [key, value] of Object.entries(config.layout.zIndex)) zIndex[dtcgName(key)] = token(value);
+  doc.zIndex = zIndex;
+  return doc;
+}
+
+/** tokens.json as text. */
+export function exportDtcgText(input, options = {}) {
+  return `${JSON.stringify(exportDtcg(input, options), null, 2)}\n`;
+}
+
+const DTCG_TYPES = new Set(['color', 'dimension', 'fontFamily', 'fontWeight', 'duration', 'cubicBezier', 'number', 'strokeStyle', 'border', 'transition', 'shadow', 'gradient', 'typography']);
+
+/**
+ * Every token of a DTCG document with its inherited type: [{ path, type, value, description, alias }].
+ * `problems` lists what a validator would refuse: a token without a type, an alias that names nothing,
+ * a name with a forbidden character. The importer and the tests both read this.
+ */
+export function walkDtcg(doc) {
+  const tokens = [];
+  const problems = [];
+  const visit = (node, path, inherited) => {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+    const type = typeof node.$type === 'string' ? node.$type : inherited;
+    if ('$value' in node) {
+      const alias = typeof node.$value === 'string' && /^\{[^{}]+\}$/.test(node.$value) ? node.$value.slice(1, -1) : null;
+      const extension = node.$extensions && typeof node.$extensions === 'object' ? node.$extensions[DTCG_EXTENSION_KEY] : null;
+      tokens.push({ path, type: type || null, value: node.$value, description: node.$description || '', alias, extension: extension && typeof extension === 'object' ? extension : null });
+      return;
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (key.startsWith('$')) continue;
+      if (/[{}.]/.test(key)) problems.push(`${[...path, key].join('.')}: a name may not contain "{", "}" or "."`);
+      visit(child, [...path, key], type);
+    }
+  };
+  visit(doc, [], null);
+  const byPath = new Map(tokens.map((entry) => [entry.path.join('.'), entry]));
+  const typeOf = (entry, depth = 0) => {
+    if (entry.type || !entry.alias || depth > 8) return entry.type;
+    const target = byPath.get(entry.alias);
+    return target ? typeOf(target, depth + 1) : null;
+  };
+  for (const entry of tokens) {
+    const name = entry.path.join('.');
+    if (entry.alias && !byPath.has(entry.alias)) problems.push(`${name}: alias {${entry.alias}} names no token`);
+    const type = typeOf(entry);
+    if (!type) problems.push(`${name}: no $type`);
+    else if (!DTCG_TYPES.has(type)) problems.push(`${name}: unknown $type ${type}`);
+    entry.type = type;
+  }
+  return { tokens, problems };
+}