@hirobius/design-system 0.19.1 → 0.21.0

package/mcp/hds-mcp.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * hds-mcp — the `hds` MCP server over stdio, shipped in @hirobius/design-system.
+ *
+ * Run from an app that has the package installed:  npx hds-mcp
+ * Without an install:  npx -y -p @hirobius/design-system hds-mcp
+ *
+ * Reads the data the package already ships (public/hds-manifest.json,
+ * src/app/data/component-api.json) from its own install directory; it never
+ * touches the network or the caller's files. Messages are newline-delimited
+ * JSON-RPC 2.0 (the MCP stdio transport); logs go to stderr only.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { loadCatalog } from './catalog.mjs';
+import { createServer } from './server.mjs';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { version } = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+
+let catalog;
+try {
+  catalog = loadCatalog(PKG_ROOT);
+} catch (err) {
+  console.error(
+    `hds-mcp: could not read the design-system data under ${PKG_ROOT} (${err.message}).\n` +
+      '  Reinstall @hirobius/design-system; in the hds repo run `node scripts/generate-component-api.mjs` first.',
+  );
+  process.exit(1);
+}
+
+const handle = createServer({ version, instructions: catalog.instructions, tools: catalog.tools });
+
+const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);
+
+createInterface({ input: process.stdin }).on('line', (line) => {
+  if (!line.trim()) return;
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+  const response = handle(message);
+  if (response) send(response);
+});

package/mcp/server.mjs

@@ -0,0 +1,94 @@
+/**
+ * The `hds` MCP server's protocol layer: JSON-RPC 2.0 messages in, responses out.
+ *
+ * Interface: `createServer({ version, instructions, tools })` returns
+ * `handle(message)`, which takes one parsed JSON value and returns the response
+ * object, or `null` for a notification. It never throws: a message that is not a
+ * request object gets -32600, and anything unexpected inside gets -32603, so one
+ * bad line cannot stop the process. Transport (stdio framing) lives in hds-mcp.mjs, the
+ * tool behaviour in catalog.mjs; this module only speaks MCP.
+ *
+ * No dependency on @modelcontextprotocol/sdk: the server needs four methods
+ * (initialize, ping, tools/list, tools/call), and a zero-dependency module keeps
+ * the published package's install graph unchanged.
+ */
+
+export const SERVER_NAME = 'hds';
+
+/** Protocol versions this server can speak; it echoes the client's when it is one of these. */
+const SUPPORTED_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+const rpcResult = (id, result) => ({ jsonrpc: '2.0', id, result });
+
+/**
+ * @param {{ version: string, instructions: string, tools: { name: string, description: string, inputSchema: object, run: (args: object) => unknown }[] }} options
+ */
+export function createServer({ version, instructions, tools }) {
+  const byName = new Map(tools.map((t) => [t.name, t]));
+
+  function dispatch(message) {
+    // MCP has no batches (removed in 2025-06-18), so an array is invalid like any non-object.
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      return rpcError(null, -32600, 'Invalid Request: expected one JSON-RPC request object');
+    }
+    const hasId = Object.prototype.hasOwnProperty.call(message, 'id');
+    const id = hasId ? message.id : null;
+    if (typeof message.method !== 'string') {
+      return hasId ? rpcError(id, -32600, 'Invalid Request: method must be a string') : null;
+    }
+    // A message without an `id` member is a notification; `id: null` is still a request.
+    if (!hasId) return null;
+    const { method } = message;
+    const params = message.params && typeof message.params === 'object' ? message.params : {};
+
+    switch (method) {
+      case 'initialize': {
+        const asked = params.protocolVersion;
+        return rpcResult(id, {
+          protocolVersion: SUPPORTED_VERSIONS.includes(asked) ? asked : SUPPORTED_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: SERVER_NAME, version },
+          instructions,
+        });
+      }
+      case 'ping':
+        return rpcResult(id, {});
+      case 'tools/list':
+        return rpcResult(id, {
+          tools: tools.map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+          })),
+        });
+      case 'tools/call': {
+        const tool = typeof params.name === 'string' ? byName.get(params.name) : undefined;
+        if (!tool) return rpcError(id, -32602, `Unknown tool: ${params.name}`);
+        try {
+          const args =
+            params.arguments && typeof params.arguments === 'object' ? params.arguments : {};
+          const data = tool.run(args);
+          return rpcResult(id, { content: [{ type: 'text', text: JSON.stringify(data) }] });
+        } catch (err) {
+          // A tool-level failure is a result with isError, so the agent can read and recover.
+          return rpcResult(id, {
+            content: [{ type: 'text', text: JSON.stringify({ error: String(err.message) }) }],
+            isError: true,
+          });
+        }
+      }
+      default:
+        return rpcError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  return function handle(message) {
+    try {
+      return dispatch(message);
+    } catch (err) {
+      const id = message && typeof message === 'object' && 'id' in message ? message.id : null;
+      return rpcError(id ?? null, -32603, `Internal error: ${err?.message ?? err}`);
+    }
+  };
+}

package/package.json

@@ -20,17 +20,12 @@
   "author": "Adrian Milsap",
   "license": "SEE LICENSE IN NOTICE.md",
   "private": false,
-  "version": "0.19.1",
+  "version": "0.21.0",
   "engines": {
     "node": ">=20",
     "pnpm": ">=8"
   },
   "type": "module",
-  "typeCoverage": {
-    "ignoreFiles": [
-      "src/app/components/mobius-distortion.ts"
-    ]
-  },
   "module": "./dist/hirobius-ui.js",
   "types": "./dist/types/src/index.d.ts",
   "sideEffects": [
@@ -44,6 +39,7 @@
     },
     "./tokens.css": "./dist/tokens.css",
     "./styles.css": "./dist/styles.css",
+    "./fonts.css": "./dist/fonts.css",
     "./variables.css": "./dist/variables.css",
     "./static.css": "./dist/static.css",
     "./tokens": {
@@ -96,6 +92,10 @@
       "import": "./dist/icons.js",
       "default": "./dist/icons.js"
     },
+    "./eslint-plugin": {
+      "types": "./scripts/eslint-plugin-hds/index.d.mts",
+      "default": "./scripts/eslint-plugin-hds/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -112,7 +112,19 @@
     "docs/CONSUMING.md",
     "src/app/data/component-api.json",
     "codemods/patterns-subpath.mjs",
-    "codemods/patterns-subpath.names.json"
+    "codemods/patterns-subpath.names.json",
+    "codemods/removed-0.20.json",
+    "codemods/hds-prefix.mjs",
+    "codemods/unrewritable.mjs",
+    "codemods/jsx-fold.mjs",
+    "codemods/not-found-pattern.mjs",
+    "codemods/tile-grid.mjs",
+    "AGENTS.md",
+    "mcp/",
+    "scripts/eslint-plugin-hds/index.mjs",
+    "scripts/eslint-plugin-hds/index.d.mts",
+    "scripts/eslint-plugin-hds/package.json",
+    "scripts/eslint-plugin-hds/rules/"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -146,26 +158,19 @@
   },
   "dependencies": {
     "@radix-ui/react-alert-dialog": "^1.1.18",
-    "@radix-ui/react-aspect-ratio": "^1.1.11",
-    "@radix-ui/react-context-menu": "^2.3.2",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.18",
-    "@radix-ui/react-hover-card": "^1.1.18",
     "@radix-ui/react-popover": "^1.1.17",
     "@radix-ui/react-select": "^2.3.1",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-toast": "^1.2.17",
-    "@radix-ui/react-toggle": "^1.1.13",
     "@radix-ui/react-toggle-group": "^1.1.13",
-    "@radix-ui/react-toolbar": "^1.1.14",
     "@radix-ui/react-tooltip": "^1.1.8",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "date-fns": "^4.4.0",
     "lucide-react": "0.487.0",
     "motion": "12.23.24",
-    "react-day-picker": "^10.0.1",
     "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {
@@ -174,6 +179,7 @@
     "@changesets/cli": "^2.27.10",
     "@cyclonedx/cyclonedx-npm": "^4.2.1",
     "@figma/code-connect": "^2.0.1",
+    "@guidepup/virtual-screen-reader": "^0.33.0",
     "@hookform/resolvers": "^5.4.0",
     "@lhci/cli": "0.15.1",
     "@microsoft/api-extractor": "7.58.7",
@@ -190,7 +196,6 @@
     "@testing-library/user-event": "^14.6.7",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
-    "@types/three": "^0.183.1",
     "@typescript-eslint/eslint-plugin": "^8.59.1",
     "@typescript-eslint/parser": "^8.59.1",
     "@vitejs/plugin-react": "4.7.0",
@@ -210,7 +215,6 @@
     "eslint-plugin-tailwindcss": "^3.18.3",
     "express": "^5.2.1",
     "fast-check": "^4.7.0",
-    "fuse.js": "^7.1.0",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "jscodeshift": "^17.3.0",
@@ -234,21 +238,23 @@
     "storybook": "^8.6.18",
     "style-dictionary": "^5.4.0",
     "tailwindcss": "^4.2.4",
-    "three": "^0.183.2",
     "type-coverage": "^2.29.7",
     "typescript": "^6.0.2",
     "vite": "6.4.2",
     "vite-bundle-visualizer": "^1.2.1",
     "vitest": "^4.1.0",
     "yaml": "^2.8.1",
-    "zod": "^4.4.3",
-    "zustand": "^5.0.12"
+    "zod": "^4.4.3"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx,mjs,cjs,json,md,mdx,css,scss,html,yaml,yml}": "prettier --write"
   },
   "bin": {
-    "hds-patterns-subpath": "codemods/patterns-subpath.mjs"
+    "hds-patterns-subpath": "codemods/patterns-subpath.mjs",
+    "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"
   },
   "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.",
@@ -264,13 +270,13 @@
     "audit:sidecar": "node scripts/generate-security-posture.mjs",
     "audit:style-dictionary": "bash scripts/poc/style-dictionary-poc/run.sh",
     "build-storybook": "storybook build",
-    "build:lib": "vite build -c vite.config.lib.ts && pnpm build:types && node scripts/build-vars-css.mjs && node scripts/embed-fonts.mjs && node scripts/build-styles-css.mjs && node scripts/build-static-css.mjs",
+    "build:lib": "vite build -c vite.config.lib.ts && pnpm build:types && node scripts/build-vars-css.mjs && node scripts/build-fonts-css.mjs && node scripts/build-styles-css.mjs && node scripts/build-static-css.mjs",
     "build:types": "tsc -p tsconfig.dts.json && node scripts/strip-dts-side-effects.mjs && node scripts/add-dts-extensions.mjs",
     "catalog": "node scripts/generate-visual-catalog.mjs",
     "changelog:generate": "node scripts/generate-changelog.mjs",
     "changeset": "changeset",
     "changeset:add": "changeset",
-    "changeset:version": "changeset version",
+    "changeset:version": "changeset version && 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",
@@ -285,11 +291,13 @@
     "check:dimensions": "node scripts/check-dimensions.mjs",
     "check:doc-refs": "node scripts/check-link-integrity.mjs --doc-refs-only",
     "check:docs": "node scripts/audit-component-integrity.mjs --docs && node scripts/check-token-descriptions.mjs --no-missing --quality",
+    "check:docs-guardrails": "node scripts/check-docs.mjs",
     "check:exemptions": "node scripts/check-exemptions.mjs",
     "check:fast": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/build-tokens.mjs && node scripts/verify-tokens.mjs && node scripts/audit-tokens.mjs --full && pnpm typecheck && node scripts/check-css-integrity.mjs && node scripts/audit-component-integrity.mjs --tokens && pnpm check:docs && node scripts/check-ref-forwarding.mjs && node scripts/check-hardcoded-spacing.mjs && node scripts/check-dimensions.mjs && node scripts/check-hardcoded-breakpoints.mjs && node scripts/check-typography-discipline.mjs && pnpm check:mojibake && node scripts/check-style-discipline.mjs --style-props-only && node scripts/check-tier-bypass.mjs && node scripts/check-link-integrity.mjs --doc-refs-only && node scripts/check-brand.mjs && node scripts/check-registry.mjs && node scripts/check-template-source-of-truth.mjs",
     "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: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",
@@ -302,6 +310,7 @@
     "check:knip": "knip",
     "check:knip-ratchet": "knip --max-issues 60",
     "check:layout-discipline": "node scripts/check-layout-discipline.mjs",
+    "check:layout-gap-vocabulary": "node scripts/check-layout-gap-vocabulary.mjs",
     "check:licenses": "node scripts/check-licenses.mjs",
     "check:lockfile": "pnpm install --frozen-lockfile --offline --prefer-offline --ignore-scripts --silent 2>/dev/null || (echo 'Lockfile drift: run pnpm install' && exit 1)",
     "check:manifest-drift": "node scripts/check-manifest-drift.mjs",
@@ -322,6 +331,8 @@
     "check:spacing": "node scripts/check-hardcoded-spacing.mjs",
     "check:spacing-vocabulary": "node scripts/check-spacing-vocabulary.mjs",
     "check:story-coverage": "node scripts/check-story-coverage.mjs",
+    "check:layout-contract": "node scripts/check-layout-contract.mjs",
+    "check:spacing-scale": "node scripts/check-tailwind-spacing-scale.mjs",
     "check:storybook-axe": "node scripts/check-storybook-axe.mjs",
     "check:style-props": "node scripts/check-style-discipline.mjs --style-props-only",
     "check:sync-map": "node scripts/check-sync-map.mjs",
