@scattered-light/loomiere 0.5.3 → 0.7.0

package/build/build-tokens.mjs

@@ -121,12 +121,30 @@ function visionBlocks(dictionary) {
 // Each component that paints with emphasis starts at a level of its own; data-emphasis on it, or
 // on a group around a toggle, picks another. Button's data-variant names are aliases for levels,
 // so the brand's roles drive every button; a button with neither is bold.
+//
+// Pinned entries keep that level's own color. A parent data-color does not recolor them; the
+// element has to set data-color itself. followsScope entries inherit a parent data-color, so a
+// section can tint them. Badge stays pinned (chrome subtle). EmptyState media follows the scope.
 const DEFAULT_LEVELS = {
-  bold: [".Button[data-variant='solid']:not([data-emphasis])", '.Button:not([data-variant]):not([data-emphasis])', '.AvatarRoot:not([data-emphasis])'],
-  standard: [".Button[data-variant='outline']:not([data-emphasis])", '.Toggle:not([data-emphasis], [data-emphasis] *)'],
-  quiet: [".Button[data-variant='ghost']:not([data-emphasis])"],
+  bold: [
+    { selector: ".Button[data-variant='solid']:not([data-emphasis])" },
+    { selector: '.Button:not([data-variant]):not([data-emphasis])' },
+    { selector: '.AvatarRoot:not([data-emphasis])' },
+    { selector: '.CalendarDay[data-selected]:not([data-emphasis])' },
+  ],
+  standard: [
+    { selector: ".Button[data-variant='outline']:not([data-emphasis])" },
+    { selector: '.Toggle:not([data-emphasis], [data-emphasis] *)' },
+  ],
+  subtle: [
+    { selector: '.Badge:not([data-emphasis])' },
+    { selector: '.EmptyStateMedia:not([data-emphasis])', followsScope: true },
+  ],
+  quiet: [{ selector: ".Button[data-variant='ghost']:not([data-emphasis])" }],
 };
 
+const levelSelectors = (level) => [`[data-emphasis='${level}']`, ...(DEFAULT_LEVELS[level] ?? []).map((entry) => entry.selector)];
+
 // A toast's type (toastManager.add({ type: 'success' })) is its status, so success, warning,
 // error and info toasts tint themselves. data-color or data-status wins when one is set.
 const TOAST_TYPES = ['success', 'warning', 'error', 'info'];
@@ -167,7 +185,7 @@ function roleBlocks(dictionary) {
 
   // Every level's style, read from whatever scope is in effect: a status's palette, data-color's, or the accent.
   for (const [level, parts] of statuses.get('default') ?? []) {
-    const selectors = [`[data-emphasis='${level}']`, ...(DEFAULT_LEVELS[level] ?? [])];
+    const selectors = levelSelectors(level);
     const style = STYLES[roles.emphasis[level].style];
     blocks.push(rule(selectors, paint(parts.map(([part]) => [part, style[part] === 'transparent' ? 'transparent' : `{scope.any.${style[part]}}`]))));
     // Default status: the pair the brand picked, or the level's own color. Accent levels follow
@@ -178,14 +196,23 @@ function roleBlocks(dictionary) {
       continue;
     }
     const color = parts.map(([, v]) => v.match(/^\{scope\.([^.]+)\./)?.[1]).find(Boolean);
-    if (color && color !== 'accent') blocks.push(rule(selectors.map((sel) => `${sel}:not([data-color], ${IN_STATUS})`), point(color)));
+    if (color && color !== 'accent') {
+      blocks.push(rule(selectors.map((sel) => {
+        // The pin sits on the element, so a parent data-color would not reach it.
+        // followsScope also skips the pin when an ancestor has data-color, so the
+        // section's scope recolors that element. Badge stays pinned.
+        const follows = (DEFAULT_LEVELS[level] ?? []).some((entry) => entry.followsScope && entry.selector === sel);
+        const except = follows ? `[data-color], [data-color] *, ${IN_STATUS}` : `[data-color], ${IN_STATUS}`;
+        return `${sel}:not(${except})`;
+      }), point(color)));
+    }
   }
   // Other statuses: the scope already holds the status's palette; only a picked pair needs its own rule.
   for (const [name, levels] of statuses) {
     if (name === 'default') continue;
     for (const [level, parts] of levels) {
       if (!pairOf(parts)) continue;
-      const selectors = `:is(${[`[data-emphasis='${level}']`, ...(DEFAULT_LEVELS[level] ?? [])].join(', ')})`;
+      const selectors = `:is(${levelSelectors(level).join(', ')})`;
       blocks.push(rule(statusSelectors(name).flatMap((s) => [`${s} ${selectors}`, `${s}${selectors}`]), paint(parts)));
     }
   }

package/exporters/chakra.mjs

@@ -14,6 +14,9 @@ import { styleKit, toSource } from './component-styles.mjs';
 const TIER = { '2xs': 'xs', xs: 'xs', sm: 'sm', md: 'md', lg: 'lg', xl: 'lg', '2xl': 'lg' };
 /** Button variant → emphasis level, as data-variant does for the Base UI Button. */
 const VARIANT_LEVEL = { solid: 'bold', outline: 'standard', subtle: 'subtle', surface: 'subtle', ghost: 'quiet', plain: 'quiet' };
+/** Chakra badge variants. Filled-looking ones are subtle, the Badge default; there is no hover. */
+const BADGE_LEVEL = { solid: 'bold', subtle: 'subtle', surface: 'subtle', outline: 'standard', plain: 'quiet' };
+const BADGE_SIZE = { xs: 'minimize', sm: 'condense', md: 'base', lg: 'base' };
 /** Chakra's own color-palette keys → scope slots, so Chakra components we leave alone still fit. */
 const CHAKRA_SLOTS = { contrast: 'on-solid', subtle: 'soft', muted: 'soft-hover', emphasized: 'soft-active', focusRing: 'focus' };
 const STATUS = ['info', 'warning', 'success', 'error'];
@@ -163,6 +166,36 @@ export default {
 
     const statusPalette = (s) => (scopes[s] ? s : 'chrome');
 
+    // Colors stay on colorPalette so colorPalette= recolors a badge. Sizes and type come from badge().
+    const chakraBadge = (level, tier = 'condense') => {
+      const b = k.badge(level, undefined, tier);
+      const { style, color } = roles.emphasis[level];
+      const slots = STYLES[style];
+      const slot = (part) => (slots[part] === 'transparent' ? 'transparent' : `colorPalette.${slots[part]}`);
+      return {
+        colorPalette: color,
+        display: 'inline-flex',
+        alignItems: 'center',
+        whiteSpace: 'nowrap',
+        bg: slot('bg'),
+        color: slot('fg'),
+        borderColor: slot('border'),
+        borderWidth: b.borderWidth,
+        borderStyle: 'solid',
+        borderRadius: b.borderRadius,
+        height: b.height,
+        minH: b.height,
+        minW: b.minWidth,
+        px: b.paddingInline,
+        gap: b.gap,
+        fontFamily: b.fontFamily,
+        fontSize: b.fontSize,
+        fontWeight: b.fontWeight,
+        lineHeight: b.lineHeight,
+        letterSpacing: b.letterSpacing,
+      };
+    };
+
     const recipes = {
       button: {
         base: {
@@ -184,6 +217,28 @@ export default {
           size: sizes(['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'], (tier) => ({ ...control(tier, { trigger: true }), _icon: { width: k.iconSize(tier), height: k.iconSize(tier) } })),
         },
       },
+      badge: {
+        base: chakraBadge('subtle', 'condense'),
+        variants: {
+          variant: Object.fromEntries(Object.entries(BADGE_LEVEL).map(([variant, level]) => [variant, chakraBadge(level)])),
+          // Size only: a full badge() here would paint over the variant's colors.
+          size: Object.fromEntries(Object.entries(BADGE_SIZE).map(([size, tier]) => {
+            const b = chakraBadge('subtle', tier);
+            return [size, {
+              height: b.height,
+              minH: b.minH,
+              minW: b.minW,
+              px: b.px,
+              gap: b.gap,
+              fontFamily: b.fontFamily,
+              fontSize: b.fontSize,
+              fontWeight: b.fontWeight,
+              lineHeight: b.lineHeight,
+              letterSpacing: b.letterSpacing,
+            }];
+          })),
+        },
+      },
       input: {
         base: { ...field, height: v('control-height-md'), minW: 0 },
         variants: { size: sizes(['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'], fieldSize), variant: { outline: {} } },
@@ -200,6 +255,23 @@ export default {
     const checked = '&:is([data-state=checked], [data-state=indeterminate])';
 
     const slotRecipes = {
+      emptyState: {
+        base: {
+          root: { width: '100%', color: v('text-primary'), textAlign: 'center' },
+          content: { display: 'flex', alignItems: 'center', justifyContent: 'center' },
+          indicator: { display: 'flex', alignItems: 'center', justifyContent: 'center' },
+          title: { margin: 0 },
+          description: { margin: 0 },
+        },
+        variants: {
+          size: {
+            sm: k.emptyStateSize('sm'),
+            md: k.emptyStateSize('md'),
+            lg: k.emptyStateSize('lg'),
+          },
+        },
+      },
+
       field: {
         base: {
           root: { gap: v('field-gap') },
@@ -593,6 +665,8 @@ export default {
  * Every palette, plus "accent" and "chrome", works as a colorPalette. Button variants are
  * the brand's emphasis levels (solid = bold, outline = standard, subtle = subtle,
  * ghost = quiet); each keeps its own color unless you pass colorPalette.
+ * Badge uses the same levels (solid = bold, outline = standard, subtle and surface = subtle,
+ * plain = quiet) and does not change on hover.
  * To add your own config on top: createSystem(config, yours).
  */
 import { createSystem, defaultConfig, mergeConfigs } from '@chakra-ui/react';

package/exporters/component-styles.mjs

@@ -149,6 +149,68 @@ export function styleKit(prefix, roles) {
     disabled: { opacity: v('check-opacity-disabled') },
   };
 
+  /**
+   * A badge at one emphasis level. Colors are the level's rest state.
+   * Min width equals the height, so a single digit is a circle and a wider label is unchanged.
+   * `tier` is minimize, condense (the default) or base.
+   */
+  const BADGE_TIER = {
+    minimize: { height: 'badge-height-minimize', pad: 'badge-padding-inline-minimize', gap: 'badge-gap-minimize', text: 'trigger-minimize' },
+    condense: { height: 'badge-height-condense', pad: 'badge-padding-inline-condense', gap: 'badge-gap-condense', text: 'trigger-condense' },
+    base: { height: 'badge-height-base', pad: 'badge-padding-inline-base', gap: 'badge-gap-base', text: 'trigger-base' },
+  };
+  const badge = (level, palette, tier = 'condense') => {
+    const e = emphasis(level, palette);
+    const s = BADGE_TIER[tier];
+    return {
+      ...text(s.text),
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      gap: v(s.gap),
+      height: v(s.height),
+      minWidth: v(s.height),
+      paddingInline: v(s.pad),
+      borderRadius: v('radius-pill'),
+      borderWidth: v('stroke-default'),
+      borderStyle: 'solid',
+      background: e.bg,
+      color: e.fg,
+      borderColor: e.border,
+      whiteSpace: 'nowrap',
+    };
+  };
+
+  /**
+   * Chakra's emptyState slots, in Loomiere sizes. sm is compact (icon, no circle),
+   * md is standard, lg is spacious. The circle is the subtle emphasis level, the
+   * same helper Badge uses, so a brand that points subtle at the accent is followed.
+   * text-gap has no slot of its own: title and description share the content gap.
+   * textStyle: null clears Chakra's own textStyle (description base is "sm", and each
+   * size variant sets one on the title). The variant slot is replaced wholesale, so
+   * the null is what drops that textStyle. fontWeight stays: subtitle and title styles are bold.
+   */
+  const EMPTY_SIZE = {
+    sm: { block: 'empty-padding-block-compact', inline: 'empty-padding-inline-compact', gap: 'empty-gap-compact', title: 'subtitle-condense', description: 'body-condense', icon: 'icon-size-condense', circle: null },
+    md: { block: 'empty-padding-block-standard', inline: 'empty-padding-inline-standard', gap: 'empty-gap-standard', title: 'title-condense', description: 'body-base', icon: 'icon-size-magnify', circle: 'empty-media-size-standard' },
+    lg: { block: 'empty-padding-block-spacious', inline: 'empty-padding-inline-spacious', gap: 'empty-gap-spacious', title: 'title-magnify', description: 'body-base', icon: 'icon-size-maximize', circle: 'empty-media-size-spacious' },
+  };
+  const emptyStateSize = (size) => {
+    const s = EMPTY_SIZE[size];
+    const tone = emphasis('subtle');
+    const circle = s.circle
+      ? { width: v(s.circle), height: v(s.circle), background: tone.bg, color: tone.fg, borderRadius: v('radius-pill') }
+      : { width: 'auto', height: 'auto', background: 'transparent', color: tone.fg, borderRadius: 0 };
+    return {
+      root: { px: v(s.inline), py: v(s.block) },
+      content: { gap: v(s.gap), flexDirection: s.circle ? 'column' : 'row' },
+      // Circle size is width and height. The icon is fontSize, which Chakra's indicator textStyle would otherwise set.
+      title: { ...text(s.title), textStyle: null, color: v('text-primary') },
+      description: { ...text(s.description), textStyle: null, color: v('text-secondary'), maxWidth: v('empty-description-max-width') },
+      indicator: { ...circle, fontSize: v(s.icon), textStyle: null },
+    };
+  };
+
   const iconButton = {
     width: v('icon-button-size'),
     height: v('icon-button-size'),
@@ -164,6 +226,8 @@ export function styleKit(prefix, roles) {
     text,
     scope,
     emphasis,
+    badge,
+    emptyStateSize,
     levels: LEVELS,
     focusRing,
     focusRingInset,

package/exporters/design-system.mjs

@@ -345,8 +345,8 @@ 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', '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.',
+      `- **Wrappers** put their own classes on, so use them bare: ${['Button', 'Input', 'Field', 'Fieldset', 'Form', 'NavigationMenu', 'Select', 'NumberField', 'OTPField', 'Autocomplete', 'Combobox', 'Checkbox', 'Radio', 'CheckboxGroup', 'Toggle', 'ToggleGroup', 'Dialog', 'AlertDialog', 'Meter', 'Progress', 'Slider', 'Menu', 'ContextMenu', 'Menubar', 'Popover', 'PreviewCard', 'Tooltip', 'Drawer', 'Accordion', 'Collapsible', 'Tabs', 'Switch', 'Toast', 'Avatar', 'Toolbar', 'ScrollArea', 'Separator', 'Badge', 'DatePicker', 'MoneyField', 'Splitter', 'ListDetail', 'EmptyState', 'DataTable', 'DataList', 'CollectionToolbar', 'CollectionPagination', 'EditableList'].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\`). Wrapped parts that are buttons (\`Dialog.Trigger\`, \`Menu.Trigger\`, \`Toolbar.Button\`, \`Drawer.Close\`...) take the same \`emphasis\` and \`palette\` props and draw square the same way. \`Popover.Trigger\`, \`Tooltip.Trigger\`, \`Select.Trigger\` and \`Dialog.Close\` become Buttons only when they set \`emphasis\`, \`palette\` or \`className="Button"\`. A plain \`.Button\` on a bare part is drawn square when it has an \`aria-label\` and a single icon inside, or when you set \`data-icon-only\` on it. \`Loomiere.Badge\` takes the same \`emphasis\` and \`palette\` props, plus \`status\`, \`size\` and \`dot\`.`,
+      '- **Table, Badge, DatePicker, MoneyField, Splitter, ListDetail, EmptyState, DataTable, DataList, CollectionToolbar, CollectionPagination and EditableList are Loomiere components**, not Base UI parts. Table is plain HTML for a static table or a report: use the classes in its stylesheet. Badge is `Loomiere.Badge`. DatePicker is `Loomiere.DatePicker`; `Loomiere.Calendar` is the month grid on its own and `Loomiere.DatePresets` is the quick-selection list. MoneyField is `Loomiere.MoneyField`: an amount of money, stored as minor units. Splitter is `Loomiere.Splitter`. ListDetail is `Loomiere.ListDetail`. EmptyState is `Loomiere.EmptyState`. DataTable, DataList, CollectionToolbar and CollectionPagination come from `@scattered-light/loomiere-base-ui/custom/collection` and need `@tanstack/react-table` installed. EditableList comes from the package root or `./custom`.',
       '',
       '`Loomiere.Base` holds the bare Base UI parts for the wrappers too (`Loomiere.Base.Button`), for when you need the part without its classes.',
       '',
@@ -357,18 +357,19 @@ 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. 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.'],
+        ['Button', 'Run one action. Set its emphasis by how much the action matters. For a small, frequent action shown as an icon alone (the month arrows inside DatePicker, 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).'],
+        ['ToggleGroup', 'Switch between 2 to 5 short modes or views that apply at once (List / Grid). Picking a date or a period is DatePicker, not a toggle.'],
         ['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.'],
+        ['NumberField', 'Enter an exact number, with steppers. For an amount of money, use MoneyField.'],
+        ['MoneyField', 'Enter an amount of money in one or more currencies. Use NumberField for plain quantities and percentages.'],
         ['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.'],
@@ -382,14 +383,29 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
         ['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.'],
+        ['Splitter', 'Let people resize side-by-side or stacked areas, like a sidebar or a documents column.'],
+        ['ListDetail', 'Show the details of one item next to its list, falling back to a drawer or a page on narrow screens. Use Dialog when the detail must block the list.'],
         ['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.'],
+        ['Badge', 'Label a status or a count next to something else. Not clickable; use Button or Toggle for that.'],
+        ['DatePicker', 'Pick a date or a period, with quick selections. Use Input type=date only when you can\'t load React. Calendar is the grid on its own; DatePresets is the list of quick selections.'],
+        ['EmptyState', 'Show that a list, table or page has nothing in it yet, nothing matches, failed to load, or is all done. Pick the kind; write your own copy.'],
+        ['DataList', 'A list people work through: a review queue, inbox, search results. Default for narrow panes.'],
+        ['DataTable', 'Rows people compare across several columns. Use the plain Table for static tables and reports.'],
+        ['EditableList', 'Repeating form rows people add, edit and remove: line items, allocations.'],
+        ['CollectionToolbar', 'Search, tabs, filters and the selection bar for a DataTable or a DataList.'],
+        ['CollectionPagination', 'Which page of a long list you are on. It also works without a collection.'],
+        ['EmptyState', 'Don\'t use it for a message about something that just happened (use Toast) or a warning above content that still shows (use a notice or an inline alert).'],
         ['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.`,
+      `A date or a period, including the quick selections beside the calendar, is DatePicker. Any other list of choices that stays on screen inside a panel, one of them selected (saved filters, views), 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.`,
+      '',
+      'An empty state\'s title says what is empty in plain words ("No invoices yet"). The description says why, or what to do next, in one sentence. The action is a verb ("Create invoice", "Clear filters"). The first action is the main one: bold when the person is creating the first thing, standard everywhere else, and a secondary action quiet. Error and no-access stay straight: no jokes.',
+      '',
+      'Use AG Grid only for spreadsheet work (cell-by-cell editing, ranges, tens of thousands of rows). A screen that is a list people work through uses DataList or DataTable, and the code should say why if it reaches for the grid.',
       '',
     );
   }
@@ -456,7 +472,7 @@ 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-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` : ''}
+${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). Collection (\`DataTable\`, \`DataList\`, \`CollectionToolbar\`, \`CollectionPagination\`) is imported from \`@scattered-light/loomiere-base-ui/custom/collection\`, and the app installs \`@tanstack/react-table\`. \`EditableList\` comes from \`@scattered-light/loomiere-base-ui/custom\`. Use AG Grid only for spreadsheet work (cell-by-cell editing, ranges, tens of thousands of rows); say why in the code. \`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/mui.mjs

@@ -135,6 +135,66 @@ export default {
         },
       },
 
+      MuiChip: {
+        styleOverrides: {
+          root: {
+            // Filled is subtle, Badge's default (a soft label). Outlined is the standard level.
+            // Chip has no minimize size: small is condense, medium is base.
+            // A clickable or deletable Chip keeps the level's hover and active colors, and the shared focus ring.
+            ...k.badge('subtle'),
+            '& .MuiChip-icon': { color: 'inherit', margin: 0 },
+            '& .MuiChip-label': { padding: 0 },
+            '&.MuiChip-clickable, &.MuiChip-deletable': {
+              '&:hover': { background: v('e-bg-hover') },
+              '&:active': { background: v('e-bg-active') },
+              '&.Mui-focusVisible': k.focusRing,
+            },
+            variants: [
+              ...['filled', 'outlined'].flatMap((variant) =>
+                Object.entries({ default: undefined, ...COLOR_SCOPE }).map(([c, palette]) => {
+                  const level = variant === 'outlined' ? 'standard' : 'subtle';
+                  const e = k.emphasis(level, palette);
+                  return {
+                    props: { variant, color: c },
+                    style: {
+                      ...k.badge(level, palette),
+                      // Same slots as --sl-e-bg-hover and --sl-e-bg-active, in this chip's palette.
+                      '&.MuiChip-clickable, &.MuiChip-deletable': {
+                        '&:hover': { background: e['bg-hover'] },
+                        '&:active': { background: e['bg-active'] },
+                        '&.Mui-focusVisible': k.focusRing,
+                      },
+                    },
+                  };
+                }),
+              ),
+              ...[
+                ['small', 'condense'],
+                ['medium', 'base'],
+              ].map(([size, tier]) => {
+                const b = k.badge('subtle', undefined, tier);
+                const icon = v(`icon-size-${tier === 'base' ? 'base' : 'condense'}`);
+                return {
+                  props: { size },
+                  style: {
+                    height: b.height,
+                    minWidth: b.height,
+                    paddingInline: b.paddingInline,
+                    gap: b.gap,
+                    fontFamily: b.fontFamily,
+                    fontSize: b.fontSize,
+                    fontWeight: b.fontWeight,
+                    lineHeight: b.lineHeight,
+                    letterSpacing: b.letterSpacing,
+                    '& .MuiChip-icon': { width: icon, height: icon },
+                  },
+                };
+              }),
+            ],
+          },
+        },
+      },
+
       MuiIconButton: {
         styleOverrides: {
           root: {

package/figma/library/pages/18-custom/01-custom.js

@@ -0,0 +1,57 @@
+// Custom: Badge. Color comes from the Emphasis and Status modes on an instance, the way Button does, not from variants.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var C = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'compHelpers'))(figma);
+var V = C.V, COL = C.COL, v = C.v, fill = C.fill, stroke = C.stroke, bind = C.bind, radius = C.radius, add = C.add, T = C.T, mode = C.mode, page = C.page;
+var icon = C.icon, comp = C.comp, textProp = C.textProp, place = C.place, removeOld = C.removeOld;
+await page('Custom');
+var PLUS = 'M 8 3 L 8 13 M 3 8 L 13 8';
+function num(k) { var x = v(k); var m = COL[k.split(':')[0]].modes[0].modeId, val = x.valuesByMode[m]; while (val && val.type === 'VARIABLE_ALIAS') { var t = Object.values(V).find(function (y) { return y.id === val.id; }); val = t.valuesByMode[Object.keys(t.valuesByMode)[0]]; } return val; }
+function frameSet(set) { fill(set, 'Theme:surface/canvas'); set.strokes = [{ type: 'SOLID', color: { r: 0.592, g: 0.278, b: 1 } }]; set.dashPattern = [6, 4]; set.strokeWeight = 1; set.cornerRadius = 8; set.clipsContent = false; }
+function grid(set, cols, colW, rowH) {
+  set.layoutMode = 'NONE';
+  set.children.forEach(function (c, i) { c.x = 24 + (i % cols) * colW; c.y = 24 + Math.floor(i / cols) * rowH; });
+  frameSet(set);
+  set.resize(24 + cols * colW, 24 + Math.ceil(set.children.length / cols) * rowH);
+}
+
+// Rows are sizes; columns are none, a dot, and an icon. Every one carries a label.
+var SIZES = [['Minimize', 'minimize'], ['Condense', 'condense'], ['Base', 'base']];
+var MARKS = ['None', 'Dot', 'Icon'];
+removeOld('Badge');
+var comps = [];
+for (var s = 0; s < SIZES.length; s++) for (var m = 0; m < MARKS.length; m++) {
+  var sizeName = SIZES[s][0], tier = SIZES[s][1], mark = MARKS[m];
+  var c = comp('Size=' + sizeName + ', Mark=' + mark);
+  c.primaryAxisAlignItems = 'CENTER'; c.counterAxisAlignItems = 'CENTER';
+  mode(c, 'Emphasis', 'Subtle');
+  fill(c, 'Emphasis:emphasis/bg');
+  stroke(c, 'Emphasis:emphasis/border', 'Size:stroke/default'); c.strokeAlign = 'INSIDE';
+  radius(c, 'Size:radius/pill');
+  bind(c, ['paddingLeft', 'paddingRight'], 'Size:badge/padding-inline-' + tier);
+  bind(c, 'itemSpacing', 'Size:badge/gap-' + tier);
+  if (mark === 'Dot') {
+    var d = figma.createEllipse(); d.name = 'Dot';
+    var dot = num('Size:badge/dot-' + tier); d.resize(dot, dot);
+    bind(d, ['width', 'height'], 'Size:badge/dot-' + tier);
+    fill(d, 'Emphasis:emphasis/fg');
+    add(c, [d]);
+  }
+  if (mark === 'Icon') {
+    var ic = icon('Icon', PLUS, num('Size:icon-size/' + tier), 'Emphasis:emphasis/fg');
+    bind(ic, ['width', 'height'], 'Size:icon-size/' + tier);
+    add(c, [ic]);
+  }
+  var lab = await T('Label', 'trigger-' + tier, 'Emphasis:emphasis/fg'); lab.name = 'Label';
+  add(c, [lab]);
+  c.counterAxisSizingMode = 'FIXED';
+  c.resize(c.width, num('Size:badge/height-' + tier));
+  bind(c, 'height', 'Size:badge/height-' + tier);
+  bind(c, 'minWidth', 'Size:badge/height-' + tier);
+  c.clipsContent = true;
+  comps.push(c);
+}
+var set = figma.combineAsVariants(comps, figma.currentPage); set.name = 'Badge';
+grid(set, MARKS.length, 160, 64);
+textProp(set, 'Label', 'Label', 'Label');
+set.description = 'A status or count label. Not clickable. Size and Mark (none, a dot, or an icon) are the variants. Color comes from the Emphasis mode (Subtle unless you change it) and the Status mode on the instance. Min width equals the height, so a single digit is a circle.';
+place(set);

package/figma/library/pages/18-custom/02-labels.js

@@ -0,0 +1,7 @@
+// Custom: a header for the Badge set. Run after 01.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var C = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'compHelpers'))(figma);
+await C.page('Custom');
+return await C.labelSets({
+  Badge: 'A status or count label. Not clickable. Subtle emphasis unless the Emphasis mode says otherwise; Status recolors it. Min width equals the height, so a single digit is a circle.',
+});

package/figma/library/pages/18-custom/03-doc.js

@@ -0,0 +1,28 @@
+// Custom doc frame. Run after 01 and 02.
+var AF = Object.getPrototypeOf(async function () {}).constructor;
+var K = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'docHelpers'))(figma);
+await K.page('Custom');
+var L = await new AF('figma', figma.root.getSharedPluginData('loomiere', 'docKit'))(figma);
+var AL = L.AL, add = L.add, T = L.T, mode = L.mode, docFrame = L.docFrame, section = L.section, hrow = L.hrow, divider = L.divider;
+var inst = L.inst, notes = L.notes, captioned = L.captioned, usage = L.usage, stage = L.stage;
+function B(size, mark) { return inst('Badge', 'Size=' + size + ', Mark=' + (mark || 'None')); }
+
+var doc = await docFrame('Custom', 'COMPONENTS', 'Custom', 'Components Base UI does not have, built from the same concepts as the rest of the library. Badge labels a status or a count beside something else. It is not clickable: use Button or Toggle for that. Components sit to the right.');
+doc.x = 0; doc.y = 400;
+
+var pick = await section(doc, 'Choosing', 'Start from whether the person can press it.');
+var picks = [['Name a status beside something else', 'Badge', 'Saved, Pending, 3. Subtle by default.'], ['Run an action', 'Button', 'A badge never takes a click.'], ['Stay pressed', 'Toggle', 'A badge does not hold a state.']];
+var pt = AL('VERTICAL', { name: 'Picker' }); add(pick, [pt]); pt.layoutSizingHorizontal = 'FILL';
+for (var i = 0; i < picks.length; i++) { var r = hrow(pt); divider(r); add(r, [await T(picks[i][0], 'body-base', 'Theme:text/primary', 380), await T(picks[i][1], 'subtitle-base', 'Theme:text/accent', 200), await T(picks[i][2], 'body-condense', 'Theme:text/secondary', 520)]); }
+
+var look = await section(doc, 'Badge', 'Three sizes and an optional dot or icon. Color is the Emphasis and Status modes on the instance, not a variant. Subtle is the default.');
+var s1 = stage(look, 'Sizes and marks');
+for (var z of ['Minimize', 'Condense', 'Base']) add(s1, [await captioned(B(z, 'None'), z)]);
+add(s1, [await captioned(B('Condense', 'Dot'), 'Dot'), await captioned(B('Condense', 'Icon'), 'Icon')]);
+var s2 = stage(look, 'Emphasis');
+for (var em of ['Bold', 'Standard', 'Subtle', 'Quiet']) { var a = B('Condense', 'None'); mode(a, 'Emphasis', em); add(s2, [await captioned(a, em)]); }
+var s3 = stage(look, 'Status');
+for (var st of ['Default', 'Info', 'Success', 'Warning', 'Error']) { var b = B('Condense', 'Dot'); mode(b, 'Status', st); add(s3, [await captioned(b, st)]); }
+await usage(look, ['A status next to a title, a row, or a count of unread items.', 'Error and Warning when the word says what is wrong, not color alone.', 'A number on its own when the count is the whole message.'], ['Anything the person clicks. Use Button or Toggle.', 'A long sentence. A badge is a label.', 'Color as the only signal. The word or the number has to say it too.']);
+await notes(look, [['Height', 'badge/height-minimize · condense · base', 'Shorter than a control, so it sits in a line of text.'], ['Padding', 'badge/padding-inline-*', 'Tighter than a button.'], ['Gap', 'badge/gap-*', 'Between the dot or icon and the label.'], ['Dot', 'badge/dot-* · current color', 'A mark, smaller than the icon.'], ['Icon', 'icon-size/minimize · condense · base', 'The same tier as the text.'], ['Text', 'trigger-minimize · trigger-condense · trigger-base', 'Medium, one whole style per size.'], ['Shape', 'radius/pill · min width = height', 'A single digit is a circle. A wider label keeps its padding.'], ['Colors', 'emphasis/bg · fg · border', 'Subtle unless the Emphasis mode says otherwise. Status recolors it.']]);
+return { id: doc.id, h: Math.round(doc.height), overflow: L.overflow(doc) };