@scattered-light/loomiere 0.4.0 → 0.5.0

package/figma/library/tools/diff-snippet.js

@@ -0,0 +1,15 @@
+// Diffs units on a real page against the same units on its check page. tools/run.mjs --diff
+// sets PAGE, UNITS (['doc:Color/Text', 'set:Input', 'wrap:Input', ...]) and MAX.
+var F = await new (Object.getPrototypeOf(async function () {}).constructor)('figma', figma.root.getSharedPluginData('loomiere', 'fingerprint'))(figma);
+var PREFIX = figma.root.getSharedPluginData('loomiere', 'pagePrefix');
+async function unitNode(name, key) {
+  var pg = figma.root.children.filter(function (p) { return p.name === name; })[0]; await pg.loadAsync();
+  var kind = key.slice(0, key.indexOf(':')), rest = key.slice(key.indexOf(':') + 1).replace(/#\d+$/, '');
+  if (kind === 'set') return pg.findAll(function (n) { return (n.type === 'COMPONENT_SET' || (n.type === 'COMPONENT' && n.parent.type !== 'COMPONENT_SET')) && n.name === rest; })[0];
+  if (kind === 'doc') { var d = rest.split('/'), top = pg.children.filter(function (n) { return n.name === d[0].replace('(frame)', ''); })[0]; return d.length > 1 ? top.children.filter(function (n) { return n.name === d.slice(1).join('/'); })[0] : top; }
+  if (kind === 'wrap') return pg.children.filter(function (n) { return n.name === 'Components'; })[0].children.filter(function (n) { return n.name === rest; })[0];
+  return pg.children.filter(function (n) { return n.name === rest.replace('(shell)', ''); })[0];
+}
+var out = {};
+for (var i = 0; i < UNITS.length; i++) out[UNITS[i]] = await F.diff(await unitNode(PAGE, UNITS[i]), await unitNode(PREFIX + PAGE, UNITS[i]), MAX || 12);
+return out;

package/figma/library/tools/kit-script.mjs

@@ -0,0 +1,21 @@
+// Prints the use_figma script that stores the library kit in a file's shared plugin data, and
+// returns each stored part's length and hash, to compare with `node tools/kit-script.mjs --hashes`.
+import fs from 'node:fs';
+const kit = new URL('../kit/', import.meta.url);
+export const KEYS = { 'base.js': 'docHelpers', 'components.js': 'compHelpers', 'docs.js': 'docKit', 'fingerprint.js': 'fingerprint' };
+const h32 = (s) => { let h = 0x811c9dc5; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; } return h.toString(16).padStart(8, '0'); };
+const read = (file) => fs.readFileSync(new URL(file, kit), 'utf8');
+if (process.argv.includes('--hashes')) {
+  console.log(JSON.stringify(Object.fromEntries(Object.entries(KEYS).map(([f, k]) => [k, `${read(f).length} ${h32(read(f))}`]))));
+} else {
+  // --only docHelpers,docKit stores just those parts.
+  const only = process.argv.includes('--only') ? process.argv[process.argv.indexOf('--only') + 1].split(',') : null;
+  let out = '';
+  for (const [file, key] of Object.entries(KEYS)) {
+    if (only && !only.includes(key)) continue;
+    out += `figma.root.setSharedPluginData('loomiere', '${key}', ${JSON.stringify(read(file))});\n`;
+  }
+  out += `function h32(s) { var h = 0x811c9dc5; for (var i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; } return ('0000000' + h.toString(16)).slice(-8); }\n`;
+  out += `var out = {}; ${JSON.stringify(Object.values(KEYS))}.forEach(function (k) { var t = figma.root.getSharedPluginData('loomiere', k); out[k] = t.length + ' ' + h32(t); }); return out;\n`;
+  process.stdout.write(out);
+}

package/figma/library/tools/run.mjs

@@ -0,0 +1,27 @@
+// Bundles page scripts into one use_figma script, under its 50,000-character limit.
+//   node tools/run.mjs [--store all|docHelpers,...] [--check|--real] [--diff Page=unit,unit] [--units Page] pages/...js ...
+// --store writes the kit first (needed once per file, and after a kit change).
+// --check builds on "✱ check / " pages beside the real ones; --real builds the real pages.
+// --diff compares units on the real page with the check page; --units returns a page's fingerprints
+// for tools/compare.mjs.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+const lib = new URL('../', import.meta.url);
+const args = process.argv.slice(2), files = [], opt = {};
+for (let i = 0; i < args.length; i++) {
+  if (!args[i].startsWith('--')) files.push(args[i]);
+  else opt[args[i].slice(2)] = ['check', 'real'].includes(args[i].slice(2)) ? true : args[++i];
+}
+let out = 'var __out = {};\n';
+if (opt.store) out += execFileSync('node', [new URL('tools/kit-script.mjs', lib).pathname, ...(opt.store === 'all' ? [] : ['--only', opt.store])], { encoding: 'utf8' }).replace(/^var out = .*$/m, '') + '\n';
+if (opt.check) out += "figma.root.setSharedPluginData('loomiere', 'pagePrefix', '✱ check / ');\n";
+if (opt.real) out += "figma.root.setSharedPluginData('loomiere', 'pagePrefix', '');\n";
+for (const f of files) out += `__out[${JSON.stringify(f)}] = await (async function () {\n${fs.readFileSync(new URL(f, lib), 'utf8')}\n})();\n`;
+if (opt.diff) {
+  const [page, units] = opt.diff.split('=');
+  out += `__out.diff = await (async function (PAGE, UNITS, MAX) {\n${fs.readFileSync(new URL('tools/diff-snippet.js', lib), 'utf8')}\n})(${JSON.stringify(page)}, ${JSON.stringify(units.split(','))}, ${Number(opt.max) || 12});\n`;
+}
+if (opt.units) out += `__out.units = await (async function () { var F = await new (Object.getPrototypeOf(async function () {}).constructor)('figma', figma.root.getSharedPluginData('loomiere', 'fingerprint'))(figma); var pg = figma.root.children.filter(function (p) { return p.name === (figma.root.getSharedPluginData('loomiere', 'pagePrefix') || '') + ${JSON.stringify(opt.units)}; })[0]; await figma.setCurrentPageAsync(pg); return await F.units(); })();\n`;
+out += 'return __out;\n';
+if (out.length > 50000) throw new Error(`Bundle is ${out.length} characters; use_figma takes 50,000. Split it.`);
+process.stdout.write(out);

package/figma/library/tools/runs.mjs

@@ -0,0 +1,34 @@
+// Packs run-order.json into as few use_figma scripts as fit under 50,000 characters each, and
+// writes them to a folder, numbered in the order to run them.
+//   node tools/runs.mjs [--real|--check] [--store] [--pages Fields,Buttons] [--out dir]
+// --real builds the real pages (the default); --check builds "✱ check / " pages to compare.
+// --store puts the kit store first (a new file, or after a kit change).
+// --pages keeps only the steps for those pages, in run order, for patching a few pages.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+const lib = new URL('../', import.meta.url);
+const args = process.argv.slice(2), opt = {};
+for (let i = 0; i < args.length; i++) opt[args[i].slice(2)] = ['real', 'check', 'store'].includes(args[i].slice(2)) ? true : args[++i];
+const { steps } = JSON.parse(fs.readFileSync(new URL('run-order.json', lib), 'utf8'));
+const want = opt.pages ? opt.pages.split(',') : null;
+const files = steps.filter((s) => !want || want.includes(s.page)).flatMap((s) => s.files);
+const run = (list, extra) => execFileSync('node', [new URL('tools/run.mjs', lib).pathname, opt.check ? '--check' : '--real', ...extra, ...list], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+const out = new URL((opt.out || 'runs').replace(/\/?$/, '/'), lib);
+fs.rmSync(out, { recursive: true, force: true }); fs.mkdirSync(out, { recursive: true });
+const bundles = [];
+if (opt.store) bundles.push({ files: ['kit'], text: run([], ['--store', 'all']) });
+let group = [];
+for (const f of files) {
+  const next = [...group, f];
+  let ok = true;
+  try { run(next, []); } catch { ok = false; }
+  if (ok) { group = next; continue; }
+  if (!group.length) throw new Error(`${f} alone is over the limit; split it.`);
+  bundles.push({ files: group, text: run(group, []) }); group = [f];
+}
+if (group.length) bundles.push({ files: group, text: run(group, []) });
+bundles.forEach((b, i) => {
+  const name = `run-${String(i + 1).padStart(2, '0')}.js`;
+  fs.writeFileSync(new URL(name, out), b.text);
+  console.log(`${name}  ${String(b.text.length).padStart(6)}  ${b.files.join(' ')}`);
+});

package/generator/brand.schema.json

@@ -21,6 +21,10 @@
       "type": "string",
       "description": "Brand id, used in file names and build output."
     },
