@scattered-light/loomiere 0.2.0 → 0.4.0

package/lib/contrast.mjs

@@ -18,12 +18,15 @@ 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
+ * A token's value in a mode ('vision:<theme>' for a color vision theme). 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}`);
+  // A color vision theme is light with the brand's colors swapped for its own.
+  const vision = mode.startsWith('vision:') && byPath.get(`vision.${mode.slice(7)}.${tokenPath}`);
+  if (vision) return vision.value;
   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(/^\{([^}]+)\}$/);
@@ -82,7 +85,9 @@ const { tokens } = JSON.parse(fs.readFileSync(path.join(outDir, 'tokens.json'),
 const byPath = new Map(tokens.map((t) => [t.path, t]));
 const failures = [];
 const rows = [];
-for (const mode of MODES) {
+const visions = [...new Set(tokens.filter((t) => t.path.startsWith('vision.')).map((t) => t.path.split('.')[1]))];
+const modes = [...MODES, ...visions.map((v) => `vision:${v}`)];
+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);
@@ -129,6 +134,6 @@ export function reportContrast({ rows, failures }) {
     }
     return false;
   }
-  console.log(`Contrast check passed: ${rows.length} pairs across ${MODES.length} modes, brand pairs included.`);
+  console.log(`Contrast check passed: ${rows.length} pairs across ${new Set(rows.map((r) => r.mode)).size} modes, brand pairs included.`);
   return true;
 }

package/lib/figma.mjs

