@hirobius/design-system 0.21.0 → 0.23.0

package/hirobius.tokens.json

@@ -149,6 +149,53 @@
         },
         "$description": "Discrete values within the green range at defined lightness steps."
       },
+      "apple": {
+        "50": {
+          "$value": "#f2faeb",
+          "$description": "Apple-green accent tint — faintest step."
+        },
+        "100": {
+          "$value": "#e2f3cf",
+          "$description": "Apple-green accent — very light tint."
+        },
+        "200": {
+          "$value": "#c7e7a4",
+          "$description": "Apple-green accent — light tint."
+        },
+        "300": {
+          "$value": "#a6d873",
+          "$description": "Apple-green accent — soft mid-light step."
+        },
+        "400": {
+          "$value": "#85c84c",
+          "$description": "Apple-green accent — bright step; dark-mode rest accent."
+        },
+        "500": {
+          "$value": "#66b239",
+          "$description": "Apple-green accent rest — bright, rich apple green; AA for dark (neutral.900) text as a fill."
+        },
+        "600": {
+          "$value": "#54922d",
+          "$description": "Apple-green accent — hover / border step."
+        },
+        "700": {
+          "$value": "#416f20",
+          "$description": "Apple-green accent — pressed and accent-intent text (AA for text on page and card surfaces)."
+        },
+        "800": {
+          "$value": "#34571b",
+          "$description": "Apple-green accent — deep step."
+        },
+        "900": {
+          "$value": "#2b4518",
+          "$description": "Apple-green accent — darkest usable step."
+        },
+        "950": {
+          "$value": "#16250c",
+          "$description": "Apple-green accent — near-black green substrate."
+        },
+        "$description": "Discrete values within the apple-green (brand accent) range at defined lightness steps. Distinct from the emerald `green` feedback/success scale."
+      },
       "violet": {
         "50": {
           "$value": "#f5f3ff",
@@ -489,8 +536,8 @@
           "$description": "Display face: Satoshi Bold (ITF), bound to the display and title composites."
         },
         "mono": {
-          "$value": ["Geist Mono", "Courier New", "monospace"],
-          "$description": "Monospace face: Geist Mono. Falls back to Courier New, monospace."
+          "$value": ["IBM Plex Mono", "Courier New", "monospace"],
+          "$description": "Monospace face: IBM Plex Mono. Falls back to Courier New, monospace."
         }
       },
       "size": {
@@ -685,14 +732,20 @@
         "$description": "Cubic bezier with restrained initial gain and steep terminal velocity."
       },
       "elastic": {
-        "$type": "spring",
-        "$value": {
-          "type": "spring",
-          "stiffness": 300,
-          "damping": 20,
-          "mass": 1
-        },
-        "$description": "Spring response defined by stiffness, damping, and mass parameters."
+        "$value": [0.34, 1.56, 0.64, 1],
+        "$description": "Spring response defined by stiffness, damping, and mass parameters.",
+        "$extensions": {
+          "com.hirobius.hds": {
+            "$type": "spring",
+            "$value": {
+              "type": "spring",
+              "stiffness": 300,
+              "damping": 20,
+              "mass": 1
+            },
+            "bezierSource": "The cubicBezier is easeOutBack (easings.net), chosen as a stand-in for the spring, not fitted to it: both overshoot once, the curve by about 10% and spring(300, 20, 1) by about 11%."
+          }
+        }
       }
     },
     "shadow": {
@@ -972,32 +1025,53 @@
   },
   "semantic": {
     "motion": {
-      "$type": "motion",
+      "$type": "transition",
+      "$extensions": {
+        "com.hirobius.hds": {
+          "$type": "motion"
+        }
+      },
       "productive": {
         "$value": {
           "duration": "{primitive.duration.short}",
-          "easing": "{primitive.easing.decelerate}"
+          "delay": {
+            "value": 0,
+            "unit": "ms"
+          },
+          "timingFunction": "{primitive.easing.decelerate}"
         },
         "$description": "For micro-interactions and status changes. No deformation."
       },
       "expressive": {
         "$value": {
           "duration": "{primitive.duration.medium}",
-          "easing": "{primitive.easing.elastic}"
+          "delay": {
+            "value": 0,
+            "unit": "ms"
+          },
+          "timingFunction": "{primitive.easing.elastic}"
         },
         "$description": "For teaching moments and significant UI entries. Includes physics-based squish."
       },
       "spatial": {
         "$value": {
           "duration": "{primitive.duration.long}",
-          "easing": "{primitive.easing.emphasized}"
+          "delay": {
+            "value": 0,
+            "unit": "ms"
+          },
+          "timingFunction": "{primitive.easing.emphasized}"
         },
         "$description": "For elements traveling long distances across the viewport."
       },
       "exit": {
         "$value": {
           "duration": "{primitive.duration.instant}",
-          "easing": "{primitive.easing.accelerate}"
+          "delay": {
+            "value": 0,
+            "unit": "ms"
+          },
+          "timingFunction": "{primitive.easing.accelerate}"
         },
         "$description": "For elements being removed from the DOM."
       },
@@ -1071,25 +1145,25 @@
           }
         },
         "accent": {
-          "$value": "{primitive.color.neutral.900}",
-          "$description": "Accent-colored background (neutral/monochrome; inverts to a light neutral on dark surfaces).",
+          "$value": "{primitive.color.apple.500}",
+          "$description": "Accent-colored background — bright apple green (stays green on dark surfaces; pair with content.onAccent dark text).",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.900}",
-                "Dark": "{primitive.color.neutral.100}"
+                "Light": "{primitive.color.apple.500}",
+                "Dark": "{primitive.color.apple.400}"
               }
             }
           }
         },
         "accentSubtle": {
-          "$value": "{primitive.color.neutral.100}",
+          "$value": "{primitive.color.apple.50}",
           "$description": "Faint accent tint for hover states or highlights",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.100}",
