@scattered-light/loomiere 0.4.0 → 0.5.0

package/README.md

@@ -54,7 +54,7 @@ Every value is a `--sl-` variable, so your own CSS, and component packages such
 
 | File | For |
 | --- | --- |
-| `tokens.css` | Every token as a `--sl-` variable, inside `@layer sl.tokens` so your own styles win. Dark mode and high contrast follow the system, or `data-theme` on `<html>`: `light`, `dark`, `light-high-contrast`, `dark-high-contrast`, or a color vision theme (`deuteranopia`, `protanopia`, `tritanopia`, `achromatopsia`). Also holds the `.sl-pair-<name>` classes, `data-color` scopes, `data-status` (info, success, warning, error) and `data-emphasis` levels. |
+| `tokens.css` | Every token as a `--sl-` variable, inside `@layer sl.tokens` so your own styles win. Dark mode and high contrast follow the system, or `data-theme` on `<html>`: `light`, `dark`, `light-high-contrast`, `dark-high-contrast`, or a color vision theme (`deuteranopia`, `protanopia`, `tritanopia`, `achromatopsia`). A brand with looks also has `data-look`. Also holds the `.sl-pair-<name>` classes, `data-color` scopes, `data-status` (info, success, warning, error) and `data-emphasis` levels. |
 | `utilities.css` | `.text-style-*`, `.icon-*`, `.focus-ring`, `.hide-on-*`. |
 | `tokens.js`, `tokens.d.ts` | Resolved values for JavaScript. |
 | `tokens.json`, `pairs.json` | The token catalog and every palette color against every other, for docs and agents. |
@@ -63,4 +63,6 @@ Every value is a `--sl-` variable, so your own CSS, and component packages such
 
 Figma: three ways to send the theme into a Figma file (a Claude chat, `loomiere figma push`, or the Loomiere plugin for designers without the repo) in [figma/README.md](figma/README.md).
 