+    "label": {
+      "type": "string",
+      "description": "The brand's display name, and its own look's name in Figma and docs. Defaults to the name, capitalized."
+    },
     "description": {
       "type": "string"
     },
@@ -677,6 +681,85 @@
           }
         }
       }
+    },
+    "tokens": {
+      "type": "object",
+      "description": "Values for semantic or component tokens that the brand inputs can't express, by token path: { \"button.radius\": \"{radius.control}\" }. A value is a literal or a {reference}.",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number"
+        ]
+      }
+    },
+    "looks": {
+      "type": "object",
+      "description": "Other looks of the same brand, by name (data-look=\"<name>\" in CSS, a Brand mode in Figma). The brand file's own values are the first look. Each look is merged over the brand: objects merge key by key, lists replace, and a palette, pair, emphasis level, concept or font metrics entry replaces the brand's whole entry. Every look keeps the same tokens, palettes, pairs and roles structure; only values change.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "label": {
+            "type": "string",
+            "description": "The look's display name. Defaults to the name, capitalized."
+          },
+          "description": {
+            "type": "string"
+          },
+          "overrides": {
+            "type": "object",
+            "description": "Exact values pinned on top of this look's math, as in <brand>.overrides.json.",
+            "additionalProperties": {
+              "type": [
+                "string",
+                "number"
+              ]
+            }
+          },
+          "tokens": {
+            "type": "object",
+            "description": "Values for semantic or component tokens that the brand inputs can't express, by token path: { \"button.radius\": \"{radius.control}\" }. A value is a literal or a {reference}.",
+            "additionalProperties": {
+              "type": [
+                "string",
+                "number"
+              ]
+            }
+          },
+          "space": {
+            "type": "object",
+            "description": "Changes to the brand's space, merged over it."
+          },
+          "color": {
+            "type": "object",
+            "description": "Changes to the brand's color, merged over it."
+          },
+          "type": {
+            "type": "object",
+            "description": "Changes to the brand's type, merged over it."
+          },
+          "radius": {
+            "type": "object",
+            "description": "Changes to the brand's radius, merged over it."
+          },
+          "stroke": {
+            "type": "object",
+            "description": "Changes to the brand's stroke, merged over it."
+          },
+          "elevation": {
+            "type": "object",
+            "description": "Changes to the brand's elevation, merged over it."
+          },
+          "motion": {
+            "type": "object",
+            "description": "Changes to the brand's motion, merged over it."
+          },
+          "roles": {
+            "type": "object",
+            "description": "Changes to the brand's roles, merged over it."
+          }
+        }
+      }
     }
   },
   "$defs": {

package/generator/generate.mjs

@@ -4,31 +4,51 @@
  * Reads a brand file (the inputs) and the optional <brand>.overrides.json beside it (exact
  * values pinned on top of the math), and writes DTCG token files to
  * <generatedDir>/tokens/primitive/ plus the brand-specific semantic files (pairs, role scopes,
- * statuses, emphasis) to <generatedDir>/tokens/semantic/. Those files are generated: edit the brand
+ * statuses, emphasis) to <generatedDir>/tokens/semantic/, and the same for each other look
+ * (looks.mjs) under <generatedDir>/looks/<name>/. Those files are generated: edit the brand
  * file, not them.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 
 import { buildPrimitives } from './brand.mjs';
+import { looksOf } from './looks.mjs';
 
 const ROLE_FILE_NOTE = 'Generated from roles in the brand file. Edit the brand file (or the Roles step of loomiere studio), not this file.';
 const PAIR_FILE_NOTE = 'Generated from color.pairs in the brand file. Edit the brand file (or use loomiere lab), not this file.';
 
 export const overridesFileFor = (brandFile) => brandFile.replace(/\.json$/, '.overrides.json');
 
