start-vibing 4.3.0 → 4.3.2

package/template/.claude/skills/super-design/references/audit-methodology.md

@@ -187,6 +187,66 @@ The 2026 WebAIM Million report (released ~30 March 2026, https://webaim.org/proj
 
 **What automation CANNOT catch** (the manual 40–70%): keyboard trap detection beyond trivial cases; screen-reader announcement quality; meaningful alt text (tools detect missing, not quality); logical focus order when CSS reorders; error message clarity; appropriate heading structure (presence vs meaning); context-appropriate link text; video caption accuracy/sync; color meaning (1.4.1); reading order under CSS transforms; reflow at 320px (no tool); text-spacing override; focus-indicator quality (2.4.11 / 2.4.13); `prefers-reduced-motion` honoring; target size / spacing (partial); autocomplete correctness; captcha alternatives; content-on-hover persistence (1.4.13); page title descriptiveness; consistent navigation/identification (3.2.3 / 3.2.4).
 
+### 2.5 Tool triangulation for automated a11y (MANDATORY)
+
+axe-core alone catches only ~57% of WCAG issues by volume (Deque's own
+coverage study) and ~40% by Success Criterion count. Running a single
+engine guarantees blind spots. sd-audit MUST run axe **plus** at least two
+more engines and dedupe the merged results by `{rule, selector}`.
+
+**Engines to run in parallel (don't serialize — they're cheap):**
+
+```bash
+# 1. axe-core — inject via Playwright MCP (already done in sd-audit Step 2,
+#    with `experimental: true` so WCAG 2.2 rules fire).
+
+# 2. Pa11y — runs both htmlcs and axe runners for broader coverage
+pa11y "$URL" \
+  --standard WCAG2AA \
+  --runner axe \
+  --runner htmlcs \
+  --reporter json \
+  > "$SESSION_DIR/a11y/pa11y_<slug>_<vp>.json"
+
+# 3. WAVE API — WebAIM's detector, overlay-oriented, strong on contrast and ARIA
+curl -s "https://wave.webaim.org/api/request?key=$WAVE_KEY&url=$(printf %s "$URL" | jq -sRr @uri)&reporttype=4" \
+  > "$SESSION_DIR/a11y/wave_<slug>_<vp>.json"
+
+# 4. IBM Equal Access Accessibility Checker — ACT-rule aligned, ~140 rules
+achecker "$URL" \
+  --reportLevel violation,potentialviolation \
+  --outputFormat json \
+  --outputFolder "$SESSION_DIR/a11y/achecker_<slug>_<vp>/"
+```
+
+**Dedup and severity normalization:**
+
+```js
+// Pseudocode — run in sd-audit Step 3a after parsing all engine outputs.
+const key = (f) => `${f.rule}::${f.selector}`;
+const bucket = new Map();
+for (const engine of ['axe', 'pa11y', 'wave', 'achecker']) {
+  for (const f of findings[engine]) {
+    const k = key(f);
+    if (!bucket.has(k)) bucket.set(k, { ...f, engines: [] });
+    bucket.get(k).engines.push(engine);
+  }
+}
+// Confidence ladder:
+//   engines.length === 1 → single-source, keep but tag "unverified"
+//   engines.length >= 2 → triangulated, high confidence
+//   engines.length >= 3 → near-certain, promote severity +1 step
+```
+
+**Why each engine is non-redundant:**
+- **axe-core** — strongest on `4.1.2`, `1.4.3`, `1.1.1`, `1.3.1` subsets; experimental flag gates 2.2.
+- **Pa11y** — htmlcs runner catches rule shapes axe doesn't ship; dual-runner mode is unique.
+- **WAVE** — contrast slider tool + in-context overlay; different heuristics for ARIA landmarks; never marks a page "passed" (useful bias — never false-clean).
+- **IBM Equal Access** — ACT-Rules aligned (different normative base than axe); baseline-file regression; severity categories (`violation / potentialviolation / recommendation / manual`) map onto Nielsen 0–4.
+
+Record per-finding `source_engines: [...]` so sd-synthesis can promote
+triangulated issues and down-weight single-engine noise.
+
 ### 2.4 Regulatory context
 
 **European Accessibility Act** (Directive (EU) 2019/882) enforceable **28 June 2025** for new products/services; 28 June 2030 deadline for pre-existing. References **EN 301 549** (currently WCAG 2.1 AA baseline; being updated to 2.2). Extraterritorial.
@@ -201,6 +261,64 @@ The 2026 WebAIM Million report (released ~30 March 2026, https://webaim.org/proj
 
 Baymard (Copenhagen, founded ~2009) is used by 71% of Fortune 500 e-commerce companies. Research: 54 rounds of benchmarking, 327 top-grossing US/EU sites, 275,000+ manually assigned UX performance scores, 200,000+ research hours. Methodology page: https://baymard.com/research/methodology. Headline finding: the average large e-commerce site can gain **+35.26% conversion** through better checkout design — **$260B** in recoverable US+EU orders.
 
+### 3.0 Baymard sub-rule enumeration (finding code prefixes)
+
+The single blanket "Baymard" verdict is too coarse for a structured audit.
+Baymard organises findings by **surface** (checkout, PDP, search, etc.) and
+each surface has a bounded, enumerable set of sub-rules. Every Baymard
+finding raised by sd-audit MUST use one of the prefixes below so
+sd-synthesis can group them and so the fix-playbook can route to the right
+U-template. Rules that do not yet have an official Baymard number are
+prefixed by count only (e.g. `baymard-cc-01` … `baymard-cc-14`) with the
+source section cited.
+
+| Surface | Prefix | Count | Source (methodology §) |
+|---|---|---|---|
+| Credit card form | `baymard-cc-<NN>` | 14 rules | §3.3 + https://baymard.com/checkout-usability/credit-card-patterns |
+| Address form | `baymard-addr-<NN>` | 8 rules | §3.4 + https://baymard.com/blog/address-line-2 + https://baymard.com/blog/automatic-address-lookup |
+| Search | `baymard-search-<NN>` | 12 rules | §3.6 + https://baymard.com/ecommerce-design-examples/34-autocomplete-suggestions |
+| Filter | `baymard-filter-<NN>` | 10 rules | §3.6 + https://baymard.com/blog/promoting-product-filters + https://baymard.com/blog/have-filters-for-list-item-info |
+| Breadcrumbs | `baymard-bread-<NN>` | 6 rules | §3.7 + https://baymard.com/blog/ecommerce-breadcrumbs |
+| PDP / Product Detail | `baymard-pdp-<NN>` | 18 rules | §3.8 + https://baymard.com/research/product-page |
+
+**`baymard-cc-*` — Credit card form (14 rules, §3.3):**
+1. `baymard-cc-01` auto-format spaces per card brand (4-4-4-4 / 4-6-5 AMEX / 4-4-4-4-3 19-digit)
+2. `baymard-cc-02` auto-detect card type via IIN ranges (adapt length limit, CVV help, spacing)
+3. `baymard-cc-03` expiration as single MM/YY field with auto-inserted slash (NOT YYYY, NOT two dropdowns)
+4. `baymard-cc-04` CVV field with adaptive help image (3-digit back for Visa/MC, 4-digit front for AMEX)
+5. `baymard-cc-05` autocomplete tokens present: `cc-number`, `cc-name`, `cc-exp`, `cc-exp-month`, `cc-exp-year`, `cc-csc`
+6. `baymard-cc-06` `inputmode="numeric"` (never `type="number"`) on card number, expiration, CVV
+7. `baymard-cc-07` never clear CC number/CVV on validation error (preserve entered data)
+8. `baymard-cc-08` stored-card edit uses "fake editing" (delete + re-add) per PCI; clear messaging
+9. `baymard-cc-09` inline validation with 5%-abandonment guardrail (no vague "Card declined" without reason)
+10. `baymard-cc-10` fallback entry path when wallet (Apple Pay / Google Pay) fails
+11. `baymard-cc-11` accept pasted numbers; strip spaces/dashes server+client
+12. `baymard-cc-12` surface accepted card brands near the input (logo strip) before submit
+13. `baymard-cc-13` billing-address reuse: "Billing same as shipping" default-checked with editable prefill
+14. `baymard-cc-14` error messages identify which field failed + how to fix (not "Payment failed")
+
+> Source: §3.3 bullets + https://baymard.com/checkout-usability/credit-card-patterns. Rules 10–14 derived from §3.3 narrative; number them in this table and supersede with Baymard's official IDs when available.
+
+**`baymard-addr-*` — Address form (8 rules, §3.4):**
+1. `baymard-addr-01` country selector FIRST (drives all subsequent field formats/validation)
+2. `baymard-addr-02` single "Address Line 1" + optional "Address Line 2" labeled "Apt, Suite — optional" (never omit Line 2)
+3. `baymard-addr-03` automatic address autocomplete preferred (9% manual-entry typo rate without it)
+4. `baymard-addr-04` postal-code autodetect of city/state (28% mobile sites fail)
+5. `baymard-addr-05` US state as dropdown (not free text); UK optional county; hide for countries without subdivisions
+6. `baymard-addr-06` autocomplete tokens: `street-address`, `address-line1`, `address-line2`, `address-level1/2`, `postal-code`, `country`
+7. `baymard-addr-07` "Billing same as shipping" default-checked with editable prefilled fields (also WCAG 3.3.7 Redundant Entry)
+8. `baymard-addr-08` name inputs accept Unicode, hyphens, apostrophes, single-name users, >20 chars
+
+> Source: §3.4.
+
+**`baymard-search-*` — Search (12 rules, §3.6):** placeholders for 12 rules covering autocomplete presence, scope suggestions in autocomplete, search-within-current-category, autodirect on category match, query-term pluralization tolerance, typo tolerance, "no results" with recovery options, recent-searches memory, sort-vs-filter separation, faceted-search state in URL, submit-without-suggestion-selection, voice search on mobile. Rules `baymard-search-01` … `baymard-search-12`. Source: §3.6 bullets + https://baymard.com/ecommerce-design-examples/34-autocomplete-suggestions. Enumerate the exact wording when next Baymard PDF is purchased.
+
+**`baymard-filter-*` — Filter (10 rules, §3.6):** placeholders `baymard-filter-01` … `baymard-filter-10` covering: promote top filters above the product grid; truncate long value lists >10 with styled "More" link; category-specific filters (megapixels, temperature rating); filters for every attribute displayed in list items; expand/collapse icons right-aligned; applied-filter pills visible and individually removable; "clear all" affordance; range sliders with keyboard + numeric input; multi-select affordance obvious; result count live-updated via `aria-live`. Source: §3.6 bullets + https://baymard.com/blog/promoting-product-filters + https://baymard.com/blog/have-filters-for-list-item-info.
+
+**`baymard-bread-*` — Breadcrumbs (6 rules, §3.7):** placeholders `baymard-bread-01` … `baymard-bread-06` covering: present on all non-home pages; implement BOTH hierarchy-based AND history-based (68% of top 50 sub-par, 45% only hierarchy, 23% none); present on mobile (65% mobile fail); no "hidden in more" collapse on desktop without reveal; last crumb non-clickable; structured-data markup (`BreadcrumbList`). Source: §3.7 + https://baymard.com/blog/ecommerce-breadcrumbs.
+
+**`baymard-pdp-*` — PDP / Product Detail (18 rules, §3.8):** placeholders `baymard-pdp-01` … `baymard-pdp-18` covering: single dominant Add-to-Cart (no 3–6 competing colorful buttons); shipping cost/ETA visible on PDP (64% of users look for it); total visible before checkout (24% abandon otherwise); accordion over horizontal tabs (67% of accordion users mis-implement; 28% use worst-performing tabs); UGC visuals present (67% lack them); minimum 3–5 images + zoom + variant-driven imagery; swatches not dropdowns for variants; out-of-stock variants visible-but-disabled (not removed); star ratings above the fold (up to +18% conversion with verified badges); stock urgency without dark patterns; delivery-date estimator; returns policy on PDP; size guide inline (not in a separate page); Q&A / reviews with filtering; cross-sell without shoving below CTA; "notify me" flow for OOS; price history for discount honesty; country/currency switcher persisted. Source: §3.8 + https://baymard.com/research/product-page.
+
 ### 3.1 Cart abandonment
 **70.19% average abandonment** across 49 studies 2006–2023, range 55–84.27% (https://baymard.com/lists/cart-abandonment-rate). By device: mobile 77.06%, tablet 66.39%, desktop 70.01%. **Reasons** (excluding 43% "just browsing"): extra costs 48%; forced account creation 24%; slow delivery 19%; distrust with CC 18–19%; too long/complicated 17–18%; couldn't see total up front 16%; errors/crashes 13%; returns policy 12%; declined CC 9%; limited payment methods 7%.
 

package/template/.claude/skills/super-design/references/design-intelligence-rubric.md

@@ -29,6 +29,8 @@ A score without evidence is invalid. Auditor records `n/a` instead of guessing.
 
 ## Category 1 — Visual hierarchy (weight 1.0)
 
+**Rationale:** Reber et al. processing fluency + Tractinsky aesthetic-usability — clean dominance hierarchies literally reduce cognitive load; beauty buys friction tolerance only after hierarchy is solved (artifact Parts 1–3).
+
 **Question:** On this view, what is the single primary goal? Is it the most
 dominant element visually?
 
@@ -47,6 +49,8 @@ dominant element visually?
 
 ## Category 2 — Density calibration per viewport (weight 1.2)
 
+**Rationale:** Fitts's Law + thumbzone ergonomics — density must respect the physical reach envelope of the device; cramming desktop density onto mobile violates motor cost.
+
 **Question:** Does information density match the device context?
 
 | Viewport | Expected primary entities visible above fold |
@@ -68,6 +72,8 @@ dominant element visually?
 
 ## Category 3 — Consistency: spacing scale (weight 0.8)
 
+**Rationale:** Gestalt proximity + rhythm — shared spacing units fuse related elements and separate distinct ones; arbitrary magic numbers break grouping perception.
+
 **Question:** Do paddings, margins, gaps come from a scale (4/8px or 0.25rem) or are they arbitrary magic numbers?
 
 **Detect:**
@@ -86,12 +92,16 @@ dominant element visually?
 
 ## Category 4 — Consistency: typography scale (weight 0.8)
 
+**Rationale:** Processing fluency (Reber) — a discrete type scale accelerates recognition; a shapeless set of sizes forces re-parsing of hierarchy on every screen.
+
 Same method for font-size, font-weight, line-height. Look for `text-\[\d+px\]` and arbitrary font-size. Expected: 6–10 sizes total in a designed system; 30+ sizes = vibecoded.
 
 ---
 
 ## Category 5 — Consistency: color palette (weight 0.8)
 
+**Rationale:** Valdez & Mehrabian (1994) — saturation × value drive emotional response more than hue; a disciplined palette with controlled lightness/saturation ranges is the single highest-leverage decision for perceived quality (artifact line 43).
+
 **Detect:**
 - Collect computed `color`, `background-color`, `border-color` from ≥100 elements.
 - Unique colors count. <15 = disciplined. 30+ = vibecoded.
@@ -108,6 +118,8 @@ Same method for font-size, font-weight, line-height. Look for `text-\[\d+px\]` a
 
 ## Category 6 — Whitespace & breathing room (weight 0.7)
 
+**Rationale:** *Ma* (間) — negative space is substance, not absence; whitespace signals confidence and lets figure/ground perception resolve without strain.
+
 **Question:** Does content have room to breathe, or is it crammed?
 
 **Detect:** Compute average `padding-inline + margin-inline` per content block. Compare to container width. Measure content-to-chrome ratio.
@@ -123,6 +135,8 @@ Same method for font-size, font-weight, line-height. Look for `text-\[\d+px\]` a
 
 ## Category 7 — Text legibility (weight 1.2)
 
+**Rationale:** Miller 4±1 (Cowan 2001) + Postel's robustness — legible bodies keep working-memory cost low; dense microtext forces re-reading and exhausts the 4-chunk budget that forms and scannable text depend on.
+
 **Detect:** `browser_evaluate` → collect `fontSize` computed px. Find minimum across visible text.
 
 | Viewport | Min body | Min meta | Min input |
@@ -142,6 +156,8 @@ Same method for font-size, font-weight, line-height. Look for `text-\[\d+px\]` a
 
 ## Category 8 — CTA hierarchy (weight 1.0)
 
+**Rationale:** Hick-Hyman Law — decision time grows with the log of equally-weighted options; multiple competing primaries flatten hierarchy into a choose-your-adventure and cost measurable conversion (Baymard PDP data).
+
 **Question:** Is there ONE primary CTA per view?
 
 **Detect:** Count buttons with `variant=default | primary | filled` OR bg-primary class. >1 above fold = competing.
@@ -159,6 +175,8 @@ Reference: Baymard PDP — 51% of e-commerce pages fail due to competing CTAs.
 
 ## Category 9 — State coverage (weight 1.1)
 
+**Rationale:** Norman's "make system state visible" (Seven Stages of Action) + Nielsen H1 visibility-of-system-status — missing loading/empty/error states break the user's feedback loop and strand them in uncertainty.
+
 Per page, does the UI handle: default / loading / empty / error / success?
 
 **Detect per scenario:**
@@ -177,37 +195,89 @@ Per page, does the UI handle: default / loading / empty / error / success?
 
 ## Category 10 — Touch targets (mobile only, weight 1.0)
 
-**Detect:** `browser_evaluate` → get `getBoundingClientRect` of every clickable. Count targets < 44×44 px.
+**Rationale:** Fitts's Law (MT = a + b·log₂(2D/W)) — acquisition time scales inversely with target width; sub-44px targets on fingers multiply error rate and exhaust motor patience.
+
+**Detect:** `browser_evaluate` → get `getBoundingClientRect` of every
+clickable (buttons, links, `[role=button|link|tab|checkbox|radio|switch]`,
+`<input>`, `<select>`, `<summary>`, anchors with click handlers). Record
+the smaller of `width × height` per target.
+
+### Spec reconciliation
+
+Three conflicting specs define "how big a touch target should be":
+
+| Spec | Size | Nature | Citation |
+|---|---|---|---|
+| **WCAG 2.5.8 Target Size (Minimum) — AA** | **24 × 24 CSS px** | Baseline (legal/accessibility floor, with spacing exception) | https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum |
+| **Apple Human Interface Guidelines** | **44 × 44 pt** | Platform-native target (iOS) | https://developer.apple.com/design/human-interface-guidelines/accessibility#Interactivity |
+| **Material Design (Android)** | **48 × 48 dp** | Platform-native target (Android) | https://m3.material.io/foundations/accessible-design/accessibility-basics |
+| **WCAG 2.5.5 Target Size (Enhanced) — AAA** | 44 × 44 CSS px | Advisory ceiling | https://www.w3.org/WAI/WCAG21/Understanding/target-size |
+
+sd-audit reconciles as follows:
+- **Baseline = 24 × 24 CSS px** — WCAG 2.5.8 AA pass; legally sufficient
+  (with 24px center-to-center spacing exception).
+- **Target = 44 × 44 CSS px** — HIG / Material / WCAG AAA; the single
+  pragmatic "platform-native" size across iOS + Android + web (Android
+  48 dp ≈ 44 CSS px at default DPI).
+- Spacing exception keeps sub-44 icons compliant with WCAG AA but does NOT
+  earn full design-intelligence points — they still feel cramped on a
+  phone, which is what Fitts's Law above predicts.
+
+### Scoring ladder
+
+Per-target classification:
+- **Full points** (≥ 44 × 44 CSS px) — platform-native, HIG/Material-clean.
+- **Half points** (24 – 43 CSS px, min dimension) — WCAG AA pass but
+  sub-optimal; counts as half a compliant target.
+- **Zero points** (< 24 CSS px, min dimension) — WCAG AA FAIL; raises a
+  separate `a11y-wcag22-2.5.8` finding in addition to pulling this score.
+
+Let `N` = total targets, `n44` = count ≥ 44×44, `n24` = count in
+[24, 44), `n0` = count < 24. Compute
+`compliance = (n44 + 0.5 × n24) / N`.
 
 | Score | Criteria |
 |---|---|
-| 10 | 100% targets ≥ 44×44 OR 24×24 with 8px+ gap |
-| 7 | 80–99% compliant |
-| 4 | 50–80% compliant (common: icon-only buttons) |
-| 0 | Widespread <24px targets |
+| 10 | `compliance ≥ 0.95` AND `n0 == 0` — essentially all targets ≥ 44 |
+| 7  | `0.80 ≤ compliance < 0.95` AND `n0 == 0` — some half-credit (24–43 px) targets, none under 24 |
+| 4  | `0.50 ≤ compliance < 0.80` OR `0 < n0 ≤ 2` — common icon-only button fail; any WCAG breach |
+| 0  | `compliance < 0.50` OR `n0 ≥ 3` — widespread <24 px targets, structural problem |
+
+Any `n0 > 0` ALWAYS also raises a separate finding with prefix
+`a11y-wcag22-2.5.8` (the rubric scores design intelligence; the finding
+records the legal breach).
 
 ---
 
-## Category 11 — Motion & feedback (weight 0.6)
+## Category 11 — Motion & feedback / perceived performance (weight 0.6)
 
-**Question:** Do interactions give feedback? Are animations tasteful and respect `prefers-reduced-motion`?
+**Rationale:** Doherty threshold (Doherty & Thadhani, IBM 1982) — system response <400 ms sustains flow; above that, perceived unresponsiveness begins. Paired with INP (Core Web Vitals) for the measurable proxy.
+
+**Question:** Do interactions give feedback? Are animations tasteful and respect `prefers-reduced-motion`? Does every interaction land within the Doherty ceiling?
 
 **Detect:**
 - `browser_evaluate` with `matchMedia('(prefers-reduced-motion: reduce)')` + check for `transition` / `animation` on interactive elements.
 - Missing hover/focus feedback on buttons = major fail.
 - >3s animations = excessive.
 
+**Perceived-performance sub-criterion (Doherty 400 ms ceiling, alongside INP).**
+- Parse `session_dir/vitals/<page>.json` for INP (from `web-vitals@5` attribution build).
+- For each primary interaction (Step 2.5 Phase A enumeration — clicks on CTA, form submit, nav link, combobox, modal trigger), compute **end-to-end response time** = click → visual feedback (spinner / state change / new pixels painted), not just INP.
+- Fail rule: an interaction that **passes INP** (≤ 200 ms rating "good") but whose **user-perceivable response exceeds 400 ms** (e.g., INP fires at 150 ms but the resulting navigation/paint lands at 900 ms with no intermediate skeleton/optimistic UI) **penalizes C11**. Doherty is the ceiling; INP is the low-floor subset. Apply the Nielsen 0.1 s / 1 s / 10 s progress rule for anything over 400 ms (skeleton, optimistic UI, determinate bar + ETA + cancel for >10 s).
+
 | Score | Criteria |
 |---|---|
-| 10 | Hover/focus/active feedback everywhere; animations ≤300ms; reduced-motion respected |
-| 7 | Most interactions feedback; reduced-motion partial |
-| 4 | Some interactions static; reduced-motion ignored |
-| 0 | No hover/focus feedback at all OR autoplay video + parallax with no disable |
+| 10 | Hover/focus/active feedback everywhere; animations ≤300 ms; reduced-motion respected; every interaction under Doherty 400 ms OR shows skeleton/optimistic state |
+| 7 | Most interactions feedback; reduced-motion partial; occasional >400 ms interaction without feedback |
+| 4 | Some interactions static; reduced-motion ignored; multiple interactions cross Doherty with no intermediate state |
+| 0 | No hover/focus feedback at all OR autoplay video + parallax with no disable OR interactions routinely exceed 400 ms with blank waits |
 
 ---
 
 ## Category 12 — Nav pattern matches platform (weight 1.0)
 
+**Rationale:** Fitts's Law + Hick-Hyman Law — nav patterns succeed when they minimize both motor cost (thumbzone/edge placement) and choice cost (limited top-level destinations, chunked per Miller 4±1).
+
 | Viewport | Expected nav |
 |---|---|
 | Mobile (≤768) | Bottom tab bar (3–5), full-screen menus, gesture back |
@@ -226,6 +296,9 @@ Per page, does the UI handle: default / loading / empty / error / success?
 
 ## Category 13 — Table-on-mobile detection (weight 1.2, mobile only)
 
+**Rationale:** Platform affordance + thumbzone — desktop tables violate mobile reading models (microtext, horizontal overflow, no visible sort); transformation to card/list is the minimum cost to preserve parse-ability.
+
+
 **Detect:** At ≤768px, find `<table>` with >3 visible columns OR `display: table` containers with horizontal scroll AND text < 13px.
 
 | Score | Criteria |
@@ -240,6 +313,8 @@ Per page, does the UI handle: default / loading / empty / error / success?
 
 ## Category 14 — Modal/sheet appropriateness (weight 0.8)
 
+**Rationale:** Fitts's Law + thumbzone — on mobile, close affordances belong where the thumb lives; centered dialogs with top-right dismiss violate reach on phones and strand users in forced-modal states.
+
 | Viewport | Expected modal pattern |
 |---|---|
 | Mobile | Bottom sheet (slide-up) or full-screen with close top-left |
@@ -258,6 +333,8 @@ Per page, does the UI handle: default / loading / empty / error / success?
 
 ## Category 15 — Color semantics (weight 0.6)
 
+**Rationale:** Jakob's Law (users spend most time on other products) + learned convention — red/green/amber mappings are pre-installed in users' mental models; using them decoratively forces re-learning and breaks status recognition at a glance.
+
 **Detect:** Collect colors used on: error messages, success states, warnings, info. Red = error? Green = success? Or decorative-only?
 
 | Score | Criteria |
@@ -270,6 +347,8 @@ Per page, does the UI handle: default / loading / empty / error / success?
 
 ## Category 16 — Design-system coherence (weight 1.1)
 
+**Rationale:** Tesler's Law (conservation of complexity) + von Neumann consistency — complexity does not disappear, it moves; a disciplined system absorbs variation once inside tokens/variants/primitives so every downstream surface stays predictable. Incoherent systems push the same complexity onto users (re-learning each screen) and onto engineers (ad-hoc classes per component). This is why C16 carries one of the highest weights: coherence is not polish, it is the mechanism that conserves attention.
+
 **The meta-category.** Does the app LOOK like it was designed by one team with one vision? Or does it look like a collection of shadcn defaults?
 
 **Detect (aesthetic signal):**
@@ -290,6 +369,8 @@ session. See `design-skills-catalog.md`.
 
 ## Category 17 — Vibecode detection (weight 1.0)
 
+**Rationale:** Norman's reflective layer (Emotional Design, 2004 — artifact line 547) — vibecoded surfaces pass the visceral/behavioral layers but fail reflective judgment; code that reads as "hand-assembled divs" telegraphs lack of intentional system, which is exactly what distinguishes "designed" from "vibecoded" output.
+
 **Question:** Does the code follow patterns (components, variants, tokens)
 or is it hand-assembled divs with inline styles?
 

package/template/.claude/skills/super-design/references/design-skills-catalog.md

@@ -62,6 +62,37 @@ it follows the skill's specific tokens + patterns instead of defaults.
 | Editorial / blog | Readable long-form | `typeui-paper` |
 | Feature-grid homepage | Modular showcase | `typeui-bento` |
 
+### Vibe → typeui skill (primary → fallback)
+
+Covers every vibe enumerated in the artifact Part 4 (12-vibe vocabulary). The
+primary skill carries the aesthetic; the fallback handles adjacent contexts or
+fills gaps when the primary would over-commit. When a project vibe has no
+single-perfect skill (e.g. Premium/luxury, Warm/organic), the fallback plus
+`/frontend-design` is the intended path.
+
+| Part-4 vibe | Primary skill | Fallback | Notes |
+|---|---|---|---|
+| Minimal / clean | `typeui-clean` | `typeui-application` | Default pick for pre-launch marketing and "honest SaaS". |
+| Bold / confident | `typeui-bold` | `typeui-dramatic` | Challenger brands, consumer launches. |
+| Playful / friendly | `typeui-doodle` | `typeui-artistic` | Education, kids, creative tools. |
+| Serious / professional (B2B) | `typeui-enterprise` | `typeui-ant` | Procurement-facing, compliance. |
+| Technical / data-dense (SaaS admin) | `typeui-dashboard` | `typeui-application` | Dark-theme analytics, operator consoles. |
+| Editorial / reading | `typeui-paper` | `typeui-clean` | Long-form content, publications. |
+| Modular / showcase | `typeui-bento` | `typeui-application` | Feature grids, portfolios. |
+| Expressive / artistic | `typeui-artistic` | `typeui-dramatic` | Design tools, non-enterprise vibe-forward. |
+| Raw / statement (neobrutalism) | `typeui-neobrutalism` | `typeui-bold` | Gen-Z, indie, deliberate rule-breaking. |
+| Premium / luxury | `typeui-dramatic` | `typeui-paper` | No dedicated luxury skill — combine dramatic hero with paper's typographic restraint, then commission custom tokens via `/frontend-design`. |
+| Tech / cyberpunk | `typeui-dashboard` | `typeui-bold` | Dashboard dark base + bold accent/glow; extend via `/frontend-design` for neon/chromatic detail. |
+| Warm / organic | `typeui-paper` | `typeui-doodle` | Paper carries the warmth via texture + typographic rhythm; doodle adds hand-made detail for craft brands. |
+| Retro / nostalgic | `typeui-paper` | `typeui-doodle` | Paper's print-era cues fit mid-century/editorial retro; doodle for 90s/zine nostalgia. `/frontend-design` required for period-specific palettes. |
+| Dark / cinematic | `typeui-dramatic` | `typeui-dashboard` | Dramatic for narrative hero surfaces; dashboard for operator/app surfaces that must stay dark through the product. |
+
+Read this table as: "if the positioning brief (sd-research §4) lands on vibe X,
+sd-audit/sd-fix should recommend the **primary** skill first; if the project
+has constraints that rule it out (e.g. already on a light palette), fall back
+to the secondary; if both are partial, log a non-blocking advisory that
+`/frontend-design` is required to finish the aesthetic."
+
 ## Recommending a skill in a finding
 
 When `design-intelligence.categories.design_system_coherence.score ≤ 4`,

package/template/.claude/skills/super-design/scripts/build-import-graph.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# build-import-graph.sh — build a JS/TS import graph for the repo so
+# super-design can propagate component-level changes to pages within N
+# hops (artifact §8, line 666: default N=3).
+#
+# Usage:
+#   build-import-graph.sh [--state <path>]            # full build
+#   build-import-graph.sh importers <file> [--hops N] # BFS query
+#
+# Output (full build): .super-design/import-graph.json with shape
+#   {
+#     "nodes":   ["src/app/page.tsx", ...],
+#     "edges":   [{"from":"src/app/page.tsx","to":"src/components/Nav.tsx"}, ...],
+#     "hash":    "sha256:<hex>",
+#     "backend": "madge" | "regex-fallback",
+#     "built_at":"<ISO-8601>"
+#   }
+#
+# State: writes `import_graph_sha` back into .audit-state.json via
+# scripts/write-state.sh. The sha lives in audit-state.schema.json so
+# detect-changes.sh can short-circuit re-propagation if the graph is
+# unchanged.
+#
+# Backend choice:
+#   1. If `npx madge --version` works, use `npx madge --json <roots>`
+#      (artifact §8: madge reads .madgerc / package.json#madge).
+#   2. Else fall back to a zero-dep regex scanner (JS/TS/JSX/TSX only —
+#      no CSS/Vue/Svelte detectives, no alias resolution). Logs a
+#      warning so the caller knows propagation is best-effort.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STATE_PATH="docs/super-design/.audit-state.json"
+OUT_DIR=".super-design"
+OUT_FILE="$OUT_DIR/import-graph.json"
+
+log() { printf '[build-import-graph] %s\n' "$*" >&2; }
+
+# Source roots — read from state, else default.
+resolve_roots() {
+  local roots=""
+  if [[ -f "$STATE_PATH" ]]; then
+    roots="$(jq -r '.source_roots // empty | .[]?' "$STATE_PATH" 2>/dev/null || true)"
+  fi
+  if [[ -z "$roots" ]]; then
+    for d in src app pages; do [[ -d "$d" ]] && echo "$d"; done
+  else
+    printf '%s\n' "$roots"
+  fi
+}
+
+# --- Full build -----------------------------------------------------------
+
+build_madge() {
+  # madge prints { "file": [deps], ... }. We flatten to edges.
+  local roots_json
+  roots_json="$(resolve_roots | jq -Rn '[inputs]')"
+  local roots
+  roots="$(printf '%s' "$roots_json" | jq -r '.[]' | tr '\n' ' ')"
+  [[ -z "$roots" ]] && { log "no source roots found"; echo '{}'; return; }
+  # shellcheck disable=SC2086
+  npx --yes madge --json $roots 2>/dev/null
+}
+
+build_regex_fallback() {
+  log "madge unavailable; using regex fallback (JS/TS only, no alias resolution)"
+  local roots
+  roots="$(resolve_roots | tr '\n' ' ')"
+  [[ -z "$roots" ]] && { echo '{}'; return; }
+
+  # Emit NDJSON: {"from":"<path>","to":"<dep>"} for each import line in
+  # each JS/TS file, then fold into {file: [deps]} via jq.
+  # shellcheck disable=SC2086
+  find $roots -type f \( \
+      -name '*.ts' -o -name '*.tsx' \
+      -o -name '*.js' -o -name '*.jsx' \
+      -o -name '*.mjs' -o -name '*.cjs' \) 2>/dev/null \
+  | while IFS= read -r f; do
+      # Grep import/require specifiers. Handles:
+      #   import ... from 'x'
+      #   import 'x'
+      #   require('x')
+      #   import('x')          (dynamic)
+      #   export ... from 'x'
+      grep -hoE "(from|require|import)[[:space:]]*\(?[[:space:]]*['\"][^'\"]+['\"]" "$f" 2>/dev/null \
+        | sed -E "s|.*['\"]([^'\"]+)['\"].*|\1|" \
+        | while IFS= read -r spec; do
+            [[ -z "$spec" ]] && continue
+            # Skip bare package specifiers for graph purposes (we only
+            # want local file edges to compute importers).
+            case "$spec" in
+              .*|/*) : ;;
+              *) continue ;;
+            esac
+            # Normalize: resolve relative to $f's directory, best-effort.
+            local dir resolved
+            dir="$(dirname "$f")"
+            resolved="$dir/$spec"
+            # Strip ./ and trailing /
+            resolved="$(printf '%s' "$resolved" \
+              | sed -E 's|/\./|/|g; s|/$||')"
+            jq -cn --arg from "$f" --arg to "$resolved" '{from:$from,to:$to}'
+          done
+    done \
+  | jq -sc 'group_by(.from) | map({key:.[0].from, value:(map(.to)|unique)}) | from_entries'
+}
+
+build_graph_json() {
+  local raw
+  if npx --yes madge --version >/dev/null 2>&1; then
+    raw="$(build_madge || echo '{}')"
+    BACKEND="madge"
+  else
+    raw="$(build_regex_fallback || echo '{}')"
+    BACKEND="regex-fallback"
+  fi
+  [[ -z "$raw" ]] && raw='{}'
+  printf '%s' "$raw"
+}
+
+emit_final() {
+  local raw="$1"
+  mkdir -p "$OUT_DIR"
+  # Build nodes + edges from the {file: [deps]} shape. Keep original
+  # paths verbatim (do not attempt alias resolution here).
+  local body
+  body="$(printf '%s' "$raw" | jq --arg backend "$BACKEND" --arg now "$(date -u +%FT%TZ)" '
+    . as $g
+    | ([keys[], (.[] | .[])] | unique) as $nodes
+    | [to_entries[] | .key as $from | .value[] | {from:$from, to:.}] as $edges
+    | {nodes:$nodes, edges:$edges, backend:$backend, built_at:$now}
+  ')"
+  # Hash over nodes+edges (stable serialization via jq --sort-keys -c).
+  local hash
+  hash="$(printf '%s' "$body" | jq -S -c '{nodes, edges}' | sha256sum | awk '{print "sha256:"$1}')"
+  printf '%s' "$body" | jq --arg h "$hash" '. + {hash:$h}' > "$OUT_FILE"
+
+  # Update state.import_graph_sha if state file exists.
+  if [[ -f "$STATE_PATH" ]]; then
+    jq --arg h "$hash" '. + {import_graph_sha:$h}' "$STATE_PATH" \
+      | bash "$SCRIPT_DIR/write-state.sh" "$STATE_PATH" >/dev/null \
+      || log "failed to persist import_graph_sha to state"
+  fi
+
+  jq -n --arg path "$OUT_FILE" --arg hash "$hash" --arg backend "$BACKEND" \
+        --argjson nodes "$(jq '.nodes|length' "$OUT_FILE")" \
+        --argjson edges "$(jq '.edges|length' "$OUT_FILE")" \
+    '{status:"ok", path:$path, hash:$hash, backend:$backend, nodes:$nodes, edges:$edges}'
+}
+
+# --- Query: importers_of --------------------------------------------------
+
+# importers_of <file> [--hops N]
+#   BFS over the edge list using jq. Emits one path per line.
+importers_of() {
+  local file="$1"; shift || true
+  local hops=3
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hops) hops="${2:-3}"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  [[ -f "$OUT_FILE" ]] || { log "no import graph; run build first"; return 1; }
+  jq -r --arg start "$file" --argjson hops "$hops" '
+    . as $g
+    # Reverse adjacency: to → [from...]
+    | ([.edges[] | {key:.to, value:.from}] | group_by(.key)
+        | map({key:.[0].key, value:(map(.value)|unique)}) | from_entries) as $rev
+    | def bfs(frontier; seen; depth):
+        if depth >= $hops or (frontier|length)==0 then seen
+        else
+          (frontier | map($rev[.] // []) | add // [] | unique) as $next
+          | ($next - (seen|keys | map(.))) as $fresh
+          | bfs($fresh; (seen + ($fresh | map({(.):true}) | add // {})); depth + 1)
+        end;
+      bfs([$start]; {}; 0) | keys[]
+  ' "$OUT_FILE"
+}
+
+# --- Dispatch -------------------------------------------------------------
+
+main() {
+  case "${1:-build}" in
+    build|"")
+      shift || true
+      while [[ $# -gt 0 ]]; do
+        case "$1" in
+          --state) STATE_PATH="${2:?}"; shift 2 ;;
+          *) shift ;;
+        esac
+      done
+      raw="$(build_graph_json)"
+      emit_final "$raw"
+      ;;
+    importers)
+      shift
+      [[ -z "${1:-}" ]] && { log "usage: importers <file> [--hops N]"; exit 2; }
+      importers_of "$@"
+      ;;
+    *)
+      log "unknown subcommand: $1"
+      exit 2
+      ;;
+  esac
+}
+
+main "$@"