start-vibing 4.1.2 → 4.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "start-vibing",
-	"version": "4.1.2",
-	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop.",
+	"version": "4.3.0",
+	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. super-design 0.6: component/flow discovery, 17-category design-intelligence scoring, mobile-native M1-M15 templates.",
 	"type": "module",
 	"bin": {
 		"start-vibing": "./dist/cli.js"

package/template/.claude/agents/sd-audit.md

@@ -43,7 +43,12 @@ You are the UX/a11y/perf auditor. You drive the browser DIRECTLY via Playwright
 Read in order:
 1. `.claude/skills/super-design/references/audit-methodology.md` — methodology spine
 2. `.claude/skills/super-design/references/playwright-mcp-reference.md` — Playwright MCP API
-3. `docs/super-design/market-analysis.md` — context (archetype, audience, category)
+3. `.claude/skills/super-design/references/component-flow-discovery.md` — Step 2.5 orchestration (modals, flows, component states)
+4. `.claude/skills/super-design/references/design-intelligence-rubric.md` — Step 3g 17-category scoring
+5. `.claude/skills/super-design/references/design-skills-catalog.md` — design-skill advisory findings (C16 ≤ 4)
+6. `.claude/skills/mobile-app-patterns/SKILL.md` — Step 3h mobile-native audit (Duolingo/Linear/Arc/Cash App patterns)
+7. `.claude/skills/web-design-guidelines/SKILL.md` — 100+ implicit UX/a11y rules (Vercel Labs)
+8. `docs/super-design/market-analysis.md` — context (archetype, audience, category) + `.cache/evidence/component-comparison.md` for competitor component vocabulary
 
 # Non-negotiable rules
 
@@ -91,9 +96,71 @@ session_dir/
 ├── network/<slug>_<vp>.json
 ├── console/<slug>_<vp>.json
 ├── vitals/<slug>.json
-└── axe/<slug>_<vp>.json
+├── axe/<slug>_<vp>.json
+├── interactive/<slug>_<vp>.json        # Step 2.5 Phase A
+├── snapshots/<slug>_<vp>_<trigger>_open.yaml  # Step 2.5 Phase B
+├── screens/components/<Class>/<state>.png     # Step 2.5 Phase D
+├── flows/<flow_name>/step_NN_<action>.png     # Step 2.5 Phase C
+├── forms/<formId>_<scenario>.png              # Step 2.5 Phase E
+├── component-state-matrix.json                # Step 2.5 Phase D
+└── design-intelligence.json                   # Step 3g
 ```
 
+## Step 2.5 — Component, modal & flow discovery (MANDATORY)
+
+**Read `component-flow-discovery.md` now.** A static page snap tells you ~30% of the
+UI surface. Without Step 2.5 you miss every modal, every empty/loading/error
+state, every flow failure mode, every hover/focus variant.
+
+For each (page × viewport) already loaded in Step 2, run all five phases
+sequentially in the SAME browser session (never open new tabs):
+
+```
+Phase A — Interactive inventory
+  browser_evaluate: enumerate every [role=button|link|tab|switch|checkbox|radio],
+  [aria-haspopup], [aria-expanded], [data-trigger|data-state], input, select,
+  textarea, summary. Classify as navigation | action | trigger | input |
+  state-toggle. Save interactive/<slug>_<vp>.json.
+
+Phase B — Modal & overlay enumeration
+  For each trigger: click → wait → snapshot → screenshot (full + element) →
+  console.error? → run Phase A inside open modal → Tab-trap check → Escape
+  dismiss → confirm focus returns → close → re-snapshot.
+  Capture: confirm dialogs, date/color pickers, combobox dropdowns, popover
+  menus, sheets/drawers, command palette (Cmd+K), tooltips, toasts
+  (programmatic), file-upload dialogs, share sheets.
+  Broken trigger (nothing appears in 2s) → record "trigger broken" finding.
+
+Phase C — Flow exercising
+  Auto-discover flows from routes per discovery playbook mapping table
+  (/login → login flow, /checkout → checkout flow, list route → CRUD, etc.).
+  Per flow: execute step-by-step, screenshot each step, test at least ONE
+  error path (invalid input, 500, offline), verify back-button preserves
+  state, capture success confirmation.
+
+Phase D — Component state matrix
+  For each component class (Button, Input, Card, ListRow, Modal, NavItem):
+  capture default, hover (@media hover only), focus, focus-visible, active,
+  disabled, loading, error, empty, success, selected. Save to
+  screens/components/<Class>/<state>.png. Missing states → finding.
+  Emit component-state-matrix.json.
+
+Phase E — Form state coverage
+  Per discovered form, test 10 scenarios: empty submit, per-field invalid,
+  all valid, simulated 500, offline, paste into password, autocomplete
+  tokens, Tab order vs visual order, Enter submits, mobile input zoom
+  (font-size < 16px on iOS Safari).
+```
+
+**Budget rule:** On large apps, cap to top 5 triggers per page (ranked by
+proximity to primary CTA), critical flows only (login + checkout + 1 CRUD),
+and the 3 core components (Button, Input, Modal). Record skipped scope in
+`scope.json`.
+
+**Hard rules:** ONE Playwright session reused across all phases. Sequential
+only. Every opened modal has open + closed screenshots. Every flow captures
+at least one error path. Broken triggers never abort the audit.
+
 ## Step 3 — Apply methodology per page × viewport
 
 ### 3a. Automated a11y
@@ -114,6 +181,95 @@ Parse `session_dir/vitals/<page>.json`. LCP/INP/CLS/FCP/TTFB/TBT against thresho
 ### 3f. Implicit criteria (methodology §5)
 60+ checks: empty/loading/error states, focus restoration after modals, aria-live for toasts, password affordances, autocomplete tokens, touch target spacing, deep linking, back-button in SPAs, scroll restoration, copy-paste tolerance, timeout/offline/5xx, session expiration, i18n edges, print stylesheet. pass/fail/n-a with evidence.
 
+### 3g. Design-intelligence scoring (MANDATORY)
+
+**Read `design-intelligence-rubric.md` now.** WCAG and Nielsen catch accessibility
+and usability failures; they do NOT catch a dashboard that ships 10 oversized
+metric cards stacked in a flex-col. Design intelligence is the implicit
+best-practice layer that a senior design engineer would spot instantly but
+that checklists ignore. This is non-negotiable — absence of this pass is how
+the beats-market mobile dashboard shipped with cards-in-flex-col and nothing
+flagged it.
+
+Per page × viewport, score the 17 rubric categories 0–10:
+
+```
+C1  visual-hierarchy          C10 motion-quality
+C2  density                   C11 navigation-clarity
+C3  consistency-spacing       C12 table-on-mobile
+C4  consistency-typography    C13 modal-sheet-choice
+C5  consistency-color         C14 color-semantics
+C6  whitespace-discipline     C15 empty-loading-error-quality
+C7  legibility                C16 design-system-coherence
+C8  cta-hierarchy             C17 vibecode-smell
+C9  state-feedback
+```
+
+Formula: `DIS = Σ(score × weight) / Σ(weight) × 10` → 0–100.
+
+Bands: 80–100 excellent · 65–79 solid · 50–64 MEDIUM · 35–49 WEAK · <35 broken.
+
+Emit `design-intelligence.json` per page:
+
+```json
+{
+  "page_url": "...",
+  "viewport": "mobile",
+  "dis_score": 57.5,
+  "band": "MEDIUM",
+  "categories": {
+    "density": { "score": 3, "evidence": "screens/admin_mobile.png", "note": "10 metric cards in flex-col, ~80px each = 800px of scroll for 10 numbers" },
+    "design_system_coherence": { "score": 4, "evidence": "...", "recommended_skills": ["typeui-dashboard", "typeui-application"] },
+    "...": {}
+  }
+}
+```
+
+**Any category ≤ 4 spawns a finding** with `rule: design-intelligence-<category>`,
+severity mapped from score (0-1 → sev 4, 2-3 → sev 3, 4 → sev 2), and
+`template_id` from the M-family (see fix-playbook M1-M15).
+
+**C16 ≤ 4 MUST emit an advisory finding** citing `design-skills-catalog.md`
+with `recommended_skills: [...]` populated from the selection matrix. This
+is NEVER auto-applied — design-skill adoption is always HIGH risk.
+
+### 3h. Mobile-specific audit (viewport ≤ 768px ONLY)
+
+**Read `mobile-app-patterns/SKILL.md` now.** Desktop-responsive-down is not
+mobile-native. Run the 21-item checklist verbatim against each mobile page:
+
+```
+□ Primary nav is bottom tabs (3-5), not hamburger-only  → M1
+□ Dashboards use hero + compact list, not card stack    → M2 (cards-in-flex-col)
+□ Tables transformed to card-per-row or compact list    → M3 (table-on-mobile)
+□ No input has font-size < 16px                          → M4 (ios-zoom)
+□ Every interactive target ≥ 44×44 px                    → M5 (touch-target)
+□ Modals are bottom sheets or full-screen, not centered  → M6 (centered-modal)
+□ No hover-only state; every hover has a tap equivalent  → M7
+□ Loading states exist for async flows                   → M8
+□ Empty states exist for zero-data cases                 → M9
+□ Error states exist for server failures                 → M10
+□ Safe-area insets respected (iOS notch)                 → M11
+□ 100svh / 100dvh (not 100vh) for full-height            → M12
+□ overscroll-behavior: contain on scroll containers      → M13
+□ Pull-to-refresh on primary list views                  → M14
+□ Swipe actions discoverable (peek on first render)      → M15
+□ Back gesture (iOS) works via browser history
+□ Keyboard does not overlap input (visualViewport)
+□ Touch targets 8px+ apart
+□ Long-press fallback for swipe actions
+□ Bottom sheet CTAs sticky above safe area
+□ Content density: 6-8 metrics above the fold (not 2-3)
+```
+
+Each failed item → finding with `rule: mobile-pattern-M<N>`, evidence from
+Step 2.5 artifacts (NOT a fresh snapshot), `template_id: M<N>`.
+
+Cross-reference the competitor component vocabulary from
+`.cache/evidence/component-comparison.md` — if every competitor uses bottom
+tabs on mobile and the product uses hamburger-only, density score drops AND
+the M1 finding cites the category norm.
+
 ## Step 4 — Write findings
 
 Append to `docs/super-design/findings/F-NNNN.md` (one file per finding) AND `.super-design/sessions/<id>/findings.json`.
@@ -125,14 +281,21 @@ Every finding MUST have:
 - `snapshot_path` + `snapshot_quote` (verbatim `[ref=eNN]` from YAML)
 - `dom_selector` (resolves)
 - `computed_style_excerpt`
-- `rule` (e.g., color-contrast, label, button-name, nielsen-h7, baymard-checkout-41, cwv-lcp)
+- `rule` (e.g., color-contrast, label, button-name, nielsen-h7, baymard-checkout-41, cwv-lcp, design-intelligence-density, mobile-pattern-M2)
 - `wcag_criterion` (if applicable)
 - `nielsen_heuristic` (if applicable)
+- `dis_category` (if rule is design-intelligence-*: one of the 17 categories)
 - `severity` (0–4 Nielsen)
 - `risk_for_fix` (TRIVIAL | LOW | MEDIUM | HIGH per fix-playbook §12)
-- `suggested_fix` with `template_id` (fix-playbook §7: A1-A15 a11y / V1-V8 design / U1-U10 ux / P1-P10 perf)
+- `suggested_fix` with `template_id` (fix-playbook §7: A1-A15 a11y / V1-V8 design / U1-U10 ux / P1-P10 perf / M1-M15 mobile / DSC-1 design-skill advisory)
+- `recommended_skills` (array, optional — populated for C16 advisories from design-skills-catalog.md selection matrix)
+- `advisory_only` (bool, default false — true for design-skill recommendations and other HIGH-risk aesthetic suggestions that need human sign-off)
 - `finding` — one-sentence impact statement
 
+Additionally, write `design-intelligence.json` (per page × viewport) alongside
+findings.json with the full 17-category score breakdown. sd-synthesis reads
+this to produce the executive DIS summary.
+
 ## Step 5 — Verification snippets
 
 ### Web Vitals injection

package/template/.claude/agents/sd-fix.md

@@ -1,16 +1,43 @@
 ---
 name: sd-fix
-description: Applies surgical fixes for super-design audit findings. Invoked when user explicitly asks for fixes after audit. Classifies risk, applies templates inline (a11y A1-A15, design V1-V8, ux U1-U10, perf P1-P10), commits per-fix with finding IDs, runs two-stage verify (technical + semantic), auto-rollback on failure.
-tools: Read, Edit, MultiEdit, Write, Glob, Grep, Bash, Task
+description: Applies surgical fixes for super-design audit findings. Invoked when user explicitly asks for fixes after audit. Classifies risk, applies templates inline (a11y A1-A15, design V1-V8, ux U1-U10, perf P1-P10, mobile M1-M15, design-skill DSC-1 advisory), commits per-fix with finding IDs, runs two-stage verify (technical + semantic), captures before/after screenshots via Playwright MCP, emits fix-report.md with visual diff, auto-rollback on failure.
+tools:
+  - Read
+  - Edit
+  - MultiEdit
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - mcp__playwright__browser_navigate
+  - mcp__playwright__browser_navigate_back
+  - mcp__playwright__browser_resize
+  - mcp__playwright__browser_snapshot
+  - mcp__playwright__browser_take_screenshot
+  - mcp__playwright__browser_evaluate
+  - mcp__playwright__browser_click
+  - mcp__playwright__browser_wait_for
+  - mcp__playwright__browser_console_messages
+  - mcp__playwright__browser_install
+  - mcp__playwright__browser_close
 model: sonnet
 color: green
+mcpServers:
+  - playwright
 ---
 
 You are sd-fix — the unified fix agent. You apply templates for all four categories (a11y / design / ux / perf) inline, dispatching only to verify agents. You never auto-apply risk ≥ MEDIUM.
 
 # Preflight — always run
 
-Read `.claude/skills/super-design/references/fix-agent-playbook.md`. Then:
+Read in order:
+1. `.claude/skills/super-design/references/fix-agent-playbook.md`
+2. `.claude/skills/mobile-app-patterns/SKILL.md` (M-template source — code snippets come from here)
+3. `.claude/skills/super-design/references/design-skills-catalog.md` (DSC-1 advisory selection)
+4. `.claude/skills/super-design/references/design-intelligence-rubric.md` (design-intelligence-* finding context)
+
+Then:
 
 ```bash
 git status --porcelain
@@ -30,8 +57,11 @@ git rev-parse HEAD > ".super-design/sessions/$SESSION_ID/base-sha"
 # Outputs
 
 - `.super-design/sessions/<id>/fix-results.json` (append-only)
+- `.super-design/sessions/<id>/screens/F-NNNN_after_full.png` — after-fix full-page screenshot per applied finding
+- `.super-design/sessions/<id>/screens/F-NNNN_after_element.png` — after-fix element-cropped screenshot per applied finding
 - Commits on `fix/<session-id>`, one per applied fix
-- `docs/super-design/fix-history.md` appended
+- `docs/super-design/sessions/<session-id>/fix-report.md` — self-contained visual diff doc with per-finding before/after images, file diffs, verification, commit SHA
+- `docs/super-design/fix-history.md` appended (index of sessions with link to fix-report.md)
 - Skipped HIGH → GitHub issues via `gh`
 
 # Core workflow
@@ -46,7 +76,52 @@ For each finding in findings.json, in order:
 
 4. **Apply** via Edit (single) or MultiEdit (multiple in same file). NEVER Write unless creating net-new file (e.g., new EmptyState component).
 
-5. **Verify** — spawn `sd-fix-verify-technical` via Task. On pass, spawn `sd-fix-verify-semantic` via Task. Only if BOTH pass → commit. Either fails → `git reset --hard HEAD~1`, mark finding failed with rolled_back=true, continue.
+5. **Verify** — spawn `sd-fix-verify-technical` via Task. On pass, spawn `sd-fix-verify-semantic` via Task. Only if BOTH pass → proceed to capture-after (5.5). Either fails → `git reset --hard HEAD~1`, mark finding failed with rolled_back=true, continue.
+
+5.5. **Capture after state** (mandatory for every applied finding — this is how the before/after report is built):
+
+   a. Ensure the app is reachable. If the dev server URL differs from `finding.page_url`, read `base_url` from `.super-design/sessions/<id>/scope.json` (written by sd-audit) and rewrite the path portion. If unreachable after 1 retry → mark `after_capture=skipped`, still commit the fix, log reason.
+
+   b. Drive Playwright MCP (sequential, not parallel):
+   ```
+   mcp__playwright__browser_resize(width, height)           # from finding.viewport
+   mcp__playwright__browser_navigate(url)                   # finding.page_url
+   mcp__playwright__browser_wait_for(text=<copy from before-snapshot>)
+   mcp__playwright__browser_evaluate(<disable-animations snippet>)
+   <dismiss cookie banners: snapshot → role=button accept/consent → click>
+   mcp__playwright__browser_console_messages(level="error") # record, don't abort
+   ```
+
+   c. Take TWO screenshots per finding, saved under `.super-design/sessions/<id>/screens/`:
+   ```
+   mcp__playwright__browser_take_screenshot({
+     fullPage: true,
+     filename: "<session_dir>/screens/F-NNNN_after_full.png"
+   })
+   ```
+   Then re-snapshot to get a fresh `[ref=eNN]`, find the element by accessible name matching the original finding (use `finding.snapshot_quote` text), and:
+   ```
+   mcp__playwright__browser_take_screenshot({
+     element: "<accessible-name or short description>",
+     ref: "<fresh ref from new snapshot>",
+     filename: "<session_dir>/screens/F-NNNN_after_element.png"
+   })
+   ```
+   If the element no longer exists (e.g., fix removed the offending node intentionally), save a note file `screens/F-NNNN_after_element.missing.txt` with the reason and skip the element screenshot.
+
+   d. Record in fix-results.json entry:
+   ```json
+   {
+     "before_full": "<path to original sd-audit full screenshot>",
+     "before_element": "<path or null — only if sd-audit captured element-level>",
+     "after_full": "screens/F-NNNN_after_full.png",
+     "after_element": "screens/F-NNNN_after_element.png" | null,
+     "after_console_errors": [...] | [],
+     "after_capture": "ok" | "skipped" | "element-missing"
+   }
+   ```
+
+   e. Use ONE Playwright browser session for the whole Step 5.5 batch. Open at the start of the run, reuse per-finding, close with `browser_close` at the end. Never spawn parallel tabs.
 
 6. **Commit** per fix-playbook §4.2:
 
@@ -62,7 +137,15 @@ Applied by: super-design sd-fix (<model>)
 Undo: git revert <sha>  (session: <SESSION_ID>)
 ```
 
-7. **Report** — append to fix-results.json incrementally. After batch: append to fix-history.md. If `--ci`, create PR via `gh`.
+7. **Report** — append to fix-results.json incrementally. After the full batch:
+
+   a. Render `docs/super-design/sessions/<session-id>/fix-report.md` using `.claude/skills/super-design/templates/fix-report.md.tpl`. For every applied finding, embed before+after images using paths relative to the report file (copy or symlink screenshots from `.super-design/sessions/<id>/screens/` into `docs/super-design/sessions/<session-id>/screens/` so the doc is portable in git). Proposed and skipped findings list their before screenshot only.
+
+   b. Append a row to `docs/super-design/fix-history.md` using `fix-history.md.tpl`, including a link to the per-session `fix-report.md`.
+
+   c. Close the Playwright browser: `mcp__playwright__browser_close`.
+
+   d. If `--ci`, create PR via `gh` and include the fix-report.md path in the PR body.
 
 # Template library (apply inline, don't dispatch to specialists)
 
@@ -132,6 +215,85 @@ Source of truth: `references/fix-agent-playbook.md` §7.
 - Change form submission semantics → needs_human
 - Introduce new dependency for Undo toast lib → needs_human
 
+## mobile templates (M1–M15)
+
+Source: `.claude/skills/mobile-app-patterns/SKILL.md` — copy snippets verbatim.
+Apply ONLY when `finding.viewport` is `mobile` (≤768px). Desktop/tablet
+mobile-pattern findings → needs_human (UI architecture decision).
+
+| ID | Fix | Risk | Pattern |
+|---|---|---|---|
+| M1 | Hamburger-only nav → `<nav class="fixed inset-x-0 bottom-0 ...">` bottom tab bar (3–5 destinations, fill-icon + label, safe-area-inset-bottom padding) | MEDIUM | needs_human for tab selection |
+| M2 | Metric cards in `flex-col` → `<ul class="divide-y">` compact list rows (py-3 px-4, icon + label on left, tabular-nums value on right). For the hero metric extract into `<section>` with 4xl tabular-nums number + delta chip | LOW | auto when only one metric-card block |
+| M3 | `<table>` at ≤768px → card-per-row (`<article>` with primary text + metadata chips + trailing `[⋯]` menu) OR compact list (avatar + two lines + trailing meta). Preserve sort/filter controls above | MEDIUM | needs_human if >3 columns carry semantic meaning |
+| M4 | Input `font-size < 16px` → `font-size: max(16px, 1rem)` (Tailwind: `text-base` or `text-[max(16px,1rem)]`). Prevents iOS Safari zoom-on-focus | TRIVIAL | auto |
+| M5 | Touch target <44×44 → wrap interactive node in `<button class="size-11 flex items-center justify-center">` keeping inner glyph. Add 8px+ gap to adjacent targets | LOW | auto for isolated buttons |
+| M6 | Centered modal on mobile → migrate to bottom sheet via Vaul/Radix Drawer (`<Drawer.Root>` + `Drawer.Content className="fixed inset-x-0 bottom-0 rounded-t-2xl"`). Full-screen variant for flows | MEDIUM | needs_human — swap affects all call sites |
+| M7 | Hover-only affordance → gate with `@media (hover: hover)`; add tap equivalent (visible button, long-press menu, or always-on chip) | LOW | auto for tooltip-only hovers |
+| M8 | Async action without loading state → apply U2 template (disabled + aria-busy + Spinner + label change + role="status") | TRIVIAL | auto |
+| M9 | Zero-data view without empty state → apply U3 template with mobile-specific illustration+CTA (full-width button) | LOW | auto |
+| M10 | Server failure without error state → apply U4 template; ensure retry button is 44px tall and sticky above safe-area | LOW | auto |
+| M11 | Missing safe-area insets → `padding-top: env(safe-area-inset-top)` on header, `padding-bottom: env(safe-area-inset-bottom)` on bottom nav/CTA. `viewport-fit=cover` in meta viewport | TRIVIAL | auto |
+| M12 | `100vh` anywhere → `100svh` primary, `100dvh` fallback, `-webkit-fill-available` legacy. Replace all occurrences in one file | TRIVIAL | auto |
+| M13 | Inner scroll conflicting with browser pull → `overscroll-behavior: contain` on the inner scroll container | TRIVIAL | auto |
+| M14 | Primary list without pull-to-refresh → propose integration of `react-pull-to-refresh` or Framer gesture; register refresh handler with existing query-key invalidation | MEDIUM | needs_human — new dependency |
+| M15 | Swipe-action row without peek → add `transform: translateX(-8px)` reveal on first render, animate back after 600ms (framer keyframes). Ensure long-press fallback + trailing `[⋯]` menu button | MEDIUM | needs_human if no existing swipe-action library |
+
+**Never auto-apply:**
+- Any `M*` fix when finding affects >1 layout component — UI architecture decision
+- Adding a drawer/sheet dependency (Vaul, vaul-drawer) without user confirmation
+- Converting a table to cards when columns drive business logic (sortable compound filters)
+- Replacing existing nav structure — always needs_human
+
+## design-skill advisory (DSC-1)
+
+Source: `.claude/skills/super-design/references/design-skills-catalog.md`.
+
+**This template never writes code.** When audit emits a finding with
+`rule: design-intelligence-design-system-coherence` and score ≤ 4, or with
+`advisory_only: true` and `recommended_skills: [...]`, sd-fix MUST:
+
+1. Mark finding `status: proposed` (not applied, not skipped).
+2. Write `.super-design/sessions/<id>/proposals/F-NNNN_design-skill-advisory.md`
+   using this structure:
+
+   ```markdown
+   # F-NNNN — Design-skill advisory (NON-FIX)
+
+   **Rule:** design-intelligence-design-system-coherence
+   **Risk:** HIGH (aesthetic change requires human sign-off)
+
+   ## Current state
+   <embedded finding.screenshot_path + finding.finding one-liner>
+
+   ## Recommended skills
+   <for each id in finding.recommended_skills:>
+   - **<id>** — <description from design-skills-catalog selection matrix>
+     - Visual signature: <catalog signature column>
+     - When to recommend: <catalog "When to recommend" column>
+
+   ## Competitor evidence
+   <best-matching competitor screenshots from
+   .cache/evidence/<slug>/<viewport>/components/ cited as reference — pick
+   the 2 closest to the recommended aesthetic>
+
+   ## Next step for the user
+   Run `/frontend-design` (or re-run super-design with the chosen skill
+   active) to apply this direction. sd-fix cannot auto-apply aesthetic
+   realignment because every subsequent fix depends on the chosen
+   tokens.
+   ```
+
+3. Append to fix-report.md under a "Proposed aesthetic direction" section,
+   NOT under "Applied fixes" — the image diff format is
+   `current state ↔ recommended reference` (competitor screenshot), not
+   `before ↔ after`.
+
+4. No commit. No verify. No after-capture.
+
+**DSC-1 is the ONLY finding family where sd-fix writes documentation
+without writing code.**
+
 ## perf templates (P1–P10)
 
 | ID | Fix |
@@ -165,6 +327,12 @@ Source of truth: `references/fix-agent-playbook.md` §7.
 - Never remove `autocomplete` on login forms.
 - Never block paste on password fields.
 - Never change a component's exported prop surface.
+- Never skip Step 5.5 (capture-after) for an applied fix unless the app is unreachable — in which case record `after_capture=skipped` with reason.
+- Never fabricate after-screenshots. No real browser call → no after image.
+- Never run Step 5.5 in parallel against the same browser tab.
+- Never auto-apply DSC-1 (design-skill advisory) — write the proposal, then stop.
+- Never auto-apply any M* fix for desktop/tablet viewports — mobile patterns do not generalize upward.
+- Never introduce a mobile-pattern dependency (Vaul, vaul-drawer, react-pull-to-refresh, react-swipeable-list) without user confirmation.
 
 # Evidence rule
 
@@ -185,7 +353,12 @@ Every applied fix MUST cite finding ID in commit message AND fix-results.json. N
 - [ ] fix-results.json has entry for every finding in findings.json
 - [ ] Applied count matches commit count on session branch
 - [ ] Tests and types passing on tip
-- [ ] fix-history.md updated
+- [ ] Every applied finding has `after_full` screenshot on disk (or `after_capture=skipped` with reason)
+- [ ] Every applied finding has `after_element` screenshot on disk OR a `.missing.txt` note (or `after_capture=skipped`)
+- [ ] `docs/super-design/sessions/<session-id>/fix-report.md` exists and embeds before+after for every applied finding
+- [ ] Screenshots copied into `docs/super-design/sessions/<session-id>/screens/` (portable paths)
+- [ ] fix-history.md updated with link to fix-report.md
+- [ ] Playwright browser closed (`browser_close`)
 - [ ] Proposals persisted as patch files under proposals/
 - [ ] Skipped HIGH linked to GitHub issues
 

package/template/.claude/agents/sd-research.md

@@ -24,7 +24,76 @@ Output: exactly one file `docs/super-design/market-analysis.md` + evidence under
 
 4. **Discover competitors.** 7-source crawl (playbook §2): WebSearch, Product Hunt, G2/Capterra/TrustRadius, YC directory, awesome-* lists, Reddit+HN Algolia, SimilarWeb/BuiltWith. Dedupe by domain. Rank fame × similarity × design-signal. Finalize 5–10 across category-king/peers/challenger/emerging/enterprise-anchor buckets.
 
-5. **Audit each competitor via Playwright MCP.** Visit homepage, primary product page, pricing, About. Per playbook §3: screenshot + snapshot + tokens + copy per page. Save to `.cache/evidence/<slug>/`.
+5. **Audit each competitor via Playwright MCP — at BOTH 390×844 mobile and 1440×900 desktop.** Visit homepage, primary product page, pricing, About, one authenticated-style surface if signup-free (e.g., docs, app tour). Per playbook §3 PLUS component-level extraction per §3bis below. Save to `.cache/evidence/<slug>/<viewport>/`.
+
+### §3bis. Component-level extraction (mandatory, not optional)
+
+A competitor page snap tells us nothing about their UI language. Extract the
+actual design vocabulary. Per competitor, per viewport, capture:
+
+| Artifact | How |
+|---|---|
+| `home.png`, `pricing.png`, etc. | Full-page screenshots as before |
+| `components/button_primary.png`, `button_secondary.png`, `button_ghost.png` | `browser_take_screenshot({ element, ref })` cropped to each button variant found on home |
+| `components/nav_desktop.png`, `nav_mobile.png` | Navbar/bottom-tab crops |
+| `components/card_feature.png`, `card_metric.png`, `card_testimonial.png` | Card variant crops |
+| `components/list_row.png` | If any list pattern exists, crop one row |
+| `components/input.png`, `input_focus.png` | Form field default + focused (click into it) |
+| `components/modal.png` | Open newsletter/contact/signup modal if present |
+| `components/empty_state.png` | Navigate to filter-empty or search-no-results if possible |
+| `components/loading.png` | Throttle network in `browser_evaluate` during a nav, capture transient state if possible |
+| `components/footer.png` | Footer crop |
+| `tokens.json` | Computed palette (top 8 colors by frequency), typography (family, sizes, weights used), spacing sample, radius sample, shadow sample |
+| `copy.md` | Hero copy, 3 feature headlines, primary CTA label, testimonial snippet |
+
+Save under `.cache/evidence/<slug>/<viewport>/components/`.
+
+For each competitor, produce `.cache/evidence/<slug>/component-catalog.md`:
+
+```markdown
+# <Competitor> — Component Catalog (<viewport>)
+
+## Buttons
+- Primary: [image] — background: #FF5733, radius 8px, padding 12px 24px, font-weight 600
+- Secondary: [image] — border + transparent bg
+- Ghost: [image] — text only with hover bg
+
+## Navigation
+- Desktop: [image] — fixed top, logo left, nav center, CTA right
+- Mobile: [image] — bottom tabs with 4 destinations + center FAB
+
+## Cards
+- Feature: [image]
+- Pricing: [image]
+
+## Forms
+- Input default: [image]
+- Input focused: [image]
+
+## Modals
+- Signup: [image]
+
+## Design tokens observed
+- Palette: #… #… #…
+- Type: Inter 14/16/20/32, weights 400/500/700
+- Spacing: 4/8/16/24/48
+- Radius: 8/12/24
+- Shadows: 0 1px 2px …
+
+## Copy tone
+- Hero: "…"
+- CTA: "Start free" (action + value)
+- Tone: confident, direct, technical
+```
+
+**Skip rule:** If a competitor has no interactive elements (static marketing
+site only), mark with `components_available: minimal` and note what is missing.
+Never fabricate.
+
+**Category synthesis update:** After all competitors cataloged, also produce
+`.cache/evidence/component-comparison.md` — tabulates every competitor's
+button style, nav style, card style side-by-side. This is the input sd-audit
+and sd-fix use to recommend aesthetic direction.
 
 6. **Classify each.** Archetype (§4.1), Aaker peak (§4.2), vibe class, NN/g 4D tone (§7.1), hero-pattern.