@scattered-light/loomiere 0.1.1 → 0.2.0

package/README.md

@@ -55,7 +55,7 @@ Every value is a `--sl-` variable, so your own CSS, and component packages such
 | `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). |
+| `exports/` | DTCG JSON, Figma variables, Tailwind v4, shadcn/ui, MUI, Chakra v3, AG Grid 31–32, 33–35 and 36+, a Claude Design System and `AGENTS.md` (the brand book for agents). 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/build/build-tokens.mjs

@@ -480,6 +480,6 @@ export async function buildTokens(config) {
   );
   // 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);
+  const written = exportAll(catalog, resolveRoles(brand), path.join(config.outDir, 'exports'), config.exports, { themeDir: config.outDir, brand });
   return { brand, applied, exports: written };
 }

package/exporters/README.md

@@ -7,12 +7,14 @@ adapter in this folder, and each one only renames. No adapter does color math.
 |---|---|---|
 | (built in) | `tokens.css` | Any framework, or none. Every token as a `--sl-` variable, with dark, contrast, color vision and roles. |
 | `dtcg` | `tokens.dtcg.json` | Any tool that reads the W3C design tokens format: Figma importers, Tokens Studio, Style Dictionary, Terrazzo, Penpot. |
-| `tailwind` | `tailwind.css` | Tailwind CSS v4. Points at the `--sl-` variables instead of copying values. |
+| `tailwind` | `tailwind.css` | Tailwind CSS v4: text styles by tier, palettes, roles, concepts, brand scales, pairs and scopes as classes. Points at the `--sl-` variables instead of copying values, and imports `tokens.css` itself. With loomiere-base-ui, pair it with `@scattered-light/loomiere-base-ui/tailwind.css`. |
+| `shadcn` | `shadcn.css` | shadcn/ui: its variables (`--primary`, `--accent`, `--ring`, charts, sidebar) pointed at Loomiere concepts. Replaces shadcn's `globals.css` color blocks; works alone or after `tailwind.css`. |
 | `mui` | `mui.js`, `.d.ts` | MUI 6, 7 and 9. `createTheme(options)`: the palette in light and dark, plus component overrides that match loomiere-base-ui. Needs `tokens.css`. |
 | `chakra` | `chakra.js`, `.d.ts` | Chakra UI 3. `<ChakraProvider value={system}>`: every palette as a color palette, plus recipes that match loomiere-base-ui. Needs `tokens.css`. |
 | `ag-grid-v36` | `ag-grid-v36.js`, `.d.ts`, `.css` | AG Grid 36 and later (Theming API). |
 | `ag-grid-v33` | `ag-grid-v33.js`, `.d.ts`, `.css` | AG Grid 33 to 35 (Theming API). |
 | `ag-grid-v32` | `ag-grid-v32.css` | AG Grid 31 and 32 (CSS themes). All three come from `ag-grid-settings.mjs`. |
+| `design-system` | `design-system/`, `AGENTS.md` | A Claude Design System (claude.ai), so Claude designs, makes decks and builds UI with the brand. `AGENTS.md` is the same brand book for coding agents, plus how to load the theme. See below. |
 | `figma` | `figma.json` | Figma variables in three collections: Brand, Pairs, Theme (Light and Dark modes). Aliases point back to Brand, so a palette change flows through. Fluid sizes use their large-screen value. |
 
 `loomiere build` writes them all to the theme's `exports/` folder, with `catalog.json` listing what's there.
@@ -20,6 +22,32 @@ adapter in this folder, and each one only renames. No adapter does color math.
 family, so `ag-grid` writes all three AG Grid themes). The Mojave demo package exposes them as
 `@scattered-light/loomiere-mojave/exports/<file>`.
 
+## Claude Design System
+
+Claude keeps a brand as a "Design System" artifact: a README written as a brand book, a
+`tokens.json`, and per component a guide and a live preview. Once it's the default, Claude uses it
+for every design and deck and checks its work against it; any chat or Claude Code session can read
+it. `design-system/` is that artifact's `project/` folder:
+
+- `README.md`: rules that name tokens (semantic first, emphasis levels, scopes, pairs, type tiers,
+  space, shape, focus, modes), written from the brand file and each token's description.
+- `tokens.json`: palettes and every semantic color in light and dark (a semantic color that
+  points at a palette step stays an alias of it), the text styles by tier, space, radius,
+  elevation and stroke. Each token's description is its usage note. Names are the CSS variables
+  without the dashes, so an edit made on the page lands on the variable the components read.
+- `components/bundle.css`: the whole theme plus the Base UI styles, so previews and Claude's
+  designs look exactly like the app, modes and pairs included.
+- `components/bundle.js`, `<Name>/README.md`, `<Name>/preview.html`: copied from
+  `@scattered-light/loomiere-base-ui/design-system/` when that package is installed (it builds them
+  from the Storybook stories). `bundle.js` sets `window.Loomiere` to every Base UI part plus the
+  wrappers.
+- `components/Cover/preview.html`: the cover, the brand's colors as blocks and its name.
+
+To publish, ask Claude Code (with the Artifact tool) to make a Design System artifact from
+`exports/design-system` the first time, and to republish the changed files after a rebuild. Then
+set it as the default in claude.ai under Settings > Design systems. The page writes its own
+`tokens.css` and component cards; the export leaves those out.
+
 ## How it works
 
 1. The build writes the token catalog (`tokens.json`).
@@ -41,5 +69,4 @@ file's text (or `{ fileName: text }` when it writes several, as the AG Grid them
 when the framework allows it (as Tailwind does), so modes and roles keep working at runtime;
 otherwise give light and dark values the way the framework expects (as MUI's palette does,
 since MUI does color math on it).
-Good next candidates: Panda CSS, Radix Themes, shadcn/ui (Tailwind plus its own variable
-names), Vuetify and Mantine.
+Good next candidates: Panda CSS, Radix Themes, Vuetify and Mantine.

package/exporters/design-system.mjs

@@ -0,0 +1,392 @@
+/**
+ * A Claude Design System: the files of a "Design System" artifact on claude.ai, which Claude reads
+ * before it designs, writes a deck or builds UI for the brand. Written to exports/design-system/,
+ * laid out as the artifact's project/ folder:
+ *
+ *   README.md            the brand book: usage rules that name tokens, generated from the brand
+ *   tokens.json          the tokens the page shows and edits: flat lists of { name, value, usage }
+ *                        where usage is each token's "why", colors in light and dark
+ *   components/bundle.css the whole theme (tokens.css, utilities.css) plus the Base UI component
+ *                        styles, so components and previews look exactly like the app
+ *   components/...       bundle.js, previews and guidelines from loomiere-base-ui, when it's installed
+ *
+ * Names are the CSS variables without the leading dashes (sl-text-primary), so a value edited on
+ * the page lands on the same variable the components read. The page reads no DTCG, var() or
+ * color-mix(), so colors are resolved per mode; a semantic color that points at a palette step
+ * stays an alias of that step. AGENTS.md is the same brand book with how to use the theme in code.
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { formatHex, formatHex8, interpolate, parse } from 'culori';
+
+import { valueIn } from './theme.mjs';
+
+const hex = (c) => ((c.alpha ?? 1) < 1 ? formatHex8(c) : formatHex(c));
+
+/** color-mix(in oklab|srgb, A p%, B) → a hex; anything else parse() understands → a hex. */
+function solve(value) {
+  const mix = String(value).match(/^color-mix\(in (\w+),\s*(.+?)\s+([\d.]+)%,\s*(.+)\)$/);
+  if (mix) {
+    const [a, b] = [solve(mix[2]), solve(mix[4])];
+    return a && b ? hex(interpolate([b, a], mix[1] === 'srgb' ? 'rgb' : mix[1])(Number(mix[3]) / 100)) : null;
+  }
+  if (value === 'transparent') return '#00000000';
+  const c = typeof value === 'string' ? parse(value) : undefined;
+  return c ? hex(c) : null;
+}
+
+/** Semantic families whose colors the page lists, in this order. */
+const SEMANTIC = ['surface', 'text', 'border', 'fill', 'interactive', 'focus', 'status', 'overlay', 'emphasis', 'content', 'field', 'popup', 'item', 'check', 'modal', 'drawer', 'bar', 'disclosure', 'notice', 'gauge', 'table', 'pair'];
+
+/** "clamp(0.875rem, 0.8333rem + 0.2083vw, 1rem)" → "1rem", the large-screen size. */
+const largest = (v) => String(v).match(/,\s*([\d.]+rem)\)$/)?.[1] ?? String(v);
+
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
+export default {
+  id: 'design-system',
+  name: 'Claude Design System',
+  file: 'design-system/README.md',
+  for: 'A Design System artifact on claude.ai, so Claude designs, makes decks and builds UI with this brand. Also AGENTS.md: the brand book for coding agents.',
+  build(theme, { themeDir, brand } = {}) {
+    const byPath = new Map(theme.tokens.map((t) => [t.path, t]));
+    const cssName = (p) => byPath.get(p).name.replace(/^--/, '');
+    const title = cap(theme.brand);
+
+    /** A token's "why", or the first one found along what it points at. */
+    function usageOf(t) {
+      for (let cur = t, hops = 0; cur && hops < 8; hops++) {
+        if (cur.description) return cur.description;
+        const ref = typeof cur.references === 'string' && cur.references.match(/^\{([^}]+)\}$/)?.[1];
+        cur = ref && byPath.get(ref);
+      }
+      return undefined;
+    }
+
+    // ------------------------------------------------------------------------------- colors
+    const palettes = theme.tokens.filter((t) => /^color\.(?!accent\.|chrome\.)/.test(t.path) && t.layer === 'primitive');
+    const semantic = SEMANTIC.flatMap((top) =>
+      theme.tokens.filter((t) => t.path.startsWith(`${top}.`) && t.layer !== 'primitive' && solve(t.value)),
+    );
+    const included = new Set([...palettes, ...semantic].map((t) => t.path));
+
+    /** What a token points at in a mode: a path, or null when the mode holds a value of its own. */
+    const refIn = (t, mode) => {
+      const ref = mode === 'dark' ? (t.modeReferences?.dark ?? (t.modes?.dark === undefined ? t.references : null)) : t.references;
+      return typeof ref === 'string' ? ref.match(/^\{([^}]+)\}$/)?.[1] ?? null : null;
+    };
+    /** "{sl-…}" for the nearest listed token along the chain, else the resolved hex. */
+    function colorIn(t, mode) {
+      for (let cur = t, hops = 0; hops < 16; hops++) {
+        const ref = refIn(cur, mode);
+        if (!ref || !byPath.has(ref)) break;
+        if (included.has(ref)) return `{${cssName(ref)}}`;
+        cur = byPath.get(ref);
+      }
+      return solve(valueIn(byPath, t.path, mode));
+    }
+    const colorTokens = [...semantic, ...palettes].flatMap((t) => {
+      const light = colorIn(t, 'light');
+      const dark = colorIn(t, 'dark');
+      if (!light) return [];
+      return [{ name: cssName(t.path), value: dark && dark !== light ? { light, dark } : light, usage: usageOf(t) ?? t.path }];
+    });
+
+    // ------------------------------------------------------------------------------- type
+    const styleNames = [...new Set(theme.tokens.filter((t) => /^font\.[^.]+\.font$/.test(t.path)).map((t) => t.path.split('.')[1]))];
+    const familyKey = (style) => byPath.get(`font.${style}.font-family`)?.references?.match(/^\{font-family\.([^}]+)\}$/)?.[1] ?? 'body';
+    const tierOf = (style) => (style === 'code' ? 'code' : style.split('-')[0]);
+    const TIERS = ['minimize', 'condense', 'base', 'magnify', 'maximize', 'code'];
+    const tiers = [...new Set(styleNames.map(tierOf))].sort((a, b) => (TIERS.indexOf(a) + 1 || 99) - (TIERS.indexOf(b) + 1 || 99));
+    const styleOf = (style) => {
+      const v = (prop) => byPath.get(`font.${style}.${prop}`)?.value;
+      const size = v('font-size');
+      const fluid = byPath.get(`font.${style}.font-size`)?.references?.match(/^\{(font-size\.[^}]+)\}$/)?.[1];
+      const sizeNote = fluid && String(size).startsWith('clamp') ? ` Fluid: ${byPath.get(fluid).description}.` : '';
+      const why = (byPath.get(`font.${style}.font`)?.description ?? '').replace(/\s*As a font shorthand;.*$/, '');
+      return {
+        name: `text-style-${style}`,
+        family: familyKey(style),
+        fontSize: largest(size),
+        lineHeight: v('line-height'),
+        fontWeight: Number(v('font-weight')) || 400,
+        ...(v('letter-spacing') && v('letter-spacing') !== '0' && { letterSpacing: v('letter-spacing') }),
+        usage: `${why}${sizeNote}`.trim(),
+      };
+    };
+    const families = Object.fromEntries(
+      theme.tokens.filter((t) => /^font-family\.(display|body|mono)$/.test(t.path)).map((t) => [t.path.split('.')[1], t.value]),
+    );
+
+    // ------------------------------------------------------------------------------- lengths
+    const list = (re, keep = () => true) =>
+      theme.tokens
+        .filter((t) => re.test(t.path) && keep(t))
+        .map((t) => ({ name: cssName(t.path), value: String(largest(t.value)), usage: usageOf(t) ?? t.path }));
+
+    const tokens = {
+      name: title,
+      version: 1,
+      meta: { source: 'loomiere', brand: theme.brand, prefix: theme.prefix },
+      color: { themes: [{ id: 'light', name: 'Light' }, { id: 'dark', name: 'Dark' }], tokens: colorTokens },
+      type: {
+        fonts: [],
+        families,
+        groups: tiers.map((tier) => ({
+          name: cap(tier),
+          family: familyKey(styleNames.find((s) => tierOf(s) === tier)),
+          styles: styleNames.filter((s) => tierOf(s) === tier).map(styleOf),
+        })),
+      },
+      spacing: { tokens: list(/^space\./) },
+      radius: { tokens: list(/^radius\./) },
+      shadow: { tokens: list(/^elevation\./) },
+      stroke: { tokens: list(/^stroke\./) },
+    };
+
+    // ------------------------------------------------------------------------------- components
+    const read = (file) => (themeDir && fs.existsSync(path.join(themeDir, file)) ? fs.readFileSync(path.join(themeDir, file), 'utf8') : '');
+    let componentsDir = null;
+    if (themeDir) {
+      try {
+        const require = createRequire(path.join(themeDir, 'package.json'));
+        const dir = path.join(path.dirname(require.resolve('@scattered-light/loomiere-base-ui/package.json')), 'dist', 'design-system', 'components');
+        if (fs.existsSync(dir)) componentsDir = dir;
+      } catch {
+        // loomiere-base-ui isn't installed: the system ships tokens and the brand book only.
+      }
+    }
+    const files = {};
+    const componentStyles = componentsDir ? fs.readFileSync(path.join(componentsDir, 'styles.css'), 'utf8') : '';
+    if (componentsDir) {
+      for (const file of fs.readdirSync(componentsDir, { recursive: true })) {
+        const full = path.join(componentsDir, String(file));
+        if (fs.statSync(full).isFile() && String(file) !== 'styles.css') files[`design-system/components/${String(file).split(path.sep).join('/')}`] = fs.readFileSync(full, 'utf8');
+      }
+    }
+    // One stylesheet: @imports first (CSS needs them on top), then the theme, then the components.
+    const sheets = [read('tokens.css'), read('utilities.css'), componentStyles];
+    const imports = sheets.flatMap((s) => s.match(/^@import url\([^)]*\);$/gm) ?? []);
+    const bundleCss = [...new Set(imports), ...sheets.map((s) => s.replace(/^@import url\([^)]*\);$/gm, ''))].join('\n');
+    files['design-system/components/bundle.css'] = bundleCss;
+
+    const componentNames = Object.keys(files)
+      .map((f) => f.match(/^design-system\/components\/([A-Z]\w+)\/README\.md$/)?.[1])
+      .filter(Boolean);
+
+    // ------------------------------------------------------------------------------- README
+    const readme = brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styleNames, componentNames });
+    files['design-system/README.md'] = readme;
+    files['design-system/components/Cover/preview.html'] = cover({ theme, brand, title });
+    files['design-system/tokens.json'] = `${JSON.stringify(tokens, null, 2)}\n`;
+    files['AGENTS.md'] = agentsGuide({ theme, readme, componentNames: componentNames.length > 0 });
+    return files;
+  },
+};
+
+/** The brand book: imperative rules a consuming agent follows, naming the tokens. */
+function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styleNames, componentNames }) {
+  const v = (p) => `\`--${cssName(p)}\``;
+  const has = (p) => byPath.has(p);
+  const why = (p) => usageOf(byPath.get(p)) ?? '';
+  const roles = theme.roles ?? {};
+  const label = (palette) => brand?.color?.palettes?.[palette]?.label;
+  const named = (palette) => (label(palette) ? `${palette} (${label(palette)})` : palette);
+  const rows = (paths) => paths.filter(has).map((p) => `| ${v(p)} | ${why(p)} |`);
+  const out = [];
+
+  if (brand?.description) out.push(brand.description, '');
+  out.push(
+    'Every value in this system is a CSS variable with the `--' + theme.prefix + '-` prefix. Reach for the semantic tokens (surfaces, text, borders, fills, emphasis); use a palette step only when no semantic token says what you mean. Never paste a hex value: the variables carry light and dark, high contrast and color vision modes, and a palette or role change in the brand reaches everything that uses them.',
+    '',
+    '## Color',
+    '',
+    `The **chrome** role is the ${named(roles.chrome ?? 'neutral')} palette: surfaces, text, borders and quiet controls. The **accent** role is the ${named(roles.accent ?? 'primary')} palette: links, focus and the loudest actions. Status colors (success, warning, error, info) mean only their status; pair each with a word or an icon, never color alone.`,
+    '',
+    '### Surfaces and text',
+    '',
+    '| Token | Use |',
+    '|---|---|',
+    ...rows(['surface.canvas', 'surface.raised', 'surface.overlay', 'surface.modal', 'surface.tray', 'surface.inverse', 'text.primary', 'text.secondary', 'text.tertiary', 'text.disabled', 'text.accent', 'text.on-primary', 'text.on-tint', 'text.on-inverse-surface']),
+    '',
+    '### Borders, fills and interaction',
+    '',
+    '| Token | Use |',
+    '|---|---|',
+    ...rows(['border.subtle', 'border.default', 'border.strong', 'border.control', 'border.control-hover', 'border.accent', 'fill.subtle', 'fill.default', 'fill.strong', 'fill.inverse', 'interactive.default', 'interactive.hover', 'interactive.active', 'interactive.tint', 'interactive.tint-hover', 'interactive.tint-active', 'focus.ring']),
+    '',
+    '### Status',
+    '',
+    '| Token | Use |',
+    '|---|---|',
+    ...rows(['status.success', 'status.warning', 'status.error', 'status.info', 'status.error-dark', 'status.error-light']),
+    '',
+    'Each status has `-dark` (text and icons that need more contrast) and `-light` (the tint behind a message) variants.',
+    '',
+    '### Palettes',
+    '',
+  );
+  const paletteNames = [...new Set(tokens.color.tokens.map((t) => t.name.match(new RegExp(`^${theme.prefix}-color-([a-z]+)-\\d+$`))?.[1]).filter(Boolean))];
+  out.push(
+    `Palettes: ${paletteNames.map((p) => `\`${p}\`${label(p) ? ` (${label(p)})` : ''}`).join(', ')}. Steps run from 50 (lightest) to the darkest step, and each step is placed by its contrast against paper, so a step number means the same contrast in every palette: text on paper needs 500 or darker (4.5:1). Every step has an on-color, \`--${theme.prefix}-color-<palette>-on-<step>\`, for text or icons placed on it.`,
+    '',
+  );
+  if (paletteNames.includes('data')) out.push(`The \`data\` palette (\`--${theme.prefix}-color-data-<n>\`) is for charts only: series colors, never UI.`, '');
+
+  out.push(
+    '### Emphasis',
+    '',
+    'Controls come in four levels of loudness. Pick the level by how much the action matters, not by color; the brand decides what each level looks like.',
+    '',
+    '| Level | Looks like | Use for |',
+    '|---|---|---|',
+  );
+  const ladder = { bold: 'The one main action in a view.', standard: 'Secondary actions beside a bold one.', subtle: 'Frequent, low-stakes actions such as toolbar buttons.', quiet: 'Actions that should stay out of the way until needed.' };
+  for (const [level, use] of Object.entries(ladder)) {
+    const e = roles.emphasis?.[level];
+    out.push(`| \`${level}\` | ${e ? `${e.style} in ${e.color}` : ''} | ${use} |`);
+  }
+  out.push(
+    '',
+    `Set it with \`data-emphasis="bold|standard|subtle|quiet"\` on a Button or any element styled from \`--${theme.prefix}-emphasis-<level>-bg|fg|border\` (with \`-hover\` and \`-active\`). On Button, \`data-variant\` is an alias: \`solid\` = bold, \`outline\` = standard, \`ghost\` = quiet.`,
+    '',
+    '### Color scopes',
+    '',
+    `\`data-color="<palette>"\` on any element repaints everything inside it in that palette (\`primary\`, \`secondary\`, \`error\`, \`accent\`, \`chrome\`...): a destructive button is \`<Button data-emphasis="bold" data-color="error">\`.`,
+    '',
+  );
+  const pairs = Object.entries(brand?.color?.pairs ?? {});
+  if (pairs.length) {
+    out.push(
+      '### Brand pairs',
+      '',
+      `A pair is a background with its own text and accent, checked to meet AA. Put \`class="${theme.prefix}-pair-<name>"\` on a band, card or callout and everything inside (text, links, buttons, focus) takes the pair's colors.`,
+      '',
+      '| Pair | Use |',
+      '|---|---|',
+      ...pairs.map(([name, p]) => `| \`.${theme.prefix}-pair-${name}\` | ${(p.description ?? '').replace(/^Example pair:\s*/, '')} |`),
+      '',
+    );
+  }
+
+  out.push(
+    '## Typography',
+    '',
+    `Families: display ${tokens.type.families.display ?? ''}, body ${tokens.type.families.body ?? ''}, mono ${tokens.type.families.mono ?? ''}.`,
+    '',
+    'All text uses one whole text style, never a size or weight on its own: `class="text-style-<name>"`, or the `--' + theme.prefix + '-font-<name>-*` variables (font-family, font-size, font-weight, line-height, letter-spacing) together. Styles come in tiers named for why the text is that size:',
+    '',
+  );
+  const tierWhy = {
+    minimize: 'the smallest functional text: captions, fine print, dense metadata.',
+    condense: 'compact UI: small controls, table cells, secondary labels.',
+    base: 'the default UI and body text.',
+    magnify: 'emphasized body text: lead paragraphs, larger controls.',
+    maximize: 'display text for headings and hero copy, in steps xs to 4xl.',
+    code: 'code, in the mono family.',
+  };
+  for (const tier of tiers) {
+    const variants = styleNames.filter((s) => s.startsWith(`${tier}-`)).map((s) => s.slice(tier.length + 1));
+    out.push(`- **${tier}**: ${tierWhy[tier] ?? ''}${variants.length ? ` Variants: ${variants.map((x) => `\`${x}\``).join(', ')}.` : ''}`);
+  }
+  out.push(
+    '',
+    'Inside a tier, `-trigger` is for buttons and triggers, `-selected` for the current tab, toggle or nav item, `-link` for links, `-subtitle` for subheads and `-label` for form labels. Sizes below the base are fixed; the base and up grow with the viewport.',
+    '',
+    '## Space, shape and depth',
+    '',
+  );
+  if (brand?.space?.unit) out.push(`Space is a ${brand.space.unit}px grid: \`--${theme.prefix}-space-<n>\` is n × ${brand.space.unit}px (\`space-4\` = ${brand.space.unit * 4}px). Use the steps; never a number in between.`, '');
+  out.push('Corners are chosen by what a thing is, not by size:', '', '| Token | Use |', '|---|---|', ...rows(['radius.control', 'radius.item', 'radius.surface', 'radius.chrome', 'radius.modal', 'radius.pill', 'radius.minimal']), '');
+  out.push(
+    `Depth: \`--${theme.prefix}-elevation-xs\` to \`-2xl\`, lowest first. Popups, menus and dialogs already carry theirs. Borders: \`--${theme.prefix}-stroke-default\` everywhere, \`-emphasis\` for selected or focused edges.`,
+    '',
+    '## Focus and states',
+    '',
+    `Keyboard focus is one ring, \`--${theme.prefix}-focus-outline\` with \`--${theme.prefix}-focus-outline-offset\`, plus a soft halo in \`--${theme.prefix}-focus-halo-color\`. Never remove it; the \`.focus-ring\` utility applies it. Hover moves one step toward more contrast, pressed one more. Disabled controls use \`--${theme.prefix}-text-disabled\` and \`--${theme.prefix}-interactive-disabled\`.`,
+    '',
+    '## Modes',
+    '',
+    `Light and dark: \`data-theme="light|dark"\` on the root, or the system setting when neither is set. High contrast follows \`prefers-contrast: more\`. Color vision themes: \`data-vision="deuteranopia|protanopia|tritanopia|achromatopsia"\`, each designed from this brand. Never hand-pick dark colors; the tokens already flip.`,
+    '',
+  );
+  if (componentNames.length) {
+    out.push(
+      '## Components',
+      '',
+      `The components are [Base UI](https://base-ui.com) parts styled by class name: ${componentNames.map((n) => `\`${n}\``).join(', ')}. Each component's README lists the classes its parts take and the data attributes they answer to (\`data-size="sm|lg"\`, \`data-emphasis\`, \`data-color\`). In previews and designs they are \`window.Loomiere.<Name>\`; Button, Input, Field, Fieldset, Form and NavigationMenu are wrappers that put their classes on themselves.`,
+      '',
+      'Icons are Material Symbols Outlined by ligature name (`<span class="material-symbols-outlined">search</span>`, or `Loomiere.MaterialSymbol name="search"`), sized by the `.icon-<tier>` utilities to match the text beside them.',
+      '',
+    );
+  }
+  return `${out.join('\n')}\n`;
+}
+
+/**
+ * The cover above the brand book: the brand's colors as large blocks, dunes of arcs drawn
+ * from the space scale, and the name in the display face. Every fill is a token, so it
+ * follows the theme and any edit on the page.
+ */
+function cover({ theme, brand, title }) {
+  const p = theme.prefix;
+  const roles = theme.roles ?? {};
+  const accent = roles.accent ?? 'primary';
+  const second = ['secondary', 'tertiary', 'quaternary'].find((x) => x !== accent && brand?.color?.palettes?.[x]) ?? accent;
+  const third = ['tertiary', 'quaternary', 'secondary'].find((x) => x !== accent && x !== second && brand?.color?.palettes?.[x]) ?? second;
+  const size = Math.max(64, Math.min(120, Math.floor(440 / (title.length * 0.6))));
+  const tagline = cap((brand?.description ?? '').replace(new RegExp(`^${title}:\\s*`, 'i'), ''));
+  return `<!-- @dsCard height=288 -->
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  body { margin: 0; background: var(--${p}-surface-canvas); }
+  .cover { position: relative; width: 960px; height: 288px; overflow: hidden; }
+  svg { position: absolute; inset: 0; }
+  .accent { fill: var(--${p}-color-${accent}-600); }
+  .second { fill: var(--${p}-color-${second}-600); }
+  .ink { fill: var(--${p}-surface-inverse); }
+  .tint { fill: var(--${p}-color-${accent}-100); }
+  .dune { fill: none; stroke: var(--${p}-color-${third}-300); stroke-width: var(--${p}-stroke-thick); }
+  .text { position: absolute; left: var(--${p}-space-10); bottom: var(--${p}-space-10); max-width: 440px; }
+  h1 { margin: 0; font-family: var(--${p}-font-family-display); font-weight: 600; font-size: ${size}px; line-height: 0.92; color: var(--${p}-text-primary); }
+  p { margin: var(--${p}-space-3) 0 0; font-family: var(--${p}-font-family-body); font-size: 14px; line-height: 1.4; color: var(--${p}-text-secondary); }
+</style>
+</head>
+<body>
+<div class="cover">
+  <svg width="960" height="288" viewBox="0 0 960 288" aria-hidden="true">
+    <!-- blocks: accent ${accent}-600 slab 192x288, ${second}-600 288x144, surface-inverse 144x144, ${accent}-100 tint 144x144
+         arrangement: one tall slab with a band and two squares beside it, bleeding off the top, right and bottom
+         pattern: dunes, concentric half-rings in ${third}-300; the brand is a desert, so its motif is the dune
+         scales: 36px (space-9) ring pitch, 144px (space-36) modules, stroke-thick rings, square corners (radius-minimal) -->
+    <rect class="accent" x="480" y="0" width="192" height="288"/>
+    <rect class="second" x="672" y="0" width="288" height="144"/>
+    <rect class="ink" x="672" y="144" width="144" height="144"/>
+    <rect class="tint" x="816" y="144" width="144" height="144"/>
+    <path class="dune" d="M636 288 a36 36 0 0 1 72 0 M600 288 a72 72 0 0 1 144 0 M564 288 a108 108 0 0 1 216 0"/>
+  </svg>
+  <div class="text">
+    <h1>${title}</h1>
+    ${tagline ? `<p>${tagline}</p>` : ''}
+  </div>
+</div>
+</body>
+</html>
+`;
+}
+
+/** AGENTS.md: the brand book plus how to load the theme in code. */
+function agentsGuide({ theme, readme, componentNames }) {
+  return `# ${cap(theme.brand)} theme: guide for agents
+
+This folder is a Loomiere theme. Load \`tokens.css\` (every token as a \`--${theme.prefix}-\` variable, light and dark) and \`utilities.css\` (text styles, focus ring, brand pairs). Framework adapters sit in \`exports/\`: \`tailwind.css\` (Tailwind v4: text styles by tier such as \`text-base\`, concept classes such as \`bg-field\` and \`text-link\`, no bare sizes like \`text-sm\`), \`shadcn.css\` (shadcn/ui), \`mui.js\`, \`chakra.js\`, AG Grid themes, \`tokens.dtcg.json\`. \`tokens.json\` lists every token with its path, value, modes and the reason it exists; read a token's \`description\` before using it.
+${componentNames ? `\nComponents: \`@scattered-light/loomiere-base-ui\` (Base UI parts styled by class name; import \`@scattered-light/loomiere-base-ui/styles.css\` after the theme). \`exports/design-system/components/<Name>/README.md\` lists each component's classes and an example.\n` : ''}
+Change the brand only in the brand file and rebuild (\`loomiere build\`); never edit generated files.
+
+${readme.replace(/^#+ /gm, (m) => `#${m}`)}`;
+}

