UI Craft

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

UI Craft

Ask for a surface. Ship it.

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

What it does

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.

Three ways to use it

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.

Same prompt, different result

<table> <tr> <td><strong>Without UI Craft</strong><br/><img src="assets/screenshots/hero-without.png" alt="Hero built without UI Craft" width="100%" /></td> <td><strong>With UI Craft</strong><br/><img src="assets/screenshots/hero-with.png" alt="Hero built with UI Craft" width="100%" /></td> </tr> <tr> <td><img src="assets/screenshots/dashboard-without.png" alt="Dashboard built without UI Craft" width="100%" /></td> <td><img src="assets/screenshots/dashboard-with.png" alt="Dashboard built with UI Craft" width="100%" /></td> </tr> </table>

More before/after comparisons on the landing page.

Install

CLI — recommended (cross-harness, installs the whole system)

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.

Claude Code plugin — alternative (skill + commands + agents + MCP, no CLI needed)

One command installs the skill, all 22 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.

Agent Skills — alternative (skill + commands, any harness)

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").

[!note] Using `npx skills add -g` with Claude Code? The skills CLI installs global skills to ~/.agents/skills, but Claude Code reads ~/.claude/skills (vercel-labs/skills#693). If the skill isn't picked up, use the CLI or plugin install above, install per-project (drop -g), or symlink it: ``bash ln -s ~/.agents/skills/ui-craft ~/.claude/skills/ui-craft ``

Other ways

# 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

CLI

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.

Commands

Key flags for install

Scripting flags (global)

Safety

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.

Discovery phase

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.

Knobs

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.

Style variants

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.

Style presets

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.

Slash commands

Twenty 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:

Four modes

The skill detects your intent and routes automatically.

31 domain references

Agents

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.

Parallel verify team

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.

When to use what

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.

Framework agnostic

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

Anti-slop

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~~

Canonical pipeline

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.

Project structure

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/           # 31 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/                      # 22 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/
│   ├── sync-harnesses.mjs        # Generates .codex/.cursor/.gemini/.opencode/.agents
│   ├── detect.mjs                # ui-craft-detect CLI (also shipped on npm)
│   └── validate.mjs              # Manifest + link checker
├── .codex/skills/                 # AUTO-GENERATED — do not edit
├── .cursor/skills/                # AUTO-GENERATED
├── .gemini/skills/                # AUTO-GENERATED
├── .opencode/skills/              # AUTO-GENERATED
├── .agents/skills/                # AUTO-GENERATED (generic agent-skills spec)
├── .github/workflows/
│   ├── sync-harnesses.yml        # Regenerates mirrors on push to main
│   └── validate.yml              # Runs validator on PR + push
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── VERSIONS.md

Anti-slop detection

Scan a codebase for common AI-generated UI anti-patterns — 33 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), 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.

Pre-commit hooks + CI — init-hook subcommand

ui-craft-detect can install its own pre-commit hook or GitHub Action 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
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.

Design-quality score

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.

UsabilityScore — the judged companion

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.

MCP Server

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.

Maintaining harness mirrors

npm run sync
# or: node scripts/sync-harnesses.mjs

The sync script copies every folder under skills/ (main skill + variants) into each harness dir and converts each file in commands/ into a standalone sub-skill. It wipes and regenerates the harness dirs, so never edit .codex/, .cursor/, etc. directly — change skills/ or commands/, then run sync. GitHub Actions runs it automatically on push to main (.github/workflows/sync-harnesses.yml).

Tuning skill descriptions

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.

Contributing

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.

Author

Eduardo Calvo

License

MIT — use it however you want.