@hegemonart/get-design-done 1.0.7

package/connections/preview.md

@@ -0,0 +1,173 @@
+# Claude Preview / Playwright MCP — Connection Specification
+
+This file is the connection specification for the Claude Preview (Playwright-backed) MCP within the get-design-done pipeline. Its primary role is to provide live browser screenshots for the verify stage — replacing `? VISUAL` flags with real rendered evidence. It also powers dark-mode screenshot capture in the darkmode stage and before/after screenshot delta in the compare stage. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- None. The Preview MCP is built into the Claude Code environment — no install required, no external package dependency.
+
+**Verification:**
+
+After session start, run:
+
+```
+ToolSearch({ query: "Claude_Preview", max_results: 5 })
+```
+
+Expect non-empty results listing `mcp__Claude_Preview__*` tools. If results are empty, the Preview MCP is not loaded in this session — all Preview steps will be skipped and visual checks will remain as `? VISUAL` static analysis only.
+
+**Warning — naming confusion:**
+
+This spec targets ONLY the built-in Claude Preview MCP. It uses the `mcp__Claude_Preview__` prefix (capital C, capital P). Do NOT confuse with any external Playwright npm packages (`@playwright/test`, `playwright-chromium`, etc.) or with `mcp__computer-use__*` screenshot tools. This spec covers ONLY `mcp__Claude_Preview__*` tools. Other Playwright-related packages cannot be invoked via the MCP protocol.
+
+---
+
+## Tools
+
+All tools use the `mcp__Claude_Preview__` prefix.
+
+| Tool shortname | Full name | Returns | Pipeline use |
+|---------------|-----------|---------|--------------|
+| `preview_list` | `mcp__Claude_Preview__preview_list` | Array of running preview sessions (may be empty) | **Lightweight probe** — used as the availability check; does not start a browser |
+| `preview_start` | `mcp__Claude_Preview__preview_start` | Preview session object with URL | Start a new preview server; used in compare stage interaction mode |
+| `preview_stop` | `mcp__Claude_Preview__preview_stop` | Confirmation of stop | Stop a preview server; used at end of compare stage |
+| `preview_navigate` | `mcp__Claude_Preview__preview_navigate` | Navigation confirmation | Navigate to a route URL before screenshot; used in verify, compare, darkmode |
+| `preview_screenshot` | `mcp__Claude_Preview__preview_screenshot` | Base64-encoded PNG image | **Primary verify workhorse** — captures rendered page screenshot; save to `.design/screenshots/<route>.png` by path, do NOT embed base64 inline |
+| `preview_eval` | `mcp__Claude_Preview__preview_eval` | JS return value | **Dark mode injection tool** — inject `document.documentElement.classList.add('dark')` or project-specific toggle; also used for focus-visible checks |
+| `preview_snapshot` | `mcp__Claude_Preview__preview_snapshot` | Accessibility tree (Aria roles, labels, focus state) | Used in Phase 4B for focus-visible heuristic check |
+| `preview_inspect` | `mcp__Claude_Preview__preview_inspect` | Computed styles, bounding box for an element | Used in Phase 4B for visual rhythm / spacing verification |
+| `preview_click` | `mcp__Claude_Preview__preview_click` | Click confirmation | Interaction mode: trigger UI state before screenshot |
+| `preview_fill` | `mcp__Claude_Preview__preview_fill` | Fill confirmation | Interaction mode: populate form fields before screenshot |
+| `preview_console_logs` | `mcp__Claude_Preview__preview_console_logs` | Array of console log entries | Diagnostic — capture JS errors during screenshot capture |
+| `preview_logs` | `mcp__Claude_Preview__preview_logs` | Server-side log entries | Diagnostic — server logs during dev server operation |
+| `preview_network` | `mcp__Claude_Preview__preview_network` | Network request/response log | Diagnostic — identify failed asset loads affecting screenshot |
+| `preview_resize` | `mcp__Claude_Preview__preview_resize` | Resize confirmation | Set viewport dimensions (e.g., mobile 375px, desktop 1280px) |
+
+`preview_list` is preferred for probing because it returns the current session list without starting a new browser context. `preview_screenshot` is the primary workhorse for the verify and compare stages. `preview_eval` is the dedicated dark-mode injection tool.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Skill/Agent | Tools used | Purpose |
+|-------|------------|------------|---------|
+| verify | `skills/verify/SKILL.md` + `agents/design-verifier.md` | `preview_navigate`, `preview_screenshot`, `preview_eval`, `preview_snapshot`, `preview_inspect` | Per-route screenshots for `? VISUAL` heuristics (H-02, H-06, H-07); dark mode parity via `preview_eval`; focus-visible via `preview_snapshot` |
+| compare | `skills/compare/SKILL.md` | `preview_start`, `preview_navigate`, `preview_screenshot`, `preview_stop` | Before/after screenshot delta in COMPARE-REPORT.md |
+| darkmode | `skills/darkmode/SKILL.md` | `preview_navigate`, `preview_eval`, `preview_screenshot` | Forced dark-mode screenshots for DARKMODE-AUDIT.md `## Dark Mode Rendering` section |
+
+---
+
+## Availability Probe
+
+**Call ToolSearch first — always.** In Claude Code sessions with many MCP servers, `mcp__Claude_Preview__*` tools may be in the deferred tool set (not loaded into context at session start). Calling a deferred tool directly fails silently or errors. ToolSearch loads the tools into context and confirms their presence in a single call.
+
+**Preview probe sequence:**
+
+```
+Step P1 — ToolSearch check:
+  ToolSearch({ query: "Claude_Preview", max_results: 5 })
+  → Empty result      → preview: not_configured  (skip all Preview steps)
+  → Non-empty result  → proceed to Step P2
+
+Step P2 — Live tool call:
+  call mcp__Claude_Preview__preview_list
+  → Success (returns array, even empty)  → preview: available
+  → Error                                → preview: unavailable
+```
+
+Write the result to `.design/STATE.md <connections>` immediately after probing.
+
+**Two operating modes:**
+
+**Screenshot mode** (primary — used in verify and darkmode):
+1. `preview_navigate` to route URL (e.g., `http://localhost:3000/dashboard`)
+2. `preview_screenshot` → returns base64 PNG
+3. Save to `.design/screenshots/<route>.png` — reference by path in markdown
+4. Repeat per route
+
+**Interaction mode** (used in compare):
+1. `preview_start` → returns session URL (if no server already running)
+2. `preview_navigate` to route URL
+3. `preview_click` / `preview_fill` to reach desired UI state
+4. `preview_screenshot` → save to path
+5. `preview_stop` when done
+
+---
+
+## Fallback Behavior
+
+When preview is `not_configured` or `unavailable`, stages degrade gracefully — no error is raised.
+
+**verify stage (`skills/verify/SKILL.md` + `agents/design-verifier.md`):**
+
+- Skip Phase 4B screenshot evidence loop entirely
+- Keep existing `? VISUAL` static analysis path for H-02, H-06, H-07 heuristics
+- Mark all Phase 4B checks: `[SKIPPED — browser not available]`
+- Design-verifier continues to Phase 5 gap analysis with partial scores
+
+**compare stage (`skills/compare/SKILL.md`):**
+
+- Omit `## Screenshot Delta` section from COMPARE-REPORT.md
+- Emit exactly: `Screenshot delta skipped — preview not configured.` in the Notes section
+- All text-based delta sections (Score Delta, Anti-Pattern Delta, Must-Have Status, Design Drift) are unaffected
+
+**darkmode stage (`skills/darkmode/SKILL.md`):**
+
+- Omit `## Dark Mode Rendering` section from DARKMODE-AUDIT.md
+- Emit: `Visual dark mode check skipped — preview not configured.` in the Notes section
+- All static architecture detection, contrast audit, and token override checks are unaffected
+
+Neither stage appends a `<blocker>` for a missing Preview connection — Preview is an enhancement, not a requirement. If a `must_have` explicitly requires browser-rendered evidence, THEN append a blocker.
+
+---
+
+## STATE.md Integration
+
+Every stage writes its probe result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+preview: available
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | `preview_list` returned a successful response (array, even empty) |
+| `unavailable` | Tool is in the session but errored (no running server, tool timeout, internal error) |
+| `not_configured` | ToolSearch returned empty for `Claude_Preview` — MCP not registered in this session |
+
+**Which stages probe vs. read:**
+
+- **scan** — probes at pipeline entry; writes initial status to STATE.md `<connections>`
+- **verify** — probes at stage entry (re-confirm; tool availability can change between sessions)
+- **compare** — probes at stage entry
+- **darkmode** — probes at stage entry
+
+Downstream stages (verify, compare, darkmode) re-probe rather than blindly reading STATE.md because MCP availability can change between sessions. However, if STATE.md already contains a `preview:` status from a prior stage in the SAME session, that status can be trusted for the rest of that session.
+
+---
+
+## Caveats and Pitfalls
+
+1. **`preview_screenshot` returns base64 — save by path.** The tool returns a full base64-encoded PNG. Embedding multiple screenshots inline in DESIGN-VERIFICATION.md or COMPARE-REPORT.md creates 500KB+ files that are unreadable and slow. **Always save to `.design/screenshots/<route>.png` and reference via file path in markdown. Only embed base64 for one critical single-image check at most.**
+
+2. **`preview_list` is the correct probe tool.** It returns the list of current preview sessions without starting a new browser context. Using `preview_start` as a probe would spin up a browser unnecessarily. Use `preview_list` always for probing.
+
+3. **Dark mode injection — check the project's actual toggle mechanism.** The default injection `document.documentElement.classList.add('dark')` works for Tailwind dark mode and most class-based toggles. However, some projects use `setAttribute('data-theme', 'dark')`, `classList.add('theme-dark')`, or CSS `prefers-color-scheme` media queries only (where JS injection has no effect). **Before injecting, check DESIGN-CONTEXT.md D-XX decisions to confirm the project's dark mode mechanism.** Alternatives:
+   - Tailwind: `document.documentElement.classList.add('dark')`
+   - data-theme: `document.documentElement.setAttribute('data-theme', 'dark')`
+   - Custom class: `document.documentElement.classList.add('theme-dark')`
+   - Media query only: `preview_eval` cannot force this; use `preview_resize` or check if a system media override is available
+
+4. **`preview_start` may require a running dev server.** If the project has no dev server running, `preview_list` may return an empty array — that is `preview: available` (not unavailable). The empty array means the MCP is functional but no sessions are running. The verify stage should attempt `preview_navigate` to `http://localhost:3000` (or project-configured port) and handle 404 / connection-refused gracefully — if navigation fails, update STATE.md to `preview: unavailable` for this session and fall back to static analysis.
+
+5. **`.design/screenshots/` should be gitignored.** Screenshots may contain rendered UI with sensitive data (user info, internal tools). The `.design/` directory is already gitignored in get-design-done projects (see Phase 1). Confirm `.gitignore` includes `.design/` before saving screenshots.

