@handamade/psi-mcp 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @handamade/psi-mcp
 
-MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 13 React 19 components, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
+MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 13 React 19 components, 3 composition patterns (D47) that recipe them together with gap-annotated compose trees, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
 
 ## Connect
 

package/dist/index-builder.js

@@ -32,6 +32,9 @@ async function readJson(path) {
 }
 export async function buildIndex(inputs) {
     const manifest = (await readJson(join(inputs.reactDist, "manifest.json")));
+    // Fail-fast is deliberate: requires @handamade/psi-react built first — same posture
+    // as the manifest/guidance reads above.
+    const patternsFile = (await readJson(join(inputs.reactDist, "patterns.json")));
     const guidance = (await readJson(join(inputs.tokensDist, "guidance.json")));
     const resolved = {};
     for (const theme of THEMES) {
@@ -61,6 +64,7 @@ export async function buildIndex(inputs) {
         themes: [...THEMES],
         components,
         tokens,
+        patterns: patternsFile.patterns,
         scales: light.scales,
         topics: {
             ...guidance,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { PsiIndex } from "./types.js";
-export type { PsiIndex, ComponentEntry, TokenEntry, PropDoc } from "./types.js";
+export type { PsiIndex, ComponentEntry, TokenEntry, PropDoc, PatternEntry, PatternNode, PatternParameter, } from "./types.js";
 export { buildIndex, GETTING_STARTED } from "./index-builder.js";
 export { createStore } from "./store.js";
 export type { Store, Brief, Detail } from "./store.js";

package/dist/init.js

@@ -28,6 +28,7 @@ export function renderAgentsBlock(index) {
         "- Never hardcode colors — bind var(--psi-*) custom properties.",
         "- Import all four token CSS files: base.css, one theme css, components.css, utilities.css (utilities is REQUIRED — .psi-container + reduced-motion zeroing) — PLUS @handamade/psi-react/styles (component CSS; separate export, never auto-imported).",
         `- Themes: ${index.themes.join(" | ")} — set data-psi-theme on <html> or a subtree root.`,
+        "- Before composing multi-component UI, search for a matching pattern and ask its clarifying parameters; only freehand when no pattern matches.",
         "",
         `## Components (${index.components.length})`,
         ...index.components.map((c) => `- ${c.name}${axes(c)}`),

package/dist/psi-index.json

@@ -1,5 +1,5 @@
 {
- "version": "0.5.0",
+ "version": "0.6.0",
  "themes": [
   "light",
   "dark",
@@ -297,7 +297,26 @@
      "description": "Additional CSS class name(s) merged onto the component's root element."
     }
    ],
-   "slots": [],
+   "slots": [
+    {
+     "name": "label",
+     "accepts": {},
+     "cardinality": "0..1",
+     "order": 1
+    },
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "1..*",
+     "order": 2
+    },
+    {
+     "name": "description",
+     "accepts": {},
+     "cardinality": "0..1",
+     "order": 3
+    }
+   ],
    "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Field\n\nLabeled form-row wrapper: label above, control, one message line below — description normally, error when set (aria-live). Auto-wires id/aria-describedby/aria-invalid into Input and Select (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `label` | `ReactNode` | — | no | Label content; renders a <label> (or <legend> in group mode). |\n| `description` | `ReactNode` | — | no | Helper line under the control; replaced by error when error is set. |\n| `error` | `ReactNode` | — | no | Error content; when truthy it replaces the description and switches the field (and a wrapped Input/Select) into error state. |\n| `required` | `boolean` | false | no | Renders the required marker and flows `required` to the control. |\n| `group` | `boolean` | false | no | Group mode: fieldset/legend wrapping several self-labeled controls (Checkbox/Switch); the message describes the whole group. |\n| `htmlFor` | `string` | — | no | Override the generated control id (pair it with the same id on the control). |\n| `ref` | `Ref<HTMLDivElement \\| HTMLFieldSetElement>` | — | no | Forwarded ref to the root element. |\n| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |\n\n## Keyboard & assistive tech\n\n| Keys | Behavior |\n|---|---|\n| Tab | Focus moves to the wrapped control; the label is announced with it. |\n\nWires label association, aria-describedby and aria-invalid into a wrapped Input/Select automatically; the message line is aria-live=polite. Group mode renders fieldset/legend.\n\n## Theming\n\nOverride `--psi-field-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n\n\n## Rules\n\n- One accent per visual group; everything else neutral or ghost.\n- danger only for actions with real consequences.\n- Sizes are px numbers (24|32|40|48), never S/M/L.\n- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.\n- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.\n- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).\n- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.\n- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.\n"
   },
   {
@@ -982,11 +1001,11 @@
     },
     "ember": {
      "oklch": {
-      "l": 0.25,
+      "l": 0.14,
       "c": 0.011,
       "h": 72
      },
-     "hex": "#25211c"
+     "hex": "#0c0805"
     }
    }
   },
@@ -1690,6 +1709,44 @@
     }
    }
   },
