# UI Craft

> Design taste for AI coding agents. UI Craft installs into the coding agent rather than the project, so any prompt that touches UI routes through a design-engineering system before code is written. Free, MIT, and it ships the enforcement half too: 52 deterministic gates and a 0-100 score that can fail a CI build.

The problem it solves: AI coding agents write code fast and have no taste. They converge on the same recognizable output — gradient hero, glowing card, ALL-CAPS eyebrow, bounce easing, emoji icons, `transition: all` — because that pattern is over-represented in training data. A developer can see it looks generated but cannot name the twenty small decisions that would fix it.

How to use it is one ladder with four rungs. You only climb when you want the next thing:

- Rung 0, Ask (no effort): install, then ask for UI the way you always do. You get real hierarchy, your own tokens, and none of the tells that make a screen look generated.
- Rung 1, Direct (one command): `/craft`, `/critique`, `/polish`, `/animate` and 15 more. A focused pass on one surface, aimed by you. Session-local.
- Rung 2, Persist (write once): `/brief`, `/tokens`, `/remember`. Design context every future session reads before it touches a pixel.
- Rung 3, Enforce (wire once): `/finalize`, two review agents, eight MCP tools, `ui-craft-detect` in CI. A gate that fails the build, plus a number.

`/sddesign` is not a fifth rung. It walks rungs 1 to 3 in one guided run, for a single big surface.

Install (one command, detects and wires every harness):

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

Works in Claude Code, Cursor, Codex, Gemini and OpenCode. Windows: `irm https://skills.smoothui.dev/install.ps1 | iex`.

Verifiable facts, counted from the installed engine at build time: 52 deterministic gates (38 anti-slop, 10 accessibility, 4 token-discipline) · 34 design domain references loaded on demand · 25 slash commands · 8 MCP tools · 2 read-only review agents · 5 supported harnesses · MIT licence · source at https://github.com/educlopez/ui-craft.

## Start — install and ask (rung 0)

