Merge pull request #1 from ryandmonk/feature/phase-16c-storybook-adapter

feat(phase-16c): Storybook MCP adapter + cross-surface drift analysis

Author: ryandmonk

README.md

@@ -97,7 +97,7 @@ It keeps them in sync continuously.
 | **Reconciled** | Design overrides, code markers, AST values, and defaults are merged with explicit precedence: `override > marker > ast > code`. |
 | **Auditable** | Every operation produces artifacts. Every decision is traceable. CI gates enforce drift thresholds. |
 | **Safe** | Dry-run by default. Opt-in writes. Echo suppression prevents feedback loops. Rollback previews before destructive changes. |
-| **Read-only adapters** | External integrations (e.g., Figma MCP, Storybook) are read-only with default-deny tool policies. Adapters are classified by surface type, access mode, authority role, and stability. AF is the only mutation authority. |
+| **Read-only adapters** | External integrations (Figma MCP, Storybook MCP) are read-only with default-deny tool policies. Adapters are classified by surface type, access mode, authority role, and stability. AF is the only mutation authority. |
 
 ### How It Differs From…
 
@@ -106,6 +106,7 @@ It keeps them in sync continuously.
 | **Prompt-to-code** (v0, Bolt, etc.) | AF doesn't generate code from designs. It *reconciles* code and design as a continuous system. |
 | **Design token export** (Style Dictionary, etc.) | AF goes beyond tokens — it syncs component structure, variants, states, and properties bidirectionally. |
 | **MCP integrations** (figma-console-mcp, etc.) | AF uses MCP as a *read-only data source*, never as a mutation path. AF's control plane is watcher → server → plugin. |
+| **Storybook MCP** (@storybook/addon-mcp) | AF connects to Storybook's MCP endpoint to read component metadata for cross-surface drift analysis — it does not run or control Storybook. |
 | **Figma plugins** (code-gen plugins) | AF's plugin is a *mutation executor*, not a decision-maker. Reconciliation happens in the watcher. |
 
 ## Architecture
@@ -200,6 +201,7 @@ Available profiles: `designer-first`, `code-first`, `balanced`, `strict-review`.
 | `af design pull` | Pull design data (tokens + components + styles) |
 | `af design screenshot` | Capture design screenshot |
 | `af design component [name]` | List or inspect components |
+| `af design drift [name]` | Cross-surface drift analysis (Figma vs Storybook vs code) |
 
 ## Project Structure
 
@@ -208,10 +210,14 @@ aesthetic-function/
 ├── packages/
 │   ├── shared/          # Protocol definitions, shared types
 │   ├── watcher/         # Reconciliation engine, AST analysis, adapters
+│   │   └── src/
+│   │       ├── designAdapter/        # Figma + Storybook MCP adapters
+│   │       └── crossSurfaceDrift/    # Cross-surface drift analysis engine
 │   ├── server/          # WebSocket/HTTP relay, audit logging
 │   ├── figma-plugin/    # Figma sandbox plugin (mutation executor)
 │   └── cli/             # `af` CLI control surface
-├── demo-app/            # Sample React app with @figma markers
+├── demo-app/            # Sample React app with @figma markers + Storybook
+│   └── .storybook/      # Storybook config (addon-mcp enabled)
 ├── docs/
 │   └── architecture-reference.md  # Full internal reference
 ├── .github/
@@ -228,6 +234,8 @@ aesthetic-function/
 | `FIGMA_FILE_KEY` | — | Figma file key |
 | `USE_LLM_ANALYZER` | `false` | Enable LLM intent parsing (optional) |
 | `TRACE` | `false` | Enable trace logging |
+| `STORYBOOK_URL` | `http://localhost:6006` | Storybook dev server URL |
+| `STORYBOOK_ENABLED` | `false` | Enable Storybook MCP adapter |
 
 See [docs/architecture-reference.md](docs/architecture-reference.md) for the complete environment variable reference.
 

claude.md

@@ -22,6 +22,12 @@ This repository implements an AI-driven Code → Design synchronization system.
    - ui.html: network allowed
    - code.ts: NO network, NO filesystem
 
+4. Storybook Dev Server (optional, Phase 16C)
+   - Runs on http://localhost:6006 (configurable)
+   - Exposes MCP endpoint via @storybook/addon-mcp at /mcp
+   - Read-only data source for cross-surface drift analysis
+   - Start with: `pnpm dev:storybook`
+
 ## Protocol Rules
 - All cross-process communication uses shared TypeScript interfaces
 - Single canonical protocol file: `/packages/shared/src/protocol.ts`
@@ -33,6 +39,12 @@ This repository implements an AI-driven Code → Design synchronization system.
 - Never mix explanation with structured output
 - Retry with repair prompts if validation fails
 