@@ -343,8 +354,12 @@
     "closure:plan:check": "node scripts/generate-closure-plan.mjs --check",
     "docs:api": "node scripts/generate-component-api.mjs",
     "docs:changelogs": "node scripts/generate-component-changelogs.mjs",
+    "docs:build": "pnpm docs:prepare && pnpm --dir docs-site build",
+    "docs:components": "node scripts/generate-docs-components.mjs",
     "docs:component": "node scripts/generate-component-page.mjs",
+    "docs:dev": "pnpm docs:prepare && pnpm --dir docs-site dev",
     "docs:llms": "node scripts/generate-llms-txt.mjs",
+    "docs:prepare": "pnpm build:lib && pnpm docs:api && pnpm docs:components && pnpm --dir docs-site install --frozen-lockfile",
     "docs:site": "node scripts/generate-component-page.mjs --all --clean",
     "docs:site:inline": "node scripts/generate-component-page.mjs --all --clean --inline",
     "docs:site:shots": "node scripts/generate-component-page.mjs --all --clean --shots",
@@ -368,8 +383,8 @@
     "health-commit": "pnpm check:semantic-report && node scripts/print-health-commit.mjs",
     "icons:sync": "node scripts/sync-icons.mjs",
     "knip": "knip",
-    "lint": "eslint src scripts validators tests --max-warnings=0",
-    "lint:fix": "eslint src scripts validators tests --fix",
+    "lint": "eslint src scripts validators tests mcp --max-warnings=0",
+    "lint:fix": "eslint src scripts validators tests mcp --fix",
     "llms:generate": "node scripts/generate-llms-txt.mjs",
     "skill:generate": "node scripts/generate-consumer-skill.mjs",
     "check:consumer-skill": "node scripts/generate-consumer-skill.mjs --check",
@@ -378,7 +393,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/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",
+    "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",
     "pretypecheck": "node scripts/audit-tokens.mjs --report-only",
     "preview:build": "vite build --config preview/vite.config.mjs",
     "promote": "node scripts/promote.mjs",
@@ -387,6 +402,9 @@
     "scaffold:component": "node scripts/scaffold-component.mjs",
     "scaffold:tenant": "node scripts/scaffold-tenant.mjs",
     "size-limit": "size-limit --config .size-limit.cjs",
+    "layout-contract:generate": "node scripts/generate-layout-contract.mjs",
+    "status:touch": "node scripts/status-touch.mjs",
+    "status:fold": "node scripts/status-fold.mjs",
     "smoke:consumer": "node scripts/smoke-consumer.mjs && node scripts/check-published-types.mjs && node scripts/check-rsc-directives.mjs && node scripts/check-pack-contents.mjs",
     "storybook": "storybook dev -p 6006",
     "storybook:deploy": "node scripts/deploy-storybook.mjs",
@@ -399,7 +417,7 @@
     "test:figma": "npx tsx scripts/figma-sync.ts",
     "test:phase1": "node scripts/test-phase1.mjs",
     "test:watch": "vitest",
-    "tokens": "node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs && node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --forbidden && node scripts/check-typography-discipline.mjs --overrides-only && node scripts/build-handoff.mjs && node scripts/build-design-md.mjs && node scripts/generate-llms-txt.mjs && node scripts/generate-consumer-skill.mjs && node scripts/build-readme-counts.mjs",
+    "tokens": "node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs && node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --forbidden && node scripts/check-typography-discipline.mjs --overrides-only && node scripts/build-handoff.mjs && node scripts/build-design-md.mjs && node scripts/generate-llms-txt.mjs && node scripts/generate-consumer-skill.mjs && node scripts/generate-agents-md.mjs && node scripts/build-readme-counts.mjs",
     "tokens:audit": "node scripts/audit-component-integrity.mjs --tokens",
     "tokens:build": "node scripts/build-hds-tokens.mjs",
     "tokens:index": "node scripts/build-token-index.mjs",
@@ -411,6 +429,9 @@
     "watch:guardrails": "nodemon --watch CLAUDE.md --watch .cursorrules --watch eslint.config.js --watch .github/workflows -e md,json,js,yml,yaml --exec \"node scripts/audit-guardrails.js\"",
     "watch:metrics": "nodemon --watch src/app/components --watch src/app/pages --watch src/app/design-system --watch src/app/styles -e tsx,ts,css --exec \"node scripts/audit-tokens.mjs --full && node scripts/generate-manifest.mjs\"",
     "consumer:usage": "node scripts/count-consumer-usage.mjs",
-    "codemod:names": "node scripts/build-codemod-pattern-names.mjs"
+    "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"
   }
 }