-                "Dark": "{primitive.color.neutral.900}"
+                "Light": "{primitive.color.apple.50}",
+                "Dark": "{primitive.color.apple.900}"
               }
             }
           }
@@ -1201,24 +1275,24 @@
           }
         },
         "accent": {
-          "$value": "{primitive.color.neutral.900}",
-          "$description": "Accent-intent text/icon color (monochrome). Pair with underline/weight for link affordance.",
+          "$value": "{primitive.color.apple.700}",
+          "$description": "Accent-intent text/icon color — a dark apple green legible on page and card surfaces. Pair with underline/weight for link affordance.",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.900}",
-                "Dark": "{primitive.color.neutral.100}"
+                "Light": "{primitive.color.apple.700}",
+                "Dark": "{primitive.color.apple.400}"
               }
             }
           }
         },
         "onAccent": {
-          "$value": "{primitive.color.neutral.white}",
-          "$description": "Text/icon color on accent fills. Flips to a dark neutral in dark mode, where accent fills are light.",
+          "$value": "{primitive.color.neutral.900}",
+          "$description": "Text/icon color on accent fills — a dark neutral, since the brand accent fill is a bright apple green in both light and dark mode.",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.white}",
+                "Light": "{primitive.color.neutral.900}",
                 "Dark": "{primitive.color.neutral.900}"
               }
             }
@@ -1320,13 +1394,13 @@
           }
         },
         "accent": {
-          "$value": "{primitive.color.neutral.900}",
-          "$description": "Accent border (neutral/monochrome; inverts on dark surfaces).",
+          "$value": "{primitive.color.apple.600}",
+          "$description": "Accent border — apple green, dark enough to read as a boundary on page and card surfaces.",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.900}",
-                "Dark": "{primitive.color.neutral.100}"
+                "Light": "{primitive.color.apple.600}",
+                "Dark": "{primitive.color.apple.400}"
               }
             }
           }
@@ -1838,37 +1912,37 @@
     "accent": {
       "$type": "color",
       "rest": {
-        "$value": "{primitive.color.neutral.900}",
-        "$description": "Default accent fill for interactive elements at rest. Neutral (monochrome) accent — inverts to a light neutral on dark surfaces.",
+        "$value": "{primitive.color.apple.500}",
+        "$description": "Default accent fill for interactive elements at rest — bright apple green. Pair with content.onAccent (a dark neutral).",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.900}",
-              "Dark": "{primitive.color.neutral.100}"
+              "Light": "{primitive.color.apple.500}",
+              "Dark": "{primitive.color.apple.400}"
             }
           }
         }
       },
       "hover": {
-        "$value": "{primitive.color.neutral.800}",
+        "$value": "{primitive.color.apple.600}",
         "$description": "Accent fill on pointer hover.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.800}",
-              "Dark": "{primitive.color.neutral.200}"
+              "Light": "{primitive.color.apple.600}",
+              "Dark": "{primitive.color.apple.500}"
             }
           }
         }
       },
       "pressed": {
-        "$value": "{primitive.color.neutral.950}",
+        "$value": "{primitive.color.apple.700}",
         "$description": "Accent fill during active press.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.950}",
-              "Dark": "{primitive.color.neutral.300}"
+              "Light": "{primitive.color.apple.700}",
+              "Dark": "{primitive.color.apple.600}"
             }
           }
         }