package/connections/refero.md

@@ -0,0 +1,189 @@
+# Refero MCP — Connection Specification
+
+This file is the connection specification for Refero within the get-design-done pipeline. It lives in `connections/` alongside other connection specs. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+Refero is the **discover stage's primary visual reference tool**. It retrieves real product screenshots and design references, replacing "imagine how this should look" with "look at how Linear/Stripe/Phantom/Raycast did it."
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- Refero account with an active subscription (required for search access)
+- Refero MCP installed via Refero's MCP setup instructions (vendor-specific — follow Refero's official documentation; do not use a generic Claude Code MCP add command unless Refero documents one)
+
+**Install:**
+
+Install per Refero's MCP setup instructions, then restart the Claude Code session. After restart, the `mcp__refero__*` tools appear in the session.
+
+**Verification:**
+
+```
+ToolSearch({ query: "refero", max_results: 10 })
+```
+
+Expect non-empty results. If empty, the Refero MCP is not registered — complete the install steps and restart.
+
+**Note on tool names:** Exact tool names may vary between Refero MCP versions. Always verify via ToolSearch before calling any `mcp__refero__*` tool. Do not hardcode tool names in prompts — treat the ToolSearch result as the authoritative list.
+
+---
+
+## Why refero is non-negotiable
+
+Without references, LLMs converge on:
+- Inter / Space Grotesk / DM Sans typefaces
+- Purple→blue gradients on white backgrounds
+- Glassmorphism + rounded rectangles + generic drop shadows
+- Card-in-card layouts, sparkline-as-decoration
+- Cyan accents on dark backgrounds
+- Identical hero-metric templates
+
+With references, you copy the *structure* of best-in-class work and adapt the aesthetic to your brand. This is how pros design.
+
+## When to use refero
+
+**Always at the start of the discover stage.** No exceptions:
+- Building any UI → pull references for similar products and layouts
+- Writing UX copy → pull references for how the canonical products in that category write the equivalent string
+- Designing animations → pull references for the interaction (then pair with `emil-design-eng`)
+- Auditing → pull references for "what best-in-class looks like" before calling something bad
+
+## Tools available (after session restart)
+
+The refero MCP exposes tools under `mcp__refero__*` after the next session restart. Check available tools via ToolSearch:
+
+```
+ToolSearch({ query: "refero", max_results: 30 })
+```
+
+Typical tool set (names may vary — verify via ToolSearch on first use):
+- **search** — semantic search across refero's indexed design corpus
+- **get** / **fetch** — retrieve a specific reference by ID or URL
+- **browse** by category / tag / brand
+
+## Search strategy
+
+Run **at least 2 queries per task**, one structural + one aesthetic:
+
+### Structural queries (what the thing IS)
+- "checkout flow mobile"
+- "empty state messaging app"
+- "admin table dashboard with filters"
+- "login screen minimal"
+- "onboarding wizard steps"
+- "settings page tabs"
+- "data visualization KPI card"
+
+### Aesthetic queries (how it should FEEL)
+- "editorial dark fintech"
+- "brutalist portfolio"
+- "retro-futuristic music player"
+- "warm terracotta SaaS landing"
+- "neutral Swiss design dashboard"
+- "Japanese minimalist e-commerce"
+- "maximalist magazine web"
+
+### Brand-specific queries (when you have a north star)
+- "linear app dashboard" — fast, dense, unimpressed
+- "stripe payments docs" — clear, direct, honest
+- "phantom wallet crypto" — calm, editorial, confident
+- "raycast launcher" — sleek, opinionated
+- "vercel dashboard" — black/white precision
+
+## Workflow
+
+```
+1. refero search "checkout flow mobile"        # structural
+2. refero search "warm editorial consumer app" # aesthetic
+3. pick 3-7 that match the brief
+4. save URLs + brief notes into the discover reference pack
+5. if relevant DESIGN.md exists for one of them:
+   → read ~/.claude/libs/awesome-design-md/{brand}/README.md
+6. proceed to the plan stage with the pack
+```
+
+## Citing references in output
+
+When presenting designs, **always name the references**. Don't say "I designed this." Say "This takes Linear's issue list structure and applies Claude's editorial warmth." This:
+- Shows the user the logic so they can push back precisely
+- Makes iteration faster (user can say "less Linear, more Notion")
+- Prevents claims of originality that don't hold up
+
+## STATE.md Integration
+
+Every stage that probes Refero writes the result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | ToolSearch returned non-empty results for `refero` |
+| `unavailable` | Refero tools are present but a live call errored |
+| `not_configured` | ToolSearch returned empty for `refero` — MCP not registered |
+
+**Probe pattern (ToolSearch-only — no tool call needed):**
+
+```
+ToolSearch({ query: "refero", max_results: 5 })
+  → Empty result     → refero: not_configured
+  → Non-empty result → refero: available
+```
+
+Rationale: calling a real Refero search as the probe would waste tokens and incur API cost before confirming the connection is even needed. ToolSearch presence is sufficient — if the tools are registered, the connection is available. A live call failure would downgrade to `unavailable`, but this is rare and best handled when an actual search is attempted.
+
+**Which stages probe Refero:** the discover stage (via `agents/design-context-builder.md`). The scan, plan, and verify stages do not use Refero and do not probe it.
+
+---
+
+## Fallback chain
+
+When Refero is `not_configured` or `unavailable`, the discover stage falls back through this three-tier chain:
+
+**Tier 1 — Refero MCP** (`mcp__refero__search` or verified tool name from ToolSearch):
+Real product screenshots from Refero's corpus of 125,000+ screens. Best quality, broadest coverage. Use when `refero: available`.
+
+**Tier 2 — awesome-design-md library** (`~/.claude/libs/awesome-design-md/design-md/`):
+68 brand archetypes with structured DESIGN.md token files. Pick 1–2 closest matches by brand category. Provides concrete token values (colors, fonts, spacing) you can copy-adapt. Use when Refero is unavailable.
+
+**Tier 3 — WebFetch** (getdesign.md URLs from the awesome-design-md list):
+Last resort. Fetch design reference URLs directly. Slower and less reliable than the MCP. Use only when tiers 1 and 2 are both unavailable.
+
+Never proceed without references — that's the whole point of Discover.
+
+## Fallbacks if refero is down / not installed
+
+1. **awesome-design-md library** — `~/.claude/libs/awesome-design-md/design-md/` has 68 real brand archetypes with DESIGN.md pointers. Pick 1–2 closest matches.
+2. **Figma MCP** — if the user's project has Figma connected, read existing designs or search their design system.
+3. **Last resort: WebFetch** getdesign.md URLs from the awesome-design-md list.
+
+Never proceed without references — that's the whole point of Discover.
+
+## Combining refero with awesome-design-md
+
+```
+Refero          → how does best-in-class look right now (images)
+awesome-design-md → structured DESIGN.md tokens for 68 brands (text)
+```
+
+Use both. Refero for visual direction, awesome-design-md for concrete token values (colors, fonts, spacing) you can copy-adapt.
+
+## Anti-pattern
+
+Do NOT use refero to:
+- Collect a huge dump of references and paste them all into the response (noise)
+- Justify a direction you've already decided on (confirmation bias; pull first, then decide)
+- Skip the plan stage ("the references tell me the brand") — references inform direction, they don't *replace* context gathering with the user.
+
+## If refero's API changes
+
+Keep this file up to date. If tool names or invocation patterns shift, update the examples here and adjust the routing in SKILL.md.

