@scattered-light/loomiere 0.4.1 → 0.5.1

package/exporters/index.mjs

@@ -30,6 +30,10 @@ const wanted = (id, only) => only === 'all' || only.some((pick) => id === pick |
  */
 export function exportAll(catalog, roles, outDir, only = 'all', context = {}) {
   const theme = readTheme(catalog, roles);
+  // A brand with several looks: each look's own theme, the brand's own look first.
+  if (context.looks?.length > 1) {
+    theme.looks = context.looks.map(({ name, label, description, base, catalog: c, roles: r }) => ({ name, label, description, base, theme: base ? theme : readTheme(c, r) }));
+  }
   // tokens.css sits beside exports/; adapters that re-use its rules (Tailwind's pair and scope
   // utilities) read it from here.
   const tokensCss = path.join(outDir, '..', 'tokens.css');

package/figma/README.md

@@ -27,7 +27,7 @@ group in a hidden collection, and the published collection's modes point at the
 
 | Collection     | Modes                                                                                                     | Holds                                                                                                                                                                                                                                                                                                                                                                                                               |
 | -------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Brand (hidden) | Default                                                                                                   | Font families, and a complete group of the brand's colors per theme: `default/color/…`, then `deuteranopia/color/…` and the other color vision themes. Data colors are here by name (`color/data/violet`). A color a vision theme doesn't change points at default's.                                                                                                                                               |
+| Brand (hidden; published with looks) | Default, or one per look                                                                                  | Font families, and a complete group of the brand's colors per theme: `default/color/…`, then `deuteranopia/color/…` and the other color vision themes. Data colors are here by name (`color/data/violet`). A color a vision theme doesn't change points at default's.                                                                                                                                               |
 | Scale (hidden) | Default                                                                                                   | The raw steps: space, radius, stroke and icon size scales, and the font sizes as `desktop/`, `tablet/` and `mobile/font-size/…`, each `clamp()` read at that width (tablet at 768px).                                                                                                                                                                                                                               |
 | Size           | Desktop, Tablet, Mobile                                                                                   | The sizes designers pick: font sizes, and the named semantic and component sizes (control heights, gaps, padding), each pointing at a Scale step.                                                                                                                                                                                                                                                                   |
 | Theme          | Light, Dark, Light high contrast, Dark high contrast, Deuteranopia, Protanopia, Tritanopia, Achromatopsia | The themes, as `data-theme` in CSS. Each color vision theme is a light theme of its own with the brand's colors redesigned for that kind of color vision. Holds every semantic color designers pick, the data series slots (`data/1`…, each pointing at the named data color that theme puts there), and, with no scopes, the palette scopes and each brand pair's parts (`pair/<name>/bg`…) that Status points at. |
@@ -50,6 +50,21 @@ Effect styles hold what a variable can't: elevation/xs to elevation/2xl from the
 focus/ring (gap, ring and halo), and focus/field and focus/field-error for fields. Shadow colors that are
 Theme tokens stay bound, so the focus styles follow light, dark and the other themes.
 
+### Looks
+
+A brand with [looks](../tokens/README.md#looks) gets one Brand mode per look, the brand's own
+first (Mojave, Classic). Everything else stays as it is: a value in Scale, Size or Theme that
+differs between looks points at a Brand variable named `look/<collection>/<mode>/<name>`
+(`look/theme/light/scope/accent/solid`), which holds each look's value. Set the Brand mode on a
+frame to switch its look; Theme, Size, Status and Emphasis still switch on their own.
+
+With looks, Brand is published, so a file that uses the library can set the look too. Its
+variables still have no scopes, so they stay out of the color and number pickers.
+
+Limits: text styles and effect styles come from the brand's own look. A text style's size and
+family are variables, so they follow the look, but its line height and letter spacing are fixed
+numbers. Shadow colors that aren't Theme tokens are the brand look's.
+
 ### Plans
 
 Modes per collection depend on the Figma plan: Professional allows 10, Organization 20. The sync

package/figma/library/pages/03-color.js

@@ -84,7 +84,7 @@ async function lane(label, items, note) {
   add(how, [l]);
 }
 await lane('Color', [
-  ['Brand', 'Hidden', 'One mode. Groups: default, deuteranopia, protanopia, tritanopia, achromatopsia', 'The ramps and 20 named data colors, a full set per group.'],
+  ['Brand', 'Hidden', 'One mode per look. Groups: default, deuteranopia, protanopia, tritanopia, achromatopsia, look', 'The ramps and 20 named data colors, a full set per group. look/ holds what changes between looks.'],
   ['Theme', 'Published', 'Light, Dark, Light/Dark high contrast, 4 vision themes', 'The jobs: surface, text, border, fill, interactive, status, pairs, data/1-20.'],
   ['Status', 'Published', 'Default, Info, Success, Warning, Error', 'What a control is about. Default is the brand accent; the rest are status palettes.'],
   ['Emphasis', 'Published', 'Bold, Standard, Subtle, Quiet', 'How loud a control is. Components bind emphasis/bg, fg and border.']

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.1",
+  "version": "0.5.1",
   "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: