start-vibing 4.3.2 → 4.3.4

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "start-vibing",
-	"version": "4.3.2",
-	"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.2: canonical audit-state.schema.json + verify --strict, per-viewport {sha256,phash,png_path} hashes with sharp/fpr fallback + MASK_SELECTORS, visual-regression.sh (pixelmatch→odiff→sha256-fallback), DTCG *.tokens.json + Tokens Studio aliases, @fixture-<id> dynamic routes + madge import-graph N=3, per-app monorepo state (pnpm/npm/yarn/Bun/Nx/Turbo).",
+	"version": "4.3.4",
+	"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.4: Baymard verbatim rules backfilled — search (12), filter (10), breadcrumbs (6), PDP (18) now enumerated in audit-methodology.md with rule IDs + source URLs (joining the existing cc/14 + addr/8 sets), plus docs/research/baymard-public-rules.md catalogs 88 rules with SHOT+QUOTE+SEL+VAL evidence for detectors. DSC-choice typeui selection + harvest-typeui.sh carry over from 0.6.3.",
 	"type": "module",
 	"bin": {
 		"start-vibing": "./dist/cli.js"

package/template/.claude/skills/super-design/SKILL.md

@@ -8,7 +8,7 @@ description: >
   UX audit (WCAG 2.2 AA, Nielsen heuristics, Baymard, CWV), and synthesized
   overview. Re-audits only what changed since last run. On explicit user request,
   applies surgical fixes with full rollback.
-version: 0.6.2
+version: 0.6.4
 ---
 
 # super-design
@@ -33,17 +33,25 @@ Four-phase pipeline with 6 specialist agents:
      low density, weak CTA hierarchy, vibecode smell).
    - **Step 3h mobile-native audit** (21-item Duolingo/Linear/Arc/Cash-App
      checklist) — replaces "responsive-web-on-a-phone" thinking.
-   - C16 ≤ 4 → design-skill advisory finding citing typeui-* selection matrix.
+   - C16 ≤ 4 → **DSC-choice** proposal: sd-synthesis runs
+     `scripts/score-typeui.mjs --from-audit <dir>` to derive a 7-axis site
+     fingerprint (density/contrast/geometry/color/typography/motion/audience)
+     and rank all installed typeui-* skills by fit 0-1. Top-3 are written to
+     `typeui-proposal.json` + shown in overview.md with a copy-paste CLI.
    Produces findings.json + design-intelligence.json with SHOT+QUOTE+SEL+VAL.
 3. **Synthesis** (sd-synthesis) — unifies research + audit + design-intelligence
-   into overview.md (per-page DIS table + executive summary).
+   into overview.md (per-page DIS table + executive summary + typeui proposal
+   when craft ≤ 4).
 4. **Fix** (sd-fix + two-stage verify) — optional. Applies safe fixes with
    technical gates (types/lint/tests) AND semantic verification ("does this
    fix actually resolve the finding, or just mask it?"). Template families:
    A1-A15 a11y · V1-V8 design · U1-U10 ux · P1-P10 perf · **M1-M15 mobile**
    (cards-in-flex-col → compact list, table-on-mobile → card-per-row,
    centered-modal → bottom-sheet, etc.) · **DSC-1 design-skill advisory**
-   (proposes typeui-* direction, never auto-applies — HIGH risk). After each
+   (proposes typeui-* direction). With `--typeui <name>` flag, sd-fix loads
+   the chosen typeui skill (tokens: primary, radius, spacing scale,
+   typography) and rebrands V1-V8 fixes so every spacing/color/radius target
+   snaps to that direction's scale — turning advisory into applied. After each
    successful fix, re-drives Playwright to capture an after-screenshot (full
    page + element crop) and emits `docs/super-design/sessions/<id>/fix-report.md`:
    a self-contained visual diff with before/after images, file diffs,
@@ -109,6 +117,15 @@ Do NOT paste overview into chat.
   `name` entry from `scripts/detect-apps.sh`). Required when `--scope <url>`
   is ambiguous between multiple apps.
 - `--fix` — run sd-fix after audit