@@ -1898,37 +1972,37 @@
         }
       },
       "content": {
-        "$value": "{primitive.color.neutral.900}",
-        "$description": "Text and icon color on neutral surfaces with accent intent. Monochrome — pair with underline/weight for link affordance.",
+        "$value": "{primitive.color.apple.700}",
+        "$description": "Accent-intent text/icon color on neutral surfaces (a dark apple green) — pair with underline/weight for link affordance.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.900}",
-              "Dark": "{primitive.color.neutral.100}"
+              "Light": "{primitive.color.apple.700}",
+              "Dark": "{primitive.color.apple.400}"
             }
           }
         }
       },
       "contentHover": {
-        "$value": "{primitive.color.neutral.700}",
+        "$value": "{primitive.color.apple.800}",
         "$description": "Accent content color on pointer hover.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.700}",
-              "Dark": "{primitive.color.neutral.300}"
+              "Light": "{primitive.color.apple.800}",
+              "Dark": "{primitive.color.apple.300}"
             }
           }
         }
       },
       "subtle": {
-        "$value": "{primitive.color.neutral.100}",
+        "$value": "{primitive.color.apple.50}",
         "$description": "Low-emphasis accent tint for hover backgrounds and selection highlights.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.100}",
-              "Dark": "{primitive.color.neutral.800}"
+              "Light": "{primitive.color.apple.50}",
+              "Dark": "{primitive.color.apple.900}"
             }
           }
         }
@@ -1974,38 +2048,58 @@
       }
     },
     "elevation": {
-      "$type": "elevation",
+      "$extensions": {
+        "com.hirobius.hds": {
+          "$type": "elevation"
+        }
+      },
       "flat": {
-        "$value": {
-          "surface": "{semantic.color.surface.page}",
-          "shadow": null,
-          "border": "{semantic.color.border.subtle}"
-        },
-        "$description": "Flat surface (no shadow, hairline border) for embedded panels."
+        "$description": "Flat surface (no shadow, hairline border) for embedded panels.",
+        "$extensions": {
+          "com.hirobius.hds": {
+            "$value": {
+              "surface": "{semantic.color.surface.page}",
+              "shadow": null,
+              "border": "{semantic.color.border.subtle}"
+            }
+          }
+        }
       },
       "raised": {
-        "$value": {
-          "surface": "{semantic.color.surface.raised}",
-          "shadow": "{semantic.shadow.subtle}",
-          "border": null
-        },
-        "$description": "Resting card / panel elevation."
+        "$description": "Resting card / panel elevation.",
+        "$extensions": {
+          "com.hirobius.hds": {
+            "$value": {
+              "surface": "{semantic.color.surface.raised}",
+              "shadow": "{semantic.shadow.subtle}",
+              "border": null
+            }
+          }
+        }
       },
       "floating": {
-        "$value": {
-          "surface": "{semantic.color.surface.raised}",
-          "shadow": "{semantic.shadow.floating}",
-          "border": null
-        },
-        "$description": "Hover, menu, and popover elevation."
+        "$description": "Hover, menu, and popover elevation.",
+        "$extensions": {
+          "com.hirobius.hds": {
+            "$value": {
+              "surface": "{semantic.color.surface.raised}",
+              "shadow": "{semantic.shadow.floating}",
+              "border": null
+            }
+          }
+        }
       },
       "overlay": {
-        "$value": {
-          "surface": "{semantic.color.surface.overlay}",
-          "shadow": "{semantic.shadow.overlay}",
-          "border": null
-        },
-        "$description": "Modal, dialog, and drawer elevation."
+        "$description": "Modal, dialog, and drawer elevation.",
+        "$extensions": {
+          "com.hirobius.hds": {
+            "$value": {
+              "surface": "{semantic.color.surface.overlay}",
+              "shadow": "{semantic.shadow.overlay}",
+              "border": null
+            }
+          }
+        }
       }
     },
     "size": {
@@ -2149,7 +2243,7 @@
         "$description": "Tag label weight."
       },
       "lineHeight": {
-        "$type": "dimension",
+        "$type": "number",
         "$value": "{primitive.typography.lineHeight.normal}",
         "$description": "Readable label rhythm for tags."
       },