+  {
+   "name": "fillStaticWhite",
+   "formula": "ref(fgStaticWhite)",
+   "values": {
+    "light": {
+     "oklch": {
+      "l": 1,
+      "c": 0,
+      "h": 250
+     },
+     "hex": "#ffffff"
+    },
+    "dark": {
+     "oklch": {
+      "l": 1,
+      "c": 0,
+      "h": 250
+     },
+     "hex": "#ffffff"
+    },
+    "acme": {
+     "oklch": {
+      "l": 1,
+      "c": 0,
+      "h": 80
+     },
+     "hex": "#ffffff"
+    },
+    "ember": {
+     "oklch": {
+      "l": 1,
+      "c": 0,
+      "h": 49
+     },
+     "hex": "#ffffff"
+    }
+   }
+  },
   {
    "name": "borderFaint",
    "formula": "ref(fgPrimary) → alpha(0.08)",
@@ -1979,6 +2036,219 @@
      "hex": "#0c0a09"
     }
    }
+  },
+  {
+   "name": "bgInverted",
+   "formula": "ref(fgPrimary)",
+   "values": {
+    "light": {
+     "oklch": {
+      "l": 0.3,
+      "c": 0.03,
+      "h": 250
+     },
+     "hex": "#222f3c"
+    },
+    "dark": {
+     "oklch": {
+      "l": 0.93,
+      "c": 0.01,
+      "h": 250
+     },
+     "hex": "#e3e8ee"
+    },
+    "acme": {
+     "oklch": {
+      "l": 0.3,
+      "c": 0.03,
+      "h": 30
+     },
+     "hex": "#3c2825"
+    },
+    "ember": {
+     "oklch": {
+      "l": 0.949,
+      "c": 0.011,
+      "h": 72
+     },
+     "hex": "#f3ede6"
+    }
+   }
+  },
+  {
+   "name": "fgOnInverted",
+   "formula": "ref(bgPrimary)",
+   "values": {
+    "light": {
+     "oklch": {
+      "l": 0.95,
+      "c": 0.005,
+      "h": 250
+     },
+     "hex": "#eceff2"
+    },
+    "dark": {
+     "oklch": {
+      "l": 0.15,
+      "c": 0.01,
+      "h": 250
+     },
+     "hex": "#080c0f"
+    },
+    "acme": {
+     "oklch": {
+      "l": 0.96,
+      "c": 0.01,
+      "h": 80
+     },
+     "hex": "#f5f1ea"
+    },
+    "ember": {
+     "oklch": {
+      "l": 0.147,
+      "c": 0.004,
+      "h": 49
+     },
+     "hex": "#0c0a09"
+    }
+   }
+  }
+ ],
+ "patterns": [
+  {
+   "id": "destructive-confirm",
+   "intent": "Dialog confirming a destructive action",
+   "match": [
+    "delete confirmation",
+    "are you sure",
+    "destructive dialog",
+    "confirm delete"
+   ],
+   "compose": {
+    "component": "Dialog",
+    "slots": {
+     "title": [
+      "{content:title}"
+     ],
+     "body": [
+      "{content:consequence}"
+     ],
+     "footer": [
+      {
+       "component": "Button",
+       "props": {
+        "variant": "ghost",
+        "size": "{param:size}"
+       },
+       "content": "cancel-label"
+      },
+      {
+       "component": "Button",
+       "props": {
+        "variant": "danger",
+        "size": "{param:size}"
+       },
+       "content": "confirm-label"
+      }
+     ]
+    }
+   },
+   "parameters": [
+    {
+     "key": "size",
+     "ask": "Button size?",
+     "options": [
+      32,
+      40
+     ],
+     "default": 32
+    }
+   ],
+   "content": {
+    "title": "<Delete the object?>",
+    "consequence": "<what is permanently lost>",
+    "cancel-label": "Cancel",
+    "confirm-label": "<verb the object>"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Dialog\n  footer={<>\n    <Button size={32} variant=\"ghost\">Cancel</Button>\n    <Button size={32} variant=\"danger\"><verb the object></Button>\n  </>}\n  title=\"<Delete the object?>\"\n>\n  <what is permanently lost>\n</Dialog>\n"
+  },
+  {
+   "id": "filter-toolbar",
+   "intent": "Toolbar of filter controls: search, category select, active-filter tags",
+   "match": [
+    "filter toolbar",
+    "filter bar",
+    "search and filter",
+    "faceted filters"
+   ],
+   "compose": {
+    "component": "Toolbar",
+    "slots": {
+     "body": [
+      {
+       "component": "Input"
+      },
+      {
+       "component": "Select"
+      },
+      {
+       "component": "Tag",
+       "content": "example-filter"
+      }
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "example-filter": "<active filter>"
+   },
+   "gaps": [
+    "Toolbar"
+   ],
+   "blocked": true,
+   "preset": null
+  },
+  {
+   "id": "settings-form-row",
+   "intent": "Labeled settings row: a self-labeled control with a group label and helper text",
+   "match": [
+    "settings row",
+    "form row",
+    "labeled switch",
+    "preference toggle",
+    "settings form"
+   ],
+   "compose": {
+    "component": "Field",
+    "props": {
+     "group": true
+    },
+    "slots": {
+     "label": [
+      "{content:row-label}"
+     ],
+     "body": [
+      {
+       "component": "Switch",
+       "content": "control-label"
+      }
+     ],
+     "description": [
+      "{content:row-description}"
+     ]
+    }
+   },
+   "parameters": [],
+   "content": {
+    "row-label": "<setting name>",
+    "control-label": "<what turning it on does>",
+    "row-description": "<one-line consequence of the setting>"
+   },
+   "gaps": [],
+   "blocked": false,
+   "preset": "<Field\n  description=\"<one-line consequence of the setting>\"\n  group={true}\n  label=\"<setting name>\"\n>\n  <Switch><what turning it on does></Switch>\n</Field>\n"
   }
  ],
  "scales": {
@@ -2042,6 +2312,11 @@
     "overlay": 1000,
     "tooltip": 1100
    }
+  },
+  "scopes": {
+   "space": [
+    "gap"
+   ]
   }
  },
  "topics": {
@@ -2258,6 +2533,11 @@
      "overlay": 1000,
      "tooltip": 1100
     }
+   },
+   "scopes": {
+    "space": [
+     "gap"
+    ]
    }
   }
  }