package/connections/storybook.md

@@ -0,0 +1,280 @@
+# Storybook — Connection Specification
+
+This file is the connection specification for Storybook within the get-design-done pipeline. It lives in `connections/` alongside other connection specs. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+Storybook is a local or CI dev server probed via HTTP `GET /index.json`. Its role is to serve as the **authoritative component inventory** for the discover stage (replacing grep-based enumeration) and to provide per-story a11y test output for the verify stage. No dedicated Storybook MCP is required — the probe is HTTP-based, using `curl` directly from Bash. For the full connection index see `connections/connections.md`.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- Storybook installed as a dev dependency:
+  ```bash
+  npm install --save-dev storybook @storybook/react @storybook/addon-a11y
+  ```
+- Project configured in `.storybook/` (run `npx storybook init` for first-time setup — this is a one-time developer step, not a probe step)
+
+**Start command:**
+
+```bash
+npx storybook dev -p 6006
+```
+
+**Verification:**
+
+```bash
+curl -sf http://localhost:6006/index.json | head -1
+```
+
+Expect JSON with `"v": 5` as the first field. If this returns empty, the dev server is not running — start it with the command above.
+
+**Note on versions:** Storybook 8 serves `/index.json`. Storybook 7 serves `/stories.json`. The probe tries both (see Availability Probe section). When Storybook 8 is confirmed, always prefer `index.json`.
+
+---
+
+## Why Storybook is non-negotiable
+
+Storybook declares every component state **explicitly and exhaustively**. A component with five variants (Primary, Disabled, Loading, WithIcon, Destructive) has five stories — not one component grep match.
+
+Grep-based component inventory:
+- Misses unnamed variants (a `<Button variant="ghost">` used inline is invisible to grep)
+- Generates false positives from test files, storybook stories themselves, and import declarations
+- Cannot enumerate story args or describe what states exist
+
+`index.json` is the canonical, exhaustive component state register. It has zero false positives (every entry is a real, intentionally-declared story) and zero missed states (if a state is undeclared, it does not exist in Storybook either — which is itself a signal).
+
+The verify stage iterates every declared story state to check a11y coverage. This is only possible because `index.json` enumerates them.
+
+---
+
+## When to use Storybook
+
+**At the discover stage entry** (when the dev server is running) to build the authoritative component inventory. Replaces the grep-based component scan in `design-context-builder.md` Step 1.
+
+**At the verify stage** after the design executor runs, to enumerate all story states for a11y coverage via `npx storybook test --ci`.
+
+**At the design stage** (project detection only — dev server not required) to determine whether to emit `.stories.tsx` stubs alongside newly scaffolded components.
+
+---
+
+## Endpoints (HTTP GET — not MCP tools)
+
+Storybook has no dedicated MCP. All integration is via HTTP GET to the running dev server or via Bash commands against the project files.
+
+| Endpoint | Returns | Pipeline use |
+|----------|---------|-------------|
+| `GET /index.json` | Flat map of storyId → `{id, title, name, importPath, type, tags}` | Authoritative component inventory (Storybook 8) |
+| `GET /stories.json` | Equivalent flat map in Storybook 7 format | Fallback for older Storybook versions |
+
+**CRITICAL: Storybook 8 `index.json` does NOT include `parameters`.** Do NOT attempt to read `entry.parameters` from index.json entries — the field does not exist in Storybook 8. A11y configuration lives in `.storybook/preview.ts`, not in index.json. (See Caveats section.)
+
+---
+
+## index.json format (Storybook 8)
+
+```json
+{
+  "v": 5,
+  "entries": {
+    "button--primary": {
+      "id": "button--primary",
+      "title": "Button",
+      "name": "Primary",
+      "importPath": "./src/components/Button.stories.tsx",
+      "type": "story",
+      "tags": ["autodocs"]
+    },
+    "button--disabled": {
+      "id": "button--disabled",
+      "title": "Button",
+      "name": "Disabled",
+      "importPath": "./src/components/Button.stories.tsx",
+      "type": "story",
+      "tags": []
+    }
+  }
+}
+```
+
+**Key fields per entry:**
+
+| Field | Description |
+|-------|-------------|
+| `id` | Kebab-case unique identifier: `{component-title}--{story-name}` |
+| `title` | Component name / hierarchy path (e.g., `"Components/Button"` or `"Button"`) |
+| `name` | Story variant name (e.g., `"Primary"`, `"Disabled"`, `"With Icon"`) |
+| `importPath` | Relative path to the `.stories.tsx` file |
+| `type` | `"story"` \| `"docs"` \| `"component"` — filter to `"story"` for variant enumeration |
+| `tags` | Array of strings; `"autodocs"` marks auto-generated docs entries |
+
+**Component inventory from index.json:** Group entries by `title` field to get the component list. Each unique `title` is one component; entries under it are its declared states. Example:
+
+```
+Title: "Button"
+  States: Primary, Secondary, Disabled, Loading, WithIcon
+  Stories file: ./src/components/Button.stories.tsx
+
+Title: "Input"
+  States: Default, Error, Disabled, WithHelperText
+  Stories file: ./src/components/Input.stories.tsx
+```
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Agent | Endpoint / Command | Purpose |
+|-------|-------|--------------------|---------|
+| discover | `agents/design-context-builder.md` | `GET /index.json` | Component inventory (replaces grep) |
+| verify | `agents/design-verifier.md` | `npx storybook test --ci` | Per-story a11y output for a11y gap analysis |
+| design | `skills/design/SKILL.md` | `.storybook/` project detection (no server required) | `.stories.tsx` stub emission alongside new components |
+
+---
+
+## Availability Probe
+
+The probe is two-phase. Run both steps in sequence at stage entry.
+
+### Step B1 — Project detection
+
+```bash
+ls .storybook/ 2>/dev/null || grep '"storybook"' package.json 2>/dev/null
+```
+
+- **Found** → `storybook_project: true` → proceed to Step B2
+- **Not found** → `storybook: not_configured` — skip all Storybook steps
+
+### Step B2 — Dev server detection
+
+```bash
+curl -sf http://localhost:6006/index.json 2>/dev/null | head -1
+```
+
+- **Returns JSON** → `storybook: available` (Storybook 8 endpoint confirmed)
+- **Fails (empty / connection refused)** → try the Storybook 7 compat endpoint:
+
+```bash
+curl -sf http://localhost:6006/stories.json 2>/dev/null | head -1
+```
+
+  - **Returns JSON** → `storybook: available` (using `stories.json` compat endpoint — log which was used)
+  - **Fails** → `storybook: unavailable` (project detected but dev server not running)
+
+### Three-value result
+
+| Status | Meaning |
+|--------|---------|
+| `available` | Dev server running; `index.json` (or `stories.json` compat) confirmed |
+| `unavailable` | Project has Storybook (`.storybook/` present) but dev server is not running |
+| `not_configured` | No `.storybook/` directory and no `"storybook"` in `package.json` |
+
+Write the resulting status to `.design/STATE.md` `<connections>`.
+
+---
+
+## Fallback Behavior
+
+**discover stage:**
+
+- `storybook: available` → read `index.json`, group entries by `title`, use as authoritative component list
+- `storybook: unavailable` → fall back to grep-based component inventory; note in output: "component inventory via grep (storybook server not running)"
+- `storybook: not_configured` → grep inventory only; no Storybook-specific steps
+
+**verify stage:**
+
+- `storybook: available` → run `npx storybook test --ci 2>&1 | tee .design/storybook-a11y-report.txt`; pass report to design-verifier
+- `storybook: unavailable` → skip per-story a11y loop; run standard WCAG grep-based a11y checks only
+- `storybook: not_configured` → skip; emit no note (this is an opt-in feature)
+
+**design stage:**
+
+- `storybook_project: true` (B1 found — dev server irrelevant) → emit `.stories.tsx` stubs alongside all new components
+- `storybook: not_configured` (B1 not found) → skip `.stories.tsx` stub emission
+
+Note: design stage uses **only Step B1** (project detection). Whether the dev server is running (B2) does not affect `.stories.tsx` stub emission — if the project has Storybook configured, new components need stories regardless.
+
+---
+
+## STATE.md Integration
+
+Every stage that probes Storybook writes the result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+storybook: available
+</connections>
+```
+
+**Status value table:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | HTTP GET confirmed; `index.json` (or stories.json) returned valid JSON |
+| `unavailable` | Project has Storybook configured but dev server is not running |
+| `not_configured` | No `.storybook/` directory and no storybook dependency in `package.json` |
+
+The scan stage writes the initial status at pipeline startup. Subsequent stages (discover, verify) re-read from STATE.md without re-probing unless they explicitly re-probe as part of their own stage entry.
+
+---
+
+## .stories.tsx CSF Stub Template
+
+When `storybook_project: true`, the design stage emits this stub alongside every new component file:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { ComponentName } from './ComponentName';
+
+const meta: Meta<typeof ComponentName> = {
+  title: 'Components/ComponentName',
+  component: ComponentName,
+  parameters: { a11y: { test: 'error' } },
+};
+export default meta;
+
+type Story = StoryObj<typeof ComponentName>;
+
+export const Default: Story = { args: {} };
+export const Primary: Story = { args: { variant: 'primary' } };
+export const Disabled: Story = { args: { disabled: true } };
+```
+
+Adjust `title` to match the component's directory structure:
+- `src/components/Button.tsx` → `title: 'Components/Button'`
+- `src/features/auth/LoginForm.tsx` → `title: 'Features/Auth/LoginForm'`
+
+The `parameters.a11y.test = 'error'` setting makes axe-core a11y violations fail the Vitest test run, surfacing accessibility issues as CI failures.
+
+---
+
+## Caveats and Pitfalls
+
+**1. Storybook 8 `index.json` does NOT contain `parameters`**
+
+Storybook 7's `stories.json` included a `parameters` field per story (used by some tooling to detect addon config). Storybook 8 removed this from `index.json`. Never read `entry.parameters.a11y` from index.json — it does not exist and will return `undefined` for all entries, making a11y integration appear unconfigured even when it is. A11y configuration lives in `.storybook/preview.ts` — read that file to determine if `@storybook/addon-a11y` is enabled.
+
+**2. Group by `title` to get component list**
+
+Each unique `title` is one component. Each entry under that title is a declared story state. Iterating entries without grouping gives stories, not components. For a component inventory, iterate unique titles.
+
+**3. Filter out `type: "docs"` entries**
+
+Auto-generated docs entries (`type: "docs"`, often tagged `"autodocs"`) are not story states. Filter to `type: "story"` when building the variant list.
+
+**4. First-time Storybook setup requires `npx storybook init`**
+
+This is a one-time developer setup step, not part of the probe. The probe only detects whether Storybook is already configured in the project — it does not initialize Storybook.
+
+**5. Chromatic dependency**
+
+Chromatic requires Storybook. If `storybook: not_configured`, Chromatic cannot function even if its API token is present. See `connections/chromatic.md` for details.
+
+**6. `stories.json` vs `index.json` version split**
+
+Always probe `index.json` first. Only fall back to `stories.json` if `index.json` returns 404 or an error. Log which endpoint was used so downstream steps know the Storybook version.