package/exporters/index.mjs

@@ -7,14 +7,16 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import chakra from './chakra.mjs';
+import designSystem from './design-system.mjs';
 import dtcg from './dtcg.mjs';
 import figma from './figma.mjs';
 import mui from './mui.mjs';
+import shadcn from './shadcn.mjs';
 import tailwind from './tailwind.mjs';
 import { agGridV32, agGridV33, agGridV36 } from './ag-grid.mjs';
 import { readTheme } from './theme.mjs';
 
-export const EXPORTERS = [dtcg, figma, tailwind, mui, chakra, agGridV36, agGridV33, agGridV32];
+export const EXPORTERS = [dtcg, figma, tailwind, shadcn, mui, chakra, agGridV36, agGridV33, agGridV32, designSystem];
 
 /**
  * Whether an exporter is wanted: `only` is "all" or a list of ids, where an id may name a
@@ -22,15 +24,25 @@ export const EXPORTERS = [dtcg, figma, tailwind, mui, chakra, agGridV36, agGridV
  */
 const wanted = (id, only) => only === 'all' || only.some((pick) => id === pick || id.startsWith(`${pick}-`));
 
-/** Writes the chosen exports into outDir and a catalog.json that lists them. */
-export function exportAll(catalog, roles, outDir, only = 'all') {
+/**
+ * Writes the chosen exports into outDir and a catalog.json that lists them. `context` is what
+ * an exporter may need beyond the theme: the built theme's folder and the brand file.
+ */
+export function exportAll(catalog, roles, outDir, only = 'all', context = {}) {
   const theme = readTheme(catalog, roles);
+  // 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');
+  if (fs.existsSync(tokensCss)) theme.tokensCss = fs.readFileSync(tokensCss, 'utf8');
   fs.mkdirSync(outDir, { recursive: true });
   const written = EXPORTERS.filter((exporter) => wanted(exporter.id, only)).map((exporter) => {
     // An exporter returns one file's text, or { fileName: text } when it writes several.
-    const out = exporter.build(theme);
+    const out = exporter.build(theme, context);
     const files = typeof out === 'string' ? { [exporter.file]: out } : out;
-    for (const [file, text] of Object.entries(files)) fs.writeFileSync(path.join(outDir, file), text);
+    for (const [file, text] of Object.entries(files)) {
+      fs.mkdirSync(path.dirname(path.join(outDir, file)), { recursive: true });
+      fs.writeFileSync(path.join(outDir, file), text);
+    }
     return { id: exporter.id, name: exporter.name, file: exporter.file, files: Object.keys(files), for: exporter.for };
   });
   fs.writeFileSync(path.join(outDir, 'catalog.json'), `${JSON.stringify({ brand: theme.brand, exports: written }, null, 2)}\n`);

package/exporters/shadcn.mjs

@@ -0,0 +1,110 @@
+/**
+ * shadcn/ui variables. shadcn components read about twenty CSS variables (--background,
+ * --primary, --ring, --radius, the chart and sidebar colors); this points each at a Loomiere
+ * concept, so the copied components take on the brand, in every mode, without edits.
+ *   @import "tailwindcss";
+ *   @import "./theme/exports/shadcn.css";
+ * It replaces everything after the imports in shadcn's globals.css. Only colors,
+ * the radius, fonts and text sizes follow the brand; shadcn's own spacing and shapes stay.
+ */
+
+/** shadcn variable → Loomiere token path. */
+const VARIABLES = {
+  background: 'surface.canvas',
+  foreground: 'text.primary',
+  card: 'surface.raised',
+  'card-foreground': 'text.primary',
+  popover: 'popup.background',
+  'popover-foreground': 'item.color',
+  // shadcn's primary is its main button, which is our bold emphasis: the accent role's solid.
+  primary: 'scope.accent.solid',
+  'primary-foreground': 'scope.accent.on-solid',
+  secondary: 'scope.chrome.soft',
+  'secondary-foreground': 'scope.chrome.on-soft',
+  muted: 'fill.subtle',
+  'muted-foreground': 'text.secondary',
+  // shadcn's accent is the hover fill of menu rows and ghost buttons, our item hover.
+  accent: 'item.background-hover',
+  'accent-foreground': 'item.color-hover',
+  destructive: 'scope.error.solid',
+  'destructive-foreground': 'scope.error.on-solid',
+  border: 'border.default',
+  input: 'border.control',
+  ring: 'focus.ring',
+  'chart-1': 'color.data.1',
+  'chart-2': 'color.data.2',
+  'chart-3': 'color.data.3',
+  'chart-4': 'color.data.4',
+  'chart-5': 'color.data.5',
+  sidebar: 'surface.tray',
+  'sidebar-foreground': 'text.primary',
+  'sidebar-primary': 'scope.accent.solid',
+  'sidebar-primary-foreground': 'scope.accent.on-solid',
+  'sidebar-accent': 'item.background-hover',
+  'sidebar-accent-foreground': 'item.color-hover',
+  'sidebar-border': 'border.default',
+  'sidebar-ring': 'focus.ring',
+  radius: 'radius.control',
+};
+
+/** shadcn's text sizes → the text tier whose size they take. */
+const SIZES = { xs: 'minimize', sm: 'condense', base: 'base', lg: 'magnify' };
+
+export default {
+  id: 'shadcn',
+  name: 'shadcn/ui',
+  file: 'shadcn.css',
+  for: 'shadcn/ui on Tailwind v4: import after tailwindcss in place of the color blocks in globals.css. Dark mode follows data-theme (next-themes: attribute="data-theme").',
+  build(theme) {
+    const name = new Map(theme.tokens.map((t) => [t.path, t.name]));
+    const root = Object.entries(VARIABLES)
+      .filter(([, path]) => name.has(path))
+      .map(([v, path]) => `  --${v}: var(${name.get(path)});`);
+    const colors = Object.keys(VARIABLES)
+      .filter((v) => v !== 'radius' && name.has(VARIABLES[v]))
+      .map((v) => `  --color-${v}: var(--${v});`);
+    const sizes = Object.entries(SIZES).flatMap(([size, tier]) =>
+      name.has(`font.${tier}.font-size`) ? [`  --text-${size}: var(${name.get(`font.${tier}.font-size`)});`, `  --text-${size}--line-height: var(${name.get(`font.${tier}.line-height`)});`] : [],
+    );
+    const fonts = [['sans', 'body'], ['mono', 'mono']].filter(([, role]) => name.has(`font-family.${role}`)).map(([tw, role]) => `  --font-${tw}: var(${name.get(`font-family.${role}`)});`);
+    return `/* shadcn/ui variables for "${theme.brand}". Generated by loomiere build; do not edit.
+   @import "tailwindcss";
+   @import "<theme>/exports/shadcn.css";
+   Replaces everything after the imports in shadcn's globals.css. Every variable
+   points at a --${theme.prefix}- concept, so dark mode, contrast modes and color vision themes come
+   along. Dark mode is data-theme="dark" on <html> (next-themes: attribute="data-theme"), or the
+   system setting. With the Loomiere Tailwind theme as well, import this after it: text-xs to
+   text-lg come back for shadcn's components, sized by the text tiers. */
+@import "../tokens.css";
+
+:root {
+${root.join('\n')}
+}
+
+@custom-variant dark {
+  &:where([data-theme='dark'], [data-theme='dark'] *) {
+    @slot;
+  }
+  @media (prefers-color-scheme: dark) {
+    &:where(:root:not([data-theme='light']), :root:not([data-theme='light']) *) {
+      @slot;
+    }
+  }
+}
+
+@theme inline {
+${[...colors, ...fonts, ...sizes].join('\n')}
+}
+
+/* shadcn's own base styles, kept so this file can stand in for globals.css. */
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+`;
+  },
+};

package/exporters/tailwind.mjs

@@ -3,14 +3,64 @@
  * instead of copying values, so dark mode, contrast modes, color vision themes and
  * data-color/data-emphasis all keep working in utility classes.
  *   @import "tailwindcss";
- *   @import "./theme/tokens.css";
- *   @import "./tailwind.css";
+ *   @import "./theme/exports/tailwind.css";   (brings tokens.css along)
  */
+/** Concept groups the Base UI CSS reads; each becomes named colors and spacing in Tailwind. */
+const CONCEPTS = ['field', 'item', 'check', 'popup', 'modal', 'bar', 'table', 'gauge', 'disclosure', 'icon-button', 'notice', 'control', 'icon-size', 'fill', 'interactive', 'status', 'border', 'text', 'surface', 'focus', 'content', 'space', 'gap', 'spacing'];
+const isColor = (t) => t.type === 'color' || /^(#|rgba?\(|hsla?\(|oklch\(|oklab\(|color-mix\(|transparent$)/i.test(String(t.value));
+const isLength = (t) => /^-?[\d.]+(rem|px|em)$/.test(String(t.value)) && !/(border-width|radius|width|width-|indicator-width|outline|ring-width|halo-spread)/.test(t.path);
+/**
+ * A concept color's Tailwind name: the background is the concept itself, text is -fg, an edge
+ * is -border. field.background → bg-field, field.color → text-field-fg,
+ * field.border-color-hover → border-field-border-hover, item.background-selected → bg-item-selected.
+ * Prose colors drop the group: content.link-color → text-link. Text colors read as fg:
+ * text.on-tint → text-fg-on-tint.
+ */
+function colorName(group, key) {
+  const words = key.split('-');
+  const out = [];
+  for (let i = 0; i < words.length; i++) {
+    if (words[i] === 'background') continue;
+    if (words[i] === 'border' && words[i + 1] === 'color') {
+      out.push('border');
+      i++;
+    } else if (words[i] === 'color') out.push(group === 'content' || i > 0 ? '' : 'fg');
+    else out.push(words[i]);
+  }
+  const k = out.filter(Boolean).join('-');
+  if (group === 'content') return k;
+  if (group === 'text') return `fg-${k}`;
+  return k ? `${group}-${k}` : group;
+}
+/** field.gap → field, modal.padding → modal, item.padding-inline → item-inline, control.height-md → control-md, icon-size.base → icon-base. */
+function spaceName(group, key) {
+  if (group === 'space' || group === 'spacing') return key;
+  if (group === 'gap') return `gap-${key}`;
+  if (group === 'icon-size') return `icon-${key}`;
+  const k = key.replace(/(^|-)(gap|padding|height|size)(?=-|$)/g, '$1').replace(/^-+|-+$/g, '').replace(/-{2,}/g, '-');
+  return k ? `${group}-${k}` : group;
+}
+/** [tailwind name, token] for every concept token that passes the test, first name wins. */
+function conceptTokens(theme, test, nameOf) {
+  const out = new Map();
+  // In CONCEPTS order, so a component's own token wins a name over prose (content.field-border).
+  const order = (t) => CONCEPTS.indexOf(t.path.split('.')[0]);
+  for (const t of [...theme.tokens].sort((a, b) => order(a) - order(b))) {
+    const [group, ...rest] = t.path.split('.');
+    if (!CONCEPTS.includes(group) || rest.length !== 1 || !test(t)) continue;
+    let twName = nameOf(group, rest[0]);
+    // A text color that lands on its background's name reads as -fg: table.header-color → table-header-fg.
+    if (out.has(twName) && /(^|-)color(-|$)/.test(rest[0])) twName += '-fg';
+    if (!out.has(twName)) out.set(twName, t);
+  }
+  return out;
+}
+
 export default {
   id: 'tailwind',
   name: 'Tailwind CSS v4',
   file: 'tailwind.css',
-  for: 'Tailwind v4 projects: import after tailwindcss and tokens.css. Utilities like bg-accent-solid, text-fg, border-chrome-border.',
+  for: 'Tailwind v4 projects: import after tailwindcss (it brings tokens.css along). Utilities like bg-accent-solid, text-fg, bg-emphasis-bg, and text styles by tier: text-base, text-magnify-trigger.',
   build(theme) {
     const name = new Map(theme.tokens.map((t) => [t.path, t.name]));
     const line = (twVar, path) => (name.has(path) ? `  ${twVar}: var(${name.get(path)});` : null);
@@ -18,18 +68,72 @@ export default {
     for (const [palette, steps] of Object.entries(theme.palettes)) for (const step of Object.keys(steps)) lines.push(line(`--color-${palette}-${step}`, `color.${palette}.${step}`));
     for (const [scope, { light }] of Object.entries(theme.scopes)) for (const slot of Object.keys(light)) lines.push(line(`--color-${scope}-${slot}`, `scope.${scope}.${slot}`));
     // The scope in effect (accent unless data-color says otherwise) and the emphasis paints.
+    // Emphasis is spelled out: "e" would read as Tailwind's inline-end side (border-e-*).
     for (const slot of Object.keys(theme.scopes.accent.light)) lines.push(`  --color-scope-${slot}: var(--${theme.prefix}-scope-${slot});`);
-    for (const part of ['bg', 'bg-hover', 'bg-active', 'fg', 'border', 'border-hover']) lines.push(`  --color-e-${part}: var(--${theme.prefix}-e-${part});`);
+    for (const part of ['bg', 'bg-hover', 'bg-active', 'fg', 'border', 'border-hover']) lines.push(`  --color-emphasis-${part}: var(--${theme.prefix}-e-${part});`);
     const semantic = { bg: 'surface.canvas', raised: 'surface.raised', overlay: 'surface.overlay', inverse: 'surface.inverse', fg: 'text.primary', 'fg-muted': 'text.secondary', 'fg-subtle': 'text.tertiary', 'fg-disabled': 'text.disabled', border: 'border.default', 'border-subtle': 'border.subtle', 'border-strong': 'border.strong', focus: 'focus.ring', white: 'color.white', black: 'color.black' };
     for (const [k, path] of Object.entries(semantic)) lines.push(line(`--color-${k}`, path));
+    // The semantic concepts the Base UI CSS reads, so a component built from utilities paints
+    // the same way: bg-field, border-field-border-hover, text-link, bg-item-hover, bg-status-error.
+    for (const [twName, t] of conceptTokens(theme, isColor, colorName)) if (!lines.some((l) => l?.startsWith(`  --color-${twName}:`))) lines.push(`  --color-${twName}: var(${t.name});`);
     lines.push('  --color-transparent: transparent;', '  --color-current: currentColor;');
+    // Tailwind's own scales are cleared wherever the brand has one, so every class is the brand's.
+    lines.push('  --font-*: initial;');
     for (const role of ['display', 'body', 'mono']) lines.push(line(`--font-${role}`, `font-family.${role}`));
     lines.push(line('--font-sans', 'font-family.body'));
-    for (const step of Object.keys(theme.fontSizes)) lines.push(line(`--text-${step}`, `font-size.${step}`), line(`--text-${step}--line-height`, `line-height.${step}`));
-    for (const r of Object.keys(theme.radii)) lines.push(line(`--radius-${r}`, `radius.${r}`));
-    for (const s of Object.keys(theme.shadows)) lines.push(line(`--shadow-${s}`, `elevation.${s}`));
+    const scale = (twNs, group) => {
+      lines.push(`  --${twNs}-*: initial;`);
+      for (const t of theme.tokens) if (t.path.startsWith(`${group}.`) && !t.path.slice(group.length + 1).includes('.')) lines.push(`  --${twNs}-${t.path.slice(group.length + 1)}: var(${t.name});`);
+    };
+    // No font sizes on their own: text always takes a whole text style (below).
+    lines.push('  --text-*: initial;');
+    scale('font-weight', 'font-weight');
+    scale('tracking', 'letter-spacing');
+    scale('radius', 'radius');
+    scale('shadow', 'elevation');
+    scale('ease', 'easing');
+    scale('container', 'container');
     const unit = name.get('space.1');
     if (unit) lines.push(`  --spacing: var(${unit});`);
-    return `/* Tailwind CSS v4 theme for "${theme.brand}". Generated by loomiere build; do not edit.\n   @import "tailwindcss";\n   @import "./theme/tokens.css";\n   @import "./tailwind.css";\n   Every value points at a --${theme.prefix}- variable, so modes and data-color keep working. */\n@theme inline {\n${lines.filter(Boolean).join('\n')}\n}\n`;
+    // Named spacing from the concepts, beside the unit scale: gap-field, p-modal, px-item-inline,
+    // h-control-md, size-icon-base.
+    for (const [twName, t] of conceptTokens(theme, isLength, spaceName)) lines.push(`  --spacing-${twName}: var(${t.name});`);
+    // Concept shadows: shadow-popup, shadow-modal.
+    for (const g of ['popup', 'modal']) lines.push(line(`--shadow-${g}`, `${g}.shadow`));
+    // Media queries can't read custom properties, so breakpoints are written as values.
+    const breakpoints = theme.tokens.filter((t) => /^breakpoint\.[\w-]+$/.test(t.path)).map((t) => `  --breakpoint-${t.path.slice(11)}: ${t.value};`);
+    // Each text style is one utility named by its tier (text-base, text-magnify-trigger), so a
+    // class sets family, size, weight, line height and letter spacing together.
+    const styles = new Map();
+    for (const t of theme.tokens) {
+      const m = t.path.match(/^font\.([\w-]+)\.(font-family|font-size|font-weight|line-height|letter-spacing|text-transform)$/);
+      if (m) (styles.get(m[1]) ?? styles.set(m[1], []).get(m[1])).push(`  ${m[2]}: var(${t.name});`);
+    }
+    const utilities = [...styles].map(([style, decls]) => `@utility text-${style} {\n${decls.join('\n')}\n}`);
+    // z-index layers by name (z-modal, z-toast); Tailwind's z-10 and friends still work.
+    const z = theme.tokens.filter((t) => /^z-index\.[\w-]+$/.test(t.path)).map((t) => `@utility z-${t.path.slice(8)} {\n  z-index: var(${t.name});\n}`);
+    const durations = theme.tokens.filter((t) => /^duration\.[\w-]+$/.test(t.path)).map((t) => `@utility duration-${t.path.slice(9)} {\n  --tw-duration: var(${t.name});\n  transition-duration: var(${t.name});\n}`);
+    // dark: follows Loomiere's mode: data-theme="dark" on <html>, or the system setting
+    // unless data-theme="light" says otherwise.
+    const dark = `@custom-variant dark {\n  &:where([data-theme='dark'], [data-theme='dark'] *) {\n    @slot;\n  }\n  @media (prefers-color-scheme: dark) {\n    &:where(:root:not([data-theme='light']), :root:not([data-theme='light']) *) {\n      @slot;\n    }\n  }\n}`;
+    // Brand pairs and color scopes as utilities (pair-stone-soft, scope-error), the same
+    // declarations as .${theme.prefix}-pair-<name> and [data-color='<name>'] in tokens.css, so
+    // variants work on them: md:pair-stone-soft, hover:scope-error.
+    const block = (selector) => theme.tokensCss?.match(new RegExp(`^\\s*${selector.replace(/[.[\]'()]/g, '\\$&')}(?:,\\n[^{]*)? \\{\\n([^}]*)\\}`, 'm'))?.[1];
+    const ruleUtility = (utility, selector) => {
+      const body = block(selector);
+      return body ? `@utility ${utility} {\n${body.split('\n').map((l) => l.trim()).filter(Boolean).map((l) => `  ${l}`).join('\n')}\n}` : null;
+    };
+    const pairNames = [...new Set(theme.tokens.filter((t) => t.path.startsWith('pair.')).map((t) => t.path.split('.')[1]))];
+    const pairs = pairNames.map((pair) => ruleUtility(`pair-${pair}`, `.${theme.prefix}-pair-${pair}`));
+    const scopeUtilities = Object.keys(theme.scopes).map((scope) => ruleUtility(`scope-${scope}`, `[data-color='${scope}']`));
+    return `/* Tailwind CSS v4 theme for "${theme.brand}". Generated by loomiere build; do not edit.
+   @import "tailwindcss";
+   @import "<theme>/exports/tailwind.css";   (or <package>/tailwind.css; it brings tokens.css along)
+   With loomiere-base-ui, add @import "@scattered-light/loomiere-base-ui/tailwind.css" so utilities win over component styles.
+   Every value points at a --${theme.prefix}- variable, so modes and data-color keep working. */
+@import "../tokens.css";
+
+@theme inline {\n${lines.filter(Boolean).join('\n')}\n}\n\n@theme {\n  --breakpoint-*: initial;\n${breakpoints.join('\n')}\n}\n\n${[dark, ...utilities, ...z, ...durations, ...pairs, ...scopeUtilities].filter(Boolean).join('\n\n')}\n`;
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scattered-light/loomiere",
-  "version": "0.1.1",
+  "version": "0.2.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": {