ui-critic 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# ui-critic
+
+**Design review that doesn't touch your code.**
+
+[![npm version](https://img.shields.io/npm/v/ui-critic)](https://www.npmjs.com/package/ui-critic)
+[![license](https://img.shields.io/npm/l/ui-critic)](./LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](./CONTRIBUTING.md)
+
+Your code has lint, tests, and type-checking. Your UI has nothing. `ui-critic` is the missing layer — a structured design review that scores your interface, detects AI-generated slop, and tells you what to fix before you ship.
+
+---
+
+## Two tools in one
+
+### 1. CLI scanner (no LLM, zero cost)
+
+A standalone regex-based scanner that catches 14 of the 31 slop patterns in milliseconds. No API key, no model, just Node.js.
+
+```bash
+npx ui-critic ./src --json
+```
+
+Finds gradient text, pure black/white, missing focus states, placeholder-as-label, and 10 more patterns. Outputs structured findings. The 17 patterns that need DOM/LLM analysis are listed as `needs-llm`.
+
+### 2. LLM-powered critique (the skill)
+
+Install the Claude Code skill for full design review:
+
+```
+npx skills add https://github.com/alex410000/ui-critic
+```
+
+Then in Claude Code / Codex / Cursor:
+
+| Command | What you get |
+|---|---|
+| `critique [target]` | Full review: Nielsen 10-point score + 31-pattern slop scan + priority-ranked fixes |
+| `score [target]` | Quick Nielsen score. 30-second temperature check. |
+| `slop-check [target]` | AI slop detection only. Does this look AI-generated? |
+| `audit [target]` | Technical quality: accessibility, performance, semantic HTML |
+| `compare [before] [after]` | Before/after diff with scoring delta |
+| `teach` | Initialize PRODUCT.md for your project. Every future review uses it as context. |
+
+---
+
+## How it compares to real alternatives
+
+| | ui-critic | frontend-design-audit | refactoring-ui-plugin | designer-skills |
+|---|---|---|---|---|
+| **Role** | Reviewer only | Reviewer + fixer | Builder + reviewer | Builder + reviewer |
+| **Touches code?** | Never | Yes (suggests fixes) | Yes | Yes |
+| **Nielsen 10-point scoring** | ✅ Full rubric | ✅ 15 heuristics (custom) | ❌ | ❌ |
+| **AI slop detection** | ✅ 31 patterns | ❌ | ❌ | ❌ |
+| **CLI scanner (no LLM)** | ✅ 14 patterns | ❌ | ❌ | ❌ |
+| **PRODUCT.md context** | ✅ | ❌ | ❌ | ❌ |
+| **Skill count / scope** | 1 focused skill | 1 focused skill | 10 skills | 91 skills |
+| **Best for** | "Can this ship?" | "Fix my UI" | "Build it from scratch" | "Full design workflow" |
+
+**These don't compete. They're different tools for different moments:**
+
+```
+refactoring-ui / designer-skills  →  BUILD   →  "Write good-looking code"
+ui-critic                          →  REVIEW  →  "Is what I wrote actually good?"
+```
+
+Install both. Build with one, review with the other.
+
+---
+
+## What the score means
+
+| Score | Rating | Action |
+|---|---|---|
+| 36–40 | Excellent | Ship it |
+| 28–35 | Good | Fix weak areas |
+| 20–27 | Acceptable | Significant improvements needed |
+| 12–19 | Poor | Major UX overhaul |
+| 0–11 | Critical | Unusable |
+
+Most real interfaces score **20–32**. A 38 is extraordinary. Single-run variance is ±3 points — trends matter more than any individual number.
+
+---
+
+## What "AI slop" means
+
+AI-generated UIs have a fingerprint. Same fonts (Inter, Space Grotesk). Same colors (purple gradient on black). Same layout (centered icon → heading → subtitle → CTA). Same cards. Same everything.
+
+We check **31 specific patterns** across 6 categories:
+
+| Category | Examples |
+|---|---|
+| Color & Visual | Gradient text, pure black/white, glassmorphism |
+| Layout | Centered-stack hero, identical cards, nested cards |
+| Typography | Inter default, flat type scale, single font |
+| Borders | Side-stripe borders, default focus rings |
+| Components | Missing states, placeholder-as-label, modal first |
+| Content | Em dashes, lorem ipsum |
+
+Each pattern has a precise detection criterion (`HIT if...`). No subjective "vibe check."
+
+---
+
+## CI integration
+
+Run the scanner in CI to catch design regressions before they ship:
+
+```yaml
+# .github/workflows/design-lint.yml
+name: Design Lint
+on: [pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx ui-critic ./src --json > design-report.json
+      - name: Check for critical issues
+        run: |
+          CRITICAL=$(jq '[.findings[] | select(.severity=="P0")] | length' design-report.json)
+          if [ "$CRITICAL" -gt 0 ]; then
+            echo "::error::Found $CRITICAL critical design issues"
+            exit 1
+          fi
+```
+
+If the scanner flags P0 issues, the PR is blocked. No human review needed for mechanical checks.
+
+---
+
+## Where the standards come from
+
+Every scoring criterion has a traceable source:
+
+| Standard | Source |
+|---|---|
+| Nielsen's 10 Heuristics | Jakob Nielsen (1994), peer-reviewed, taught in every HCI program |
+| 31 AI slop patterns | Community-observed (impeccable, hallmark, X/Twitter design discourse) |
+| Reflex-reject font list | Impeccable v3.1.1 (Apache 2.0), training-data frequency analysis |
+| Brand vs Product register | Impeccable v3.1.1, adapted for Claude Code |
+| Cognitive load checklist | Sweller's Cognitive Load Theory + Nielsen's recognition-over-recall |
+
+**You can disagree with any rule.** The checklist is a starting point. If your brand intentionally uses Inter, mark pattern #13 as "accepted deviation" and move on. The tool serves you.
+
+---
+
+## Why it never touches your code
+
+Deliberate design choice:
+
+- **Objectivity.** A tool that builds AND reviews its own work can't be trusted to review honestly.
+- **Separation of concerns.** Lint flags problems; you fix them. Same model.
+- **Model independence.** The same critique report can be handed to any LLM (or human).
+
+Want the fix implemented? Copy the priority issue into the same conversation and say "fix these." Review and fix are two separate steps by design.
+
+---
+
+## Model compatibility
+
+Works with any LLM. Model choice affects accuracy by ±1–3 points, not fundamental conclusions.
+
+- **Best aesthetic judgment:** Claude Opus or Sonnet
+- **Slop detection + Nielsen scoring:** DeepSeek, GPT-4o — perfectly fine
+- **CLI scanner:** Model-agnostic. Pure regex. Runs anywhere Node.js runs.
+
+---
+
+## Project structure
+
+```
+skills/ui-critic/
+├── SKILL.md                    # Core: role, commands, scoring framework
+├── eval/
+│   └── test-cases.md           # Regression test cases
+├── reference/
+│   ├── heuristics-scoring.md   # Nielsen 10-point rubric
+│   ├── slop-patterns.md        # 31 AI slop detection points (canonical)
+│   ├── register.md             # Brand vs Product scoring
+│   ├── cognitive-load.md        # 8-item cognitive load checklist
+│   ├── design-laws.md          # Color, typography, layout, motion baseline
+│   └── teach.md                # PRODUCT.md initialization flow
+└── scripts/
+    └── scan.mjs                # Deterministic regex scanner (no LLM)
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ui-critic",
+  "version": "0.3.0",
+  "description": "Deterministic design lint for frontend — catch AI slop, hardcoded styles, and accessibility issues before you ship. No LLM required.",
+  "keywords": [
+    "design-lint",
+    "ui-review",
+    "design-qa",
+    "ai-slop",
+    "nielsen-heuristics",
+    "accessibility",
+    "css-lint",
+    "cli",
+    "claude-code",
+    "codex",
+    "cursor"
+  ],
+  "homepage": "https://github.com/alex410000/ui-critic#readme",
+  "bugs": "https://github.com/alex410000/ui-critic/issues",
+  "repository": "alex410000/ui-critic",
+  "license": "MIT",
+  "author": "alex410000",
+  "type": "module",
+  "bin": {
+    "ui-critic": "./skills/design-qa/scripts/scan.mjs"
+  },
+  "files": [
+    "skills/design-qa/scripts/scan.mjs"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/design-qa/scripts/scan.mjs

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+/**
+ * ui-critic scan — Deterministic slop-pattern scanner.
+ *
+ * Reads HTML/CSS/JSX/TSX/Vue/Svelte/Astro files and flags 31 known
+ * AI-slop patterns using regex. Patterns that require DOM or AST
+ * analysis are listed separately as "needs-llm".
+ *
+ * Usage:
+ *   node scan.mjs <file-or-dir> [--json] [--fast]
+ *
+ *   --json   Output machine-readable JSON
+ *   --fast   Skip jsdom-dependent checks (regex only)
+ *
+ * Exit code: 0 = clean, 1 = findings
+ */
+
+import { readFileSync, statSync, readdirSync } from 'node:fs';
+import { join, extname, resolve } from 'node:path';
+
+// ── Collect target files ──────────────────────────────────────
+
+function walk(dir, exts) {
+  const results = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const s = statSync(full);
+    if (s.isDirectory() && !entry.startsWith('.') && entry !== 'node_modules') {
+      results.push(...walk(full, exts));
+    } else if (s.isFile() && exts.has(extname(entry).toLowerCase())) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+// Only UI files — .js/.ts are excluded because they rarely contain
+// visual output directly. Patterns like Zero Imagery and Default Focus
+// Rings are meaningless on backend logic files.
+const SCAN_EXTS = new Set([
+  '.html', '.htm', '.css',
+  '.jsx', '.tsx', '.vue', '.svelte', '.astro',
+]);
+
+function collect(targets) {
+  const files = [];
+  for (const t of targets) {
+    const abs = resolve(t);
+    try {
+      const s = statSync(abs);
+      if (s.isDirectory()) files.push(...walk(abs, SCAN_EXTS));
+      else if (s.isFile()) files.push(abs);
+    } catch { /* skip missing */ }
+  }
+  return files;
+}
+
+// ── Pattern definitions ───────────────────────────────────────
+
+/**
+ * Each pattern:
+ *   id:        canonical number (matches slop-patterns.md)
+ *   name:      short label
+ *   method:    "regex" | "ast"
+ *   test(content): returns { hit: true, evidence: [...] } | { hit: false }
+ */
+
+const PATTERNS = [
+  // ── Category A: Color & Visual (regex-able: 5/5) ──
+
+  {
+    id: 1, name: 'Gradient Text', method: 'regex',
+    test(c) {
+      const hasClip = /background(?:-clip)?\s*:\s*text/.test(c);
+      const hasGrad = /background(?:-image)?\s*:\s*linear-gradient\s*\(/.test(c);
+      if (!hasClip || !hasGrad) return { hit: false };
+      const matches = c.match(/background(?:-clip)?\s*:\s*text/g);
+      return { hit: true, evidence: matches.slice(0, 3) };
+    }
+  },
+
+  {
+    id: 2, name: 'Pure Black or White', method: 'regex',
+    test(c) {
+      const matches = c.match(/#000\b|#fff\b|#000000\b|#ffffff\b/gi);
+      if (!matches) return { hit: false };
+      const filtered = matches.filter(m => {
+        const ctx = c.substring(
+          Math.max(0, c.indexOf(m) - 30),
+          c.indexOf(m) + m.length + 10
+        );
+        return /color|background|fill|stroke|border/.test(ctx);
+      });
+      return filtered.length > 0
+        ? { hit: true, evidence: [...new Set(filtered)].slice(0, 5) }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 3, name: 'Glassmorphism as Default', method: 'regex',
+    test(c) {
+      const matches = c.match(/backdrop-filter\s*:\s*blur\s*\(/g);
+      if (!matches) return { hit: false };
+      return matches.length >= 2
+        ? { hit: true, evidence: [`${matches.length} occurrences of backdrop-filter: blur()`] }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 4, name: 'Heavy Color on Inactive States', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 5, name: 'Timid Palette (Brand Register)', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  // ── Category B: Layout & Composition ──
+
+  {
+    id: 6, name: 'Centered-Stack Hero', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 7, name: 'Identical Card Grids', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 8, name: 'Hero-Metric Template', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 9, name: 'Nested Cards', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 10, name: 'Over-Containerization', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 11, name: 'Monotonous Spacing', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 12, name: 'Zero Imagery', method: 'regex',
+    test(c) {
+      // Only meaningful in markup files — skip pure CSS/JS.
+      // Check for closing tags (</div>) which never appear in CSS.
+      if (!/<\/[a-zA-Z]+/.test(c)) return { hit: false };
+      const hasImg = /<img\s/.test(c) || /<svg\s/.test(c) || /<picture\s/.test(c);
+      return { hit: !hasImg, evidence: !hasImg ? ['No <img>, <svg>, or <picture> tags found'] : [] };
+    }
+  },
+
+  // ── Category C: Typography ──
+
+  {
+    id: 13, name: 'Inter as Unconsidered Default', method: 'regex',
+    test(c) {
+      const hasInter = /font-family\s*:\s*[^;]*\bInter\b/.test(c);
+      if (!hasInter) return { hit: false };
+      // Count distinct font-family values to check for typographic system
+      const families = c.match(/font-family\s*:\s*([^;}]+)/g) || [];
+      const uniqueFamilies = new Set(families.map(f => f.toLowerCase()));
+      return uniqueFamilies.size <= 2
+        ? { hit: true, evidence: [`Inter found with only ${uniqueFamilies.size} font-family declaration(s) — no typographic system visible`] }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 14, name: 'Reflex-Reject Fonts', method: 'regex',
+    test(c) {
+      const banned = [
+        'Fraunces', 'Newsreader', 'Lora', 'Crimson', 'Playfair Display',
+        'Cormorant', 'Syne', 'IBM Plex Mono', 'IBM Plex Sans', 'IBM Plex Serif',
+        'Space Mono', 'Space Grotesk', 'DM Sans', 'DM Serif Display',
+        'DM Serif Text', 'Outfit', 'Plus Jakarta Sans', 'Instrument Sans',
+        'Instrument Serif',
+      ];
+      const hits = [];
+      for (const font of banned) {
+        const re = new RegExp(`font-family\\s*:\\s*[^;]*\\b${font.replace(/ /g, '\\s')}\\b`, 'i');
+        if (re.test(c)) hits.push(font);
+      }
+      return hits.length > 0
+        ? { hit: true, evidence: hits }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 15, name: 'All-Caps Body Copy', method: 'regex',
+    test(c) {
+      // Strip <style> and <script> blocks to avoid false positives
+      // on CSS section headers and JS constant names
+      const text = c.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+                    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '');
+      const capsWords = text.match(/\b[A-Z]{8,}\b/g);
+      return capsWords && capsWords.length >= 3
+        ? { hit: true, evidence: capsWords.slice(0, 5) }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 16, name: 'Display Fonts in Functional UI', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 17, name: 'Flat Type Scale', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 18, name: 'Single-Family Without Choice', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  // ── Category D: Borders & Decorations ──
+
+  {
+    id: 19, name: 'Side-Stripe Borders', method: 'regex',
+    test(c) {
+      const matches = c.match(/border-(?:left|right)\s*:\s*(\d+)px\s+solid/gi);
+      if (!matches) return { hit: false };
+      const thick = matches.filter(m => {
+        const px = parseInt(m.match(/(\d+)px/)?.[1] || '0');
+        return px > 1;
+      });
+      return thick.length > 0
+        ? { hit: true, evidence: thick.slice(0, 3) }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 20, name: 'Large Rounded-Corner Icons Above Headings', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 21, name: 'Default Focus Rings', method: 'regex',
+    test(c) {
+      const hasFocus = /:focus-visible/.test(c);
+      if (!hasFocus) return { hit: true, evidence: ['No :focus-visible rule found — likely using browser defaults'] };
+      // Check if the focus style is just the default outline reset
+      const focusRules = c.match(/:focus-visible\s*\{[^}]*\}/g) || [];
+      const styled = focusRules.filter(r => r.length > 30); // nontrivial rule body
+      return styled.length === 0
+        ? { hit: true, evidence: [':focus-visible present but appears un-customized'] }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 22, name: 'Z-Index Chaos', method: 'regex',
+    test(c) {
+      const zs = c.match(/z-index\s*:\s*(\d+)/g) || [];
+      const values = zs.map(z => parseInt(z.match(/(\d+)/)[1]));
+      const high = values.filter(v => v >= 100);
+      return values.length >= 10 && high.length >= 3
+        ? { hit: true, evidence: [`${values.length} z-index declarations, ${high.length} values ≥ 100 — high stacking-context complexity`] }
+        : { hit: false };
+    }
+  },
+
+  // ── Category E: Components & Interaction ──
+
+  {
+    id: 23, name: 'Modal as First Thought', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 24, name: 'Inconsistent Component Vocabulary', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 25, name: 'Missing Interactive States', method: 'regex',
+    test(c) {
+      const hasBtn = /<button\s|<a\s.*class="[^"]*btn/.test(c);
+      if (!hasBtn) return { hit: false };
+      // Check all 4 core interactive states — need ≥2 missing to trigger
+      const hasHover = /:hover/.test(c);
+      const hasFocus = /:focus/.test(c);
+      const hasActive = /:active/.test(c);
+      const hasDisabled = /:disabled/.test(c);
+      const missing = [];
+      if (!hasHover) missing.push(':hover');
+      if (!hasFocus) missing.push(':focus/:focus-visible');
+      if (!hasActive) missing.push(':active');
+      if (!hasDisabled) missing.push(':disabled');
+      return missing.length >= 2
+        ? { hit: true, evidence: [`${missing.length}/4 interactive states missing: ${missing.join(', ')}`] }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 26, name: 'Non-Standard Affordances', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 27, name: 'Placeholder as Label', method: 'regex',
+    test(c) {
+      const places = c.match(/placeholder\s*=\s*["'][^"']+["']/g) || [];
+      const labels = (c.match(/<label\s/gi) || []).length;
+      return places.length > labels.length
+        ? { hit: true, evidence: [`${places.length} placeholders but only ${labels} <label> elements`] }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 28, name: 'Icon-Only Interactive Elements', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  {
+    id: 29, name: 'Decorative Motion That Blocks Tasks', method: 'ast',
+    test() { return { hit: false }; }
+  },
+
+  // ── Category F: Content & Copy ──
+
+  {
+    id: 30, name: 'Em Dashes in UI Copy', method: 'regex',
+    test(c) {
+      // Strip <style> and <script> blocks: CSS custom properties (--foo)
+      // and JS operators (--, --i) are not UI copy. Also strip HTML comments.
+      let text = c.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+                  .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+                  .replace(/<!--[\s\S]*?-->/g, '');
+      // For standalone .css files (no <style> wrapper), strip CSS comments
+      // and CSS custom property names which use -- prefix by spec.
+      text = text.replace(/\/\*[\s\S]*?\*\//g, '');
+      text = text.replace(/--[a-zA-Z][\w-]*/g, '');
+      // Count actual em dash (U+2014) and double-hyphens used in prose
+      const emDashCount = (text.match(/—/g) || []).length;
+      const doubleHyphenCount = (text.match(/--/g) || []).length;
+      const total = emDashCount + doubleHyphenCount;
+      return total >= 3
+        ? { hit: true, evidence: [`${total} em dashes or double-hyphens in content (CSS/JS excluded)`] }
+        : { hit: false };
+    }
+  },
+
+  {
+    id: 31, name: 'Lorem Ipsum / Placeholder Copy', method: 'regex',
+    test(c) {
+      const matches = c.match(/lorem ipsum|TODO|\[placeholder\]|content goes here/gi);
+      return matches
+        ? { hit: true, evidence: [...new Set(matches)] }
+        : { hit: false };
+    }
+  },
+];
+
+// ── Scanner ────────────────────────────────────────────────────
+
+function scanFile(filePath) {
+  const content = readFileSync(filePath, 'utf-8');
+  const findings = [];
+  const llmOnly = [];
+
+  for (const p of PATTERNS) {
+    if (p.method === 'ast') {
+      llmOnly.push({ id: p.id, name: p.name });
+      continue;
+    }
+    try {
+      const result = p.test(content);
+      if (result.hit) {
+        findings.push({ id: p.id, name: p.name, method: 'regex', evidence: result.evidence });
+      }
+    } catch {
+      // skip broken patterns silently
+    }
+  }
+
+  return { file: filePath, findings, llmOnly };
+}
+
+function scanAll(files) {
+  const results = [];
+  let totalFindings = 0;
+  const llmOnlySet = new Map(); // dedupe by id
+
+  for (const f of files) {
+    const r = scanFile(f);
+    results.push(r);
+    totalFindings += r.findings.length;
+    // Aggregate LLM-only patterns across all files (deduplicated)
+    for (const p of r.llmOnly) {
+      if (!llmOnlySet.has(p.id)) llmOnlySet.set(p.id, p);
+    }
+  }
+
+  return {
+    results,
+    totalFindings,
+    filesScanned: files.length,
+    llmOnly: [...llmOnlySet.values()].sort((a, b) => a.id - b.id),
+  };
+}
+
+// ── Formatters ─────────────────────────────────────────────────
+
+function formatText(report) {
+  const lines = [];
+  lines.push('');
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push('  ui-critic scan');
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push(`  Files scanned: ${report.filesScanned}`);
+  lines.push(`  Regex hits:    ${report.totalFindings}`);
+  lines.push(`  AST-only patterns (needs LLM): ${report.llmOnly?.length || 0}`);
+  lines.push('');
+
+  for (const r of report.results) {
+    if (r.findings.length === 0) continue;
+    lines.push(`  ${r.file}`);
+    for (const f of r.findings) {
+      const evidence = f.evidence?.join(', ') || '';
+      lines.push(`    #${f.id} ${f.name}`);
+      if (evidence) lines.push(`       → ${evidence}`);
+    }
+    lines.push('');
+  }
+
+  if (report.totalFindings === 0) {
+    lines.push('  ✓ No regex-detectable slop patterns found.');
+    lines.push('  ℹ This covers ~16 of 31 patterns. Run a full LLM critique');
+    lines.push('    for the remaining 15 AST-only patterns.');
+  } else {
+    lines.push(`  ⚠ ${report.totalFindings} finding(s). Run a full LLM critique with`);
+    lines.push('    /ui-critic critique for Nielsen scoring + AST patterns.');
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ── Main ───────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const jsonOut = args.includes('--json');
+const targets = args.filter(a => !a.startsWith('--'));
+
+if (targets.length === 0) {
+  console.error('Usage: node scan.mjs <file-or-dir> [--json]');
+  console.error('  Scans HTML/CSS/JSX/TSX/Vue/Svelte/Astro files for AI slop patterns.');
+  process.exit(1);
+}
+
+const files = collect(targets);
+if (files.length === 0) {
+  console.error('No scannable files found.');
+  process.exit(1);
+}
+
+const report = scanAll(files);
+
+if (jsonOut) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  console.log(formatText(report));
+}
+
+process.exit(report.totalFindings > 0 ? 2 : 0);