+/**
+ * Writes every look's generated tokens: the brand's own look to <generatedDir>/tokens/, each
+ * other look to <generatedDir>/looks/<name>/tokens/. Returns the brand's own look's results
+ * plus `looks`: [{ name, label, description, brand, base, dir }].
+ */
 export function generate(brandFile, generatedDir) {
   const overridesFile = overridesFileFor(brandFile);
   const brand = JSON.parse(fs.readFileSync(brandFile, 'utf8'));
   const overrides = fs.existsSync(overridesFile) ? JSON.parse(fs.readFileSync(overridesFile, 'utf8')) : {};
 
-  const { files, applied, pairs, problems, roleTokens } = buildPrimitives(brand, overrides);
+  const looks = looksOf(brand, overrides);
+  fs.rmSync(path.join(generatedDir, 'looks'), { recursive: true, force: true });
+  let own;
+  for (const look of looks) {
+    look.dir = look.base ? generatedDir : path.join(generatedDir, 'looks', look.name);
+    const result = writeLook(look, look.dir);
+    if (look.base) own = result;
+  }
+  return { brand, ...own, looks };
+}
+
+function writeLook(look, dir) {
+  const { files, applied, pairs, problems, roleTokens } = buildPrimitives(look.brand, look.overrides);
+  const where = look.base ? '' : ` (look "${look.name}")`;
   if (problems.length) {
-    throw new Error(`Brand pairs need AA (4.5:1) text:\n  ${problems.join('\n  ')}\nPick a passing pair in \`loomiere lab\` or fix color.pairs in the brand file.`);
+    throw new Error(`Brand pairs need AA (4.5:1) text${where}:\n  ${problems.join('\n  ')}\nPick a passing pair in \`loomiere lab\` or fix color.pairs in the brand file.`);
   }
 
-  const primitiveDir = path.join(generatedDir, 'tokens', 'primitive');
-  const semanticDir = path.join(generatedDir, 'tokens', 'semantic');
+  const primitiveDir = path.join(dir, 'tokens', 'primitive');
+  const semanticDir = path.join(dir, 'tokens', 'semantic');
   fs.mkdirSync(primitiveDir, { recursive: true });
   fs.mkdirSync(semanticDir, { recursive: true });
   for (const [name, content] of Object.entries(files)) {
@@ -39,5 +59,5 @@ export function generate(brandFile, generatedDir) {
   for (const name of ['scope', 'status', 'emphasis']) {
     fs.writeFileSync(path.join(semanticDir, `${name}.json`), `${JSON.stringify({ $description: ROLE_FILE_NOTE, ...roleTokens[name] }, null, 2)}\n`);
   }
-  return { brand, applied, files };
+  return { applied, files };
 }

package/generator/looks.mjs

@@ -0,0 +1,62 @@
+/**
+ * Looks: one brand, several ways it can look. The brand file's own values are the first look;
+ * each entry in `looks` changes some of them:
+ *
+ *   "looks": {
+ *     "classic": {
+ *       "label": "Classic",
+ *       "description": "The look before the rebrand.",
+ *       "color": { "palettes": { "primary": { "keys": ["#e5927d"] } } },
+ *       "type": { "families": { "body": ["Roboto", "sans-serif"] } },
+ *       "radius": { "base": 3 },
+ *       "tokens": { "button.radius": "{radius.control}" }
+ *     }
+ *   }
+ *
+ * A look is merged over the brand: objects merge key by key, lists replace, and a palette, a
+ * pair, an emphasis level, a concept or a font's metrics replaces the brand's whole entry, so a
+ * look's palette never keeps keys from the brand's. Every look has the same tokens; only their
+ * values change, so components, Figma bindings and code written against one look work in all.
+ * In CSS a look is data-look="<name>" on the root element; with no data-look the brand's own
+ * look applies. `tokens` picks a value for any semantic or component token (also allowed at the
+ * top of the brand file), for what the brand inputs can't say, such as square buttons.
+ */
+
+/** Entries a look replaces whole instead of merging into. */
+const WHOLE = /^(color\.palettes|color\.pairs|roles\.concepts|roles\.emphasis|roles\.status|type\.metrics)\.[^.]+$/;
+/** What a look may change. */
+const LOOK_KEYS = ['label', 'description', 'overrides', 'tokens', 'space', 'color', 'type', 'radius', 'stroke', 'elevation', 'motion', 'roles'];
+
+const isObject = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+function merge(base, over, at = '') {
+  if (!isObject(base) || !isObject(over) || WHOLE.test(at)) return structuredClone(over);
+  const out = structuredClone(base);
+  for (const [key, value] of Object.entries(over)) {
+    const p = at ? `${at}.${key}` : key;
+    out[key] = key in base ? merge(base[key], value, p) : structuredClone(value);
+  }
+  return out;
+}
+
+const labelOf = (name) => name.replace(/(^|-)(\w)/g, (_, dash, c) => (dash ? ' ' : '') + c.toUpperCase());
+
+/**
+ * The brand's looks, its own first: [{ name, label, description, brand, overrides, base }].
+ * `brand` is the whole brand file as that look sees it (without `looks`); `overrides` are the
+ * exact values pinned for that look: the brand's .overrides.json for its own look, a look's
+ * `overrides` for the others.
+ */
+export function looksOf(brand, overrides = {}) {
+  const { looks = {}, ...own } = brand;
+  const list = [{ name: brand.name, label: brand.label ?? labelOf(brand.name), description: brand.description, brand: own, overrides, base: true }];
+  for (const [name, look] of Object.entries(looks)) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error(`Look "${name}": names use a-z, 0-9 and dashes, starting with a letter`);
+    if (name === brand.name) throw new Error(`Look "${name}" has the brand's own name; the brand file's values are already the look "${name}".`);
+    const unknown = Object.keys(look).filter((k) => !LOOK_KEYS.includes(k));
+    if (unknown.length) throw new Error(`Look "${name}" sets ${unknown.join(', ')}; a look can set ${LOOK_KEYS.join(', ')}.`);
+    const { label, description, overrides: pinned = {}, ...changes } = look;
+    list.push({ name, label: label ?? labelOf(name), description, brand: { ...merge(own, changes), name: brand.name }, overrides: pinned, base: false });
+  }
+  return list;
+}

package/lib/contrast.mjs

@@ -6,12 +6,13 @@
  * Brand pairs (color.pairs in the brand file) are checked too, in light and dark: the
  * text, the accent, the button label on hover and press, and text on the tinted parts.
  * loomiere build runs it after every build and fails if anything falls short; loomiere check
- * runs it on its own.
+ * runs it on its own. A brand with several looks is checked once per look.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { wcagContrast } from 'culori';
 
+import { looksOf } from '../generator/looks.mjs';
 import { resolvePair } from '../generator/pairs.mjs';
 
 export const MODES = ['light', 'dark', 'contrast-more', 'dark-contrast-more'];
@@ -79,9 +80,26 @@ const PAIRS = [
   ['scope.accent.focus', 'surface.canvas', UI, 'accent focus ring'],
 ];
 
-/** Checks a built theme: { rows, failures }, one row per pair and mode. */
+/**
+ * Checks a built theme: { rows, failures }, one row per pair and mode, in every look. Rows of a
+ * look other than the brand's own carry its name in `look`.
+ */
 export function checkContrast(outDir, brandFile) {
-const { tokens } = JSON.parse(fs.readFileSync(path.join(outDir, 'tokens.json'), 'utf8'));
+  const looks = looksOf(JSON.parse(fs.readFileSync(brandFile, 'utf8')));
+  const rows = [];
+  const failures = [];
+  for (const look of looks) {
+    const file = look.base ? path.join(outDir, 'tokens.json') : path.join(outDir, 'generated', 'looks', look.name, 'tokens.json');
+    const { tokens } = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const result = checkLook(tokens, look.brand.color.pairs ?? {});
+    const tag = (r) => (look.base ? r : { ...r, look: look.name });
+    rows.push(...result.rows.map(tag));
+    failures.push(...result.failures.map(tag));
+  }
+  return { rows, failures };
+}
+
+function checkLook(tokens, brandPairs) {
 const byPath = new Map(tokens.map((t) => [t.path, t]));
 const failures = [];
 const rows = [];
@@ -99,7 +117,6 @@ for (const mode of modes) {
 }
 
 // Palettes are the same in every mode, so a pair resolves from the light palette values.
-const brandPairs = JSON.parse(fs.readFileSync(brandFile, 'utf8')).color.pairs ?? {};
 const hexOf = (tokenPath) => byPath.get(tokenPath)?.value;
 for (const [name, { dark, ...spec }] of Object.entries(brandPairs)) {
   for (const [mode, modeSpec] of [['light', spec], ...(dark ? [['dark', { ...spec, ...dark }]] : [])]) {
@@ -130,10 +147,11 @@ export function reportContrast({ rows, failures }) {
   if (failures.length) {
     console.error(`Contrast check: ${failures.length} of ${rows.length} pairs fall short.`);
     for (const f of failures) {
-      console.error(`  ${f.mode.padEnd(18)} ${f.fg} on ${f.bg}: ${f.ratio}:1, needs ${f.min}:1 (${f.kind})`);
+      console.error(`  ${(f.look ? `${f.look} ${f.mode}` : f.mode).padEnd(18)} ${f.fg} on ${f.bg}: ${f.ratio}:1, needs ${f.min}:1 (${f.kind})`);
     }
     return false;
   }
-  console.log(`Contrast check passed: ${rows.length} pairs across ${new Set(rows.map((r) => r.mode)).size} modes, brand pairs included.`);
+  const looks = new Set(rows.map((r) => r.look ?? '')).size;
+  console.log(`Contrast check passed: ${rows.length} pairs across ${new Set(rows.map((r) => r.mode)).size} modes${looks > 1 ? ` in ${looks} looks` : ''}, brand pairs included.`);
   return true;
 }

package/lib/figma.mjs

@@ -10,7 +10,8 @@
  *   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
+ * --since <snapshot.json> (scripts: only what changed; the data goes in compressed unless
+ * --plain), --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.
@@ -19,8 +20,11 @@ import { execFileSync, spawn } from 'node:child_process';
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import vm from 'node:vm';
 
+import LZString from 'lz-string';
+
 import { engineRoot } from './tool-server.mjs';
 
 const ENGINE_FILE = path.join(engineRoot, 'figma', 'engine.js');
@@ -76,13 +80,37 @@ export function snapshotScript() {
  * 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 } = {}) {
+/**
+ * lz-string's decompressor, for compressed pushes: use_figma has no network and no zlib, and
+ * the code it takes is what costs time in a chat, so the data goes in compressed.
+ */
+const lzDecompressor = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.resolve('lz-string'))), 'lz-string.min.js'), 'utf8');
+
+/**
+ * The head of a compressed part: the decompressor, then the engine, itself compressed. The first
+ * part also keeps both in the file (shared plugin data "loomiere"/"push"), so the later parts
+ * load them from there instead of carrying them again.
+ */
+const PUSH_KEY = ['loomiere', 'push'];
+const compressedHeads = () => {
+  const kept = JSON.stringify({ lz: lzDecompressor(), engine: LZString.compressToBase64(`${engineCompact()}\nreturn loomiereSync;`) });
+  const load = 'var LZString = new Function(HEAD.lz + "\\nreturn LZString;")();\nvar loomiereSync = new Function(LZString.decompressFromBase64(HEAD.engine))();\n';
+  return {
+    first: `var HEAD = ${kept};\nfigma.root.setSharedPluginData(${PUSH_KEY.map((k) => JSON.stringify(k)).join(', ')}, JSON.stringify(HEAD));\n${load}`,
+    later: `var HEAD = JSON.parse(figma.root.getSharedPluginData(${PUSH_KEY.map((k) => JSON.stringify(k)).join(', ')}) || "null");\nif (!HEAD) throw new Error("Run the first push script first: it keeps the engine in the file for the others.");\n${load}`,
+  };
+};
+const compressedCall = (data, options) => `\nreturn await loomiereSync(JSON.parse(LZString.decompressFromBase64(${JSON.stringify(LZString.compressToBase64(JSON.stringify(data)))})), ${JSON.stringify(options)});\n`;
+
+export function pushScripts(data, snapshot, { remove = false, dryRun = false, compress = 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 heads = compress ? compressedHeads() : { first: engineCompact(), later: engineCompact() };
+  const room = PART_LIMIT - heads.first.length - 400;
+  const roomLater = PART_LIMIT - heads.later.length - 400;
+  const callFor = compress ? compressedCall : call;
   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 }) }));
