Ship designer-grade UI by default. A design engineering system for AI coding agents — install it as a skill or as the ui-craft CLI, and your agent starts designing like it has taste. Ask for a dashboard, get one you'd put in production. Not gradient cards and bounce animations.

Website: skills.smoothui.dev

/craft dashboard

Three questions (or none — the defaults are strong), a named composition, a production theme preset, and a build that must pass a 10-item acceptance bar before it reports done: "would a designer retouch this?" If a box fails, it isn't done.

For everything else — reviews, animations, forms, polish — the skill routes by intent: just describe what you're building.

New here? Run /start — it reads your project (framework, tokens, brief, existing UI) and tells you what ui-craft can do right now, then points you at the right next step.

UI Craft gives AI coding agents the design knowledge they're missing. Not templates. Not component libraries. Actual craft knowledge — opinionated rules about how interfaces should look, move, and feel — plus the tooling to verify the result. Stack-agnostic by design.

Every UI gets tested against a single question: "Would someone believe AI made this?" If yes, it starts over.

You don't have to learn any of it to benefit. It grows with you.

Start at Layer 1. Most people never leave it — that's the point. Layers 2 and 3 are there the day you want them.

What makes this different: the only AI design system that produces a scoreable, defensible critique — Nielsen's 10 usability heuristics × 6 classic design laws (Fitts, Hick, Doherty, Cleveland-McGill, Miller, Tesler) × 5 persona walkthroughs, with every finding tagged by business impact (blocks-conversion / adds-friction / reduces-trust / minor-polish). Paste the scorecard straight into any issue tracker.

Without UI Craft	With UI Craft

More before/after comparisons on the landing page.

A single static Go binary that detects your AI coding harness and wires skill+commands, MCP gates, review agents, and design-memory into its native config in one interactive pass. No Node required at install time.

macOS / Linux:

brew install --cask educlopez/tap/ui-craft

Windows (Scoop):

scoop bucket add educlopez https://github.com/educlopez/scoop-bucket
scoop install educlopez/ui-craft

Then run:

ui-craft install

ui-craft install detects Claude Code / Cursor / Codex / Gemini / OpenCode, walks you through à-la-carte component selection (interactive TUI or --yes for CI), and writes each chosen component into that harness's native config. All writes are idempotent, backed up before they happen, and rolled back automatically on any failure.

What rides which install?

Full reference docs: skills.smoothui.dev/docs.

One command installs the skill, all 25 slash commands, the 2 review agents, and the MCP quality-gate server — auto-wired, no .mcp.json editing:

/plugin marketplace add educlopez/ui-craft
/plugin install ui-craft

The plugin bundles a .mcp.json (npx -y ui-craft-mcp), so the deterministic gates register automatically on install — first launch fetches the package via npx. This uses Claude Code's own plugin system, so it's not affected by the global-path issue noted below.

npx skills add educlopez/ui-craft

Works with any agent that supports the Agent Skills spec. Each agent gets a pre-built mirror under a dedicated folder (.codex/, .cursor/, .gemini/, .opencode/, .agents/). The main ui-craft skill lands as a peer skill; each slash command is materialized as its own sub-skill in non-Claude harnesses (other agents trigger them by intent: "audit my UI", "polish this page").

ln -s ~/.agents/skills/ui-craft ~/.claude/skills/ui-craft

# Clone
git clone https://github.com/educlopez/ui-craft.git ~/.skills/ui-craft
# Git submodule
git submodule add https://github.com/educlopez/ui-craft.git .skills/ui-craft

The ui-craft binary is a single static Go binary (distributed via Homebrew and Scoop). It is the lifecycle and cross-harness wiring core for the system.

Run ui-craft with no arguments to open the interactive hub — a full-screen menu with an async update check that routes into install, upgrade, backups, and uninstall. Every subcommand below also works directly for scripting/CI.

Every install snapshots existing configs to ~/.ui-craft/backups/ (tar.gz, SHA-256 deduped) before writing. Any mid-plan failure rolls back the whole plan. rollback [harness] restores from the latest snapshot at any time. State is persisted to ~/.ui-craft/state.json so update can replay your choices at the new version without re-prompting.

Before building anything, the skill analyzes your project for existing design decisions — CSS variables, Tailwind config, font imports, component themes. If your project already has a design system, it respects it. If not, it asks 4 quick questions (style, accent color, font, optional animation stack) so it never defaults to generic blue/Inter.

Three numeric knobs (1-10) that the skill asks about during Discovery. They change behavior, not just tone.

