@hirobius/design-system 0.21.0 → 0.22.0

package/dist/types/src/index.d.ts

@@ -726,14 +726,20 @@ export declare const tokens: {
                 $description: string;
             };
             elastic: {
-                $type: string;
-                $value: {
-                    type: string;
-                    stiffness: number;
-                    damping: number;
-                    mass: number;
-                };
+                $value: number[];
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $type: string;
+                        $value: {
+                            type: string;
+                            stiffness: number;
+                            damping: number;
+                            mass: number;
+                        };
+                        bezierSource: string;
+                    };
+                };
             };
         };
         shadow: {
@@ -1014,31 +1020,52 @@ export declare const tokens: {
     semantic: {
         motion: {
             $type: string;
+            $extensions: {
+                "com.hirobius.hds": {
+                    $type: string;
+                };
+            };
             productive: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
             expressive: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
             spatial: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
             exit: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
@@ -2015,38 +2042,58 @@ export declare const tokens: {
             };
         };
         elevation: {
-            $type: string;
-            flat: {
-                $value: {
-                    surface: string;
-                    shadow: null;
-                    border: string;
+            $extensions: {
+                "com.hirobius.hds": {
+                    $type: string;
                 };
+            };
+            flat: {
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: null;
+                            border: string;
+                        };
+                    };
+                };
             };
             raised: {
-                $value: {
-                    surface: string;
-                    shadow: string;
-                    border: null;
-                };
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: string;
+                            border: null;
+                        };
+                    };
+                };
             };
             floating: {
-                $value: {
-                    surface: string;
-                    shadow: string;
-                    border: null;
-                };
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: string;
+                            border: null;
+                        };
+                    };
+                };
             };
             overlay: {
-                $value: {
-                    surface: string;
-                    shadow: string;
-                    border: null;
-                };
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: string;
+                            border: null;
+                        };
+                    };
+                };
             };
         };
         size: {

package/hirobius.tokens.json

@@ -685,14 +685,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 +978,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."
       },
@@ -1974,38 +2001,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 +2196,7 @@
         "$description": "Tag label weight."
       },
       "lineHeight": {
-        "$type": "dimension",
+        "$type": "number",
         "$value": "{primitive.typography.lineHeight.normal}",
         "$description": "Readable label rhythm for tags."
       },

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',
+];

package/mcp/guide.mjs

@@ -13,6 +13,8 @@
  * scripts/__tests__/generate-agents-md.test.mjs enforces it.
  */
 