@@ -103,24 +131,31 @@ export function pushScripts(data, snapshot, { remove = false, dryRun = false } =
   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;
+  // Compressed, a part holds about `ratio` times its size in data; start there and shrink until every part fits.
+  const ratio = compress ? JSON.stringify(changed.map(([, g]) => g.variables)).length / LZString.compressToBase64(JSON.stringify(changed.map(([, g]) => g.variables))).length : 1;
+  let parts;
+  for (let scale = 0.9; ; scale *= 0.85) {
+    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((parts.length ? heads.later : heads.first) + callFor({ ...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;
+      const budget = (parts.length ? roomLater : room) * ratio * scale;
+      if (size && size + n > budget) 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 } });
+    if (!compress || parts.every((p) => p.length <= PART_LIMIT) || ratio * scale < 1) break;
   }
-  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);
@@ -304,7 +339,7 @@ async function viaApi(config, fileKey, token, { remove, dryRun }) {
 
 // --- the command -------------------------------------------------------------
 
-export async function figmaCommand(config, sub, { via, file, since, remove = false, dryRun = false, port } = {}) {
+export async function figmaCommand(config, sub, { via, file, since, remove = false, dryRun = false, plain = 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);
@@ -316,7 +351,7 @@ export async function figmaCommand(config, sub, { via, file, since, remove = fal
       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 { layout, limit, changed, groups, parts, warnings } = pushScripts(readFigmaJson(config), snapshot, { remove, dryRun, compress: !plain });
     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).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scattered-light/loomiere",
-  "version": "0.4.0",
+  "version": "0.5.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": {
@@ -44,6 +44,7 @@
   },
   "dependencies": {
     "culori": "^4.0.2",
+    "lz-string": "^1.5.0",
     "style-dictionary": "^5.7.0"
   },
   "peerDependencies": {

package/tokens/README.md

@@ -45,6 +45,32 @@ The generator (`generator/vision.mjs`) designs each theme from the brand's own a
 
 For low vision, the `contrast-more` modes above already raise contrast when the system asks for it.
 
+## Looks
+
+A look is another way the same brand can look: an old and a new brand, a quiet and a bold version, a white-label client. The brand file's own values are the first look, named after the brand. Each entry in `looks` changes only what differs:
+
+```json
+"looks": {
+  "classic": {
+    "label": "Classic",
+    "description": "The look before the rebrand.",
+    "color": { "palettes": { "primary": { "name": "coral", "keys": ["#fedfd7", "#e5927d", "#c37c6a"] } } },
+    "type": { "families": { "display": ["Roboto", "sans-serif"], "body": ["Roboto", "sans-serif"] } },
+    "radius": { "base": 3 },
+    "tokens": { "button.radius": "{radius.control}" }
+  }
+}
+```
+
+- A look can set `label`, `description`, `overrides` (exact values, like `.overrides.json`), `tokens`, `space`, `color`, `type`, `radius`, `stroke`, `elevation`, `motion` and `roles`.
+- It is merged over the brand: objects merge key by key and lists replace. A palette, a pair, a concept, an emphasis or status entry, or a font's metrics replaces the brand's whole entry, so a look's palette never keeps keys from the brand's.
+- `tokens` picks a value for any semantic or component token, for what the brand inputs can't say (square buttons, a thicker focus ring). It works at the top of the brand file too.
+- Every look has the same tokens; only their values change. Components, Figma bindings and code written against one look work in all of them. Pair names and role rules must match across looks; the build says so if they don't.
+
+In CSS a look is `data-look="<name>"` on the root element, next to `data-theme`. With no `data-look` the brand's own look applies. `tokens.css` holds one `[data-look]` block with only the variables that change, plus that look's dark, high contrast and color vision blocks. The contrast check runs on every look, and `tokens.json` lists the looks under `looks` with what each one changes. In Figma each look is a mode of the Brand collection (see [figma/README.md](../figma/README.md)), and Storybook has a Look toolbar.
+
+Mojave's brand file has one: `classic`, the look the brand had before.
+
 ## Roles: chrome, accent and the emphasis ladder
 
 Semantic and component tokens never name a brand color. They say `color.chrome.*` (surfaces, text, borders) or `color.accent.*` (links, focus, the loudest actions), and the brand file's `roles` decides which palettes those are: