@scattered-light/loomiere 0.2.0 → 0.4.0

package/exporters/chakra.mjs

@@ -19,8 +19,8 @@ const CHAKRA_SLOTS = { contrast: 'on-solid', subtle: 'soft', muted: 'soft-hover'
 const STATUS = ['info', 'warning', 'success', 'error'];
 /** Text styles a Chakra user can name as textStyle="…". */
 const TEXT_STYLES = [
-  'minimize', 'condense', 'base', 'magnify', 'base-label', 'base-selected', 'condense-subtitle-label',
-  'condense-trigger', 'base-trigger', 'magnify-trigger', 'maximize-md', 'maximize-lg', 'maximize-xl', 'maximize-2xl', 'maximize-3xl', 'maximize-4xl',
+  'body-minimize', 'body-condense', 'body-base', 'body-magnify', 'label-base', 'selected-base', 'eyebrow-condense',
+  'trigger-condense', 'trigger-base', 'trigger-magnify', 'title-condense', 'title-base', 'title-magnify', 'title-amplify', 'title-maximize',
 ];
 
 /** Merges our recipe pieces into Chakra's own, in the generated file (see RESTYLE below). */
@@ -127,7 +127,7 @@ export default {
 
     const field = {
       ...k.field,
-      ...text('base'),
+      ...text('body-base'),
       focusVisibleRing: null,
       focusRingColor: null,
       _hover: k.fieldStates.hover,
@@ -137,7 +137,7 @@ export default {
       _placeholder: k.fieldStates.placeholder,
     };
     const fieldSize = (tier) => ({
-      ...text(tier === 'xs' || tier === 'sm' ? 'condense' : tier === 'lg' ? 'magnify' : 'base'),
+      ...text(tier === 'xs' || tier === 'sm' ? 'body-condense' : tier === 'lg' ? 'body-magnify' : 'body-base'),
       textStyle: null,
       '--input-height': v(`control-height-${tier}`),
       height: v(`control-height-${tier}`),
@@ -196,7 +196,7 @@ export default {
 
     const checkControl = (tier) => ({ boxSize: k.iconSize(tier), '& svg': { width: v(`icon-size-${{ xs: 'minimize', sm: 'minimize', md: 'condense', lg: 'base' }[tier]}`), height: v(`icon-size-${{ xs: 'minimize', sm: 'minimize', md: 'condense', lg: 'base' }[tier]}`) } });
     const checkRow = { gap: v('gap-control'), color: v('text-primary') };
-    const label = { ...text('base'), textStyle: null, _disabled: { color: v('text-disabled'), opacity: null } };
+    const label = { ...text('body-base'), textStyle: null, _disabled: { color: v('text-disabled'), opacity: null } };
     const checked = '&:is([data-state=checked], [data-state=indeterminate])';
 
     const slotRecipes = {
@@ -204,9 +204,9 @@ export default {
         base: {
           root: { gap: v('field-gap') },
           // A disabled field fades as a whole, as a disabled Base UI Field.Root does.
-          label: { ...text('base-label'), textStyle: null, gap: v('space-1'), marginBottom: v('field-label-spacing'), color: v('text-primary'), _disabled: { opacity: v('field-opacity-disabled') } },
-          helperText: { ...text('condense'), textStyle: null, margin: `${v('field-message-spacing')} 0 0`, color: v('text-secondary'), _disabled: { opacity: v('field-opacity-disabled') } },
-          errorText: { ...text('base-label'), textStyle: null, margin: `${v('field-message-spacing')} 0 0`, color: v('status-error') },
+          label: { ...text('label-base'), textStyle: null, gap: v('space-1'), marginBottom: v('field-label-spacing'), color: v('text-primary'), _disabled: { opacity: v('field-opacity-disabled') } },
+          helperText: { ...text('body-condense'), textStyle: null, margin: `${v('field-message-spacing')} 0 0`, color: v('text-secondary'), _disabled: { opacity: v('field-opacity-disabled') } },
+          errorText: { ...text('label-base'), textStyle: null, margin: `${v('field-message-spacing')} 0 0`, color: v('status-error') },
           requiredIndicator: { color: v('status-error') },
         },
       },
@@ -260,7 +260,7 @@ export default {
       switch: {
         base: {
           root: { gap: v('gap-control'), '--switch-diff': 'calc(var(--switch-width) - var(--switch-height))' },
-          label: { ...text('base-label'), fontSize: v('font-base-label-font-size'), color: v('text-primary'), _disabled: { color: v('text-disabled'), opacity: null } },
+          label: { ...text('label-base'), fontSize: v('font-label-base-font-size'), color: v('text-primary'), _disabled: { color: v('text-disabled'), opacity: null } },
           control: {
             boxSizing: 'border-box',
             alignItems: 'center',
@@ -271,7 +271,7 @@ export default {
             transition: `background-color ${v('duration-normal')} ${v('easing-in-out')}`,
             focusVisibleRing: null,
             _before: {
-              ...text('condense-subtitle-label'),
+              ...text('eyebrow-condense'),
               content: '"off"',
               position: 'absolute',
               insetBlock: 0,
@@ -318,9 +318,9 @@ export default {
       },
       slider: {
         base: {
-          root: { ...text('base'), textStyle: null, gap: v('gauge-gap'), _disabled: { opacity: v('check-opacity-disabled') } },
-          label: { ...text('base-label'), textStyle: null, color: v('gauge-label-color') },
-          valueText: { ...text('base'), color: v('gauge-value-color') },
+          root: { ...text('body-base'), textStyle: null, gap: v('gauge-gap'), _disabled: { opacity: v('check-opacity-disabled') } },
+          label: { ...text('label-base'), textStyle: null, color: v('gauge-label-color') },
+          valueText: { ...text('body-base'), color: v('gauge-value-color') },
           track: { bg: v('gauge-track-color'), borderRadius: v('gauge-radius'), boxShadow: 'none' },
           range: { bg: 'colorPalette.solid', borderRadius: v('gauge-radius') },
           thumb: {
@@ -343,7 +343,7 @@ export default {
         base: {
           list: { borderColor: v('disclosure-divider-color') },
           trigger: {
-            ...text('base'),
+            ...text('body-base'),
             height: 'auto',
             minW: 0,
             padding: `${v('space-2')} ${v('space-4')}`,
@@ -361,7 +361,7 @@ export default {
               list: { display: 'flex', borderColor: v('disclosure-divider-color'), _horizontal: { borderBottomWidth: v('stroke-default') }, _vertical: { borderEndWidth: v('stroke-default') } },
               trigger: {
                 _selected: {
-                  ...text('base-selected'),
+                  ...text('selected-base'),
                   color: v('disclosure-selected-color'),
                   _horizontal: { layerStyle: 'indicator.bottom', '--indicator-offset-y': `calc(${v('stroke-default')} * -1)`, '--indicator-color': v('disclosure-indicator-color'), '--indicator-thickness': v('disclosure-indicator-width') },
                   _vertical: { layerStyle: 'indicator.end', '--indicator-offset-x': `calc(${v('stroke-default')} * -1)`, '--indicator-color': v('disclosure-indicator-color'), '--indicator-thickness': v('disclosure-indicator-width') },
@@ -376,7 +376,7 @@ export default {
           root: { color: v('text-primary') },
           item: { borderBottom: `${v('stroke-default')} solid ${v('disclosure-divider-color')}`, _last: { borderBottom: 'none' } },
           itemTrigger: {
-            ...text('maximize-md'),
+            ...text('title-base'),
             justifyContent: 'space-between',
             gap: v('space-4'),
             padding: `${v('space-4')} ${v('space-6')}`,
@@ -388,7 +388,7 @@ export default {
             _disabled: { opacity: v('disclosure-opacity-disabled'), layerStyle: null },
           },
           itemIndicator: { color: v('disclosure-icon-color') },
-          itemBody: { ...text('base'), padding: `0 ${v('space-6')} ${v('space-4')}`, color: v('disclosure-content-color') },
+          itemBody: { ...text('body-base'), padding: `0 ${v('space-6')} ${v('space-4')}`, color: v('disclosure-content-color') },
         },
         variants: {
           variant: { outline: { item: {} } },
@@ -401,7 +401,7 @@ export default {
           content: { ...popup, minW: v('popup-min-width'), padding: v('popup-padding'), overflow: null },
           item: { ...row, paddingBlock: v('item-padding-block-dense'), '&[data-type]': { ps: null } },
           itemGroupLabel: groupLabel,
-          itemCommand: { ...text('condense'), color: v('text-tertiary'), opacity: null, letterSpacing: null },
+          itemCommand: { ...text('body-condense'), color: v('text-tertiary'), opacity: null, letterSpacing: null },
           itemIndicator: { color: v('item-indicator-color') },
           separator: { ...k.separator, mx: 0, my: null },
           arrow: { '--arrow-background': v('popup-background') },
@@ -424,7 +424,7 @@ export default {
             _placeholderShown: { color: v('field-placeholder-color') },
           },
           indicator: { color: v('text-tertiary') },
-          label: { ...text('base-label'), textStyle: null, color: v('text-primary') },
+          label: { ...text('label-base'), textStyle: null, color: v('text-primary') },
           ...listParts,
         },
         variants: {
@@ -438,9 +438,9 @@ export default {
       combobox: {
         base: {
           input: { ...field, focusVisibleRing: null },
-          label: { ...text('base-label'), textStyle: null, color: v('text-primary') },
+          label: { ...text('label-base'), textStyle: null, color: v('text-primary') },
           trigger: { color: v('text-tertiary') },
-          empty: { ...text('condense'), color: v('text-tertiary'), justifyContent: 'center', paddingBlock: v('popup-empty-padding-block') },
+          empty: { ...text('body-condense'), color: v('text-tertiary'), justifyContent: 'center', paddingBlock: v('popup-empty-padding-block') },
           ...listParts,
         },
         variants: {
@@ -450,16 +450,16 @@ export default {
       },
       popover: {
         base: {
-          content: { ...popup, '--popover-bg': v('popup-background'), textStyle: null, ...text('base') },
-          title: { ...text('maximize-md') },
-          description: { ...text('base'), color: v('text-secondary') },
+          content: { ...popup, '--popover-bg': v('popup-background'), textStyle: null, ...text('body-base') },
+          title: { ...text('title-base') },
+          description: { ...text('body-base'), color: v('text-secondary') },
           arrow: { '--arrow-background': v('popup-background') },
         },
       },
       tooltip: {
         base: {
           content: {
-            ...text('condense'),
+            ...text('body-condense'),
             textStyle: null,
             maxW: v('tooltip-max-width'),
             padding: `${v('space-1-5')} ${v('space-2-5')}`,
@@ -476,12 +476,12 @@ export default {
       dialog: {
         base: {
           backdrop: { bg: v('modal-backdrop') },
-          content: { ...k.modalSurface, bg: null, background: v('modal-background'), textStyle: null, ...text('base'), width: v('modal-width'), maxH: v('modal-max-height') },
+          content: { ...k.modalSurface, bg: null, background: v('modal-background'), textStyle: null, ...text('body-base'), width: v('modal-width'), maxH: v('modal-max-height') },
           header: { padding: 0, gap: v('space-2') },
           body: { padding: 0 },
           footer: { padding: 0, gap: v('modal-actions-gap'), marginTop: v('modal-actions-spacing') },
-          title: { ...text('maximize-xl'), textStyle: null, color: v('modal-title-color') },
-          description: { ...text('base'), color: v('modal-description-color') },
+          title: { ...text('title-amplify'), textStyle: null, color: v('modal-title-color') },
+          description: { ...text('body-base'), color: v('modal-description-color') },
           closeTrigger: { top: v('space-3'), insetEnd: v('space-3') },
         },
         variants: { size: { md: { content: { maxW: v('modal-max-width') } } } },
@@ -489,9 +489,9 @@ export default {
       drawer: {
         base: {
           backdrop: { bg: v('modal-backdrop') },
-          content: { bg: v('modal-background'), color: v('text-primary'), boxShadow: v('modal-shadow'), textStyle: null, ...text('base') },
-          title: { ...text('maximize-xl'), textStyle: null, color: v('modal-title-color') },
-          description: { ...text('base'), color: v('modal-description-color') },
+          content: { bg: v('modal-background'), color: v('text-primary'), boxShadow: v('modal-shadow'), textStyle: null, ...text('body-base') },
+          title: { ...text('title-amplify'), textStyle: null, color: v('modal-title-color') },
+          description: { ...text('body-base'), color: v('modal-description-color') },
           footer: { gap: v('modal-actions-gap') },
         },
       },
@@ -500,7 +500,7 @@ export default {
         base: {
           root: {
             ...k.popupSurface,
-            ...text('base'),
+            ...text('body-base'),
             padding: v('notice-padding'),
             gap: v('notice-gap'),
             '--toast-trigger-bg': v('surface-raised'),
@@ -508,16 +508,16 @@ export default {
               STATUS.filter((s) => scopes[s]).map((s) => [`&[data-type=${s}]`, { colorPalette: s, bg: 'colorPalette.soft', borderColor: 'colorPalette.border', color: 'colorPalette.on-soft' }]),
             ),
           },
-          title: { ...text('maximize-md'), textStyle: null },
-          description: { ...text('base'), textStyle: null, marginTop: v('notice-text-gap'), color: v('notice-description-color'), '[data-type] &': { color: 'inherit' } },
+          title: { ...text('title-base'), textStyle: null },
+          description: { ...text('body-base'), textStyle: null, marginTop: v('notice-text-gap'), color: v('notice-description-color'), '[data-type] &': { color: 'inherit' } },
           closeTrigger: k.iconButton,
         },
       },
       alert: {
         base: {
-          root: { ...text('base'), textStyle: null, padding: v('notice-padding'), gap: v('notice-gap'), borderRadius: v('popup-radius'), borderWidth: v('popup-border-width'), borderStyle: 'solid', borderColor: 'transparent' },
-          title: { ...text('maximize-md') },
-          description: { ...text('base'), marginTop: v('notice-text-gap') },
+          root: { ...text('body-base'), textStyle: null, padding: v('notice-padding'), gap: v('notice-gap'), borderRadius: v('popup-radius'), borderWidth: v('popup-border-width'), borderStyle: 'solid', borderColor: 'transparent' },
+          title: { ...text('title-base') },
+          description: { ...text('body-base'), marginTop: v('notice-text-gap') },
           indicator: { color: 'inherit' },
         },
         variants: {
@@ -534,8 +534,8 @@ export default {
       progress: {
         base: {
           root: { gap: v('gauge-gap') },
-          label: { ...text('base-label'), textStyle: null, color: v('gauge-label-color') },
-          valueText: { ...text('base'), textStyle: null, color: v('gauge-value-color') },
+          label: { ...text('label-base'), textStyle: null, color: v('gauge-label-color') },
+          valueText: { ...text('body-base'), textStyle: null, color: v('gauge-value-color') },
           track: { bg: v('gauge-track-color'), borderRadius: v('gauge-radius') },
           range: { bg: 'colorPalette.solid', borderRadius: v('gauge-radius'), transition: v('gauge-transition') },
         },
@@ -546,7 +546,7 @@ export default {
       },
       avatar: {
         base: {
-          root: { ...text('maximize-md'), boxSizing: 'border-box', border: `${v('stroke-emphasis')} solid ${v('surface-canvas')}`, boxShadow: v('elevation-sm'), textTransform: 'uppercase' },
+          root: { ...text('title-base'), boxSizing: 'border-box', border: `${v('stroke-emphasis')} solid ${v('surface-canvas')}`, boxShadow: v('elevation-sm'), textTransform: 'uppercase' },
         },
         variants: {
           variant: Object.fromEntries(['solid', 'subtle', 'outline'].map((s) => [s, { root: { bg: 'colorPalette.solid', color: 'colorPalette.on-solid' } }])),
@@ -555,8 +555,8 @@ export default {
       },
       table: {
         base: {
-          root: { ...text('condense'), textStyle: null, color: v('table-color') },
-          columnHeader: { ...text('base-label'), bg: v('table-header-background'), color: v('table-header-color'), borderColor: v('table-row-border-color') },
+          root: { ...text('body-condense'), textStyle: null, color: v('table-color') },
+          columnHeader: { ...text('label-base'), bg: v('table-header-background'), color: v('table-header-color'), borderColor: v('table-row-border-color') },
           cell: { borderColor: v('table-row-border-color'), paddingInline: v('table-cell-padding-inline') },
           row: { '&[data-selected]': { bg: v('table-row-selected') } },
         },
@@ -567,7 +567,7 @@ export default {
 
     const config = {
       // Dark follows data-theme, the attribute tokens.css (and Base UI's stories) use.
-      conditions: { light: ':root &, .light &, [data-theme=light] &', dark: '.dark &, [data-theme=dark] &' },
+      conditions: { light: ':root &, .light &, [data-theme=light] &', dark: '.dark &, [data-theme=dark] &, [data-theme=dark-high-contrast] &' },
       globalCss: { html: { colorPalette: 'accent' } },
       theme: {
         tokens: {

package/exporters/component-styles.mjs

@@ -69,7 +69,7 @@ export function styleKit(prefix, roles) {
   const control = (size, { trigger = false } = {}) => {
     const s = SIZES[size];
     return {
-      ...text(trigger ? `${s.text}-trigger` : s.text),
+      ...text(trigger ? `trigger-${s.text}` : `body-${s.text}`),
       height: v(`control-height${s.suffix || '-md'}`),
       paddingInline: v(`control-padding-inline${s.suffix}`),
       gap: v(size === 'xs' ? 'gap-control-xs' : size === 'sm' ? 'gap-control-sm' : 'gap-control'),
@@ -107,7 +107,7 @@ export function styleKit(prefix, roles) {
   };
 
   const itemRow = {
-    ...text('base'),
+    ...text('body-base'),
     display: 'flex',
     alignItems: 'center',
     gap: v('item-gap'),
@@ -120,11 +120,11 @@ export function styleKit(prefix, roles) {
   };
   const itemStates = {
     hover: { background: v('item-background-hover'), color: v('item-color-hover') },
-    selected: { ...text('base-selected'), background: v('item-background-selected'), color: v('item-color-selected') },
+    selected: { ...text('selected-base'), background: v('item-background-selected'), color: v('item-color-selected') },
     disabled: { color: v('item-color-disabled'), opacity: v('item-opacity-disabled') },
   };
   const groupLabel = {
-    ...text('condense-subtitle-label'),
+    ...text('eyebrow-condense'),
     paddingBlock: `${v('popup-group-label-padding-top')} ${v('popup-group-label-padding-bottom')}`,
     paddingInline: v('item-padding-inline'),
     color: v('text-secondary'),

package/exporters/design-system.mjs

@@ -97,8 +97,8 @@ export default {
     // ------------------------------------------------------------------------------- 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 tierOf = (style) => style.split('-').pop();
+    const TIERS = ['minimize', 'condense', 'base', 'magnify', 'amplify', 'maximize'];
     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;
@@ -256,6 +256,12 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
     '',
     `\`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">\`.`,
     '',
+    '### Statuses',
+    '',
+    `\`data-status="info|success|warning|error"\` on any element gives every emphasis level inside it that status's version, so a subtle warning banner is \`<div data-status="warning" data-emphasis="subtle">\`. A level is the level's style in the status's palette unless the brand picked a pair for it:`,
+    '',
+    ...Object.entries(roles.status ?? {}).flatMap(([status, picks]) => Object.entries(picks).map(([level, pair]) => `- ${level} in ${status}: the \`${pair}\` pair`)),
+    ...(Object.keys(roles.status ?? {}).length ? [''] : ['(This brand picks none, so every level is automatic.)', '']),
   );
   const pairs = Object.entries(brand?.color?.pairs ?? {});
   if (pairs.length) {
@@ -284,16 +290,16 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
     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.',
+    amplify: 'titles of dialogs, drawers and page sections.',
+    maximize: 'the page head.',
   };
   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(', ')}.` : ''}`);
+    const variants = styleNames.filter((s) => s.endsWith(`-${tier}`)).map((s) => s.slice(0, -tier.length - 1));
+    out.push(`- **${tier}**: ${tierWhy[tier] ?? ''}${variants.length ? ` Roles: ${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.',
+    'Names are role first, then tier: `body-` for running text, `trigger-` for buttons and triggers, `selected-` for the current tab, toggle or nav item, `link-` for links, `subtitle-` for subheads, `label-` for form labels, `eyebrow-` for small uppercase labels, `title-` for titles in the display family, `code-` for code in the mono family. Sizes below the base are fixed; the base and up grow with the viewport.',
     '',
     '## Space, shape and depth',
     '',
@@ -309,17 +315,75 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
     '',
     '## 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.`,
+    `Themes: \`data-theme="light|dark|light-high-contrast|dark-high-contrast"\` on the root, or the system setting (including \`prefers-contrast: more\`) when none is set. Color vision themes are themes of their own, each a light theme designed from this brand: \`data-theme="deuteranopia|protanopia|tritanopia|achromatopsia"\`. Never hand-pick dark colors; the tokens already flip.`,
     '',
   );
   if (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\`). In previews and designs they are \`window.Loomiere.<Name>\`; Button, Input, Field, Fieldset, Form and NavigationMenu are wrappers that put their classes on themselves.`,
+      `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', '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. For a small, frequent action shown as an icon alone (calendar arrows, row actions), use a quiet neutral icon-only Button: `<Loomiere.Button emphasis="quiet" palette="neutral" data-size="xs" aria-label="Next month">` with one icon inside.'],
+        ['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`;
@@ -384,7 +448,7 @@ function cover({ theme, brand, title }) {
 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.
+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-body-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.