package/llms.txt

@@ -1,6 +1,6 @@
 # Hirobius Design System
 
-Generated: 2026-10-07T16:09:09.631Z
+Generated: 2026-10-09T13:43:23.079Z
 Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`, `hirobius.tokens.json`
 
 ## Agents Using The Package: Start Here
@@ -9,6 +9,16 @@ Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`,
 - MCP server `hds` ships in the package: run `npx hds-mcp` (stdio). Tools: `list_core`, `search_components`, `get_component`, `search_tokens`; each answer is under 2 KB.
 - Lint before you finish: `import hds from '@hirobius/design-system/eslint-plugin'` and spread `hds.configs.recommended` into `eslint.config.mjs`.
 
+## Voice
+
+How these docs speak. Every page, and every agent writing for HDS, follows it. Source: `content/docs/voice.mdx` (published at `/docs/voice`).
+
+- Use plain words a reader already knows. Name a thing by what it does, not by how it is built.
+- Keep sentences short, one idea each.
+- Tell the reader what to do. Leave out brand adjectives.
+- Keep maintainer references off public pages: issue and ADR numbers, script names, internal counts.
+- Don't use: "systems-first".
+
 ## Pick By Need
 
 One answer per need. Use the components after the arrow; what follows "Not:" is what agents reached for instead, which is the wrong answer for that need even where it has a purpose of its own. Generated from `mcp/guide.mjs`, the same list as `AGENTS.md`.