At MOTION_INTENSITY 8+ the skill loads references/stack.md only if the user opts into Motion / GSAP / Three.js during Discovery.

Three opt-in sibling skills that pre-commit to a style and lock the knobs to matching values. Agents pick them when the user mentions a specific aesthetic or product reference.

Each variant defers to the main ui-craft skill for base rules and references — it only overrides knob defaults and adds style-specific guidance.

For playful and brutalist aesthetics (Clay / Gumroad / Duolingo / Arc-playful, Nothing-phone / Swiss-print / brutalist), see examples/presets/playful.md and examples/presets/brutalist.md. The main ui-craft skill applies these preset knob values + style overrides on top of the base rules when the user asks for those aesthetics.

25 commands total — 23 single-lens passes, plus /sddesign (the pipeline that chains them) and /start (the front door).

Front door:

Decision spine & finalize:

Review & ship:

Plan & transform:

Taste dial:

The skill detects your intent and routes automatically.

Two read-only Claude Code plugin agents form the ui-craft parallel verify team. They complement the slash commands — they do not replace them.

Both agents are read-only (tools: Read, Grep, Glob) and run in a fresh context, making them suitable for dedicated review passes and PR audits where you want independent judgment uncontaminated by the build session.

Delegate both agents simultaneously on the same diff or file for a full design + a11y sweep in one pass:

Delegate ui-craft:design-reviewer and ui-craft:a11y-auditor together on [target]. Run both simultaneously. Each returns an independent severity-tagged findings table.

When to use agents vs. commands:

• Agents — fresh context, parallel, read-only. Best for final review passes, PR audits, and CI-style verification. Invoke as ui-craft:design-reviewer / ui-craft:a11y-auditor.
• Commands (/critique, /audit) — inline in the caller's context, sequential. Best for interactive build sessions where you want a quick lens mid-work.

UI Craft surfaces the same craft knowledge five ways. They don't compete — each fits a different moment. The two axes that decide: does it write code? and is it judgment or a deterministic check?

The short version: taste that writes code → the skill + commands. Independent review, no edits → the agents. A check that must be identical every run → MCP or the CLI. New to it or unsure? Run /start and it picks for you.

The skill detects your project's styling approach and adapts:

• Tailwind CSS — uses utility classes, maps design rules to Tailwind equivalents
• CSS Modules — writes scoped .module.css files
• styled-components / Emotion — uses tagged templates
• Vanilla CSS — uses custom properties and modern features
• SFC styles (Vue, Svelte, Astro) — writes in <style> blocks

The skill actively rejects patterns that scream "AI made this":