@@ -0,0 +1,338 @@
+/**
+ * loomiere figma: sends the built theme (exports/figma.json) to a Figma file.
+ *
+ *   loomiere figma push              build, then push by the first way that works here:
+ *     --via claude                   Claude Code with a Figma connector runs the push scripts
+ *     --via api                      Figma's REST API with FIGMA_TOKEN (Enterprise plans only;
+ *                                    variables only, the API can't write text styles)
+ *     --via plugin                   serve the build for the Loomiere plugin's Pull from project
+ *     --via scripts                  write the push scripts and stop (what Claude runs in chat)
+ *   loomiere figma serve             serve the build for the plugin, without pushing
+ *
+ * Options: --file <Figma URL or key> (or "figma": { "file": … } in loomiere.config.json),
+ * --since <snapshot.json> (scripts: only what changed), --remove (delete what the build no
+ * longer has), --dry-run (report only), --port <n>.
+ *
+ * Every way runs the same engine (figma/engine.js), so they leave the file the same.
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import vm from 'node:vm';
+
+import { engineRoot } from './tool-server.mjs';
+
+const ENGINE_FILE = path.join(engineRoot, 'figma', 'engine.js');
+/** use_figma takes up to 50,000 characters of code; leave room for the call around the engine. */
+const PART_LIMIT = 48000;
+export const DEFAULT_PORT = 4322;
+
+const engineText = () => fs.readFileSync(ENGINE_FILE, 'utf8');
+/** The engine without its comments, so more of each part is data. */
+const engineCompact = () =>
+  engineText()
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '')
+    .replace(/\n\s*\n/g, '\n')
+    .trim();
+
+/** The engine's own functions, for Node: fingerprints and layouts match the file side exactly. */
+export function engine() {
+  const context = {};
+  vm.runInNewContext(`${engineText()}\nthis.api = { loomiereFingerprint, loomiereLayout, loomiereGroupOf, loomiereGroupHash, loomiereHash, loomiereText };`, context);
+  return context.api;
+}
+
+export const figmaJsonPath = (config) => path.join(config.outDir, 'exports', 'figma.json');
+
+export function readFigmaJson(config) {
+  const file = figmaJsonPath(config);
+  if (!fs.existsSync(file)) throw new Error(`No ${path.relative(config.cwd, file)} yet. Run loomiere build (and keep "figma" in "exports" if you list them).`);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/** "https://www.figma.com/design/KEY/Name?…" or "KEY" → "KEY". */
+export function fileKeyOf(value) {
+  if (!value) return null;
+  const m = String(value).match(/figma\.com\/(?:design|file)\/([0-9a-zA-Z]{22,128})(?:\/branch\/([0-9a-zA-Z]{22,128}))?/);
+  if (m) return m[2] ?? m[1];
+  return /^[0-9a-zA-Z]{22,128}$/.test(value) ? value : null;
+}
+
+const call = (data, options) => `\nreturn await loomiereSync(${JSON.stringify(data)}, ${JSON.stringify(options)});\n`;
+
+const SNAPSHOT_NEEDS = ['LOOMIERE_FLAT_NAMES', 'LOOMIERE_MODE_NAMES', 'loomiereRgba', 'loomiereHex8', 'loomiereCanon', 'loomiereText', 'loomiereHash', 'loomiereModeLimit', 'loomiereReadFile', 'loomiereFileFingerprint', 'loomiereGroupOf', 'loomiereGroupHash', 'loomiereSnapshot'];
+
+/** The script that reads what the file has, run first in every scripted push: just the parts it needs. */
+export function snapshotScript() {
+  const blocks = engineCompact().split(/\n(?=(?:var|function|async function) )/);
+  const needed = blocks.filter((b) => SNAPSHOT_NEEDS.includes(b.match(/^(?:var|function|async function) (\w+)/)?.[1]));
+  return `${needed.join('\n')}\nreturn await loomiereSnapshot();\n`;
+}
+
+/**
+ * The push as use_figma scripts, each under the size limit. `snapshot` is what
+ * snapshotScript() returned: the plan's mode limit and a hash per group of variables, so only
+ * groups that differ are sent, each whole in one part.
+ */
+export function pushScripts(data, snapshot, { remove = false, dryRun = false } = {}) {
+  const { loomiereFingerprint, loomiereLayout, loomiereGroupOf, loomiereGroupHash } = engine();
+  const limit = snapshot.modeLimit ?? 1;
+  const warnings = [];
+  const layout = loomiereLayout(data, limit, 'auto', warnings);
+  const head = engineCompact();
+  const room = PART_LIMIT - head.length - 400;
+  const base = { format: data.format, version: data.version, brand: data.brand };
+  const options = { layout: 'modes', modeLimit: limit, dryRun, partial: true, remove };
+  const headers = layout.collections.map((c) => ({ name: c.name, modes: c.modes, ...(c.hidden && { hidden: true }) }));
+
+  // The build's groups, the same way the snapshot groups the file.
+  const groups = new Map();
+  for (const c of layout.collections) {
+    for (const v of c.variables) {
+      const g = `${c.name}:${loomiereGroupOf(v.name)}`;
+      if (!groups.has(g)) groups.set(g, { collection: c.name, variables: [], entries: [] });
+      groups.get(g).variables.push(v);
+      groups.get(g).entries.push([v.name, loomiereFingerprint(c, v)]);
+    }
+  }
+  const have = snapshot.groups ?? {};
+  const changed = [...groups].filter(([g, { entries }]) => have[g] !== loomiereGroupHash(entries));
+  const ours = layout.collections.map((c) => c.name);
+  const removeGroups = Object.keys(have).filter((g) => ours.includes(g.slice(0, g.indexOf(':'))) && !groups.has(g));
+  const removeCollections = (snapshot.collections ?? []).filter((n) => !ours.includes(n));
+
+  const parts = [];
+  let current = [];
+  let size = 0;
+  const flush = (extra = {}) => {
+    const collections = headers.map((h) => ({ ...h, variables: current.filter(([, g]) => g.collection === h.name).flatMap(([, g]) => g.variables) }));
+    parts.push(head + call({ ...base, collections, ...extra.data }, { ...options, complete: current.map(([key]) => key), textStyles: false, ...extra.options }));
+    current = [];
+    size = 0;
+  };
+  for (const entry of changed) {
+    const n = JSON.stringify(entry[1].variables).length + entry[0].length + 4;
+    if (size && size + n > room) flush();
+    current.push(entry);
+    size += n;
+  }
+  if (current.length) flush();
+  // Last: text and effect styles, and the groups and collections the build no longer has.
+  flush({ data: { textStyles: data.textStyles, effectStyles: data.effectStyles }, options: { textStyles: true, removeGroups, removeCollections } });
+  const tooBig = parts.findIndex((p) => p.length > 50000);
+  if (tooBig !== -1) throw new Error(`Push part ${tooBig + 1} is over use_figma's 50,000 characters; a variable group is too large to send in one part.`);
+  const variables = changed.reduce((n, [, g]) => n + g.variables.length, 0);
+  return { layout: layout.name, limit, changed: variables, groups: changed.length, parts, warnings };
+}
+
+/** Writes the scripts to <out>/figma-push/ and returns their paths. */
+function writeScripts(config, scripts) {
+  const dir = path.join(config.outDir, 'figma-push');
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  return scripts.map((text, i) => {
+    const file = path.join(dir, `${String(i + 1).padStart(2, '0')}.js`);
+    fs.writeFileSync(file, text);
+    return file;
+  });
+}
+
+// --- via plugin --------------------------------------------------------------
+
+/** Serves exports/figma.json for the plugin's Pull from project, read fresh on each request. */
+export function serve(config, { port = DEFAULT_PORT } = {}) {
+  const server = http.createServer((req, res) => {
+    const headers = { 'access-control-allow-origin': '*', 'access-control-allow-private-network': 'true', 'cache-control': 'no-store' };
+    if (req.method === 'OPTIONS') return res.writeHead(204, { ...headers, 'access-control-allow-methods': 'GET' }), res.end();
+    if (req.method !== 'GET' || new URL(req.url, 'http://localhost').pathname !== '/figma.json') return res.writeHead(404, headers), res.end();
+    try {
+      res.writeHead(200, { ...headers, 'content-type': 'application/json' });
+      res.end(fs.readFileSync(figmaJsonPath(config)));
+    } catch (err) {
+      res.writeHead(500, headers);
+      res.end(err.message);
+    }
+  });
+  server.listen(port, '127.0.0.1', () => {
+    console.log(`Serving ${path.relative(config.cwd, figmaJsonPath(config))} at http://localhost:${port}/figma.json`);
+    console.log('In Figma: Plugins › Development › Loomiere › Pull from project. Ctrl+C to stop.');
+  });
+  return server;
+}
+
+// --- via claude --------------------------------------------------------------
+
+const hasClaude = () => {
+  try {
+    execFileSync('claude', ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const FIGMA_TOOLS = ['mcp__figma__use_figma', 'mcp__Figma__use_figma', 'mcp__claude_ai_Figma__use_figma', 'mcp__figma-remote-mcp__use_figma'];
+
+function viaClaude(config, fileKey, { remove, dryRun }) {
+  const dir = path.join(config.outDir, 'figma-push');
+  fs.mkdirSync(dir, { recursive: true });
+  const snap = path.join(dir, 'snapshot.js');
+  fs.writeFileSync(snap, snapshotScript());
+  const rel = (p) => path.relative(config.cwd, p);
+  const flags = [remove && '--remove', dryRun && '--dry-run'].filter(Boolean).join(' ');
+  const prompt = [
+    `Push this project's Loomiere theme to the Figma file ${fileKey} with the Figma connector's use_figma tool.`,
+    `1. Run the code in ${rel(snap)} with use_figma on that file, exactly as written. Save the JSON it returns to ${rel(path.join(dir, 'snapshot.json'))}.`,
+    `2. Run: npx loomiere figma push --via scripts --since ${rel(path.join(dir, 'snapshot.json'))} ${flags}`.trim(),
+    `   It writes numbered scripts to ${rel(dir)}/.`,
+    '3. Run each numbered script with use_figma on the file, one at a time, in order, exactly as written. Do not edit them.',
+    '4. Report what the last script returned: what was created, updated and removed, and any warnings.',
+  ].join('\n');
+  console.log(`Pushing to Figma through Claude Code (file ${fileKey})…`);
+  const child = spawn('claude', ['-p', prompt, '--allowedTools', ['Read', 'Write', 'Bash(npx loomiere figma push:*)', ...FIGMA_TOOLS].join(',')], {
+    cwd: config.cwd,
+    stdio: 'inherit',
+  });
+  return new Promise((resolve) => child.on('exit', (code) => resolve(code === 0)));
+}
+
+// --- via api (Figma Enterprise) ---------------------------------------------
+
+async function figmaApi(token, method, url, body) {
+  const res = await fetch(`https://api.figma.com${url}`, {
+    method,
+    headers: { 'X-Figma-Token': token, 'content-type': 'application/json' },
+    body: body && JSON.stringify(body),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`Figma API ${res.status}: ${json.message ?? json.err ?? res.statusText}${res.status === 403 ? ' (writing variables through the API needs an Enterprise plan and a token with file_variables:write)' : ''}`);
+  return json;
+}
+
+const rgba = (hex) => {
+  const h = hex.replace('#', '');
+  const n = (i) => parseInt(h.slice(i, i + 2), 16) / 255;
+  return { r: n(0), g: n(2), b: n(4), a: h.length === 8 ? n(6) : 1 };
+};
+
+/**
+ * Variables through POST /v1/files/:key/variables. Enterprise allows modes in every
+ * collection, so this sends the modes layout. Matched by name like the engine; only changed
+ * variables are sent. Text styles can't go through the API.
+ */
+async function viaApi(config, fileKey, token, { remove, dryRun }) {
+  const { loomiereFingerprint, loomiereHash, loomiereText } = engine();
+  const data = readFigmaJson(config);
+  const { meta } = await figmaApi(token, 'GET', `/v1/files/${fileKey}/variables/local`);
+  const cols = Object.values(meta.variableCollections).filter((c) => !c.remote);
+  const vars = Object.values(meta.variables).filter((v) => !v.remote);
+  const colByName = new Map(cols.map((c) => [c.name, c]));
+  const keyOf = (v) => `${meta.variableCollections[v.variableCollectionId]?.name}:${v.name}`;
+  const varByKey = new Map(vars.map((v) => [keyOf(v), v]));
+  const idOf = (key) => varByKey.get(key)?.id ?? `tmp:${key}`;
+  const canon = (type, raw) => {
+    if (raw?.type === 'VARIABLE_ALIAS') return `@${keyOf(meta.variables[raw.id] ?? {})}`;
+    if (type === 'COLOR') return `#${['r', 'g', 'b', 'a'].map((k) => `0${Math.round((raw[k] ?? 1) * 255).toString(16)}`.slice(-2)).join('')}`;
+    if (type === 'FLOAT') return String(Math.round(raw * 1000) / 1000);
+    return String(raw);
+  };
+  const body = { variableCollections: [], variableModes: [], variables: [], variableModeValues: [] };
+  const modeId = {};
+  for (const c of data.collections) {
+    const col = colByName.get(c.name);
+    const colId = col?.id ?? `tmp:${c.name}`;
+    if (!col) body.variableCollections.push({ action: 'CREATE', id: colId, name: c.name, initialModeId: `tmp:${c.name}:${c.modes[0]}`, hiddenFromPublishing: !!c.hidden });
+    c.modes.forEach((m, i) => {
+      const found = col?.modes.find((x) => x.name === m);
+      modeId[`${c.name}:${m}`] = found?.modeId ?? `tmp:${c.name}:${m}`;
+      if (!found && (col || i > 0)) body.variableModes.push({ action: 'CREATE', id: `tmp:${c.name}:${m}`, name: m, variableCollectionId: colId });
+      if (!col && i === 0) body.variableModes.push({ action: 'UPDATE', id: `tmp:${c.name}:${m}`, name: m, variableCollectionId: colId });
+    });
+    for (const v of c.variables) {
+      const key = `${c.name}:${v.name}`;
+      const existing = varByKey.get(key);
+      if (existing && col) {
+        const parts = [existing.resolvedType, ...c.modes.slice().sort().map((m) => {
+          const raw = existing.valuesByMode[col.modes.find((x) => x.name === m)?.modeId];
+          return `${m}=${raw === undefined ? '' : canon(existing.resolvedType, raw)}`;
+        }), existing.scopes.slice().sort().join(','), existing.codeSyntax?.WEB ?? '', loomiereText(existing.description), col.hiddenFromPublishing ? 'hidden' : ''];
+        if (loomiereHash(parts.join('|')) === loomiereFingerprint(c, v)) continue;
+      }
+      body.variables.push({
+        action: existing ? 'UPDATE' : 'CREATE',
+        id: idOf(key),
+        ...(!existing && { name: v.name, variableCollectionId: colId, resolvedType: v.type }),
+        scopes: v.scopes,
+        ...(v.code && { codeSyntax: { WEB: v.code } }),
+        description: v.description ?? '',
+      });
+      for (const m of c.modes) {
+        const value = v.values[m];
+        if (value === undefined || value === null) continue;
+        body.variableModeValues.push({
+          variableId: idOf(key),
+          modeId: modeId[`${c.name}:${m}`],
+          value: value.alias ? { type: 'VARIABLE_ALIAS', id: idOf(value.alias) } : v.type === 'COLOR' ? rgba(value) : value,
+        });
+      }
+    }
+  }
+  const wanted = new Set(data.collections.flatMap((c) => c.variables.map((v) => `${c.name}:${v.name}`)));
+  const gone = vars.filter((v) => data.collections.some((c) => c.name === meta.variableCollections[v.variableCollectionId]?.name) && !wanted.has(keyOf(v)));
+  if (remove) for (const v of gone) body.variables.push({ action: 'DELETE', id: v.id });
+  console.log(`${body.variables.filter((v) => v.action === 'CREATE').length} to create, ${body.variables.filter((v) => v.action === 'UPDATE').length} to update, ${gone.length} no longer in the build${remove ? ' (deleting)' : ''}.`);
+  if (dryRun) return true;
+  // The API takes up to 5,000 changes a request, and temporary ids only last one request: send
+  // collections, modes and variables first, then the values in batches with the real ids.
+  const { variableModeValues, ...structure } = body;
+  const first = await figmaApi(token, 'POST', `/v1/files/${fileKey}/variables`, structure);
+  const real = (id) => first.meta?.tempIdToRealId?.[id] ?? id;
+  for (let i = 0; i < variableModeValues.length; i += 4000) {
+    const batch = variableModeValues.slice(i, i + 4000).map((v) => ({
+      ...v,
+      variableId: real(v.variableId),
+      modeId: real(v.modeId),
+      value: v.value?.type === 'VARIABLE_ALIAS' ? { ...v.value, id: real(v.value.id) } : v.value,
+    }));
+    await figmaApi(token, 'POST', `/v1/files/${fileKey}/variables`, { variableModeValues: batch });
+  }
+  console.log('Variables pushed. Text and effect styles can only be written inside Figma: ask Claude to sync, or use the plugin.');
+  return true;
+}
+
+// --- the command -------------------------------------------------------------
+
+export async function figmaCommand(config, sub, { via, file, since, remove = false, dryRun = false, port } = {}) {
+  if (sub === 'serve') return serve(config, { port });
+  if (sub !== 'push') throw new Error('Use loomiere figma push or loomiere figma serve.');
+  const fileKey = fileKeyOf(file ?? config.figma?.file ?? config.figma);
+
+  if (via === 'scripts') {
+    if (!since) {
+      const [snap] = writeScripts(config, [snapshotScript()]);
+      console.log(`Wrote ${path.relative(config.cwd, snap)}. Run it with use_figma, save what it returns, then: loomiere figma push --via scripts --since <that file>`);
+      return true;
+    }
+    const snapshot = JSON.parse(fs.readFileSync(path.resolve(config.cwd, since), 'utf8'));
+    const { layout, limit, changed, groups, parts, warnings } = pushScripts(readFigmaJson(config), snapshot, { remove, dryRun });
+    const files = writeScripts(config, parts);
+    for (const w of warnings) console.log(`Note: ${w}`);
+    console.log(`${changed} variables in ${groups} groups differ from the file (${layout} layout, ${limit} modes per collection allowed).`);
+    console.log(`Wrote ${files.length} scripts to ${path.relative(config.cwd, path.dirname(files[0]))}/: run them in order with use_figma.`);
+    return true;
+  }
+
+  const token = process.env.FIGMA_TOKEN;
+  const chosen = via ?? (token && fileKey ? 'api' : hasClaude() && fileKey ? 'claude' : 'plugin');
+  if (chosen !== 'plugin' && !fileKey) throw new Error('Which Figma file? Pass --file <url> or set "figma": { "file": "<url>" } in loomiere.config.json.');
+  if (chosen === 'api') {
+    if (!token) throw new Error('--via api needs FIGMA_TOKEN (a Figma personal access token with file_variables:write).');
+    return viaApi(config, fileKey, token, { remove, dryRun });
+  }
+  if (chosen === 'claude') return viaClaude(config, fileKey, { remove, dryRun });
+  if (!via) console.log('No FIGMA_TOKEN (Enterprise) or Claude Code here, so serving the build for the Loomiere plugin instead.');
+  serve(config, { port });
+  return true;
+}

package/lib/studio.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 
 import { formatBrand } from '../generator/format-brand.mjs';
 import { brandFiles, schemaPathFor } from './config.mjs';
+import { readFigmaJson } from './figma.mjs';
 import { engineRoot, readJson, saveAndRebuild, serveTool } from './tool-server.mjs';
 
 const toolDir = path.join(engineRoot, 'tools', 'brand-builder');
@@ -92,7 +93,10 @@ export function studio(config, { port = 4322, exportFile } = {}) {
     routes: {
       'GET /api/brand': (_, url) => load(url.searchParams.get('name') || brandName),
       'POST /api/brand': save,
+      // The built theme for the Loomiere Figma plugin's Pull from project.
+      'GET /figma.json': () => readFigmaJson(config),
     },
+    open: ['/figma.json'],
     onListen: () => {
       console.log(`Brand studio for "${brandName}": http://localhost:${port}`);
       console.log(`Save writes ${path.relative(config.cwd, brandDir) || '.'}/<name>.json; saving "${brandName}" also rebuilds the theme. Ctrl+C to stop.`);

package/lib/tool-server.mjs

@@ -53,16 +53,19 @@ const TYPES = {
 /**
  * Serves `dir` at / plus any `mounts` ({ '/prefix/': directory }), and JSON `routes`
  * ({ 'GET /data.json': () => data, 'POST /save': (body) => result }). A route that throws
- * answers 400 with { ok: false, error }.
+ * answers 400 with { ok: false, error }. Paths in `open` can be read from other origins (the
+ * Figma plugin reads /figma.json).
  */
-export function serveTool({ dir, mounts = {}, routes, port, onListen }) {
+export function serveTool({ dir, mounts = {}, routes, port, onListen, open = [] }) {
   const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    const cors = open.includes(url.pathname) ? { 'access-control-allow-origin': '*', 'access-control-allow-private-network': 'true' } : {};
     const send = (status, body, type = TYPES['.json']) => {
-      res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store' });
+      res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store', ...cors });
       res.end(typeof body === 'string' ? body : JSON.stringify(body));
     };
     try {
-      const url = new URL(req.url, 'http://localhost');
+      if (req.method === 'OPTIONS' && open.includes(url.pathname)) return res.writeHead(204, { ...cors, 'access-control-allow-methods': 'GET' }), res.end();
       const route = routes[`${req.method} ${url.pathname}`];
       if (route) {
         let body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scattered-light/loomiere",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Turns a small brand file into a full design token theme: OKLCH color ramps, a type scale, light, dark and high-contrast modes, plus Tailwind, MUI, Chakra, AG Grid and Figma exports.",
   "keywords": ["design-tokens", "theme", "style-dictionary", "dtcg", "oklch", "base-ui", "ag-grid", "tailwind"],
   "repository": {
@@ -25,12 +25,16 @@
     "bin",
     "build",
     "exporters",
+    "figma",
     "generator",
     "lib",
     "templates",
     "tokens",
     "tools"
   ],
+  "scripts": {
+    "build": "node figma/build-plugin.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": false

package/tokens/README.md

@@ -26,18 +26,21 @@ Light, dark and high-contrast colors are decided in one place: the slot table in
 | `dark` | `prefers-color-scheme: dark` (unless `data-theme="light"`), or `data-theme="dark"` |
 | `contrast-more` | `prefers-contrast: more` |
 | `dark-contrast-more` | Both of the above |
-| `reduced-motion` | `prefers-reduced-motion: reduce` (shadows flatten to outlines) |
+| `reduced-motion` | `prefers-reduced-motion: reduce` (durations drop to 1ms, so things change at once instead of moving) |
 
 Palettes never change between modes. Dark mode picks different palette steps, so `--sl-color-neutral-100` is the same color everywhere and `--sl-scope-neutral-overlay` (and through it `--sl-surface-overlay`) is what flips. Use semantic tokens in app code. Set `data-theme` on the root element: the variables that point at slots resolve there.
 
 ### Color vision themes
 
-There's no media query for color blindness, so these are opt-in, like a theme switch: set `data-vision` on the root element to `deuteranopia` (green-blind, the most common), `protanopia` (red-blind), `tritanopia` (blue-blind) or `achromatopsia` (no color vision, which also suits grayscale screens). Each re-declares the spot palettes (`--sl-color-primary-*` through `quaternary` and `success`, `warning`, `error`, `info`, with their on-colors) and the data colors (`--sl-color-data-*`) with versions generated for that kind of color vision; everything that reads them follows, in light and dark. They work with any mode. Set the attribute on the root element only: variables declared at `:root` resolve there.
+Color vision themes are themes of their own, next to light, dark and the two high-contrast themes. There's no media query for color blindness, so they're opt-in: set `data-theme` on the root element to `deuteranopia` (green-blind, the most common), `protanopia` (red-blind), `tritanopia` (blue-blind) or `achromatopsia` (no color vision, which also suits grayscale screens). Each is a light theme that re-declares the spot palettes (`--sl-color-primary-*` through `quaternary` and `success`, `warning`, `error`, `info`, with their on-colors) and the data colors (`--sl-color-data-*`) with versions generated for that kind of color vision; everything that reads them follows. The system's dark mode and contrast setting don't change them. Set the attribute on the root element only: variables declared at `:root` resolve there.
+
+The full list of `data-theme` values: `light`, `dark`, `light-high-contrast`, `dark-high-contrast`, `deuteranopia`, `protanopia`, `tritanopia`, `achromatopsia`. With no `data-theme`, the system picks light or dark and high contrast.
 
 The generator (`generator/vision.mjs`) designs each theme from the brand's own alert and data colors every build, so any brand file gets its own four themes. Nothing is a fixed, shared palette:
 
 - **Palettes.** Every spot palette (brand colors and alerts; the neutral stays) moves until colors that look different with typical vision don't blur together with that vision. Colors that look alike to everyone, like an ember brand color and an error red, aren't pushed apart. For the three color blindnesses palettes turn hue (alerts at most 40°, so a green success never turns yellow; brand colors cost four times as much to move, since they carry identity). For achromatopsia, where hue means nothing, they darken instead (never lighten, so none loses contrast). Each ramp is rebuilt on the same contrast table, so every step keeps its contrast, and the theme re-declares every step and on-color.
 - **Data colors** are nudged, in series order, until each is at least ΔE 15 from the two before and after it as seen with that vision. None loses contrast on paper.
+- **Order.** `color.vision.tritanopia.dataOrder = ["coral", "navy"]` puts the data series in that theme's own order (names left out follow in the brand's order), so the first few series can be the ones that stay apart for that vision. Data colors are tokens by name (`--sl-color-data-coral`); the series slots `--sl-color-data-1`… point at a name, and each theme re-points them.
 - **Pins.** `color.vision.deuteranopia.keys.primary = "#3a5bd9"` fixes the color that stands for a palette (its most colorful key; the whole ramp moves with it), and `color.vision.deuteranopia.data.coral = "#d55e00"` fixes one data color. The others move to make room. The brand builder's **Color vision** section shows the brand and each theme as cards; open a theme to see every color as designed and as seen, and pin any of them.
 
 For low vision, the `contrast-more` modes above already raise contrast when the system asks for it.
@@ -65,7 +68,9 @@ The accent can be any brand color; a red brand might keep red for errors and pic
 
 **Concept picks.** `roles.concepts` in the brand file replaces a role's default step for one concept, in light, dark or both: `"chrome.fg": { "light": "primary.1000" }` sets body text to the brand's text color without touching any palette. A pick is `palette.step`, `white` (paper), `black` (ink) or a hex. The Concepts section of `loomiere studio` shows every concept in light and dark with its contrast and what uses it, and Reset drops a pick. Spot palettes share a contrast table, so `solid` has the same contrast in every hue; that is why any palette can stand in for another. `--sl-scope-<slot>` is the scope in effect: the accent by default, any palette under `data-color="secondary"` (or `error`, `chrome`…).
 
-**Emphasis.** Styles are `solid`, `soft`, `outline` and `ghost`. `data-emphasis="subtle"` sets `--sl-e-bg`, `-bg-hover`, `-bg-active`, `-fg`, `-border` and `-border-hover` from the level's style. Accent levels follow the scope around them, so a `data-color` on a section re-colors them; chrome and named-palette levels stay put unless the element sets its own `data-color`. In React: `<Button emphasis="bold">`, `<Button emphasis="subtle" palette="error">`. Any component can read `--sl-e-*` the same way.
+**Emphasis.** Styles are `solid`, `soft`, `outline` and `ghost`. `data-emphasis="subtle"` sets `--sl-e-bg`, `-bg-hover`, `-bg-active`, `-fg`, `-border` and `-border-hover` from the level's style. Accent levels follow the scope around them, so a `data-color` on a section re-colors them; chrome and named-palette levels stay put unless the element sets its own `data-color`. In React: `<Button emphasis="bold">`, `<Button emphasis="subtle" palette="error">`. Emphasis isn't only for buttons: each component that has a loudness choice starts at a level of its own (Button bold, Toggle's pressed state standard, Avatar initials bold) and paints with `--sl-e-*`, so `data-emphasis` on it picks another level, and on a Toggle Group sets every toggle in it. A new component joins by reading `--sl-e-*` and getting a default level in `DEFAULT_LEVELS` (build/build-tokens.mjs).
+
+**Statuses.** `data-status="info|success|warning|error"` on any element gives every emphasis level inside it that status's version: by default the level's style in the status's palette, chrome levels included, so `<div data-status="warning" data-emphasis="subtle">` is a soft warning banner and a bold button inside it is solid warning. A toast's type is its status. `roles.status` in the brand file lets a brand pair stand in for a level, per status: `{ "default": { "bold": "mirage-deep" }, "warning": { "subtle": "dune-soft" } }`. The pair paints the element: `bg` and `fg`, with `bg-hover` and `bg-active` mixed from them (`pair.<name>.bg-hover`, kept at AA). Levels left out stay automatic. The tokens are `status-level.<status>.<level>.<part>` (`tokens/semantic/status.json`, generated); `emphasis.<level>.<part>` is the default status's row.
 
 ## Exports for other frameworks
 
@@ -88,7 +93,7 @@ The universal outputs are the CSS variables (`tokens.css`, works with any framew
 
 ## Text styles and utilities
 
-Each text style is one `typography` token in `semantic/typography.json`, named by tier and use: `base`, `base-label`, `condense-subtitle-label`, `maximize-2xl`. A style can be another style (`"base-link": "{font.base}"`) when only color sets it apart. The build expands every style into the CSS variables components use, `--sl-font-<style>-font` (shorthand), `-font-family`, `-font-size`, `-font-weight`, `-line-height`, `-letter-spacing` and, for uppercase styles, `-text-transform`.
+Each text style is one `typography` token in `semantic/typography.json`, named role first, then tier: `body-base`, `label-base`, `trigger-condense`, `eyebrow-condense`, `title-magnify`. The role is the job (body, label, trigger, selected, link, subtitle, eyebrow, title, code); the tier sets the size (minimize, condense, base, magnify, amplify, maximize). Titles use the display family: `title-amplify` for dialogs and sections, `title-maximize` for the page head. A style can be another style (`"link-base": "{font.body-base}"`) when only color sets it apart. The build expands every style into the CSS variables components use, `--sl-font-<style>-font` (shorthand), `-font-family`, `-font-size`, `-font-weight`, `-line-height`, `-letter-spacing` and, for uppercase styles, `-text-transform`.
 
 `loomiere build` also writes the utility classes into `<theme>/utilities.css`, so they always match the tokens: `.text-style-<style>` for every text style, `.icon-<tier>` for every icon size, `.focus-ring` and `.focus-ring-inset`, and `.hide-on-mobile|tablet|desktop` from the breakpoints.
 
@@ -110,7 +115,7 @@ Some looks belong to a family of components, not to one. Those are concepts in t
 - Tooltip, Preview card and Navigation menu are built from existing concepts. Tooltip uses `surface.inverse` with `text.on-inverse-surface`, which has its own Concepts row. Preview card uses `popup.*`. Navigation menu uses `bar.*` for the strip, `popup.*` for the panel, and item hover for links. Each keeps only size tokens.
 - `notice.*` (`semantic/notice.json`): toasts, on the popup surface. A toast whose type is success, warning, error or info takes that palette's soft fill, edge and text (the build points the scope at it); `data-color` picks any other palette. Toast keeps only the stack's width and corner margins.
 - `gauge.*` (`semantic/gauge.json`): Meter and Progress share one bar. The track is `fill.track` (a Concepts row, near the page in dark mode so every palette's fill reads 3:1 on it); the fill is the scope's solid color, so `data-color` on the root sets a zone or status. Neither has component tokens. Slider is a gauge you can drag: its track, fill and label row are `gauge.*` (thin size), the knob is field-colored and ringed in the scope's solid color, and it keeps only its knob size and vertical length.
-- Avatar, Separator and Scroll area are built from existing tokens. Avatar initials use the scope's solid fill and on-solid text (the bold emphasis colors), its ring is the page color, and it keeps only its five sizes. Separator is `border.default`; Scroll area is `content.scrollbar-*`. Neither has component tokens. Badge, Card and Dropdown token files were removed: no style read them (Base UI has no Badge or Card; menus and selects use `popup.*` and `item.*`).
+- Avatar, Separator and Scroll area are built from existing tokens. Avatar initials paint with the bold emphasis level (data-emphasis picks another), its ring is the page color, and it keeps only its five sizes. Separator is `border.default`; Scroll area is `content.scrollbar-*`. Neither has component tokens. Badge, Card and Dropdown token files were removed: no style read them (Base UI has no Badge or Card; menus and selects use `popup.*` and `item.*`).
 - `item.*` (`semantic/item.json`): rows inside menus and listboxes, and the check or dot that marks a chosen row. `item.padding-block-dense` is for menus.
 - `icon-button.*` (`semantic/icon-button.json`): small icon-only buttons, such as the X that dismisses a popover, dialog or toast, and a field's clear and open buttons.
 - `check.*` (`semantic/check.json`): the box or circle you tick. Checkbox, Radio and the Switch track share it, and AG Grid's checkboxes point at it.

package/tokens/component/avatar.json

@@ -1,10 +1,45 @@
 {
   "avatar": {
-    "$description": "Avatar tokens: only the five sizes. The ring is the page color so overlapping avatars cut out of each other; initials are the scope's solid fill and its text (bold emphasis), so data-color re-colors them.",
-    "size-xs": { "$value": "{space.8}", "$description": "32px, inline with text and in dense lists." },
-    "size-sm": { "$value": "{space.10}", "$description": "40px, in list rows and comments." },
-    "size-md": { "$value": "{space.12}", "$description": "48px, the default." },
-    "size-lg": { "$value": "{space.16}", "$description": "64px, in cards and headers." },
-    "size-xl": { "$value": "{space.24}", "$description": "96px, on a profile page." }
+    "$description": "Avatar tokens: the five sizes and the initials that fit each. The ring is the page color so overlapping avatars cut out of each other; initials are the scope's solid fill and its text (bold emphasis), so data-color re-colors them.",
+    "size-xs": {
+      "$value": "{space.8}",
+      "$description": "32px, inline with text and in dense lists."
+    },
+    "size-sm": {
+      "$value": "{space.10}",
+      "$description": "40px, in list rows and comments."
+    },
+    "size-md": {
+      "$value": "{space.12}",
+      "$description": "48px, the default."
+    },
+    "size-lg": {
+      "$value": "{space.16}",
+      "$description": "64px, in cards and headers."
+    },
+    "size-xl": {
+      "$value": "{space.24}",
+      "$description": "96px, on a profile page."
+    },
+    "initials-font-size-xs": {
+      "$value": "{font-size.xs}",
+      "$description": "Sized to the avatar, not a text style: initials have to fit inside the circle at each size. The rest of the type is title-base."
+    },
+    "initials-font-size-sm": {
+      "$value": "{font-size.sm}",
+      "$description": "Sized to the avatar, not a text style: initials have to fit inside the circle at each size. The rest of the type is title-base."
+    },
+    "initials-font-size-md": {
+      "$value": "{font-size.md}",
+      "$description": "Sized to the avatar, not a text style: initials have to fit inside the circle at each size. The rest of the type is title-base."
+    },
+    "initials-font-size-lg": {
+      "$value": "{font-size.lg}",
+      "$description": "Sized to the avatar, not a text style: initials have to fit inside the circle at each size. The rest of the type is title-base."
+    },
+    "initials-font-size-xl": {
+      "$value": "{font-size.2xl}",
+      "$description": "Sized to the avatar, not a text style: initials have to fit inside the circle at each size. The rest of the type is title-base."
+    }
   }
 }

package/tokens/component/popover.json

@@ -1,9 +1,9 @@
 {
   "popover": {
     "$description": "Popover's own sizes. Everything else is the popup and close concepts, text styles and CSS.",
-    "popup-max-width": {
-      "$value": "400px",
-      "$description": "Keeps longer text to a readable line length."
+    "text-max-width": {
+      "$value": "{measure.narrow}",
+      "$description": "Keeps the title and description to a readable line length. The popup itself has no fixed cap, so wider content such as a calendar or a form fits; it stops at the space Base UI reports beside the trigger."
     },
     "popup-min-width": {
       "$value": "{popup.min-width}",

package/tokens/semantic/color.json

@@ -185,7 +185,7 @@
       "$description": "Accent text such as active tabs. One step darker than the interactive color so it stays AA as text."
     },
     "disabled": {
-      "$value": "{scope.chrome.soft-strong}",
+      "$value": "{scope.chrome.fg-disabled}",
       "$type": "color",
       "$description": "Text in disabled controls. Deliberately below AA, which WCAG allows for disabled UI."
     },