+Several looks for one brand (`data-look`, Brand modes in Figma): [tokens/README.md#looks](tokens/README.md#looks).
+
 How the layers work, the brand file's fields, roles, concepts and pairs: [tokens/README.md](tokens/README.md).

package/bin/loomiere.mjs

@@ -40,6 +40,7 @@ Options
   --file <url>              figma: the Figma file (or "figma": { "file" } in the config)
   --via <way>               figma push: claude, api, plugin or scripts (default: the first that works)
   --since <file>            figma push --via scripts: the snapshot, to send only what changed
+  --plain                   figma push --via scripts: write the data as plain JSON, not compressed
   --remove                  figma push: delete what the build no longer has
   --dry-run                 figma push: report what would change, change nothing
   --help                    Show this help
@@ -56,6 +57,7 @@ const { values: flags, positionals } = parseArgs({
     file: { type: 'string' },
     via: { type: 'string' },
     since: { type: 'string' },
+    plain: { type: 'boolean' },
     remove: { type: 'boolean' },
     'dry-run': { type: 'boolean' },
     help: { type: 'boolean', short: 'h' },
@@ -121,7 +123,7 @@ async function main() {
       const sub = rest[0] ?? 'push';
       // Push what the brand says now, the way a designer would expect.
       if (sub === 'push' && flags.via !== 'scripts' && !(await build(config))) return void (process.exitCode = 1);
-      const ok = await figmaCommand(config, sub, { via: flags.via, file: flags.file, since: flags.since, remove: flags.remove, dryRun: flags['dry-run'], port });
+      const ok = await figmaCommand(config, sub, { via: flags.via, file: flags.file, since: flags.since, plain: flags.plain, remove: flags.remove, dryRun: flags['dry-run'], port });
       if (ok === false) process.exitCode = 1;
       return;
     }

package/build/build-tokens.mjs

@@ -9,7 +9,8 @@
  *
  * Tokens can carry mode values in $extensions["sl.modes"] (dark, contrast-more,
  * dark-contrast-more, reduced-motion); the CSS output emits each mode as its own block.
- * Color vision themes (vision.* primitives) become [data-theme='<theme>'] blocks.
+ * Color vision themes (vision.* primitives) become [data-theme='<theme>'] blocks, and the
+ * brand's other looks (generator/looks.mjs) [data-look='<name>'] blocks.
  *
  * Run it through the command line (loomiere build), which reads loomiere.config.json.
  */
@@ -242,6 +243,81 @@ function pairBlocks(dictionary) {
   return `/* Brand pairs: generated from color.pairs in the brand file. */\n${blocks.join('\n\n')}`;
 }
 
+/**
+ * Looks (generator/looks.mjs). Each look is built on its own, and what it changes becomes
+ * [data-look='<name>'] blocks: the variables whose value differs from the brand's own look, then
+ * each mode's values where they differ, so a look's dark mode is its own. Every look has the
+ * same tokens, so the class rules (roles, pairs, color vision) are the brand's, shared; a look
+ * whose rules come out different is an error.
+ */
+let lookParts = [];
+
+const declarationsIn = (text) =>
+  new Map(
+    text
+      .split('\n')
+      .map((line) => line.match(/^\s*(--[\w-]+):\s*(.*?);(?:\s*\/\*\*.*\*\/)?$/))
+      .filter(Boolean)
+      .map((m) => [m[1], m[2]]),
+  );
+
+/** What a look's CSS is made of: its :root values, its mode values, and its class rules. */
+function partsOf(dictionary, options) {
+  const root = declarationsIn(formattedVariables({ format: 'css', dictionary, outputReferences: options.outputReferences, usesDtcg: true }));
+  const modeValues = {};
+  for (const [mode] of modes(visionsIn(dictionary))) {
+    modeValues[mode] = Object.fromEntries(
+      dictionary.allTokens.filter((token) => modeValue(token, mode) !== undefined).map((token) => [varName(token.path), refsToVars(modeValue(token, mode))]),
+    );
+  }
+  return { root: Object.fromEntries(root), modes: modeValues, rules: { roles: roleBlocks(dictionary), pairs: pairBlocks(dictionary), vision: visionBlocks(dictionary) } };
+}
+
+StyleDictionary.registerFormat({
+  name: 'json/sl-look-parts',
+  format: ({ dictionary, options }) => `${JSON.stringify(partsOf(dictionary, options))}\n`,
+});
+
+/** Adds [data-look='<name>'] to each selector in a list (commas inside :not() stay). */
+const inLook = (selectors, name) =>
+  selectors
+    .split(/,(?![^(]*\))/)
+    .map((s) => `${s.trim()}[data-look='${name}']`)
+    .join(', ');
+
+/** [rootBlocks, modeBlocks] for every look against the brand's own parts. */
+function lookBlocks(dictionary, base) {
+  const roots = [];
+  const modeRules = [];
+  for (const { name, label, parts } of lookParts) {
+    for (const [rule, text] of Object.entries(parts.rules)) {
+      // Color vision blocks list the data colors by name, so a look with its own names has its own.
+      if (rule === 'vision') continue;
+      if (text !== base.rules[rule]) throw new Error(`Look "${name}" changes the ${rule} rules, not only values. A look can change colors, fonts and sizes, but it has to keep the brand's palettes, pairs, statuses and emphasis levels.`);
+    }
+    const changed = Object.entries(parts.root).filter(([v, value]) => base.root[v] !== value);
+    if (changed.length) roots.push(`/* Look: ${label} (data-look='${name}'). */\n[data-look='${name}'] {\n${indent(changed.map(([v, value]) => `${v}: ${value};`).join('\n'), 2)}\n}`);
+    if (parts.rules.vision !== base.rules.vision) {
+      roots.push(parts.rules.vision.replace(/^(\[data-theme='[\w-]+'\]) \{/gm, (_, sel) => `${inLook(sel, name)} {`));
+    }
+    // A mode value the look's own root value or mode value would lose to: the brand's mode
+    // blocks come after the look's root block, so restate the look's value in each mode.
+    for (const [mode, targets] of modes(visionsIn(dictionary))) {
+      const lines = [];
+      for (const v of Object.keys(parts.root)) {
+        const own = parts.modes[mode][v] ?? (base.modes[mode][v] !== undefined ? parts.root[v] : undefined);
+        if (own !== undefined && own !== base.modes[mode][v]) lines.push(`${v}: ${own};`);
+      }
+      if (!lines.length) continue;
+      for (const [media, selector] of targets) {
+        const rule = `${inLook(selector, name)} {\n${indent(lines.join('\n'), 2)}\n}`;
+        modeRules.push(media ? `${media} {\n${indent(rule, 2)}\n}` : rule);
+      }
+    }
+  }
+  return [roots.join('\n\n'), modeRules.join('\n\n')];
+}
+
 StyleDictionary.registerTransform({
   name: 'name/sl-path',
   type: 'name',
@@ -260,7 +336,9 @@ StyleDictionary.registerFormat({
       usesDtcg: true,
     });
     const root = `:root {\n${variables}\n}`;
-    const body = [root, modeBlocks(dictionary), visionBlocks(dictionary), roleBlocks(dictionary), pairBlocks(dictionary)].filter(Boolean).join('\n\n');
+    // Look roots come before the mode and color vision blocks, so those still win in their themes.
+    const [lookRoots, lookModes] = lookParts.length ? lookBlocks(dictionary, partsOf(dictionary, options)) : ['', ''];
+    const body = [root, lookRoots, modeBlocks(dictionary), visionBlocks(dictionary), lookModes, roleBlocks(dictionary), pairBlocks(dictionary)].filter(Boolean).join('\n\n');
     return `${header}@layer ${prefix}.tokens {\n${indent(body, 2)}\n}\n`;
   },
 });
@@ -379,6 +457,24 @@ export function expandTextStyles(tokens) {
 
 StyleDictionary.registerPreprocessor({ name: 'sl/text-styles', preprocessor: (tokens) => expandTextStyles(tokens) });
 
+/**
+ * `tokens` in the brand file or a look: { "button.radius": "{radius.control}" } replaces a
+ * semantic or component token's value, for what the brand inputs can't say. Set per build.
+ */
+let picks = {};
+StyleDictionary.registerPreprocessor({
+  name: 'sl/picks',
+  preprocessor: (tokens) => {
+    for (const [tokenPath, value] of Object.entries(picks)) {
+      const token = tokenPath.split('.').reduce((node, key) => node?.[key], tokens);
+      if (token?.$value === undefined) throw new Error(`tokens."${tokenPath}" in the brand file is not a token`);
+      token.$extensions = { ...token.$extensions, 'sl.pick': { was: token.$value } };
+      token.$value = value;
+    }
+    return tokens;
+  },
+});
+
 /**
  * Classes made from tokens, so they can't drift from them. All go in <out>/utilities.css:
  *   .text-style-<name>  every text style in tokens/semantic/typography.json
@@ -457,51 +553,75 @@ function utilitiesCss() {
   return `/* Utility classes for "${brandName}". Generated by loomiere build; do not edit. */\n\n${body}\n`;
 }
 
+/**
+ * Builds one theme. `config` comes from resolveConfig() (lib/config.mjs):
+ * { brandFile, outDir, generatedDir, prefix, exports }.
+ */
+/** Style Dictionary over this package's tokens and one look's generated ones. */
+const sourcesFor = (generatedDir) => [
+  // Layer order, so tokens.css reads foundation → primitive → semantic → component.
+  path.join(root, 'tokens', 'foundation', '**', '*.json'),
+  path.join(generatedDir, 'tokens', 'primitive', '**', '*.json'),
+  path.join(root, 'tokens', 'semantic', '**', '*.json'),
+  path.join(generatedDir, 'tokens', 'semantic', '**', '*.json'),
+  path.join(root, 'tokens', 'component', '**', '*.json'),
+];
+const dictionary = (generatedDir, platforms) =>
+  new StyleDictionary({ usesDtcg: true, preprocessors: ['sl/picks', 'sl/text-styles'], log: { verbosity: 'default', warnings: 'warn' }, source: sourcesFor(generatedDir), platforms });
+const CSS_TRANSFORMS = ['name/sl-path', 'fontFamily/css', 'cubicBezier/css'];
+
 /**
  * Builds one theme. `config` comes from resolveConfig() (lib/config.mjs):
  * { brandFile, outDir, generatedDir, prefix, exports }.
  */
 export async function buildTokens(config) {
   prefix = config.prefix;
-  const { brand, applied, files } = generate(config.brandFile, config.generatedDir);
+  const { brand, applied, files, looks } = generate(config.brandFile, config.generatedDir);
   brandName = brand.name;
-  roles = resolveRoles(brand);
   const out = config.outDir + path.sep;
 
-  const sd = new StyleDictionary({
-    usesDtcg: true,
-    preprocessors: ['sl/text-styles'],
-    log: { verbosity: 'default', warnings: 'warn' },
-    source: [
-      // Layer order, so tokens.css reads foundation → primitive → semantic → component.
-      path.join(root, 'tokens', 'foundation', '**', '*.json'),
-      path.join(config.generatedDir, 'tokens', 'primitive', '**', '*.json'),
-      path.join(root, 'tokens', 'semantic', '**', '*.json'),
-      path.join(config.generatedDir, 'tokens', 'semantic', '**', '*.json'),
-      path.join(root, 'tokens', 'component', '**', '*.json'),
-    ],
-    platforms: {
+  // Every other look first: its parts for tokens.css, and its catalog for the exports.
+  lookParts = [];
+  for (const look of looks.filter((l) => !l.base)) {
+    roles = resolveRoles(look.brand);
+    picks = look.brand.tokens ?? {};
+    await dictionary(look.dir, {
       css: {
         prefix,
-        transforms: ['name/sl-path', 'fontFamily/css', 'cubicBezier/css'],
-        buildPath: out,
+        transforms: CSS_TRANSFORMS,
+        buildPath: look.dir + path.sep,
         files: [
-          {
-            destination: 'tokens.css',
-            format: 'css/sl-layered',
-            options: { outputReferences: true, showFileHeader: true },
-          },
+          { destination: 'parts.json', format: 'json/sl-look-parts', options: { outputReferences: true } },
           { destination: 'tokens.json', format: 'json/sl-catalog' },
         ],
       },
-      js: {
-        transforms: ['name/camel', 'fontFamily/css', 'cubicBezier/css'],
-        buildPath: out,
-        files: [
-          { destination: 'tokens.js', format: 'javascript/sl-values' },
-          { destination: 'tokens.d.ts', format: 'typescript/sl-values' },
-        ],
-      },
+    }).buildAllPlatforms();
+    lookParts.push({ ...look, parts: JSON.parse(fs.readFileSync(path.join(look.dir, 'parts.json'), 'utf8')) });
+  }
+
+  roles = resolveRoles(brand);
+  picks = brand.tokens ?? {};
+  const sd = dictionary(config.generatedDir, {
+    css: {
+      prefix,
+      transforms: CSS_TRANSFORMS,
+      buildPath: out,
+      files: [
+        {
+          destination: 'tokens.css',
+          format: 'css/sl-layered',
+          options: { outputReferences: true, showFileHeader: true },
+        },
+        { destination: 'tokens.json', format: 'json/sl-catalog' },
+      ],
+    },
+    js: {
+      transforms: ['name/camel', 'fontFamily/css', 'cubicBezier/css'],
+      buildPath: out,
+      files: [
+        { destination: 'tokens.js', format: 'javascript/sl-values' },
+        { destination: 'tokens.d.ts', format: 'typescript/sl-values' },
+      ],
     },
   });
 
@@ -522,8 +642,33 @@ export async function buildTokens(config) {
     path.join(config.outDir, 'pairs.json'),
     `${JSON.stringify({ brand: brandName, levels: Object.fromEntries(LEVELS), colors: Object.fromEntries(colors.map((c) => [c.path, c.hex])), pairs: compact })}\n`,
   );
-  // Other frameworks: DTCG JSON plus one adapter per framework (exporters/).
+  // The looks in tokens.json: each one's name and what it changes, by CSS variable.
   const catalog = JSON.parse(fs.readFileSync(path.join(config.outDir, 'tokens.json'), 'utf8'));
-  const written = exportAll(catalog, resolveRoles(brand), path.join(config.outDir, 'exports'), config.exports, { themeDir: config.outDir, brand });
-  return { brand, applied, exports: written };
+  const lookCatalogs = looks.map((look) => ({
+    ...look,
+    catalog: look.base ? catalog : JSON.parse(fs.readFileSync(path.join(look.dir, 'tokens.json'), 'utf8')),
+    roles: resolveRoles(look.brand),
+  }));
+  if (looks.length > 1) {
+    const own = new Map(catalog.tokens.map((t) => [t.name, t]));
+    catalog.looks = lookCatalogs.map(({ name, label, description, base, catalog: c }) => ({
+      name,
+      label,
+      ...(description && { description }),
+      ...(base
+        ? { base: true }
+        : {
+            css: `[data-look='${name}']`,
+            changes: Object.fromEntries(
+              c.tokens
+                .filter((t) => JSON.stringify(t.value) !== JSON.stringify(own.get(t.name)?.value) || JSON.stringify(t.modes) !== JSON.stringify(own.get(t.name)?.modes))
+                .map((t) => [t.name, t.modes ? { value: t.value, modes: t.modes } : t.value]),
+            ),
+          }),
+    }));
+    fs.writeFileSync(path.join(config.outDir, 'tokens.json'), `${JSON.stringify(catalog, null, 2)}\n`);
+  }
+  // Other frameworks: DTCG JSON plus one adapter per framework (exporters/).
+  const written = exportAll(catalog, resolveRoles(brand), path.join(config.outDir, 'exports'), config.exports, { themeDir: config.outDir, brand, looks: lookCatalogs });
+  return { brand, applied, looks, exports: written };
 }

package/exporters/design-system.mjs

@@ -318,6 +318,13 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
     `Themes: \`data-theme="light|dark|light-high-contrast|dark-high-contrast"\` on the root, or the system setting (including \`prefers-contrast: more\`) when none is set. Color vision themes are themes of their own, each a light theme designed from this brand: \`data-theme="deuteranopia|protanopia|tritanopia|achromatopsia"\`. Never hand-pick dark colors; the tokens already flip.`,
     '',
   );
+  if (theme.looks?.length > 1) {
+    const others = theme.looks.filter((l) => !l.base);
+    out.push(
+      `Looks: this brand can look ${theme.looks.length} ways. With no \`data-look\` it is ${theme.looks[0].label}; ${others.map((l) => `\`data-look="${l.name}"\` on the root is ${l.label}${l.description ? ` (${l.description.replace(/\.$/, '')})` : ''}`).join('; ')}. A look changes token values, never names, so design with the tokens and every look follows. The values listed here are ${theme.looks[0].label}'s; \`bundle.css\` holds every look.`,
+      '',
+    );
+  }
   if (componentNames.length) {
     const has = (n) => componentNames.includes(n);
     const pick = (list) => list.filter(([n]) => has(n)).map(([n, use]) => `| \`${n}\` | ${use} |`);