+- `--typeui <name>` — combine with `--fix` to apply fixes aligned to a
+  chosen typeui direction (e.g. `--fix --typeui application`). Loads tokens
+  from `~/.claude/skills/typeui-<name>/SKILL.md` and rebrands V1-V8 targets
+  to that scale. Picked from the top-3 proposed in overview.md typeui
+  block. Without this flag, DSC-1 stays advisory. Run
+  `bash scripts/score-typeui.mjs --list` to see all installed directions.
+- `--harvest-typeui` — run `scripts/harvest-typeui.sh` first to pull
+  missing typeui-* and related design skills (typeui.sh registry with
+  built-in catalog fallback). Idempotent; add `--refresh` to re-download.
 - `--dry-run` — artifacts without committing state
 - `--ci` — non-interactive, create PR, exit non-zero on blockers
 - `--update-baselines` — Re-hash pages and tokens without re-auditing (use after accepted cosmetic drift). Also accepted by `scripts/visual-regression.sh` to overwrite `.super-design/baselines/*.png` with the current capture.

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

@@ -311,13 +311,69 @@ source section cited.
 
 > 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.
+**`baymard-search-*` — Search (12 rules, §3.6):**
+1. `baymard-search-01` persist search query in the field after submission
+2. `baymard-search-02` autocomplete list capped at 10 items desktop, 4–8 mobile
+3. `baymard-search-03` style category-scope suggestions distinctly within autocomplete
+4. `baymard-search-04` highlight the predictive (un-typed) portion of autocomplete suggestions
+5. `baymard-search-05` copy active autocomplete suggestion into the field on keyboard navigation
+6. `baymard-search-06` support misspellings in autocomplete (spell-tolerant suggestions)
+7. `baymard-search-07` autodirect exact category-match queries to the category page
+8. `baymard-search-08` support synonym and alternate-term searches
+9. `baymard-search-09` support abbreviation and symbol searches
+10. `baymard-search-10` allow "search within" current category on mobile
+11. `baymard-search-11` support non-product queries (return policy, order status, FAQ)
+12. `baymard-search-12` provide 5 proven no-results recovery paths (spelling fix, broaden, contact, etc.)
+
+> Source: §3.6 bullets + https://baymard.com/ecommerce-design-examples/34-autocomplete-suggestions + per-rule URLs in `/docs/research/baymard-public-rules.md` (B-S-01…B-S-12).
+
+**`baymard-filter-*` — Filter (10 rules, §3.6):**
+1. `baymard-filter-01` provide the 5 essential filter types (category, price, rating, brand, user-relevant attribute)
+2. `baymard-filter-02` have filters for every attribute displayed in list items
+3. `baymard-filter-03` display applied filters in a visible overview area, individually removable
+4. `baymard-filter-04` use OR logic within a facet, AND logic across facets
+5. `baymard-filter-05` show product counts per filter value and update them dynamically
+6. `baymard-filter-06` collapse long facet lists to top 4–6 values with a "Show more" link
+7. `baymard-filter-07` explain industry-specific or jargon filter labels
+8. `baymard-filter-08` promote important filters above the product grid / above the fold
+9. `baymard-filter-09` provide 4 essential sort options (featured, price asc/desc, rating, newest)
+10. `baymard-filter-10` persist filter state when user returns from a product detail page
+
+> Source: §3.6 bullets + https://baymard.com/blog/promoting-product-filters + https://baymard.com/blog/have-filters-for-list-item-info + per-rule URLs in `/docs/research/baymard-public-rules.md` (B-F-01…B-F-10).
+
+**`baymard-bread-*` — Breadcrumbs (6 rules, §3.7):**
+1. `baymard-bread-01` provide both hierarchy-based AND history-based breadcrumbs
+2. `baymard-bread-02` include the full category hierarchy in the breadcrumb trail
+3. `baymard-bread-03` suppress homepage and current product page layers from the trail
+4. `baymard-bread-04` make breadcrumbs swipeable on mobile for long paths
+5. `baymard-bread-05` use clear tappability cues on mobile breadcrumbs (size, underline, chevron)
+6. `baymard-bread-06` expose `BreadcrumbList` structured-data markup for SEO and assistive tech
+
+> Rules 01–05 from verified public research (B-B-01…B-B-05). Rule 06 enumerated from §3.7 narrative; supersede when Baymard Premium IDs become available.
+> Source: §3.7 + https://baymard.com/blog/ecommerce-breadcrumbs + per-rule URLs in `/docs/research/baymard-public-rules.md`.
+
+**`baymard-pdp-*` — PDP / Product Detail (18 rules, §3.8):**
+1. `baymard-pdp-01` use button-style size selectors (swatches), not dropdowns
+2. `baymard-pdp-02` provide at least one in-scale product image (size/context reference)
+3. `baymard-pdp-03` show product on a human model for worn or carried items
+4. `baymard-pdp-04` provide sufficient image resolution and zoom on desktop and mobile
+5. `baymard-pdp-05` support both pinch and double-tap zoom gestures on mobile
+6. `baymard-pdp-06` allow guest users to save / wishlist items without account creation
+7. `baymard-pdp-07` display a return-policy link or summary directly on the product page
+8. `baymard-pdp-08` show the lowest shipping-cost estimate (and ETA) on the product page
+9. `baymard-pdp-09` allow carousel navigation across reviewer-submitted images (UGC)
+10. `baymard-pdp-10` respond publicly to negative reviews to demonstrate accountability
+11. `baymard-pdp-11` display price-per-unit for multi-quantity or weight-priced products
+12. `baymard-pdp-12` synchronize product data (price, stock, images) across variation selections
+13. `baymard-pdp-13` include descriptive text or graphics on key product images (annotations)
+14. `baymard-pdp-14` single dominant Add-to-Cart CTA — not 3–6 competing colorful buttons
+15. `baymard-pdp-15` prefer accordion over horizontal tabs for PDP detail sections
+16. `baymard-pdp-16` show out-of-stock variants as visible-but-disabled (never remove from UI)
+17. `baymard-pdp-17` offer a "notify me when back in stock" flow for OOS variants
+18. `baymard-pdp-18` surface size-guide inline on the PDP — not hidden behind a separate page
+
+> Rules 01–13 from verified public research (B-P-01…B-P-13). Rules 14–18 enumerated from §3.8 narrative; supersede when Baymard Premium IDs become available.
+> Source: §3.8 + https://baymard.com/research/product-page + per-rule URLs in `/docs/research/baymard-public-rules.md`.
 
 ### 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/scripts/harvest-typeui.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# harvest-typeui.sh — discover + install typeui-* and related design skills.