- [Getting started](https://skills.smoothui.dev/docs/getting-started): One install, then four rungs. Start by asking for UI the way you always do — climb only when you want more control, more memory, or a gate that fails the build.
- [Install options](https://skills.smoothui.dev/docs/install-options): Every other way to install UI Craft — package managers, the Claude Code plugin, the Agent Skills CLI, git clone — plus where files land in each harness.
- [CLI reference](https://skills.smoothui.dev/docs/cli): The ui-craft binary detects your AI coding harness and wires the whole system: skill, commands, MCP gates, review agents and design memory, in one interactive pass.
- [Questions](https://skills.smoothui.dev/docs/faq): Straight answers to what people actually ask before installing: does it fight my design system, will it rewrite my code, is 25 commands a lot to learn, and what the number actually measures.

## Direct — aim one pass (rung 1)

- [Commands](https://skills.smoothui.dev/docs/commands): All 25 slash commands, grouped by rung — so the group tells you what a command costs you before you read what it does.
- [/sddesign pipeline](https://skills.smoothui.dev/docs/sddesign): The full spec-driven design pipeline — brief → tokens → shape → craft → converge → ship in one guided run. Writes .ui-craft/spec.md.
- [Style variants](https://skills.smoothui.dev/docs/variants): Three opt-in sibling skills that pre-commit to a style and lock the knobs. Plus two style presets (playful, brutalist) as examples, not full skills.

## Persist — write it down once (rung 2)

- [Brief](https://skills.smoothui.dev/docs/brief): Durable design brief at `.ui-craft/brief.md` — anchors every design decision in the project across sessions.
- [Tokens](https://skills.smoothui.dev/docs/tokens): 3-layer token spine — primitive → semantic → component. Both light and dark intentionally crafted, not just inverted.
- [Theme Presets](https://skills.smoothui.dev/docs/themes): Four production-ready token stacks: Graphite, Porcelain, Carbon and Signal. Full OKLCH ramps, type, radius, shadows and motion. Light and dark both intentional.
- [Design memory](https://skills.smoothui.dev/docs/design-memory): The typed .ui-craft/ directory — durable, project-local design decisions plus self-correction that the skill reads at Discovery.
- [Principles catalog](https://skills.smoothui.dev/docs/principles-catalog): 42 example design principles across 8 product categories — seed material for the /brief principles workshop.

## Enforce — gate it (rung 3)

- [Finish bar](https://skills.smoothui.dev/docs/finish-bar): 10-pass finishing protocol with measurable criteria. The pre-ship gate that turns "done" into "ships with intent".
- [Verify-team agents](https://skills.smoothui.dev/docs/agents): Two read-only Claude Code plugin agents — design-reviewer + a11y-auditor — that run in a fresh context for independent design + accessibility review.
- [MCP server](https://skills.smoothui.dev/docs/mcp): ui-craft-mcp exposes eight deterministic tools over the Model Context Protocol — task routing, anti-slop, token lint, acceptance bar, the composite score, and the two fold tools.
- [Design-quality score](https://skills.smoothui.dev/docs/score): UICraftScore — a deterministic 0-100 composite grade from anti-slop, token discipline, and a11y. Plus UsabilityScore, the judged companion.
- [ui-craft-detect](https://skills.smoothui.dev/docs/ui-craft-detect): Zero-dependency static scanner for AI-generated UI anti-patterns. Rules mirror the Anti-Slop Test in the skill. Usable as a CI gate.

## How it thinks — engine internals the agent loads on demand

- [Skill anatomy](https://skills.smoothui.dev/docs/skill-anatomy): How UI Craft is structured under the hood — the slim entry point, its 34 on-demand domain references, the 25 commands, and the 3 style variants.
- [Heuristic critique](https://skills.smoothui.dev/docs/heuristics): Score your UI against Nielsen's 10 usability heuristics + 6 design laws, with impact framing for PMs.
- [State-first design](https://skills.smoothui.dev/docs/state-design): Every interactive surface has 7 states. Design the unhappy path first.
- [Persona walkthroughs](https://skills.smoothui.dev/docs/personas): Five archetypes for walking your UI through real users — first-timer, power, low-bandwidth, screen-reader, one-thumb.
- [Motion](https://skills.smoothui.dev/docs/motion): Decision ladder, duration + easing token scales, choreography, motion budget, reduced-motion contract.
- [Component Contracts](https://skills.smoothui.dev/docs/components): Anatomy rules for the workhorse components — buttons (including the destructive friction ladder), text links, icon labels, menus, modals, search, cards, and nav.
- [Forms](https://skills.smoothui.dev/docs/forms): Holistic form system design — validation timing, multi-step wizards, autosave, optimistic submit, and field-specific patterns.
- [UX copy](https://skills.smoothui.dev/docs/copy): Voice, tone, reading level, terminology, inclusive language, locale-aware strings, error anatomy, CTAs, empty states.
- [Data visualization](https://skills.smoothui.dev/docs/dataviz): Cleveland-McGill perceptual hierarchy, chart selection, ColorBrewer palettes, Tufte principles.
- [AI / chat surfaces](https://skills.smoothui.dev/docs/ai-chat): Framework-agnostic interaction patterns for streaming UIs, tool traces, citations, and generative UI.
- [Recipe — SaaS Dashboard](https://skills.smoothui.dev/docs/recipe-dashboard): Build contract for a production SaaS dashboard — three named compositions, exact shell spec, component inventory, strict build order, and a 10-item acceptance bar.
- [Recipe — Landing Page](https://skills.smoothui.dev/docs/recipe-landing): Build contract for a marketing landing page: three named compositions with ASCII layouts, section grammar, pricing block rules, and a 10-item acceptance bar.
- [Recipe — Auth (Sign in / Sign up)](https://skills.smoothui.dev/docs/recipe-auth): Build contract for authentication surfaces — two named compositions, form contract, sign-up deltas, and an 8-item acceptance bar.

## Other

- [Anti-slop, demonstrated](https://skills.smoothui.dev/anti-slop): eight patterns that make interfaces look AI-generated, each shown before and after the skill rewrites it.
- [Pricing](https://skills.smoothui.dev/pricing.md): there is none. Free and MIT, no tiers, no account.
- [Full documentation as one file](https://skills.smoothui.dev/llms-full.txt): every page above concatenated, for reading in a single fetch.
- [Source repository](https://github.com/educlopez/ui-craft)

## Discovery

- [API catalog](https://skills.smoothui.dev/.well-known/api-catalog): RFC 9727 linkset of public HTTP resources
- [OpenAPI](https://skills.smoothui.dev/openapi.json): the same resources as an OpenAPI 3.1 document
- [Agent skills](https://skills.smoothui.dev/.well-known/agent-skills/index.json): ui-craft and the three style variants
- [MCP server card](https://skills.smoothui.dev/.well-known/mcp/server-card.json): local stdio server, `npx -y ui-craft-mcp@0.9.0`
- [Capability manifest](https://skills.smoothui.dev/.well-known/ai-catalog.json): ARD / ai-catalog entries for the above