• Purple-cyan gradients
• Glassmorphism with neon accents
• Identical card grids
• Bounce and elastic easing
• Glow effects as affordances
• Colored accent borders on cards
• ALL CAPS headings
• Uniform border-radius everywhere
• Emoji as icons
• Background gradient blobs
• Bento grid abuse
• Stagger-animate everything on load
• Star ratings on testimonials
• Generic CTAs ("Learn more", "Click here")
• Walls of text on landing pages
• Pure black (#000) text

Once the spine is in place, the workflow is:

Discovery → /brief → /tokens → build → /finalize → ship

The brief and tokens land as durable artifacts at .ui-craft/brief.md and the project's preferred token destination — they survive across sessions and anchor every subsequent design decision. Build proceeds with full reference loading via the routing table. /finalize runs the 10-pass finish bar before merge, gated on the brief existing.

ui-craft/
├── agents/                        # 2 Claude Code plugin agents (auto-discovered)
│   ├── design-reviewer.md        # Adversarial design critic — read-only, severity-tagged output
│   └── a11y-auditor.md           # Accessibility auditor — read-only, severity-tagged output
├── skills/
│   ├── ui-craft/                 # Main skill
│   │   ├── SKILL.md              # Slim entry — knobs, discovery, anti-slop, routing
│   │   └── references/           # 32 domain references (accessibility, motion, layout,
│   │                             #   typography, color, modern-css, responsive,
│   │                             #   sound, copy, review, dashboard, inspiration, stack,
│   │                             #   heuristics, personas, state-design, dataviz,
│   │                             #   ai-chat, forms, brief, tokens,
│   │                             #   finish-bar, principles-catalog, spec, agents)
│   ├── ui-craft-minimal/          # Variant — Linear/Notion aesthetic
│   ├── ui-craft-editorial/        # Variant — Medium/Substack aesthetic
│   └── ui-craft-dense-dashboard/  # Variant — Bloomberg/Retool aesthetic
├── commands/                      # 25 Claude Code slash commands (source of truth)
├── examples/
│   ├── animation-storyboard.md   # Multi-stage animation pattern template
│   └── presets/
│       ├── playful.md            # Clay / Gumroad / Duolingo / Arc aesthetic preset
│       └── brutalist.md          # Swiss print / Nothing / terminal aesthetic preset
├── evals/                         # Eval query sets for description optimizer
│   └── presets/                   # Playful + brutalist eval JSONs (reference material)
├── scripts/
│   ├── detect.mjs                # ui-craft-detect CLI (also shipped on npm)
│   └── validate.mjs              # Manifest + link checker
├── .codex/skills/                 # harness mirror for `npx skills add` / submodule installs
├── .cursor/skills/                # harness mirror
├── .gemini/skills/                # harness mirror
├── .opencode/skills/              # harness mirror
├── .agents/skills/                # harness mirror (generic agent-skills spec)
├── cli/assets/<harness>/          # hand-authored per-harness assets the CLI embeds + installs
├── .github/workflows/
│   └── validate.yml              # Runs validator on PR + push
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── VERSIONS.md

Scan a codebase for common AI-generated UI anti-patterns — 38 rules covering AI slop (transition: all, bounce easing, purple gradients, ALL CAPS headings), dark patterns (confirmshaming, destructive actions without confirmation), a11y (icon-only buttons without labels, modal-without-<dialog>, outline: none without :focus-visible replacement, streaming without aria-live, heading-level skips), forms (placeholder-as-label, missing autocomplete), auth tells (caps "OR" dividers, full-bleed saturated brand panels), marketing copy tells (eyebrow floods, scroll cues, numbered section eyebrows, duplicate CTA intent, em-dash floods), perf (images without dimensions → CLS), tables (no overflow handling on mobile), dataviz (categorical rainbow palettes), state design (data fetching without empty/error branches), and placeholder copy shipped to prod (Lorem ipsum, TODO, John Doe). Zero dependencies, works out of the box.

Published as a standalone CLI on npm — use it anywhere without cloning:

npx ui-craft-detect ./src
# or with JSON output:
npx ui-craft-detect ./src --json

Or from a clone of this repo:

node scripts/detect.mjs ./src

Exit code 0 when clean, 1 when findings — usable as a CI gate. Rules mirror the Anti-Slop Test in skills/ui-craft/SKILL.md.

Scope findings to what a branch actually changed, so CI only flags new anti-patterns instead of the entire pre-existing codebase.

# Local pre-commit-style gate: only fail on new critical issues in changed lines
npx ui-craft-detect --scope changed --fail-on error

# Compare against a specific ref instead of the default branch
npx ui-craft-detect --scope changed --base origin/develop

# Advisory mode — see scoped findings without affecting the exit code
npx ui-craft-detect --scope files --fail-on none --json

If git is unavailable, the directory isn't a git repository, or the base ref can't be resolved (e.g. shallow clone), the tool falls back to --scope full automatically and prints a note on stderr — it never crashes or silently drops findings.

Point the detector at a deployed page instead of source files:

npx ui-craft-detect https://your-site.com
npx ui-craft-detect https://your-site.com --json --fail-on none

Two engines, picked automatically:

• puppeteer (optional — npm install puppeteer) loads the page in headless Chromium and scans the JS-rendered DOM, so SPA/client-rendered markup is covered.
• fetch (zero-dep fallback) scans the server-rendered HTML as delivered. No JS execution.

Force one with --engine puppeteer or --engine fetch. Findings report the URL as the file and line numbers within the fetched HTML document. The core detector stays zero-dependency — puppeteer is resolved via dynamic import only when present.

Pre-commit and CI catch problems after the fact. Agent hooks catch them while the agent is still working — the detector runs after every agent file edit and feeds findings straight back into the loop:

npx ui-craft-detect hooks install            # both harnesses
npx ui-craft-detect hooks install --harness claude   # just one
npx ui-craft-detect hooks status
npx ui-craft-detect hooks uninstall

Install is merge-safe and idempotent: existing manifest entries are always preserved, re-running is a no-op, and uninstall removes only the detector's own entries. The hook runner scans just the edited file, stays silent on clean edits and warn-level findings, and fails open on internal errors so a broken hook can never stall an agent.

ui-craft-detect can install its own pre-commit hook with zero config.

# Auto-detect (uses husky if present, else native .githooks)
npx ui-craft-detect init-hook

# Pick explicitly
npx ui-craft-detect init-hook --native         # .githooks/pre-commit (no deps)
npx ui-craft-detect init-hook --husky          # .husky/pre-commit (assumes husky)
npx ui-craft-detect init-hook --github-action  # .github/workflows/ui-craft-detect.yml (deprecated; use `ci install`)
npx ui-craft-detect init-hook --all            # all three
npx ui-craft-detect init-hook --dry-run        # preview without writing

The native hook scans only staged file content (via git show :path), so working-tree noise is ignored. Skip ad-hoc with git commit --no-verify. This repo's own .githooks/pre-commit also auto-bumps marketplace.json CalVer on every commit.

One command sets up a full PR-feedback loop as a GitHub Action — no YAML to hand-write, no octokit dependency (it's all gh api under the hood):

npx ui-craft-detect@latest ci install

This writes .github/workflows/ui-craft-detect.yml, wired to:

• Sticky PR summary comment — one comment per PR, created on first push and edited (not duplicated) on every subsequent push, matched via a hidden marker.
• Inline review comments — findings are posted directly on the diff-visible lines that introduced them, scoped to --scope changed so pre-existing issues elsewhere in the file don't get flagged.
• Commit status — on pushes to the default branch (no PR context), posts a ui-craft-detect status with error/warning counts.
• Minimal permissions — pull-requests: write and statuses: write are each granted only for the steps that need them, with a one-line comment explaining why (same convention as this repo's own CodeQL workflow).

By default the workflow scans --scope changed --fail-on error on pull requests (--scope full on default-branch pushes, since a push has no PR diff to scope against).

Change settings anytime without reinstalling:

npx ui-craft-detect ci config --scope files            # widen scope to whole changed files
npx ui-craft-detect ci config --fail-on warning         # stricter gate
npx ui-craft-detect ci config --comment false           # disable the sticky PR comment
npx ui-craft-detect ci config --inline-comments false   # disable inline review comments
npx ui-craft-detect ci config --status false            # disable the commit status

ci config reads and rewrites a small config marker embedded in the workflow file, so only the settings you pass change — the rest of the file (steps, permissions) is left untouched.

Bump the workflow to the latest template version while keeping your settings:

npx ui-craft-detect ci upgrade

ci upgrade compares the embedded version marker against the installed CLI version; if there's drift, it regenerates the template body and preserves your ci config settings exactly. If you're already current, it's a no-op.

init-hook --github-action still works (it's the same code path ci install wraps) but is deprecated in favor of ci install.

The --scope/--fail-on flags used above aren't CI-only — they work as plain CLI flags for local pre-commit-style gating too (see Diff-scoped scanning above).

UICraftScore is a deterministic 0-100 composite that turns three static-analysis signals into a single defensible grade. It gives you objective, reproducible design-quality evidence — not vibes.

Formula:

score = 100
      − (antiSlop_critical × 8) − (antiSlop_major × 4) − (antiSlop_warn × 1)
      − (token_findings × 2)
      − (a11y_critical × 8) − (a11y_major × 4)

clamped [0, 100]  ·  A ≥ 90  ·  B ≥ 80  ·  C ≥ 70  ·  D ≥ 60  ·  F < 60

Three dimensions, each with its own subscore:

The formula, weights, and grade bands are published in evals/quality/score.mjs (WEIGHTS, GRADE_BANDS). Hand-authored fixtures in evals/quality/fixtures/ and bands in evals/quality/baselines.json form the regression gate.

Run the CLI benchmark:

# Score a single file
node scripts/eval.mjs src/components/Hero.tsx

# Score a directory
node scripts/eval.mjs src/components/

# Run the full regression gate (8 fixtures — slop vs. designer separation)
node scripts/eval.mjs --baseline

# JSON output (CI-friendly)
node scripts/eval.mjs src/components/Hero.tsx --json

# Fail if score below threshold (default 70)
node scripts/eval.mjs src/components/Hero.tsx --threshold 80

Exit codes: 0 clean / in-band · 1 below threshold or out of band · 2 arg error.

Score via MCP tool (score_ui):

The score_ui tool in the MCP server exposes the same scorer to any MCP-compatible client:

// Call score_ui with inline code:
{ "code": "<your tsx source>" }

// Or with a file path:
{ "path": "src/components/Hero.tsx" }

Returns { overall: { score, grade }, dimensions: { anti_slop, token_discipline, a11y }, version } — the same envelope as the CLI --json output.

See evals/README.md for how to run the regression gate, add fixtures, and regen baselines after rule changes.

UICraftScore is deterministic, which also bounds it: static analysis can't see experience friction (a confusing flow, a missing undo, a 2-second save with no feedback). UsabilityScore covers that axis — a 0-100 score + grade rolled up from the /heuristic scorecard (Nielsen's 10 + 6 design laws):

heuristic_base = round( ((mean(nielsen_scores) − 1) / 4) × 100 )   # 10 scores, each 1–5
UsabilityScore = clamp( heuristic_base − 5 × (failed design laws) , 0 , 100 )

Same bands as UICraftScore: A ≥ 90 · B ≥ 80 · C ≥ 70 · D ≥ 60 · F < 60

It is judged, not deterministic — computed by the host agent from the rubric (zero deps, no API key, works in any harness), so it may vary run to run. Gate CI on UICraftScore; use UsabilityScore for review depth. The two render side by side in an extended report and are deliberately never averaged — that would hide which number is reproducible. Run it with /heuristic <path>; rubric + formula live in heuristics.md.

The ui-craft-mcp package exposes four deterministic design-quality tools over the Model Context Protocol (stdio transport). Works with Claude Desktop, Cursor, and any MCP-compatible client.

Boundary: the MCP server is the checks layer — deterministic, rule-based, identical output for identical input. The SKILL.md is the taste layer — judgment, aesthetics, architectural decisions. These never overlap.

Quick start:

# Wire in your project's .mcp.json:
{ "mcpServers": { "ui-craft": { "command": "npx", "args": ["ui-craft-mcp"] } } }

See mcp/README.md for full install, tool docs, and the acceptance-data.json regen note.

The canonical skill content lives in skills/ (main skill + variants) and commands/ (the slash-command lenses). Two consumers ship that content:

• CLI (ui-craft install) — per-harness assets are hand-authored under cli/assets/<harness>/ (claude, cursor, codex, gemini, opencode) and compiled into the binary via go:embed. Command-capable harnesses (Claude Code, OpenCode) receive real commands/*.md; skills-only harnesses (Cursor, Codex, Gemini) receive each lens as a flat depth-1 peer skill. The embedded tree is also the uninstall manifest — cleanup removes exactly what it installed.
• npx skills add / git submodule — the repo-root mirror dirs (.codex/, .cursor/, .gemini/, .opencode/, .agents/) serve those install paths.

When you change a skill or command, update the canonical source under skills/ + commands/ and the matching harness copies.

Every skill's description field is the primary trigger mechanism. The evals/ folder holds query sets for skill-creator's description optimizer (run_loop.py), which evaluates and iterates descriptions against realistic should-trigger / should-not-trigger prompts. See evals/README.md for the commands and how to add new eval sets.

Where ui-craft is heading. Not commitments with dates — a public list of the directions we consider worth building, roughly ordered by how much they'd raise output quality. Feedback and PRs on any of these welcome.

Design-tool integration

• Figma spec compliance — read component specs (spacing, type, color, variants) via Figma's Dev Mode / REST API and score an implementation against them, the same way the detector scores anti-slop today. "Does the built component match the design?" becomes a deterministic gate instead of eyeball review.
• Design-token import — pull a token set from Figma variables / Tokens Studio / a design-tokens.json and emit the project's 3-layer spine (/tokens) from it, instead of hand-transcribing values.

Detector

• Computed-style checks for URL scans — the URL engine currently scans rendered markup; the next layer is computed styles via the browser engine: real contrast ratios (not class-name heuristics), effective tap-target sizes, actual font fallback chains.
• Screenshot-diff regression (exploratory) — likely as a thin integration over existing visual-regression tooling (Playwright snapshots / Chromatic-style diffs) rather than a bespoke engine.
• More harnesses for edit-time hooks — hooks install covers Claude Code and Cursor today; extend to other agents as their hook mechanisms stabilize.

Skill & pipeline

• Reference-board step — optional pre-build step that generates or collects visual references (mood board, type specimens, palette candidates) before the Craft Read, for briefs where the direction is genuinely open.
• Multi-page consistency — today's recipes reason about one surface at a time; a site-level pass would enforce shared rhythm, type scale, and CTA vocabulary across pages.
• UsabilityScore trend tracking — persist /heuristic and UICraftScore results per commit so quality is a curve you watch, not a snapshot.

Evals

• Automated blind-build harness — run the evals/craft-quality/PROMPTS.md tracks through an agent automatically and score the output, turning today's manual auditor pass into a repeatable regression suite.

Have a strong opinion on priority, or something missing? Open an issue.

Spotted a new AI-generated pattern that should be in the anti-slop list? Have a craft rule from a product you admire? Want to add a new reference domain? PRs and issues welcome.

See CONTRIBUTING.md for guidelines on adding rules, improving references, or proposing new domains.

Eduardo Calvo

MIT — use it however you want.