+## Design Adapter Rules
+- Adapters are read-only with default-deny tool policies
+- Storybook MCP adapter: `af design drift [component]` for cross-surface analysis
+- Storybook adapter requires dev server running (`pnpm dev:storybook`)
+- Cross-surface drift is a separate analysis pass — it does NOT modify reconciliation
+
 ## Design Token Rules
 - Prefer semantic tokens over raw values
 - Token resolution happens before Figma operations

demo-app/.storybook/main.ts

@@ -0,0 +1,15 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-mcp',
+  ],
+  framework: '@storybook/react-vite',
+  features: {
+    componentsManifest: true,
+  },
+};
+
+export default config;

demo-app/.storybook/preview.ts

@@ -0,0 +1,14 @@
+import type { Preview } from '@storybook/react';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;

demo-app/package.json

@@ -2,5 +2,23 @@
   "name": "demo-app",
   "version": "0.1.0",
   "private": true,
-  "description": "Demo React app with @figma markers for testing the watcher"
+  "description": "Demo React app with @figma markers for testing the watcher",
+  "scripts": {
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-mcp": "^0.5.0",
+    "@storybook/react": "^8.6.14",
+    "@storybook/react-vite": "^8.6.14",
+    "storybook": "^8.6.14",
+    "typescript": "^5.3.3",
+    "@types/react": "^18.3.20",
+    "@types/react-dom": "^18.3.7"
+  }
 }

demo-app/src/stories/App.stories.tsx

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { DemoButton, TestBox, WelcomeHeading } from '../App';
+
+// =============================================================================
+// DEMO BUTTON
+// =============================================================================
+
+const buttonMeta: Meta<typeof DemoButton> = {
+  title: 'Components/DemoButton',
+  component: DemoButton,
+};
+
+export default buttonMeta;
+
+type ButtonStory = StoryObj<typeof DemoButton>;
+
+export const Default: ButtonStory = {};
+
+// =============================================================================
+// TEST BOX
+// =============================================================================
+
+export const Box: StoryObj<typeof TestBox> = {
+  render: () => <TestBox />,
+};
+
+// =============================================================================
+// WELCOME HEADING
+// =============================================================================
+
+export const Heading: StoryObj<typeof WelcomeHeading> = {
+  render: () => <WelcomeHeading />,
+};

demo-app/src/stories/Card.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Card, SuccessButton, ErrorButton } from '../Card';
+
+// =============================================================================
+// CARD
+// =============================================================================
+
+const cardMeta: Meta<typeof Card> = {
+  title: 'Components/Card',
+  component: Card,
+  args: {
+    title: 'Card Title',
+    children: 'Card content goes here.',
+  },
+};
+
+export default cardMeta;
+
+type CardStory = StoryObj<typeof Card>;
+
+export const Default: CardStory = {};
+
+export const WithLongTitle: CardStory = {
+  args: { title: 'A Very Long Card Title That Wraps' },
+};
+
+// =============================================================================
+// SUCCESS BUTTON (co-located for simplicity)
+// =============================================================================
+
+export const Success: StoryObj<typeof SuccessButton> = {
+  render: () => <SuccessButton />,
+};
+
+// =============================================================================
+// ERROR BUTTON (co-located for simplicity)
+// =============================================================================
+
+export const Error: StoryObj<typeof ErrorButton> = {
+  render: () => <ErrorButton />,
+};

docs/adapter-model.md

@@ -13,6 +13,7 @@ AF uses design adapters to read data from external design systems. Adapters are
 |---------|-----------|------------|-------|
 | **Figma REST** | HTTP (Figma API) | Tokens, components, styles | 16A |
 | **Figma Console MCP** | stdio / SSE / REST fallback | Screenshots, component inspection | 16B |
+| **Storybook MCP** | StreamableHTTP / SSE / HTTP fallback | Component metadata, stories, props | 16C |
 
 ## Safety Model
 
@@ -21,6 +22,51 @@ AF uses design adapters to read data from external design systems. Adapters are
 - The MCP adapter validates tool names against an allow-list before every call
 - Blocked tools are rejected with a descriptive error, never silently dropped
 