@@ -149,42 +159,54 @@ One line per component that declares when to use it (`@usage` / `@useInstead` in
 
 Alert: [core] Show a persistent inline message with a severity, next to the content it concerns. Use instead: ToastProvider, Badge
 AlertDialog: Confirm a destructive or irreversible action (delete, archive, remove) before it runs, with Cancel and Action buttons. Use instead: Dialog, ToastProvider
+AssetImg: Show an image that scales to its frame, with a placeholder if it fails to load.
 Avatar: [core] Show a person or entity as an image with an initials fallback. Use instead: Icon, Badge
 Badge: [core] Label a status, state or count with a compact neutral or semantic chip, or a dot. Use instead: Tag, Alert
 Box: [core] Build one-off layout that no named layout primitive covers, using token keys through `sx`. Use instead: Stack, Grid, Container
 Breadcrumb: [core] Show where the current page sits in a hierarchy and link back up it. Use instead: Tabs, Pagination
-Button: [core] Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft and label; for an on/off toggle pass pressed. Use instead: InlineLink
+Button: [core] Run an action, such as submit, save or open a dialog. For an icon-only control pass iconOnly, iconLeft and label; for an on/off toggle pass pressed. Use instead: InlineLink
 Card: [core] Group related content on a raised surface with header, body, footer and metric slots, or as one selectable option. Use instead: Surface, Card.Metric
 CardMetric: Show one headline figure (a KPI, a count, a total) with its label inside a Card. Use instead: MetricTiles
 Checkbox: [core] Let people tick one or more independent options, or a parent choice that is partly selected. Use instead: Toggle, Radio
+CodeBlock: Show a code sample with a copy button, optionally collapsed.
 Combobox: [core] Pick one value, or several with `multiple`, from a long list of options, with a search field that filters as you type. Use instead: Select, Menu
 Container: [core] Constrain a page region to the content or maximum width and centre it. Use instead: Stack, Grid, Box
+DataTableSection: Put a heading and toolbar above a Table.
+DestructiveSection: Put a dangerous action, such as delete, in its own section with a warning and a confirm step.
 Dialog: [core] Interrupt the page with a modal that needs a decision or focused input before people continue. Use instead: Tooltip, Alert, ToastProvider, AlertDialog
 Disclosure: [core] Hide optional explanatory content behind a heading that people can expand. Use instead: Tabs
-Divider: [core] Separate two regions of content with a thin semantic rule. Use instead: Stack, Surface
+Divider: [core] Separate two blocks of content with a thin line. Use instead: Stack, Surface
 EmptyState: [core] Say that a list, grid or section has no data yet, with a title and an optional description. Use instead: Skeleton, Alert
+ErrorPattern: Show an error with a short message and a Back button, in place or as a full page.
 Field: [core] Show a labelled read-only value, such as a name and its value in a detail view. Use instead: Input, Card.Metric
-Grid: [core] Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid. Use instead: Stack, Box
+Form: Wrap form fields so they stack with even spacing.
+FormActions: Lay out a form's buttons in a fixed order: danger on the left, then secondary, then primary on the right.
+Grid: [core] Lay out content in columns that adapt to the screen width, or line up nested content with subgrid. Use instead: Stack, Box
 HdsRouterProvider: [core] Wrap the app root once so HDS links and navigation use your client router; with no provider they stay plain anchors.
 HdsThemeProvider: [core] Wrap an app or region once to set theme, density and other root attributes for everything inside it. Use instead: Surface
-Icon: [core] Draw a Lucide glyph at a size and colour from the design tokens. Use instead: Button, Avatar
+Icon: [core] Show a Lucide icon at a set size and color. Use instead: Button, Avatar
 InlineLink: [core] Link to a route or external URL from inside body copy. Use instead: Button, Text
 Input: [core] Collect a single line of text, a number, an email, a password, a date or a time, with label, helper and error slots. Use instead: Textarea, Select, Combobox
 Kbd: [core] Show a keyboard key or shortcut hint inline, as a native kbd element. Use instead: Text
 Menu: [core] Offer a list of actions from a trigger, closed until opened. Use instead: Select
+MetricTile: Show one key number with its label, inside a MetricTiles row.
+MetricTiles: Show a row of key numbers, one tile each.
+Page: Wrap a screen in the standard width and padding.
+PageHeader: Open a screen with its title, plus optional breadcrumb, status and actions.
 Pagination: [core] Move between pages of a long result set, with truncated page numbers. Use instead: Breadcrumb
 Popover: [core] Anchor interactive content, such as a short form, a filter set or a picker, to a trigger people click to open. Use instead: Tooltip, Menu, Dialog
 Progress: [core] Show how far a task has got, as a bar or ring that is determinate or indeterminate. Use instead: Spinner, Skeleton
 Radio: [core] Choose exactly one option from a small set that should stay visible together. Use instead: Checkbox, Select, SegmentedControl
+Reveal: Fade content in as it scrolls into view.
 SegmentedControl: [core] Switch between two to five mutually exclusive views or modes in a compact row. Use instead: Radio, Tabs, Select
 Select: [core] Choose one value from a short list of options in a form field. Use instead: Menu, Combobox
 Skeleton: [core] Reserve the shape of content that is still loading, so the layout does not jump. Use instead: Progress, Spinner
 Slider: [core] Pick a number within a known range by dragging, when the exact value matters less than the position. Use instead: Input
 Spinner: [core] Show that something is loading when the wait is short or has no measurable end. Use instead: Progress, Skeleton
-Stack: [core] Space a row or column of content with token gaps and simple flex alignment. Use instead: Grid, Surface
+Stack: [core] Space items in a row or column with even gaps. Use instead: Grid, Surface
 Stat: Show one headline figure inline, inside prose or a dense list, with its label and an optional sub-line. Use instead: MetricTiles, Card.Metric, StatusTile
 StatusTile: Show a titled status block with optional notes and a trailing badge or affordance. Use instead: MetricTiles, Card.Metric, StatusListItem
-Surface: [core] Wrap content in a padded, background-bearing inset surface with no header or footer anatomy. Use instead: Card, Stack
+Surface: [core] Give a block of content a background and padding, with no header or footer. Use instead: Card, Stack
 Table: [core] Show rows of structured data in aligned columns, with optional sorting. Use instead: Field, Stack
 Tabs: [core] Switch between panels of related content in the same place, one visible at a time. Use instead: SegmentedControl, Disclosure
 Tag: [core] Show an interactive filter or category chip that people can toggle. Use instead: Badge

package/mcp/catalog.mjs

@@ -16,7 +16,8 @@
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { HOOKS, INTENTS, coreComponents } from './guide.mjs';
+import { CORE_COMPONENTS } from './core-set.mjs';
+import { HOOKS, INTENTS, recommendedComponents } from './guide.mjs';
 
 export const RESULT_BUDGET = 1900;
 
@@ -75,7 +76,7 @@ export function loadCatalog(root) {
 
   /**
    * The flags both search_components and get_component put on a component:
-   * `core` when the guide prefers it, `insteadFor` for each need it is the
+   * `core` for the ratified core set, `recommended` for the rest of what the guide prefers, `insteadFor` for each need it is the
    * wrong answer to (the guide names `use` instead).
    */
   const steer = (name) => {
@@ -84,11 +85,12 @@ export function loadCatalog(root) {
       use: i.use[0],
     }));
     return {
-      ...(core.has(name) ? { core: true } : {}),
+      ...(ratified.has(name) ? { core: true } : recommended.has(name) ? { recommended: true } : {}),
       ...(insteadFor.length ? { insteadFor } : {}),
     };
   };
