@scattered-light/loomiere 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @scattered-light/loomiere
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Loomiere brand engine. You write one small brand file (seed colors, fonts, a base unit, a type ratio, radius), and `loomiere build` weaves it into a full theme: OKLCH color ramps with contrast built in, a fluid type scale, light, dark, high-contrast and color-vision modes, utility classes, and themes for other frameworks.
+
+## Start a theme
+
+```bash
+npm install --save-dev @scattered-light/loomiere
+npx loomiere init acme      # brand/acme.json + loomiere.config.json
+npx loomiere studio         # set colors and type with live previews, then Save
+npx loomiere build          # writes theme/
+```
+
+Then load the theme in your app:
+
+```ts
+import './theme/tokens.css';
+import './theme/utilities.css';
+```
+
+Every value is a `--sl-` variable, so your own CSS, and component packages such as [@scattered-light/loomiere-base-ui](../loomiere-base-ui/README.md), read it directly.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `loomiere init [name]` | Starts `brand/<name>.json` (a copy of the Mojave brand) and `loomiere.config.json`. |
+| `loomiere build` | Writes the theme, then checks contrast. Fails if any text pair falls short of AA. |
+| `loomiere check` | Checks contrast of the theme already built. |
+| `loomiere studio` | Opens the brand studio at `http://localhost:4322`. `--export page.html` writes a standalone copy (needs esbuild). |
+| `loomiere lab` | Opens the pair lab at `http://localhost:4321` to pick brand pairs (a background, its text and an accent). |
+
+`--brand <file>`, `--out <dir>` and `--prefix <name>` override the config for one run. `--port <n>` moves studio or lab.
+
+## loomiere.config.json
+
+```json
+{
+  "brand": "brand/acme.json",
+  "out": "src/theme",
+  "exports": ["ag-grid", "tailwind"]
+}
+```
+
+- `brand`: the brand file. Optional when `brand/` holds exactly one.
+- `out`: where the theme goes. Default `theme`.
+- `prefix`: the CSS variable prefix. Default `sl`, which is what loomiere-base-ui reads.
+- `exports`: which framework files to write. Default all of them.
+
+## What a build writes
+
+| File | For |
+| --- | --- |
+| `tokens.css` | Every token as a `--sl-` variable, inside `@layer sl.tokens` so your own styles win. Dark mode follows `prefers-color-scheme` or `data-theme="dark"`. Also holds the `.sl-pair-<name>` classes and `data-color` scopes. |
+| `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. |
+| `exports/` | DTCG JSON, Figma variables, Tailwind v4, MUI, Chakra v3, AG Grid 31–32, 33–35 and 36+. See [exporters/README.md](exporters/README.md). |
+| `generated/` | The brand's primitive tokens. Rebuilt every time; no need to commit. |
+
+How the layers work, the brand file's fields, roles, concepts and pairs: [tokens/README.md](tokens/README.md).

package/bin/loomiere.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * loomiere: turns a brand file into a theme.
+ *
+ *   loomiere init [name]   start a brand file (brand/<name>.json) and loomiere.config.json
+ *   loomiere build         write the theme (tokens, utilities, framework exports), then check contrast
+ *   loomiere check         check contrast of the theme already built
+ *   loomiere studio        edit the brand with live previews (--export page.html for a static copy)
+ *   loomiere lab           pick brand pairs
+ *
+ * Flags: --brand <file>  --out <dir>  --prefix <name>  --port <n>
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { formatBrand } from '../generator/format-brand.mjs';
+import { CONFIG_FILE, resolveConfig, schemaPathFor } from '../lib/config.mjs';
+import { engineRoot } from '../lib/tool-server.mjs';
+
+const HELP = `loomiere: turns a brand file into a theme.
+
+Usage
+  loomiere init [name]      Start brand/<name>.json and ${CONFIG_FILE}
+  loomiere build            Write the theme, then check contrast
+  loomiere check            Check contrast of the built theme
+  loomiere studio           Edit the brand with live previews
+  loomiere lab              Pick brand pairs (background + text)
+
+Options
+  --brand <file>            Brand file (default: the only one in brand/)
+  --out <dir>               Where the theme goes (default: theme)
+  --prefix <name>           CSS variable prefix (default: sl)
+  --port <n>                Port for studio and lab
+  --export <file>           studio only: write one self-contained page instead of serving
+  --help                    Show this help
+`;
+
+const { values: flags, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    brand: { type: 'string' },
+    out: { type: 'string' },
+    prefix: { type: 'string' },
+    port: { type: 'string' },
+    export: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+  },
+});
+const [command, ...rest] = positionals;
+const configFlags = { brand: flags.brand, out: flags.out, prefix: flags.prefix };
+const port = flags.port ? Number(flags.port) : undefined;
+
+async function build(config) {
+  const { buildTokens } = await import('../build/build-tokens.mjs');
+  const { checkContrast, reportContrast } = await import('../lib/contrast.mjs');
+  const { brand, exports } = await buildTokens(config);
+  const out = path.relative(config.cwd, config.outDir) || '.';
+  console.log(`Built "${brand.name}" into ${out}/ (tokens.css, utilities.css${exports.length ? `, exports/ for ${exports.map((e) => e.name).join(', ')}` : ''}).`);
+  return reportContrast(checkContrast(config.outDir, config.brandFile));
+}
+
+function init(name = 'brand') {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('Brand names use a-z, 0-9 and dashes, starting with a letter');
+  const cwd = process.cwd();
+  const file = path.join(cwd, 'brand', `${name}.json`);
+  if (fs.existsSync(file)) throw new Error(`${path.relative(cwd, file)} already exists.`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const schema = schemaPathFor(path.dirname(file), cwd);
+  const brand = JSON.parse(fs.readFileSync(path.join(engineRoot, 'templates', 'brand.json'), 'utf8'));
+  fs.writeFileSync(file, formatBrand(Object.assign({ $schema: schema, name }, brand, { $schema: schema, name })));
+  console.log(`Wrote ${path.relative(cwd, file)}.`);
+  const configFile = path.join(cwd, CONFIG_FILE);
+  if (!fs.existsSync(configFile)) {
+    fs.writeFileSync(configFile, `${JSON.stringify({ brand: `brand/${name}.json`, out: flags.out ?? 'theme' }, null, 2)}\n`);
+    console.log(`Wrote ${CONFIG_FILE}.`);
+  }
+  console.log('Next: loomiere studio to set your colors and type, then loomiere build.');
+}
+
+async function main() {
+  if (flags.help || !command || command === 'help') return void console.log(HELP);
+  switch (command) {
+    case 'init':
+      return init(rest[0]);
+    case 'build':
+      if (!(await build(resolveConfig(configFlags)))) process.exitCode = 1;
+      return;
+    case 'check': {
+      const config = resolveConfig(configFlags);
+      const { checkContrast, reportContrast } = await import('../lib/contrast.mjs');
+      if (!fs.existsSync(path.join(config.outDir, 'tokens.json'))) throw new Error('Nothing built yet: run loomiere build');
+      if (!reportContrast(checkContrast(config.outDir, config.brandFile))) process.exitCode = 1;
+      return;
+    }
+    case 'studio': {
+      const { studio } = await import('../lib/studio.mjs');
+      return studio(resolveConfig(configFlags), { port, exportFile: flags.export });
+    }
+    case 'lab': {
+      const { lab } = await import('../lib/lab.mjs');
+      return lab(resolveConfig(configFlags), { port });
+    }
+    default:
+      throw new Error(`Unknown command "${command}". Run loomiere --help.`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exitCode = 1;
+});

package/build/build-tokens.mjs

@@ -0,0 +1,485 @@
+/**
+ * Brand file → theme folder.
+ *
+ * 1. Generates primitives from the brand (generator/generate.mjs) into <out>/generated/.
+ * 2. Runs Style Dictionary over this package's foundation, semantic and component tokens plus
+ *    the generated primitive and brand-specific semantic tokens.
+ * 3. Writes the theme to <out>/: tokens.css, utilities.css, tokens.js, tokens.d.ts,
+ *    tokens.json, pairs.json, and exports/ (one file or set per framework).
+ *
+ * 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-vision='<theme>'] blocks.
+ *
+ * Run it through the command line (loomiere build), which reads loomiere.config.json.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import StyleDictionary from 'style-dictionary';
+import { fileHeader, formattedVariables } from 'style-dictionary/utils';
+
+import { exportAll } from '../exporters/index.mjs';
+import { generate } from '../generator/generate.mjs';
+import { LEVELS, PAIR_ROLES, pairTable, paletteColors } from '../generator/pairs.mjs';
+import { resolveRoles } from '../generator/roles.mjs';
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+// Set by buildTokens() from the config; the Style Dictionary formats below read them.
+let prefix = 'sl';
+let brandName = '';
+
+const LAYERS = ['foundation', 'primitive', 'semantic', 'component'];
+
+/** Selectors for each mode, in cascade order: later blocks win. */
+const MODES = [
+  ['dark', [['@media (prefers-color-scheme: dark)', ":root:not([data-theme='light'])"], [null, "[data-theme='dark']"]]],
+  ['contrast-more', [['@media (prefers-contrast: more)', ':root']]],
+  [
+    'dark-contrast-more',
+    [
+      ['@media (prefers-contrast: more) and (prefers-color-scheme: dark)', ":root:not([data-theme='light'])"],
+      ['@media (prefers-contrast: more)', "[data-theme='dark']"],
+    ],
+  ],
+  ['reduced-motion', [['@media (prefers-reduced-motion: reduce)', ':root']]],
+];
+
+const varName = (tokenPath) => `--${[prefix, ...tokenPath].join('-')}`;
+const refsToVars = (value) => String(value).replace(/\{([^}]+)\}/g, (_, ref) => `var(${varName(ref.split('.'))})`);
+const indent = (text, spaces) =>
+  text
+    .split('\n')
+    .map((line) => (line ? ' '.repeat(spaces) + line : line))
+    .join('\n');
+
+/**
+ * A token's value in a mode, with its references kept, so a mode value that points at
+ * another token follows that token's own mode the way var() does.
+ */
+const modeValue = (token, mode) => token.original.$extensions?.['sl.modes']?.[mode];
+
+function modeBlocks(dictionary) {
+  const blocks = [];
+  for (const [mode, targets] of MODES) {
+    const declarations = dictionary.allTokens
+      .filter((token) => modeValue(token, mode) !== undefined)
+      .map((token) => `${varName(token.path)}: ${refsToVars(modeValue(token, mode))};`)
+      .join('\n');
+    if (!declarations) continue;
+    for (const [media, selector] of targets) {
+      const rule = `${selector} {\n${indent(declarations, 2)}\n}`;
+      blocks.push(media ? `${media} {\n${indent(rule, 2)}\n}` : rule);
+    }
+  }
+  return blocks.join('\n\n');
+}
+
+/**
+ * [data-vision="<theme>"] re-declares the brand's palette and data variables with the
+ * theme's (vision.<theme>.* tokens, generated in generator/vision.mjs). Set it on the root
+ * element: variables declared at :root resolve there, so everything that reads them follows.
+ */
+function visionBlocks(dictionary) {
+  const byTheme = new Map();
+  for (const token of dictionary.allTokens) {
+    if (token.path[0] !== 'vision') continue;
+    const [, theme, ...rest] = token.path;
+    if (!byTheme.has(theme)) byTheme.set(theme, []);
+    byTheme.get(theme).push(`${varName(rest)}: var(${varName(token.path)});`);
+  }
+  return [...byTheme].map(([theme, lines]) => `[data-vision='${theme}'] {\n${indent(lines.join('\n'), 2)}\n}`).join('\n\n');
+}
+
+/**
+ * Color scopes and emphasis (generator/roles.mjs). Every palette's slots are tokens
+ * (scope.<palette>.<slot>); these blocks point the generic --sl-scope-<slot> at one of them:
+ * the accent by default, any palette under [data-color], and the level's own color under
+ * [data-emphasis] when that color is chrome or a named palette, unless the element names a color itself. --sl-e-<part> is what a
+ * component paints with: the level's style read from whatever scope is in effect.
+ */
+// Button's data-variant names are aliases for emphasis levels, so the brand's roles drive every
+// button. data-emphasis wins when both are set; a button with neither is bold.
+const VARIANT_LEVELS = {
+  bold: [".Button[data-variant='solid']:not([data-emphasis])", '.Button:not([data-variant]):not([data-emphasis])'],
+  standard: [".Button[data-variant='outline']:not([data-emphasis])"],
+  quiet: [".Button[data-variant='ghost']:not([data-emphasis])"],
+};
+
+// A toast's type (toastManager.add({ type: 'success' })) picks the status palette of the same
+// name, so success, warning, error and info toasts tint themselves. data-color wins when both are set.
+const TOAST_TYPES = ['success', 'warning', 'error', 'info'];
+const COLOR_ALIASES = (name) => (TOAST_TYPES.includes(name) ? [`.Toast[data-type='${name}']:not([data-color])`] : []);
+
+function roleBlocks(dictionary) {
+  const scopes = new Map();
+  const levels = new Map();
+  for (const token of dictionary.allTokens) {
+    if (token.path[0] === 'scope') {
+      const [, name, slot] = token.path;
+      if (!scopes.has(name)) scopes.set(name, []);
+      scopes.get(name).push(slot);
+    }
+    if (token.path[0] === 'emphasis') {
+      const [, level, part] = token.path;
+      if (!levels.has(level)) levels.set(level, []);
+      levels.get(level).push([part, String(token.original.$value)]);
+    }
+  }
+  if (!scopes.size) return '';
+  const point = (name) => scopes.get(name).map((slot) => `${varName(['scope', slot])}: var(${varName(['scope', name, slot])});`).join('\n');
+  const rule = (selector, body) => `${selector} {\n${indent(body, 2)}\n}`;
+  const blocks = [rule(':root', point('accent'))];
+  for (const name of scopes.keys()) blocks.push(rule([`[data-color='${name}']`, ...COLOR_ALIASES(name)].join(',\n'), point(name)));
+  for (const [level, parts] of levels) {
+    const color = parts.map(([, v]) => v.match(/^\{scope\.([^.]+)\./)?.[1]).find(Boolean);
+    const paint = parts
+      .map(([part, v]) => {
+        const slot = v.match(/^\{scope\.[^.]+\.([^}]+)\}$/)?.[1];
+        return `${varName(['e', part])}: ${slot ? `var(${varName(['scope', slot])})` : v};`;
+      })
+      .join('\n');
+    const selectors = [`[data-emphasis='${level}']`, ...(VARIANT_LEVELS[level] ?? [])];
+    blocks.push(rule(selectors.join(',\n'), paint));
+    // Accent levels follow the scope around them, so data-color on a section re-colors them;
+    // chrome or a named palette stays put unless the element itself names a color.
+    if (color && color !== 'accent') blocks.push(rule(selectors.map((sel) => `${sel}:not([data-color])`).join(',\n'), point(color)));
+  }
+  return blocks.join('\n\n');
+}
+
+const refsOf = (value) => [...JSON.stringify(value ?? '').matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+
+/**
+ * One class per brand pair: .sl-pair-<name> re-points the semantic color tokens listed in
+ * PAIR_ROLES at the pair's parts.
+ *
+ * Custom properties resolve where they are declared, so a component token declared at
+ * :root as var(--sl-surface-canvas) keeps the :root surface even inside the class. The
+ * class therefore re-declares every token that leads to a re-pointed one, so it resolves
+ * again inside the pair. Mode blocks only set :root, so inside the class these
+ * declarations hold in every mode: the pair tokens carry the pair's own dark colors, and
+ * the dark values that some component tokens take straight from a palette don't apply.
+ * Put the class on a container, not on :root.
+ */
+function pairBlocks(dictionary) {
+  const names = [...new Set(dictionary.allTokens.filter((t) => t.path[0] === 'pair').map((t) => t.path[1]))];
+  if (!names.length) return '';
+  const byPath = new Map(dictionary.allTokens.map((t) => [t.path.join('.'), t]));
+  const roles = Object.entries(PAIR_ROLES).filter(([p]) => byPath.has(p));
+  const repointed = new Set(roles.map(([p]) => p));
+
+  // Every token that reaches a re-pointed token through references, in any mode.
+  const dependents = new Map();
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const [p, t] of byPath) {
+      if (repointed.has(p) || dependents.has(p) || t.path[0] === 'pair') continue;
+      const refs = [...refsOf(t.original.$value), ...refsOf(t.original.$extensions?.['sl.modes'])];
+      if (refs.some((r) => repointed.has(r) || dependents.has(r))) {
+        dependents.set(p, t);
+        grew = true;
+      }
+    }
+  }
+
+  const part = (name, source) =>
+    Array.isArray(source)
+      ? `color-mix(in oklab, var(${varName(['pair', name, source[0]])}) ${source[1]}%, var(${varName(['pair', name, source[2]])}))`
+      : `var(${varName(['pair', name, source])})`;
+  const deps = [...dependents.values()];
+  const blocks = names.map((name) => {
+    const lines = [
+      ...roles.map(([p, source]) => `${varName(p.split('.'))}: ${part(name, source)};`),
+      ...deps.map((t) => `${varName(t.path)}: ${refsToVars(t.original.$value)};`),
+    ];
+    return `.${prefix}-pair-${name} {\n${indent(lines.join('\n'), 2)}\n}`;
+  });
+
+  return `/* Brand pairs: generated from color.pairs in the brand file. */\n${blocks.join('\n\n')}`;
+}
+
+StyleDictionary.registerTransform({
+  name: 'name/sl-path',
+  type: 'name',
+  transform: (token, options) => [options.prefix, ...token.path].filter(Boolean).join('-'),
+});
+const layerOf = (token) => LAYERS.find((layer) => token.filePath.includes(`/tokens/${layer}/`));
+
+StyleDictionary.registerFormat({
+  name: 'css/sl-layered',
+  format: async ({ dictionary, file, options }) => {
+    const header = await fileHeader({ file });
+    const variables = formattedVariables({
+      format: 'css',
+      dictionary,
+      outputReferences: options.outputReferences,
+      usesDtcg: true,
+    });
+    const root = `:root {\n${variables}\n}`;
+    const body = [root, modeBlocks(dictionary), visionBlocks(dictionary), roleBlocks(dictionary), pairBlocks(dictionary)].filter(Boolean).join('\n\n');
+    return `${header}@layer ${prefix}.tokens {\n${indent(body, 2)}\n}\n`;
+  },
+});
+
+StyleDictionary.registerFormat({
+  name: 'json/sl-catalog',
+  format: ({ dictionary }) => {
+    const catalog = dictionary.allTokens.map((token) => ({
+      name: `--${token.name}`,
+      path: token.path.join('.'),
+      layer: layerOf(token),
+      type: token.$type,
+      value: token.$value,
+      ...(token.original.$value !== token.$value &&
+        typeof token.original.$value === 'string' &&
+        token.original.$value.includes('{') && { references: token.original.$value }),
+      ...(token.$description && { description: token.$description }),
+      ...(token.$extensions?.['sl.override'] && { pinned: true }),
+      ...(token.$extensions?.['sl.modes'] && { modes: token.$extensions['sl.modes'] }),
+      ...(token.$extensions?.['sl.modes'] &&
+        JSON.stringify(token.original.$extensions['sl.modes']) !== JSON.stringify(token.$extensions['sl.modes']) && {
+          modeReferences: token.original.$extensions['sl.modes'],
+        }),
+    }));
+    return `${JSON.stringify({ prefix, brand: brandName, tokens: catalog }, null, 2)}\n`;
+  },
+});
+
+function nestedValues(dictionary) {
+  const values = {};
+  for (const token of dictionary.allTokens) {
+    let cursor = values;
+    for (const key of token.path.slice(0, -1)) cursor = cursor[key] ??= {};
+    cursor[token.path.at(-1)] = token.$value;
+  }
+  return values;
+}
+
+function typeOf(value, indent = '') {
+  if (Array.isArray(value)) return 'readonly string[]';
+  if (typeof value !== 'object') return typeof value;
+  const inner = `${indent}  `;
+  const fields = Object.entries(value).map(([key, v]) => `${inner}readonly ${JSON.stringify(key)}: ${typeOf(v, inner)};`);
+  return `{\n${fields.join('\n')}\n${indent}}`;
+}
+
+/** Nested object of resolved values only, e.g. tokens.color.primary['600'] → '#883ac3'. */
+StyleDictionary.registerFormat({
+  name: 'javascript/sl-values',
+  format: async ({ dictionary, file }) => {
+    const header = await fileHeader({ file });
+    return `${header}const tokens = ${JSON.stringify(nestedValues(dictionary), null, 2)};\n\nexport default tokens;\n`;
+  },
+});
+
+StyleDictionary.registerFormat({
+  name: 'typescript/sl-values',
+  format: async ({ dictionary, file }) => {
+    const header = await fileHeader({ file });
+    return `${header}declare const tokens: ${typeOf(nestedValues(dictionary))};\n\nexport default tokens;\n`;
+  },
+});
+
+/**
+ * Text styles are written as one DTCG typography token each (tokens/semantic/typography.json).
+ * CSS can't use a composite, so this expands each into its parts plus a `font` shorthand:
+ *   font.base → font.base.font, .font-family, .font-size, .font-weight, .line-height,
+ *               .letter-spacing (and .text-transform when $extensions["sl.text-transform"] is set)
+ * so --sl-font-base-font-size and friends exist for components. A text style whose value is
+ * another text style ("{font.base}") takes that style's parts.
+ */
+const TEXT_PARTS = { fontFamily: 'font-family', fontSize: 'font-size', fontWeight: 'font-weight', lineHeight: 'line-height', letterSpacing: 'letter-spacing' };
+export const TEXT_STYLE_TYPE = 'typography';
+
+export function expandTextStyles(tokens) {
+  // Look aliases up in the tokens as written, since the walk replaces styles as it goes.
+  const written = structuredClone(tokens);
+  const at = (p) => p.split('.').reduce((o, k) => o?.[k], written);
+  const walk = (node, here) => {
+    for (const [key, child] of Object.entries(node)) {
+      if (key.startsWith('$') || !child || typeof child !== 'object') continue;
+      const p = [...here, key];
+      if ((child.$type ?? node.$type) !== TEXT_STYLE_TYPE || !('$value' in child)) {
+        walk(child, p);
+        continue;
+      }
+      let style = child;
+      const seen = new Set();
+      while (typeof style.$value === 'string') {
+        const ref = style.$value.match(/^\{([^}]+)\}$/)?.[1];
+        if (!ref || seen.has(ref) || !at(ref)) throw new Error(`Text style ${p.join('.')}: ${style.$value} is not a text style`);
+        seen.add(ref);
+        style = at(ref);
+      }
+      const name = p.join('.');
+      const what = child.$description ?? `The ${key} text style.`;
+      const group = { $description: what };
+      for (const [prop, part] of Object.entries(TEXT_PARTS)) {
+        if (style.$value[prop] === undefined) throw new Error(`Text style ${name} has no ${prop}`);
+        group[part] = { $value: style.$value[prop], $description: `${part} of ${name}.` };
+      }
+      const transform = child.$extensions?.['sl.text-transform'] ?? style.$extensions?.['sl.text-transform'];
+      if (transform) group['text-transform'] = { $value: transform, $description: `text-transform of ${name}.` };
+      group.font = {
+        $value: `{${name}.font-weight} {${name}.font-size} / {${name}.line-height} {${name}.font-family}`,
+        $description: `${what} As a font shorthand; letter-spacing and text-transform are separate.`,
+      };
+      // Parts keep the file the style came from, which says which layer they belong to.
+      for (const [part, token] of Object.entries(group)) if (!part.startsWith('$')) Object.assign(token, { filePath: child.filePath, isSource: child.isSource });
+      node[key] = group;
+    }
+  };
+  walk(tokens, []);
+  return tokens;
+}
+
+StyleDictionary.registerPreprocessor({ name: 'sl/text-styles', preprocessor: (tokens) => expandTextStyles(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
+ *   .icon-<tier>        every icon size in tokens/semantic/icon.json
+ *   .focus-ring, .focus-ring-inset  from tokens/semantic/focus.json
+ *   .hide-on-mobile|tablet|desktop  from the foundation breakpoints
+ * They read only this package's tokens, so every brand gets the same classes.
+ */
+const readTokens = (file) => JSON.parse(fs.readFileSync(path.join(root, 'tokens', file), 'utf8'));
+
+function textStyleBlocks() {
+  const { font } = readTokens('semantic/typography.json');
+  const styles = Object.entries(font).filter(([name, t]) => !name.startsWith('$') && t.$type === TEXT_STYLE_TYPE);
+  return styles.map(([name, t]) => {
+    const v = (part) => `var(${varName(['font', name, part])})`;
+    const transform = t.$extensions?.['sl.text-transform'] ?? (typeof t.$value === 'string' && font[t.$value.slice(1, -1).split('.')[1]]?.$extensions?.['sl.text-transform']);
+    // Longhands, not the font shorthand: the shorthand would also reset font-feature-settings
+    // and the other font properties the page sets once on body.
+    const parts = ['font-family', 'font-size', 'font-weight', 'line-height', 'letter-spacing', ...(transform ? ['text-transform'] : [])];
+    const lines = parts.map((part) => `${part}: ${v(part)};`);
+    return `/* ${t.$description ?? name} */\n.text-style-${name} {\n${indent(lines.join('\n'), 2)}\n}`;
+  });
+}
+
+/**
+ * The text styles as CSS patterns, so component CSS can use a whole text style:
+ * @sl-pattern text-<style>; (expanded by loomiere-base-ui's build).
+ */
+export function textStylePatterns(cssPrefix = 'sl') {
+  prefix = cssPrefix;
+  return textStyleBlocks()
+    .map((block) => block.replace(/\n\.text-style-([\w-]+) \{/, '\n@sl-define text-$1 {'))
+    .join('\n\n');
+}
+
+function utilitiesCss() {
+  const sections = [['Text styles: one class per text style token.', textStyleBlocks()]];
+
+  // Custom properties can't be used inside @media, so the widths are written in.
+  const { breakpoint: bp } = readTokens('foundation/layout.json');
+  sections.push([
+    'Responsive visibility from the breakpoint tokens.',
+    [
+      ['mobile', `(width < ${bp.sm.$value})`, 'Phones, below the sm breakpoint.'],
+      ['tablet', `(${bp.sm.$value} <= width < ${bp.md.$value})`, 'Tablets, from sm up to md.'],
+      ['desktop', `(width >= ${bp.md.$value})`, 'md and wider.'],
+    ].map(([name, query, what]) => `/* ${what} */\n@media ${query} {\n  .hide-on-${name} {\n    display: none !important;\n  }\n}`),
+  ]);
+
+  // Icons: font icons size by font-size, SVGs by width and height, so set all three.
+  const { 'icon-size': icons } = readTokens('semantic/icon.json');
+  sections.push([
+    'Icon sizes: one class per text tier.',
+    Object.entries(icons)
+      .filter(([name]) => !name.startsWith('$'))
+      .map(([name, t]) => {
+        const v = `var(${varName(['icon-size', name])})`;
+        return `/* ${t.$description} */\n.icon-${name} {\n  width: ${v};\n  height: ${v};\n  font-size: ${v};\n  line-height: 1;\n}`;
+      }),
+  ]);
+
+  const { focus } = readTokens('semantic/focus.json');
+  sections.push([
+    'Keyboard focus rings from the focus tokens.',
+    [
+      ['focus-ring', 'outline-offset'],
+      ['focus-ring-inset', 'outline-offset-inset'],
+    ].map(
+      ([name, offset]) =>
+        `/* ${focus[offset].$description} */\n.${name}:focus-visible {\n  outline: var(${varName(['focus', 'outline'])});\n  outline-offset: var(${varName(['focus', offset])});${
+          offset === 'outline-offset' ? `\n  box-shadow: 0 0 0 var(${varName(['focus', 'halo-spread'])}) var(${varName(['focus', 'halo-color'])});` : ''
+        }\n}`,
+    ),
+  ]);
+  const body = sections.map(([what, blocks]) => `/* ${what} */\n\n${blocks.join('\n\n')}`).join('\n\n');
+  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 }.
+ */
+export async function buildTokens(config) {
+  prefix = config.prefix;
+  const { brand, applied, files } = generate(config.brandFile, config.generatedDir);
+  brandName = brand.name;
+  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: {
+      css: {
+        prefix,
+        transforms: ['name/sl-path', 'fontFamily/css', 'cubicBezier/css'],
+        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' },
+        ],
+      },
+    },
+  });
+
+  await sd.buildAllPlatforms();
+
+  fs.writeFileSync(path.join(config.outDir, 'utilities.css'), utilitiesCss());
+
+  // Every palette color against every other, for docs, agents and the ramp page.
+  const colors = paletteColors(files.color.color);
+  const pairs = pairTable(colors);
+  const compact = Object.fromEntries(
+    Object.entries(pairs).map(([p, levels]) => [
+      p,
+      Object.fromEntries(Object.entries(levels).map(([level, list]) => [level, list.map(({ path: b, ratio }) => [b, ratio])])),
+    ]),
+  );
+  fs.writeFileSync(
+    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/).
+  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);
+  return { brand, applied, exports: written };
+}