@scattered-light/loomiere 0.1.1 → 0.3.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,451 @@
+/**
+ * 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) {
+    const has = (n) => componentNames.includes(n);
+    const pick = (list) => list.filter(([n]) => has(n)).map(([n, use]) => `| \`${n}\` | ${use} |`);
+    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\`).`,
+      '',
+      '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.',
+      '',
+      '### Using the components in a page or design',
+      '',
+      'Load three things, in this order:',
+      '',
+      '1. `components/bundle.css`: the whole theme in one sheet. It holds every token (light, dark, high contrast and color vision modes), the text style, icon and focus utilities, the brand pairs, and every component\'s styles, and it imports the brand fonts and Material Symbols from Google Fonts itself. Nothing else is needed for styling; `tokens.json` is the same tokens as data for the Design System page.',
+      '2. React 18 and ReactDOM 18 as the `window.React` and `window.ReactDOM` globals. A design canvas or the preview frame already has them.',
+      '3. `components/bundle.js`: one classic script that sets `window.Loomiere`.',
+      '',
+      '`window.Loomiere` holds two kinds of component:',
+      '',
+      `- **Wrappers** put their own classes on, so use them bare: ${['Button', 'IconButton', 'Input', 'Field', 'Fieldset', 'Form', 'NavigationMenu'].filter(has).map((n) => `\`Loomiere.${n}\``).join(', ')}. \`Loomiere.Button\` also takes \`emphasis\` (\`bold|standard|subtle|quiet\`) and \`palette\` props, and a Button holding only an icon draws itself square (it sets \`data-icon-only\`). A plain \`.Button\`, such as a Popover or Toolbar trigger, is drawn square when it has an \`aria-label\` and a single icon inside, or when you set \`data-icon-only\` on it.`,
+      '- **Everything else is the bare Base UI part** under its usual name (`Loomiere.Popover.Popup`, `Loomiere.ToggleGroup`). It draws nothing until you give each part its class, which is the component and part names joined: `<Loomiere.Popover.Popup className="PopoverPopup">`, `<Loomiere.Toggle className="Toggle">`. The component READMEs list every class.',
+      '',
+      '`Loomiere.Base` holds the bare Base UI parts for the wrappers too (`Loomiere.Base.Button`), for when you need the part without its classes.',
+      '',
+      '### Choosing a component',
+      '',
+      'Pick by what the person is doing, not by look:',
+      '',
+      '| Component | Use it to |',
+      '|---|---|',
+      ...pick([
+        ['Button', 'Run one action. Set its emphasis by how much the action matters.'],
+        ['IconButton', 'Run a small, frequent action shown as an icon alone, where a Button would be too loud: calendar arrows, row actions, a clear button. Always give it an aria-label.'],
+        ['Switch', 'Turn one setting on or off, taking effect at once.'],
+        ['Checkbox', 'Turn one option on or off inside a form that is submitted later.'],
+        ['Toggle', 'A tool that stays pressed, such as Bold in a toolbar.'],
+        ['ToggleGroup', 'Switch between 2 to 5 short modes or views that apply at once (Single date / Date range, List / Grid).'],
+        ['Tabs', 'Switch between panels of content in the same place.'],
+        ['Radio', 'Choose one of 2 to 6 options in a form, where each option can carry a label and description.'],
+        ['CheckboxGroup', 'Choose any number of a few visible options.'],
+        ['Select', 'Choose one of a fixed list too long to show (about 6 to 15 items).'],
+        ['Combobox', 'Choose one or more from a long list by typing to filter it.'],
+        ['Autocomplete', 'Type free text, with suggestions to speed it up.'],
+        ['NumberField', 'Enter an exact number, with steppers.'],
+        ['Slider', 'Set a value in a range where roughly is good enough.'],
+        ['OTPField', 'Enter a one-time code.'],
+        ['Menu', 'Offer commands from a button. Menus run actions; they don\'t hold a value.'],
+        ['ContextMenu', 'Offer commands on right-click or long press.'],
+        ['Menubar', 'An app\'s top row of menus.'],
+        ['Toolbar', 'A row of buttons, toggles and fields that act on one thing.'],
+        ['NavigationMenu', 'Site navigation, with panels of links.'],
+        ['Tooltip', 'Name an icon-only control. Never put anything you can click inside one.'],
+        ['PreviewCard', 'Preview what a link leads to on hover.'],
+        ['Popover', 'Show interactive content beside its trigger: a picker, a short form, filters.'],
+        ['Dialog', 'A task that needs full attention before the page goes on.'],
+        ['AlertDialog', 'Confirm a destructive or hard-to-undo action.'],
+        ['Drawer', 'A side task or detail panel that keeps the page in view.'],
+        ['Accordion', 'Several sections where only some need to be open.'],
+        ['Collapsible', 'One section to show or hide.'],
+        ['Toast', 'Report the result of an action, briefly.'],
+        ['Progress', 'Show how far a task has got.'],
+        ['Meter', 'Show a measured amount within known limits, such as storage used.'],
+      ]),
+      '',
+      `A list of choices that stays on screen inside a panel, one of them selected (quick picks, saved filters, presets), has no Base UI part. Make each row a \`<button aria-pressed>\` drawn from the item concept: \`--${theme.prefix}-item-padding-block\`, \`-padding-inline\`, \`-radius\` and \`-gap\`, \`--${theme.prefix}-item-background-hover\` and \`-color-hover\` on hover, \`--${theme.prefix}-item-background-selected\` and \`-color-selected\` with the \`-selected\` text style when chosen. These are the same rows menus and selects use. When the choice is a form value, use Radio instead.`,
+      '',
+    );
+  }
+  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.3.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": {

package/tokens/component/popover.json

@@ -1,9 +1,9 @@
 {
   "popover": {
     "$description": "Popover's own sizes. Everything else is the popup and close concepts, text styles and CSS.",
-    "popup-max-width": {
-      "$value": "400px",
-      "$description": "Keeps longer text to a readable line length."
+    "text-max-width": {
+      "$value": "{measure.narrow}",
+      "$description": "Keeps the title and description to a readable line length. The popup itself has no fixed cap, so wider content such as a calendar or a form fits; it stops at the space Base UI reports beside the trigger."
     },
     "popup-min-width": {
       "$value": "{popup.min-width}",