-  const core = new Set(coreComponents());
+  const ratified = new Set(CORE_COMPONENTS);
+  const recommended = new Set(recommendedComponents());
   const components = Object.keys(api)
     .filter((name) => !api[name].hidden)
     .sort();
@@ -126,14 +128,14 @@ export function loadCatalog(root) {
     for (const name of components) {
       const lower = name.toLowerCase();
       if (lower === compact) add(name, 100);
-      else if (partAliases.has(name) && !core.has(name)) continue;
+      else if (partAliases.has(name) && !recommended.has(name)) continue;
       else if (qWords.some((w) => w.length > 2 && (lower.includes(w) || w.includes(lower))))
         add(name, 20);
       const entry = api[name];
       const text = words(`${entry.description} ${entry.usage?.when ?? ''}`);
       add(name, 2 * qWords.filter((w) => text.includes(w)).length);
       if (scores.get(name) > 0) {
-        if (core.has(name)) add(name, 1);
+        if (recommended.has(name)) add(name, 1);
       }
     }
     const ranked = components
@@ -289,11 +291,12 @@ export function loadCatalog(root) {
 
   // ── list_core ───────────────────────────────────────────────────────────
   function listCore() {
-    const names = [...core].filter((n) => api[n]);
+    const names = [...recommended].filter((n) => api[n]);
     // `id → use`: short enough that every need fits; search_components takes the id.
     const needs = INTENTS.map((i) => `${i.id} → ${i.use.join(', ')}`);
     // Needs are ordered most common first; what does not fit is one search_components away.
     return fitList(needs, (shown, dropped) => ({
+      set: 'recommended: the ratified core plus what the needs name',
       root: names.filter((n) => !patternNames.has(n)),
       patterns: names.filter((n) => patternNames.has(n)),
       hooks: Object.keys(HOOKS),

package/mcp/core-set.mjs

@@ -0,0 +1,66 @@
+/**
+ * The `core` rows of the hds#254 right-sizing table in
+ * docs/hds-architecture-2026-09-18.html (ratified 2026-09-26, #297), with the
+ * hds#315 renames applied: HdsCheckbox → Checkbox, HdsRadio → Radio,
+ * HdsSelect → Select, HdsSlider → Slider, HdsToggle → Toggle. The table has 42
+ * rows; ButtonGroup, ContextMenu and HoverCard were removed from the package in
+ * 0.20.0 (hds#394), which leaves 39. hds#393 adds Menu, Popover, Tooltip and
+ * HdsRouterProvider, each with a usage contract (and Menu, Popover and Tooltip
+ * a keyboard contract), which makes 43.
+ *
+ * THE ONLY FILE THAT LISTS THE CORE SET. It lives in mcp/ because mcp/ ships in
+ * the package and scripts/ does not; scripts/lib/core-components.mjs re-exports it,
+ * mcp/guide.mjs builds the recommended set on it, and the manifest `core` flag,
+ * llms.txt, SKILL.md and the README are generated from it
+ * (scripts/__tests__/core-set-sources.test.mjs fails on any disagreement).
+ *
+ * This is not the manifest `tier` field: 5 core components are `tier: pattern`
+ * and most `tier: primitive` components are not core. Read by
+ * scripts/check-contract-coverage.mjs.
+ */
+export const CORE_COMPONENTS = [
+  'Combobox',
+  'Checkbox',
+  'Radio',
+  'Select',
+  'Slider',
+  'Toggle',
+  'Input',
+  'SegmentedControl',
+  'Tag',
+  'Textarea',
+  'Box',
+  'Container',
+  'Disclosure',
+  'Divider',
+  'Grid',
+  'Stack',
+  'Surface',
+  'Avatar',
+  'Card',
+  'EmptyState',
+  'Field',
+  'Icon',
+  'Kbd',
+  'Table',
+  'Breadcrumb',
+  'InlineLink',
+  'Pagination',
+  'Tabs',
+  'Alert',
+  'Badge',
+  'Progress',
+  'Skeleton',
+  'Spinner',
+  'ToastProvider',
+  'Button',
+  'Dialog',
+  'Text',
+  'HdsThemeProvider',
+  'VisuallyHidden',
+  // hds#393 step 7
+  'Menu',
+  'Popover',
+  'Tooltip',
+  'HdsRouterProvider',
+];