ui-critic

Design review that doesn't touch your code.

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.

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:

# .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