@handamade/psi-mcp 0.5.0 → 0.7.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 15 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.7.0",
  "themes": [
   "light",
   "dark",
@@ -164,6 +164,42 @@
    "slots": [],
    "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Card\n\nContent container with an optional edge-to-edge media slot; `stacked` (media above body) or `featured` (media beside body) layout.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"stacked\" \\| \"featured\"` | stacked | no | stacked = media above body; featured = media beside body (~1.6fr/1fr), stacks under md. |\n| `media` | `ReactNode` | — | no | Media slot rendered edge-to-edge (img, AspectRatio, …). |\n| `hoverLift` | `boolean` | false | no | Lift on hover: translateY(-6px) over --psi-duration-350. |\n| `ref` | `Ref<HTMLDivElement>` | — | 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## Theming\n\nOverride `--psi-card-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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"
   },
+  {
+   "name": "Panel",
+   "description": "Elevated surface panel (D51): secondary background, faint hairline, radius-12 — the shared --psi-surface-* recipe Dialog's panel also binds. Not a Card: no media slot, no hover lift, opaque by design.",
+   "props": [
+    {
+     "name": "padding",
+     "type": "16 | 24",
+     "required": false,
+     "default": 24,
+     "description": "Inner padding in px."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the root element."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "1..*",
+     "order": 1
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Panel\n\nElevated surface panel (D51): secondary background, faint hairline, radius-12 — the shared --psi-surface-* recipe Dialog's panel also binds. Not a Card: no media slot, no hover lift, opaque by design.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `padding` | `16 \\| 24` | 24 | no | Inner padding in px. |\n| `ref` | `Ref<HTMLDivElement>` | — | 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 | Skipped — Panel itself is not focusable; focus moves through its children. |\n\nPlain <div> container with no implicit role. Pass aria-* host props if the panel should announce as a region.\n\n## Theming\n\nOverride `--psi-panel-*` 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"
+  },
   {
    "name": "Input",
    "description": "Single-line text input with pixel-true heights (24–48) and an error state. Inside a Field, id/aria-describedby/aria-invalid/required are wired automatically (D49).",
@@ -189,6 +225,13 @@
      "default": null,
      "description": "Forwarded ref to the underlying `<input>` element."
     },
+    {
+     "name": "placeholder",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Native placeholder text shown while the field is empty (only on components whose host element supports it)."
+    },
     {
      "name": "className",
      "type": "string",
@@ -198,7 +241,7 @@
     }
    ],
    "slots": [],
-   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Input\n\nSingle-line text input with pixel-true heights (24–48) and an error state. Inside a Field, id/aria-describedby/aria-invalid/required are wired automatically (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). |\n| `error` | `boolean` | false | no | Show error styling. Inside a Field, the Field's error also lights this. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input>` 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 | Focuses the native <input>; focus ring on the field. |\n\nerror sets a red border only. Inside a Field, aria-invalid and aria-describedby are wired automatically (D49); standalone, pair them yourself.\n\n## Theming\n\nOverride `--psi-input-*` 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"
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Input\n\nSingle-line text input with pixel-true heights (24–48) and an error state. Inside a Field, id/aria-describedby/aria-invalid/required are wired automatically (D49).\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `size` | `24 \\| 32 \\| 40 \\| 48` | 32 | no | Height in px (24 \\| 32 \\| 40 \\| 48). |\n| `error` | `boolean` | false | no | Show error styling. Inside a Field, the Field's error also lights this. |\n| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input>` element. |\n| `placeholder` | `string` | — | no | Native placeholder text shown while the field is empty (only on components whose host element supports it). |\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 | Focuses the native <input>; focus ring on the field. |\n\nerror sets a red border only. Inside a Field, aria-invalid and aria-describedby are wired automatically (D49); standalone, pair them yourself.\n\n## Theming\n\nOverride `--psi-input-*` 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"
   },
   {
    "name": "Select",
@@ -297,7 +340,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"
   },
   {
@@ -495,6 +557,42 @@
    "slots": [],
    "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Tag\n\nCompact label for status or category; semantic variants, optional subtle tint and dismiss button.\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `variant` | `\"neutral\" \\| \"accent\" \\| \"success\" \\| \"warning\" \\| \"danger\"` | neutral | no | Semantic color variant. |\n| `subtle` | `boolean` | false | no | Use tinted background with semantic foreground. |\n| `onDismiss` | `(() => void)` | — | no | When provided, renders a dismiss button that calls this handler. |\n| `ref` | `Ref<HTMLSpanElement>` | — | no | Forwarded ref to the underlying `<span>` 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| Enter / Space (dismiss button) | onDismiss renders a real <button>; keyboard-dismissible. |\n\nPassive label otherwise; not in the tab order without onDismiss.\n\n## Theming\n\nOverride `--psi-tag-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).\n\n## Variant guidance\n\n- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.\n- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.\n- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.\n- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.\n- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.\n- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.\n- **danger** — Destructive action. Delete, remove, disconnect.\n- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.\n- **success | warning** — Status communication (Tag only). Status badges, labels.\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"
   },
+  {
+   "name": "Toolbar",
+   "description": "Horizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\".",
+   "props": [
+    {
+     "name": "gap",
+     "type": "8 | 12 | 16",
+     "required": false,
+     "default": 8,
+     "description": "Gap between controls in px."
+    },
+    {
+     "name": "ref",
+     "type": "Ref<HTMLDivElement>",
+     "required": false,
+     "default": null,
+     "description": "Forwarded ref to the root element."
+    },
+    {
+     "name": "className",
+     "type": "string",
+     "required": false,
+     "default": null,
+     "description": "Additional CSS class name(s) merged onto the component's root element."
+    }
+   ],
+   "slots": [
+    {
+     "name": "body",
+     "accepts": {},
+     "cardinality": "0..*",
+     "order": 1
+    }
+   ],
+   "doc": "<!-- Generated by emit-docs.ts — do not edit. -->\n# Toolbar\n\nHorizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\".\n\n## Props\n\n| Prop | Type | Default | Required | Description |\n|---|---|---|---|---|\n| `gap` | `8 \\| 12 \\| 16` | 8 | no | Gap between controls in px. |\n| `ref` | `Ref<HTMLDivElement>` | — | 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 | Moves through the controls in DOM order — no roving tabindex (deliberately not role=toolbar, D52). |\n\nWith aria-label it renders role=group so the control cluster announces with a name; unlabeled it is a plain layout div.\n\n## Theming\n\nOverride `--psi-toolbar-*` 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"
+  },
   {
    "name": "Tooltip",
    "description": "Short hover/focus hint attached to a single trigger element.",
@@ -982,11 +1080,11 @@
     },
     "ember": {
      "oklch": {
-      "l": 0.25,
+      "l": 0.14,
       "c": 0.011,
       "h": 72
      },
-     "hex": "#25211c"
+     "hex": "#0c0805"
     }
    }
   },
@@ -1690,6 +1788,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 +2115,217 @@
      "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": [],
+   "blocked": false,
+   "preset": "<Toolbar>\n  <Input />\n  <Select />\n  <Tag><active filter></Tag>\n</Toolbar>\n"
+  },
+  {
+   "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 +2389,11 @@
     "overlay": 1000,
     "tooltip": 1100
    }
+  },
+  "scopes": {
+   "space": [
+    "gap"
+   ]
   }
  },
  "topics": {
@@ -2258,6 +2610,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.7.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-tokens": "0.7.0",
+    "@handamade/psi-react": "0.7.0"
   },
   "scripts": {
     "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"