@scattered-light/loomiere 0.3.0 → 0.4.1

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,7 +315,7 @@ 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) {
@@ -332,7 +338,7 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
       '',
       '`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.`,
+      `- **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.',
@@ -344,8 +350,7 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
       '| 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.'],
+        ['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.'],
@@ -443,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.