+import { CORE_COMPONENTS } from './core-set.mjs';
+
 /** Hooks are not components, so component-api.json has no entry for them. */
 export const HOOKS = {
   useToast: {
@@ -257,59 +259,14 @@ export const INTENTS = [
 ];
 
 /**
- * The ratified core set (scripts/lib/core-components.mjs, hds#254). Copied, not
- * imported, because scripts/ does not ship; scripts/__tests__/generate-agents-md.test.mjs
- * pins the two together.
+ * The recommended set: the ratified core (mcp/core-set.mjs, hds#254) plus every
+ * component a need above names, hooks excluded. This is a different set from the
+ * ratified core: it adds the patterns and layout parts the guide steers agents to
+ * (Page, MetricTiles, ...). list_core and AGENTS.md show this one and say so; the
+ * manifest `core` flag, llms.txt and SKILL.md show the ratified core.
  */
-export const RATIFIED_CORE = [
-  'Alert',
-  'Avatar',
-  'Badge',
-  'Box',
-  'Breadcrumb',
-  'Button',
-  'Card',
-  'Checkbox',
-  'Combobox',
-  'Container',
-  'Dialog',
-  'Disclosure',
-  'Divider',
-  'EmptyState',
-  'Field',
-  'Grid',
-  'HdsRouterProvider',
-  'HdsThemeProvider',
-  'Icon',
-  'InlineLink',
-  'Input',
-  'Kbd',
-  'Menu',
-  'Pagination',
-  'Popover',
-  'Progress',
-  'Radio',
-  'SegmentedControl',
-  'Select',
-  'Skeleton',
-  'Slider',
-  'Spinner',
-  'Stack',
-  'Surface',
-  'Table',
-  'Tabs',
-  'Tag',
-  'Text',
-  'Textarea',
-  'ToastProvider',
-  'Toggle',
-  'Tooltip',
-  'VisuallyHidden',
-];
-
-/** The core set agents should prefer: the ratified core plus every `use` above, hooks excluded. */
-export function coreComponents() {
-  const names = new Set(RATIFIED_CORE);
+export function recommendedComponents() {
+  const names = new Set(CORE_COMPONENTS);
   for (const intent of INTENTS) for (const name of intent.use) if (!HOOKS[name]) names.add(name);
   return [...names].sort();
 }

package/package.json

@@ -20,7 +20,7 @@
   "author": "Adrian Milsap",
   "license": "SEE LICENSE IN NOTICE.md",
   "private": false,
-  "version": "0.21.0",
+  "version": "0.22.0",
   "engines": {
     "node": ">=20",
     "pnpm": ">=8"
@@ -110,6 +110,12 @@
     "DESIGN.md",
     "CONSUMING.md",
     "docs/CONSUMING.md",
+    "UPGRADING.md",
+    "MIGRATIONS.md",
+    "CHANGELOG.md",
+    "upgrade/schema.json",
+    "upgrade/index.json",
+    "upgrade/releases/",
     "src/app/data/component-api.json",
     "codemods/patterns-subpath.mjs",
     "codemods/patterns-subpath.names.json",
@@ -119,6 +125,14 @@
     "codemods/jsx-fold.mjs",
     "codemods/not-found-pattern.mjs",
     "codemods/tile-grid.mjs",
+    "codemods/upgrade.mjs",
+    "codemods/registry.mjs",
+    "codemods/lib/atomic-write.mjs",
+    "codemods/lib/installed-version.mjs",
+    "codemods/lib/project.mjs",
+    "codemods/lib/record.mjs",
+    "codemods/lib/scan.mjs",
+    "codemods/lib/semver.mjs",
     "AGENTS.md",
     "mcp/",
     "scripts/eslint-plugin-hds/index.mjs",
@@ -254,7 +268,9 @@
     "hds-prefix": "codemods/hds-prefix.mjs",
     "hds-not-found-pattern": "codemods/not-found-pattern.mjs",
     "hds-tile-grid": "codemods/tile-grid.mjs",
-    "hds-mcp": "mcp/hds-mcp.mjs"
+    "hds-mcp": "mcp/hds-mcp.mjs",
+    "design-system": "codemods/upgrade.mjs",
+    "hds-upgrade": "codemods/upgrade.mjs"
   },
   "scripts": {
     "_comment:a11y-high-value": "The following check:* validators are high-value accessibility checks that catch real violations (check:focus found 1 missing focus class). Kept dormant/manual-only to avoid pre-commit performance regression. Candidates to wire into pretest after CI stability review.",
@@ -276,7 +292,7 @@
     "changelog:generate": "node scripts/generate-changelog.mjs",
     "changeset": "changeset",
     "changeset:add": "changeset",
-    "changeset:version": "changeset version && node scripts/audit-component-integrity.mjs --api --update-baseline",
+    "changeset:version": "changeset version && node scripts/upgrade/compile.mjs --release && node scripts/audit-component-integrity.mjs --api --update-baseline",
     "check": "pnpm check:full",
     "check:a11y": "pnpm lint --rule '{\"jsx-a11y/alt-text\":\"error\",\"jsx-a11y/img-redundant-alt\":\"error\"}'",
     "check:attributions": "node scripts/check-attributions.mjs",
@@ -297,7 +313,7 @@
     "check:figma-coverage": "node scripts/check-figma-coverage.mjs",
     "check:figma-drift": "node scripts/check-figma-drift.mjs",
     "check:figma-mapping": "node scripts/check-figma-mapping.mjs",
-    "check:figma-staging-urls": "node scripts/check-figma-staging-urls.mjs",
+    "check:figma-retired-keys": "node scripts/check-figma-retired-keys.mjs",
     "check:focus": "node scripts/check-focus-states.mjs",
     "check:font-files": "node scripts/check-typography-discipline.mjs --font-files-only",
     "check:fonts": "node scripts/check-typography-discipline.mjs --fonts-only",
@@ -374,7 +390,6 @@
     "figma:native-import": "node scripts/build-figma-native-import.mjs",
     "figma:push": "node scripts/figma-push.mjs",
     "figma:snapshot": "node scripts/figma-snapshot.mjs",
-    "figma:staging-inventory": "node scripts/generate-staging-inventory.mjs",
     "guardrail:sweep": "node scripts/guardrail-sweep.mjs",
     "harvest:design-md": "node scripts/harvest-design-md.mjs",
     "hds:new": "node scripts/scaffold-component.mjs",
@@ -393,7 +408,7 @@
     "prebuild-storybook": "node scripts/generate-component-api.mjs",
     "prebuild:lib": "node scripts/generate-component-api.mjs",
     "prestorybook": "node scripts/generate-component-api.mjs",
-    "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/audit-component-integrity.mjs --api && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && node scripts/check-props-exports.mjs && knip --no-exit-code && node scripts/check-dark-alias-flip.mjs && node scripts/check-focus-states.mjs && node scripts/generate-staging-inventory.mjs --check && node scripts/generate-consumer-skill.mjs --check && node scripts/generate-agents-md.mjs --check && node scripts/check-deprecations.mjs && node scripts/upgrade/schema.mjs --check && node scripts/check-docs.mjs && node --test scripts/check-docs.selftest.mjs",
+    "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/audit-component-integrity.mjs --api && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && node scripts/check-props-exports.mjs && knip --no-exit-code && node scripts/check-dark-alias-flip.mjs && node scripts/check-focus-states.mjs && node scripts/generate-consumer-skill.mjs --check && node scripts/generate-agents-md.mjs --check && node scripts/check-deprecations.mjs && node scripts/upgrade/schema.mjs --check && node scripts/upgrade/compile.mjs --check && node scripts/check-docs.mjs && node --test scripts/check-docs.selftest.mjs && node scripts/check-upgrade-ledger.mjs",
     "pretypecheck": "node scripts/audit-tokens.mjs --report-only",
     "preview:build": "vite build --config preview/vite.config.mjs",
     "promote": "node scripts/promote.mjs",
@@ -432,6 +447,7 @@
     "upgrade:consumers": "node scripts/upgrade/consumers.mjs",
     "codemod:names": "node scripts/build-codemod-pattern-names.mjs",
     "agents:generate": "node scripts/generate-agents-md.mjs",
-    "check:agents-md": "node scripts/generate-agents-md.mjs --check"
+    "check:agents-md": "node scripts/generate-agents-md.mjs --check",
+    "upgrade:note": "node scripts/upgrade/note.mjs"
   }
 }