package/dist/server.js

@@ -4,8 +4,9 @@ export function createPsiServer(store, version) {
     const server = new McpServer({ name: "psi", version });
     server.registerTool("search", {
         title: "Search the Psi design system",
-        description: "Keyword search over Psi components, semantic tokens, and guidance topics. " +
-            "Returns compact briefs with ids for the get tool. Empty query returns an overview.",
+        description: "Keyword search over Psi components, composition patterns, semantic tokens, and " +
+            "guidance topics. Returns compact briefs with ids for the get tool. Empty query " +
+            "returns an overview.",
         inputSchema: { query: z.string().describe("Keywords, e.g. 'button variants' or 'bg token'") },
     }, async ({ query }) => ({
         content: [{ type: "text", text: JSON.stringify(store.search(query), null, 1) }],
@@ -13,8 +14,11 @@ export function createPsiServer(store, version) {
     server.registerTool("get", {
         title: "Get full Psi detail by id",
         description: "Full detail for one id from search: component (props, defaults, a11y doc), " +
-            "token (formula + resolved OKLCH/hex in all four themes), or topic (guidance). " +
-            "Accepts 'component:Button', 'token:bgPrimary', 'topic:variants', or a bare name.",
+            "pattern (composition recipe: compose tree, clarifying parameters, content, " +
+            "gaps/blocked status, and a copy-paste preset when unblocked), token (formula + " +
+            "resolved OKLCH/hex in all four themes), or topic (guidance). Accepts " +
+            "'component:Button', 'pattern:destructive-confirm', 'token:bgPrimary', " +
+            "'topic:variants', or a bare name.",
         inputSchema: { id: z.string().describe("An id from search results, or a bare name") },
     }, async ({ id }) => {
         const detail = store.get(id);

package/dist/store.d.ts

@@ -1,7 +1,7 @@
-import type { ComponentEntry, PsiIndex, TokenEntry } from "./types.js";
+import type { ComponentEntry, PatternEntry, PsiIndex, TokenEntry } from "./types.js";
 export interface Brief {
     id: string;
-    kind: "component" | "token" | "topic";
+    kind: "component" | "token" | "topic" | "pattern";
     title: string;
     summary: string;
 }
@@ -9,7 +9,9 @@ export type Detail = ({
     kind: "component";
 } & ComponentEntry) | ({
     kind: "token";
-} & TokenEntry) | {
+} & TokenEntry) | ({
+    kind: "pattern";
+} & PatternEntry) | {
     kind: "topic";
     name: string;
     content: unknown;

package/dist/store.js

@@ -29,6 +29,12 @@ function componentSummary(c) {
         parts.push(`props: ${c.props.map((p) => p.name).slice(0, 6).join(", ")}`);
     return parts.join(" — ").slice(0, 220);
 }
+function patternSummary(p) {
+    let summary = `${p.intent} — ${p.match.join(", ")}, ${p.parameters.length} parameters`;
+    if (p.blocked)
+        summary += `, blocked (gaps: ${p.gaps.join(", ")})`;
+    return summary;
+}
 export function createStore(index) {
     const briefs = [
         ...index.components.map((c) => ({
@@ -37,6 +43,12 @@ export function createStore(index) {
             title: c.name,
             summary: componentSummary(c),
         })),
+        ...index.patterns.map((p) => ({
+            id: `pattern:${p.id}`,
+            kind: "pattern",
+            title: p.id,
+            summary: patternSummary(p),
+        })),
         ...Object.keys(index.topics).map((name) => ({
             id: `topic:${name}`,
             kind: "topic",
@@ -67,7 +79,7 @@ export function createStore(index) {
     function search(query) {
         const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
         if (terms.length === 0) {
-            // Overview: all components + all topics (tokens are discoverable via query).
+            // Overview: all components, patterns, and topics (tokens are discoverable via query).
             return briefs.filter((b) => b.kind !== "token").slice(0, MAX_RESULTS + 10);
         }
         return briefs
@@ -91,6 +103,11 @@ export function createStore(index) {
             if (t)
                 return { kind: "token", ...t };
         }
+        if (want("pattern")) {
+            const p = index.patterns.find((p) => p.id.toLowerCase() === name);
+            if (p)
+                return { kind: "pattern", ...p };
+        }
         if (want("topic")) {
             const key = Object.keys(index.topics).find((k) => k.toLowerCase() === name);
             if (key)

package/dist/types.d.ts

@@ -37,11 +37,43 @@ export interface TokenEntry {
         hex: string;
     }>;
 }
+/** A single node in a pattern's `compose` tree: a component instance, its
+ * props (which may hold `{param:key}` / `{content:key}` placeholders), and
+ * its slot fills (nested nodes or string literals / placeholders). Mirrors
+ * `packages/react/scripts/patterns.ts`'s `PatternNode` — the shape emitted
+ * into `packages/react/dist/patterns.json` (D47). */
+export interface PatternNode {
+    component: string;
+    props?: Record<string, unknown>;
+    slots?: Record<string, Array<PatternNode | string>>;
+    content?: string;
+}
+export interface PatternParameter {
+    key: string;
+    ask: string;
+    options: Array<string | number>;
+    default?: string | number;
+}
+/** Shape of one entry in `packages/react/dist/patterns.json` (D47/D48):
+ * an authored composition recipe plus its build-time validation/render
+ * results (`gaps`, `blocked`, `preset`). */
+export interface PatternEntry {
+    id: string;
+    intent: string;
+    match: string[];
+    compose: PatternNode;
+    parameters: PatternParameter[];
+    content: Record<string, string>;
+    gaps: string[];
+    blocked: boolean;
+    preset: string | null;
+}
 export interface PsiIndex {
     version: string;
     themes: string[];
     components: ComponentEntry[];
     tokens: TokenEntry[];
+    patterns: PatternEntry[];
     scales: Record<string, unknown>;
     topics: Record<string, unknown>;
 }

package/llms.txt

@@ -2,9 +2,9 @@
 
 Two read-only tools over a baked index of the generated artifacts:
 - search(query): briefs {id, kind, title, summary}; empty query = overview
-- get(id): component (props/defaults/a11y doc) | token (formula + OKLCH/hex per theme) | topic (guidance)
-Ids: component:<Name>, token:<name>, topic:<key>; bare names resolve case-insensitively.
+- get(id): component (props/defaults/a11y doc) | token (formula + OKLCH/hex per theme) | topic (guidance) | pattern (compose tree, clarifying parameters, content, gaps/blocked status, preset JSX)
+Ids: component:<Name>, token:<name>, topic:<key>, pattern:<id>; bare names resolve case-insensitively.
 
 Connect: https://psi.kurkin.de/mcp (Streamable HTTP) or `npx @handamade/psi-mcp` (stdio).
 Agent context: `npx @handamade/psi-mcp init [--claude]` writes a marker-delimited block into AGENTS.md/CLAUDE.md (D44).
-The index bakes packages/react/dist/manifest.json + packages/tokens/dist/{guidance.json,resolved/*.json} at publish; lockstep versioning keeps it truthful (D43).
+The index bakes packages/react/dist/{manifest.json,patterns.json} (patterns.json: 3 composition patterns with clarifying parameters, blocked/gaps flags, preset JSX) + packages/tokens/dist/{guidance.json,resolved/*.json} at publish; lockstep versioning keeps it truthful (D43).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server and agent-context generator for the Psi (Ψ) design system",
   "type": "module",
   "bin": {
@@ -32,8 +32,8 @@
     "tsx": "^4.22.4",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6",
-    "@handamade/psi-react": "0.5.0",
-    "@handamade/psi-tokens": "0.5.0"
+    "@handamade/psi-react": "0.6.0",
+    "@handamade/psi-tokens": "0.6.0"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"