ui-craft

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

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.

The ladder — four rungs

There is one thing to learn, and it's a ladder. Each rung is a real jump in what you get, and each costs a little more than the one below. You only climb when you want the next thing.

Rung	You want	You do	You get	Effort
0 · Ask	Better UI with zero effort	Install, then ask for UI the way you always do	Real hierarchy, your own tokens, no AI slop — same prompt, shippable result	none
1 · Direct	Control over one pass	/craft, /critique, /polish, /animate, …	A focused pass on one surface, aimed by you	one command
2 · Persist	Consistency across sessions	/brief, /tokens, /remember	Durable design context every future session reads	write once
3 · Enforce	Proof it cannot regress	/finalize, review agents, MCP gates, ui-craft-detect	Gates in review and CI, plus a deterministic 0-100 score	wire once

Start at rung 0. Most people never leave it — that's the point. Rungs 1 to 3 are there the day you want them, and /start will tell you which rung your project is on right now.

/sddesign is not a fifth rung. It's the express lane that walks rungs 1 to 3 in one guided run, for a single big surface.

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

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:

curl -fsSL https://skills.smoothui.dev/install | bash

Windows:

irm https://skills.smoothui.dev/install.ps1 | iex

The script detects your OS/arch, downloads the latest release, verifies its checksum, and installs the ui-craft binary — no brew/scoop required.

Then run:

ui-craft install

macOS (Homebrew):

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

Windows (Scoop):

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

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?

Component	CLI	Claude Code plugin	npx skills add
Skill + commands	All harnesses	✅	All harnesses
MCP gates (check_anti_slop, tokens_lint, acceptance_bar, score_ui)	All MCP-capable harnesses	✅ auto-wired	Manual .mcp.json
Review agents (design-reviewer, a11y-auditor)	Claude Code + OpenCode	✅	—
Design memory (.ui-craft/)	✅ (component opt-in)	—	—

Platform support

Six binaries ship on every release. They are not equally exercised, and the difference is worth knowing before you rely on one.

Platform	Binary	Go suite in CI	Installer end-to-end	Gatekeeper / fresh install
macOS Apple Silicon · darwin/arm64	✅	✅	✅	✅ by hand, every release
macOS Intel · darwin/amd64	✅	—	—	—
Linux x86-64 · linux/amd64	✅	✅	✅ Ubuntu · Fedora · Arch	n/a
Linux arm64 · linux/arm64	✅	—	—	n/a
Windows x86-64 · windows/amd64	✅	✅	✅	n/a
Windows arm64 · windows/arm64	✅	—	—	n/a

A dash means the binary is built and published but nothing runs on it. Those rows are honest gaps, not oversights we have quietly closed.

Windows has only been covered since v1.0.16. Before that the suite had never been green there, and five Windows-only bugs shipped as a result — one of them deleting files during rollback that it existed to protect. The suite now gates every pull request that touches the CLI.

macOS on Intel is the largest remaining gap: built and shipped, never tested, and not covered by the manual Gatekeeper check either — that one is Apple-Silicon-only.

Two conditions are untested on every platform: installing with the disk nearly full, and two ui-craft install runs racing against the same machine. See RELEASE_CHECKLIST.md for what each release actually verifies, and what a completed checklist does not promise.

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

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

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@0.9.0), so the deterministic gates register automatically on install. The exact package version is declared in distribution-manifest.json, avoiding an implicit upgrade on first launch. 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 only, any harness)

npx skills add educlopez/ui-craft

[!warning] This installs the skill only — no slash commands beyond the ones mirrored as sub-skills, no review agents, no MCP gates, no hooks. For the full system (MCP quality gates, review agents, design memory), use the installer above.

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:

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 (see Install above for the recommended install script, plus Homebrew/Scoop alternatives). 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.

Commands

Command	Does
ui-craft (no subcommand)	Open the interactive TUI hub: welcome menu + update check → Start installation · Upgrade · Manage backups · Managed uninstall.
ui-craft install	Detect harnesses, à-la-carte component selection, write configs.
ui-craft update [harness]	Re-apply all installed components at the new embedded version.
ui-craft update [harness] --component <name>	Re-apply one component only.
ui-craft uninstall [harness]	Remove managed blocks and wired components.
ui-craft doctor	Health check — verifies each harness install is coherent.
ui-craft backup	Snapshot all harness configs without installing.
ui-craft backup list	List existing snapshots.
ui-craft backup pin <id> / unpin <id>	Protect or unprotect a snapshot from retention cleanup.
ui-craft rollback [harness]	Restore latest backup for a harness.
ui-craft self-update	Upgrade binary to latest GitHub release (or prints the correct package-manager command when installed via Homebrew/Scoop).
ui-craft version	Print the binary version.
ui-craft version --json	Print { "version": "…" }; there is no separate mirror-version field.
ui-craft version --check-parity	Verify the Claude Code install matches the expected surface.

Key flags for install

Flag	Effect
--harness <name>	Target a specific harness (cursor, codex, gemini, opencode) instead of auto-detecting.
--components <list>	Comma-separated components to install (skill-commands, mcp-gates, review-agents, design-memory).
--dry-run	Preview all planned writes without touching any file.
--yes	Non-interactive — skip TUI prompts and apply defaults.

Scripting flags (global)

Flag	Effect
--json	Machine-readable JSON output. Implies non-interactive.
--quiet	Suppress non-essential output; print only errors and a final one-line outcome.

Safety