+#
+# Sources, in order:
+#   1. typeui.sh registry (if reachable) — fetch catalog.json, install missing
+#   2. vercel-labs/agent-skills design skills (composition, web-design-guidelines)
+#   3. anthropics/skills webapp-testing + mcp-builder (already covered, idempotent)
+#
+# Usage:
+#   harvest-typeui.sh              # install everything missing (user-scope ~/.claude/skills/)
+#   harvest-typeui.sh --list       # print catalog without installing
+#   harvest-typeui.sh --refresh    # re-download even if already installed
+#   harvest-typeui.sh --dest <dir> # install to custom dir (default: ~/.claude/skills)
+
+set -euo pipefail
+
+DEST="${HOME}/.claude/skills"
+LIST_ONLY=0
+REFRESH=0
+
+while (( $# )); do
+  case "$1" in
+    --list) LIST_ONLY=1 ;;
+    --refresh) REFRESH=1 ;;
+    --dest) DEST="$2"; shift ;;
+    -h|--help)
+      sed -n '2,18p' "$0"
+      exit 0 ;;
+    *) echo "unknown flag: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+mkdir -p "$DEST"
+
+TYPEUI_CATALOG_URL="${TYPEUI_CATALOG_URL:-https://typeui.sh/catalog.json}"
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+
+log() { echo "[harvest-typeui] $*"; }
+
+fetch_catalog() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -sSfL --max-time 10 "$TYPEUI_CATALOG_URL" -o "$TMP" 2>/dev/null && return 0
+  fi
+  if command -v wget >/dev/null 2>&1; then
+    wget -q --timeout=10 -O "$TMP" "$TYPEUI_CATALOG_URL" 2>/dev/null && return 0
+  fi
+  return 1
+}
+
+# Fallback catalog — built-in list of known typeui skills + companions.
+# Format: name|base_url (raw SKILL.md location)
+DEFAULT_CATALOG=$(cat <<'EOF'
+typeui-ant|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-ant/SKILL.md
+typeui-application|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-application/SKILL.md
+typeui-artistic|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-artistic/SKILL.md
+typeui-bento|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-bento/SKILL.md
+typeui-bold|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-bold/SKILL.md
+typeui-clean|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-clean/SKILL.md
+typeui-dashboard|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-dashboard/SKILL.md
+typeui-doodle|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-doodle/SKILL.md
+typeui-dramatic|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-dramatic/SKILL.md
+typeui-enterprise|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-enterprise/SKILL.md
+typeui-neobrutalism|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-neobrutalism/SKILL.md
+typeui-paper|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-paper/SKILL.md
+composition-patterns|https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/composition-patterns/SKILL.md
+web-design-guidelines|https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/web-design-guidelines/SKILL.md
+react-best-practices|https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/react-best-practices/SKILL.md
+webapp-testing|https://raw.githubusercontent.com/anthropics/skills/main/skills/webapp-testing/SKILL.md
+mcp-builder|https://raw.githubusercontent.com/anthropics/skills/main/skills/mcp-builder/SKILL.md
+EOF
+)
+
+CATALOG=""
+if fetch_catalog; then
+  # typeui.sh returned JSON — extract {name,url} tuples via node
+  if command -v node >/dev/null 2>&1; then
+    CATALOG=$(node -e "
+      const c = JSON.parse(require('fs').readFileSync('$TMP','utf8'));
+      const items = c.skills || c.items || c;
+      for (const it of items) {
+        const n = it.name || it.slug;
+        const u = it.skill_url || it.url || it.raw || it.source;
+        if (n && u) console.log(n + '|' + u);
+      }
+    " 2>/dev/null || echo "")
+  fi
+fi
+
+if [[ -z "$CATALOG" ]]; then
+  log "registry unreachable or empty — using built-in catalog"
+  CATALOG="$DEFAULT_CATALOG"
+fi
+
+if (( LIST_ONLY )); then
+  echo "$CATALOG"
+  exit 0
+fi
+
+INSTALLED=0
+SKIPPED=0
+FAILED=0
+
+while IFS='|' read -r name url; do
+  [[ -z "$name" ]] && continue
+  target_dir="$DEST/$name"
+  target_file="$target_dir/SKILL.md"
+
+  if [[ -f "$target_file" && $REFRESH -eq 0 ]]; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  mkdir -p "$target_dir"
+  if command -v curl >/dev/null 2>&1; then
+    if curl -sSfL --max-time 15 "$url" -o "$target_file" 2>/dev/null; then
+      log "installed $name"
+      INSTALLED=$((INSTALLED + 1))
+    else
+      log "failed $name ($url)"
+      FAILED=$((FAILED + 1))
+      rmdir "$target_dir" 2>/dev/null || true
+    fi
+  else
+    log "curl missing — cannot fetch $name"
+    FAILED=$((FAILED + 1))
+  fi
+done <<< "$CATALOG"
+
+log "done: installed=$INSTALLED skipped=$SKIPPED failed=$FAILED dest=$DEST"

package/template/.claude/skills/super-design/scripts/score-typeui.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// score-typeui.mjs — rank typeui-* skills by fit against a site fingerprint.
+//
+// Usage:
+//   node score-typeui.mjs <fingerprint.json> [--top 3]
+//   node score-typeui.mjs --from-audit <audit-dir>         # derive fingerprint from sd-audit findings + DIS
+//   node score-typeui.mjs --list                            # list available typeui skills with axes
+//
+// Fingerprint input (JSON):
+//   { density: "low|medium|high", contrast: "low|medium|high",
+//     geometry: "round|square|mixed", color: "muted|vibrant|bold",
+//     typography: "neutral|expressive|display", motion: "static|subtle|dynamic",
+//     audience: "enterprise|developer|consumer|creative" }
+//
+// Output (stdout): JSON { ranked: [{ name, fit, reasons, applies_tokens }] }
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const AXES = ['density', 'contrast', 'geometry', 'color', 'typography', 'motion', 'audience'];
+
+// Static fingerprint matrix — derived from each typeui SKILL.md style foundations.
+// Keep in sync with skills at ~/.claude/skills/typeui-*/SKILL.md. Expand via harvest-typeui.sh.
+const TYPEUI = {
+  ant: {
+    density: 'high', contrast: 'medium', geometry: 'square',
+    color: 'muted', typography: 'neutral', motion: 'static', audience: 'enterprise',
+    tokens: { primary: '#1677ff', radius: 6, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Structured, enterprise-focused design. Data-dense tables, forms.',
+  },
+  application: {
+    density: 'medium', contrast: 'high', geometry: 'round',
+    color: 'vibrant', typography: 'neutral', motion: 'subtle', audience: 'developer',
+    tokens: { primary: '#9333ea', radius: 8, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Vercel/GitHub purple aesthetic. Top-bar nav, card layouts.',
+  },
+  artistic: {
+    density: 'low', contrast: 'high', geometry: 'mixed',
+    color: 'bold', typography: 'expressive', motion: 'dynamic', audience: 'creative',
+    tokens: { primary: '#000000', radius: 0, spacing: [8, 16, 24, 40, 64, 96] },
+    summary: 'High-contrast, expressive. Creative typography, bold color.',
+  },
+  bento: {
+    density: 'medium', contrast: 'medium', geometry: 'round',
+    color: 'muted', typography: 'neutral', motion: 'subtle', audience: 'consumer',
+    tokens: { primary: '#0ea5e9', radius: 16, spacing: [8, 16, 24, 32, 48, 64] },
+    summary: 'Modular grid of card-blocks. Clear hierarchy, soft spacing.',
+  },
+  bold: {
+    density: 'low', contrast: 'high', geometry: 'square',
+    color: 'bold', typography: 'display', motion: 'dynamic', audience: 'consumer',
+    tokens: { primary: '#111111', radius: 4, spacing: [8, 16, 24, 48, 80, 128] },
+    summary: 'Strong visual presence. Heavyweight type, high-contrast.',
+  },
+  clean: {
+    density: 'low', contrast: 'medium', geometry: 'round',
+    color: 'muted', typography: 'neutral', motion: 'static', audience: 'consumer',
+    tokens: { primary: '#18181b', radius: 8, spacing: [8, 16, 24, 32, 48, 72] },
+    summary: 'Simplicity-focused. Whitespace, legible type, limited palette.',
+  },
+  dashboard: {
+    density: 'high', contrast: 'high', geometry: 'round',
+    color: 'vibrant', typography: 'neutral', motion: 'subtle', audience: 'developer',
+    tokens: { primary: '#3b82f6', radius: 6, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Dark cloud-platform. Modular grids, glass panels, data hierarchy.',
+  },
+  doodle: {
+    density: 'low', contrast: 'medium', geometry: 'mixed',
+    color: 'vibrant', typography: 'expressive', motion: 'dynamic', audience: 'creative',
+    tokens: { primary: '#f59e0b', radius: 12, spacing: [8, 16, 24, 40, 64, 96] },
+    summary: 'Hand-drawn, sketch-like. Doodles, handwritten fonts.',
+  },
+  dramatic: {
+    density: 'low', contrast: 'high', geometry: 'mixed',
+    color: 'bold', typography: 'display', motion: 'dynamic', audience: 'creative',
+    tokens: { primary: '#dc2626', radius: 0, spacing: [16, 32, 48, 80, 128, 200] },
+    summary: 'Theatrical. Bold layouts, immersive visuals, unconventional.',
+  },
+  enterprise: {
+    density: 'high', contrast: 'high', geometry: 'square',
+    color: 'muted', typography: 'neutral', motion: 'static', audience: 'enterprise',
+    tokens: { primary: '#0f172a', radius: 4, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Clean, high-contrast enterprise. Drag-drop, structured layouts.',
+  },
+  neobrutalism: {
+    density: 'medium', contrast: 'high', geometry: 'square',
+    color: 'bold', typography: 'display', motion: 'subtle', audience: 'creative',
+    tokens: { primary: '#ffd700', radius: 0, spacing: [8, 16, 24, 32, 48, 64] },
+    summary: 'Bold borders, vivid accents, raw high-contrast on warm surfaces.',
+  },
+  paper: {
+    density: 'medium', contrast: 'medium', geometry: 'round',
+    color: 'muted', typography: 'expressive', motion: 'static', audience: 'consumer',
+    tokens: { primary: '#78350f', radius: 4, spacing: [8, 16, 24, 32, 48, 64] },
+    summary: 'Paper-textured, print-inspired. Serif/sans, tactile.',
+  },
+};
+
+// Axis weights — density/contrast/geometry dominate; audience is secondary.
+const WEIGHTS = {
+  density: 0.22, contrast: 0.18, geometry: 0.16, color: 0.14,
+  typography: 0.12, motion: 0.10, audience: 0.08,
+};
+
+function matchScore(a, b) {
+  if (a === b) return 1.0;
+  const pairs = {
+    'low|medium': 0.5, 'medium|high': 0.5,
+    'muted|vibrant': 0.5, 'vibrant|bold': 0.5,
+    'neutral|expressive': 0.5, 'expressive|display': 0.5,
+    'static|subtle': 0.5, 'subtle|dynamic': 0.5,
+    'round|mixed': 0.6, 'square|mixed': 0.6,
+  };
+  const key = [a, b].sort().join('|');
+  return pairs[key] ?? 0;
+}
+
+function scoreFor(fp, typeui) {
+  let total = 0;
+  const reasons = [];
+  for (const axis of AXES) {
+    const fpv = fp[axis];
+    const tuv = typeui[axis];
+    if (!fpv || !tuv) continue;
+    const s = matchScore(fpv, tuv);
+    total += s * WEIGHTS[axis];
+    if (s >= 0.5) reasons.push(`${axis}:${tuv}`);
+  }
+  return { fit: Math.round(total * 100) / 100, reasons };
+}
+
+function rank(fp, topN = 3) {
+  const scored = Object.entries(TYPEUI).map(([name, tu]) => ({
+    name: `typeui-${name}`,
+    ...scoreFor(fp, tu),
+    applies_tokens: tu.tokens,
+    summary: tu.summary,
+  }));
+  scored.sort((a, b) => b.fit - a.fit);
+  return scored.slice(0, topN);
+}
+
+// Derive fingerprint from sd-audit findings.json + design-intelligence.json.
+function fingerprintFromAudit(auditDir) {
+  const fp = {};
+  const diPath = path.join(auditDir, 'design-intelligence.json');
+  const fPath = path.join(auditDir, 'findings.json');
+  if (!fs.existsSync(diPath)) {
+    throw new Error(`design-intelligence.json not found in ${auditDir}`);
+  }
+  const di = JSON.parse(fs.readFileSync(diPath, 'utf8'));
+  const findings = fs.existsSync(fPath) ? JSON.parse(fs.readFileSync(fPath, 'utf8')) : [];
+
+  const scores = di.per_page?.[0]?.categories || di.categories || {};
+  const s = (k) => scores[k]?.score ?? scores[k] ?? 5;
+
+  // Density: C1 density + C11 information scent
+  const densityScore = (s('C1') + s('C11')) / 2;
+  fp.density = densityScore >= 7 ? 'high' : densityScore >= 4 ? 'medium' : 'low';
+
+  // Contrast: C6 contrast (inverse — low craft = low contrast detected)
+  fp.contrast = s('C6') >= 7 ? 'high' : s('C6') >= 4 ? 'medium' : 'low';
+
+  // Geometry: C14 border-radius variance (heuristic)
+  const radiusVar = di.summary?.radius_variance ?? 0;
+  fp.geometry = radiusVar > 8 ? 'mixed' : radiusVar > 2 ? 'round' : 'square';
+
+  // Color: C5 palette saturation
+  const satScore = di.summary?.color_saturation ?? 0.5;
+  fp.color = satScore > 0.7 ? 'bold' : satScore > 0.4 ? 'vibrant' : 'muted';
+
+  // Typography: C7 type scale variance
+  const typeVariance = di.summary?.type_variance ?? 0.5;
+  fp.typography = typeVariance > 0.7 ? 'display' : typeVariance > 0.4 ? 'expressive' : 'neutral';
+
+  // Motion: C13 motion/transitions
+  fp.motion = s('C13') >= 7 ? 'dynamic' : s('C13') >= 4 ? 'subtle' : 'static';
+
+  // Audience: inferred from findings categories — best-effort
+  const mobileCount = findings.filter((f) => f.id?.startsWith('M')).length;
+  const dataCount = findings.filter((f) => /table|dense|data/i.test(f.quote || '')).length;
+  fp.audience = dataCount > mobileCount ? 'enterprise' : 'consumer';
+
+  return fp;
+}
+
+function listSkills() {
+  return Object.entries(TYPEUI).map(([name, tu]) => ({
+    name: `typeui-${name}`,
+    axes: AXES.reduce((o, a) => ({ ...o, [a]: tu[a] }), {}),
+    summary: tu.summary,
+  }));
+}
+
+// CLI
+const args = process.argv.slice(2);
+if (args.includes('--list')) {
+  console.log(JSON.stringify(listSkills(), null, 2));
+  process.exit(0);
+}
+
+let fp;
+let topN = 3;
+const topIdx = args.indexOf('--top');
+if (topIdx >= 0) topN = parseInt(args[topIdx + 1], 10) || 3;
+
+const fromAuditIdx = args.indexOf('--from-audit');
+if (fromAuditIdx >= 0) {
+  const dir = args[fromAuditIdx + 1];
+  if (!dir) {
+    console.error('--from-audit requires a directory path');
+    process.exit(2);
+  }
+  fp = fingerprintFromAudit(dir);
+} else if (args[0] && fs.existsSync(args[0])) {
+  fp = JSON.parse(fs.readFileSync(args[0], 'utf8'));
+} else {
+  console.error('Usage: score-typeui.mjs <fingerprint.json> | --from-audit <dir> | --list');
+  process.exit(2);
+}
+
+const ranked = rank(fp, topN);
+console.log(JSON.stringify({ fingerprint: fp, ranked }, null, 2));