+## Storybook MCP Adapter (Phase 16C)
+
+The Storybook MCP adapter connects to `@storybook/addon-mcp` running inside a local Storybook dev server. It enables **cross-surface drift analysis** — comparing component metadata across Figma, Storybook, and code AST.
+
+### Transport
+
+Connects via HTTP to the Storybook dev server's `/mcp` endpoint (not stdio). Falls back to direct HTTP (`/manifests/components.json`) if MCP is unavailable.
+
+### Operating Modes
+
+| Mode | Condition | Capabilities |
+|------|-----------|-------------|
+| `mcp` | MCP endpoint responds | Full: component metadata, stories, props, screenshots |
+| `http-fallback` | Server up, MCP unavailable | Reduced: component metadata from manifest only |
+| `unavailable` | Server unreachable | None — `isAvailable()` returns false |
+
+The capability manifest (`getCapabilities()`) reflects the actual operating mode. MCP-only capabilities (e.g., `readScreenshots`) report `false` in HTTP-fallback mode.
+
+### Tool Policy
+
+Same default-deny pattern as Figma Console MCP:
+
+| Tool | Status | Reason |
+|------|--------|--------|
+| `list-all-documentation` | Allowed | Read-only component listing |
+| `get-documentation` | Allowed | Read-only component metadata |
+| `get-documentation-for-story` | Allowed | Read-only story metadata |
+| `get-storybook-story-instructions` | Allowed | Read-only story instructions |
+| `run-story-tests` | **Blocked** | Side-effects (test execution) |
+| `preview-stories` | **Blocked** | May trigger renders |
+| *(any unlisted tool)* | **Blocked** | Default-deny |
+
+### Framework Guard
+
+The adapter validates that the Storybook instance is React-based. Non-React frameworks (Vue, Angular, Svelte) cause `isAvailable()` to return `false` with an explicit error.
+
+### Cross-Surface Drift Analysis
+
+The `af design drift` command compares component data across available surfaces:
+- **Figma** — variants, properties from Figma adapter
+- **Storybook** — props, stories, variant axes from Storybook MCP
+- **Code** — props, union types from AST analysis
+
+Drift findings use **corroboration rules** to filter noise: a story-derived variant is only reported if (1) the variant axis maps to a real prop, (2) the value appears in the prop's type definition. Findings carry `confidence: 'high'` (constrained union match) or `'low'` (unconstrained type like `string`).
+
 ## Detailed Reference
 
-The full adapter model, including MCP transport configuration, tool policies, and Phase 16A/16B implementation details, is documented in [architecture-reference.md](architecture-reference.md).
+The full adapter model, including MCP transport configuration, tool policies, and Phase 16A/16B/16C implementation details, is documented in [architecture-reference.md](architecture-reference.md).

docs/architecture-reference.md

@@ -534,6 +534,7 @@ The system follows a **three-legged stool** design with strict runtime boundarie
 | **Phase 16A** | Design Adapter Interface (verification-scoped) | ✅ |
 | **Phase 16A.1** | Surface Classification Metadata (adapter taxonomy) | ✅ |
 | **Phase 16B** | Figma Console MCP Adapter (read-only) | ✅ |
+| **Phase 16C** | Storybook MCP Adapter + Cross-Surface Drift Analysis | ✅ |
 
 ### Not Implemented Yet
 
@@ -557,7 +558,7 @@ The reconciliation system is **feature-complete through Phase 14F**. Key capabil
 - **Unified Reconcile CLI (14A–14F)**: `figma:reconcile` entry point, profiles (local/record/ci), bundle artifacts, GitHub Actions matrix workflow, multi-source discovery
 - **Configuration & Profiles (15A–15B)**: `af.config.json`, named policy profiles (designer-first, code-first, balanced, strict-review)
 - **CLI & Inspector (15C–15D)**: Unified `af` CLI (control surface, not runtime), artifact listing/inspection/trace
-- **Design Adapters (16A–16B)**: Read-only design adapter interface, Figma Console MCP adapter, surface classification metadata (taxonomy layer for adapter categorization)
+- **Design Adapters (16A–16C)**: Read-only design adapter interface, Figma Console MCP adapter, Storybook MCP adapter, surface classification metadata, cross-surface drift analysis
 
 Echo suppression prevents feedback loops when AST writes trigger file save events.
 

package.json

@@ -22,7 +22,8 @@
     "demo:watcher": "echo '👁 Starting watcher...' && pnpm --filter @aesthetic-function/watcher watch",
     "demo:feature": "echo '🎯 Running feature orchestrator...' && pnpm --filter @aesthetic-function/watcher cli:feature",
     "demo:fast": "echo '⚡ Quick demo: server + watcher + feature (use --prompt)' && concurrently -n server,watcher 'pnpm demo:server' 'sleep 2 && pnpm demo:watcher'",
-    "demo:tunnel": "echo '🚇 Expose server for Figma plugin...' && pnpm tunnel && echo 'Copy the HTTPS URL to Figma plugin settings'"
+    "demo:tunnel": "echo '🚇 Expose server for Figma plugin...' && pnpm tunnel && echo 'Copy the HTTPS URL to Figma plugin settings'",
+    "dev:storybook": "cd demo-app && npx storybook dev -p 6006"
   },
   "engines": {
     "node": ">=18.0.0",