Documentation
These docs follow the ladder. Four rungs, each one a real jump in what you get — plus the engine internals, kept out of your way until you want them.
Everything here is derived from the source of truth in the ui-craft repo. If you haven't installed anything yet, Getting started is the only page you need.
The whole product, in four rungs
These docs are grouped the same way. Find the rung you want to be on, read that group, ignore the rest.
/sddesign is not a fifth rung. It walks rungs 1 to 3 in one guided run, for a single big surface.
0 · Ask
Better UI with zero effort
- ask like you always do
Real hierarchy, your own tokens, and none of the tells that make a screen look generated.
Discovery runs before any code: the skill reads your CSS variables, Tailwind config, fonts and accent colors, then decides layout, type, color, motion and a11y in one pass.
1 · Direct
Control over one pass
/craft/critique/polish/animate- +15 more
A focused pass on one surface, aimed by you instead of inferred from a sentence.
Still session-local. Close the session and the choices leave with it — that is exactly what rung 2 fixes.
2 · Persist
Consistency across sessions
/brief/tokens/remember
Design context every future session reads before it touches a pixel.
The brief lands in .ui-craft/, the tokens land in your real token file. New session, new agent, new machine — same decisions.
3 · Enforce
Proof it cannot regress
/finalize- review agents
- MCP gates
- detect CLI
A gate that fails the build, plus a 0-100 number you can argue with.
52 deterministic gates — 38 anti-slop, 10 accessibility, 4 token-discipline. Taste becomes something that fits in a pull request.
0 · Start — install and ask
The only two pages a new user needs.
- 01Getting startedOne 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.→
- 02Install optionsEvery 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.→
- 03CLI referenceThe 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.→
- 04QuestionsStraight 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.→
1 · Direct — aim one pass
One command, one lens, one surface. Session-local.
- 01CommandsAll 25 slash commands, grouped by rung — so the group tells you what a command costs you before you read what it does.→
- 02/sddesign pipelineThe full spec-driven design pipeline — brief → tokens → shape → craft → converge → ship in one guided run. Writes .ui-craft/spec.md.→
- 03Style variantsThree 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.→
2 · Persist — write it down once
Design context that every future session reads.
- 01BriefDurable design brief at `.ui-craft/brief.md` — anchors every design decision in the project across sessions.→
- 02Tokens3-layer token spine — primitive → semantic → component. Both light and dark intentionally crafted, not just inverted.→
- 03Theme PresetsFour production-ready token stacks: Graphite, Porcelain, Carbon and Signal. Full OKLCH ramps, type, radius, shadows and motion. Light and dark both intentional.→
- 04Design memoryThe typed .ui-craft/ directory — durable, project-local design decisions plus self-correction that the skill reads at Discovery.→
- 05Principles catalog42 example design principles across 8 product categories — seed material for the /brief principles workshop.→
3 · Enforce — gate it
Review agents, MCP gates, a CI scanner, and a 0-100 score.
- 01Finish bar10-pass finishing protocol with measurable criteria. The pre-ship gate that turns "done" into "ships with intent".→
- 02Verify-team agentsTwo read-only Claude Code plugin agents — design-reviewer + a11y-auditor — that run in a fresh context for independent design + accessibility review.→
- 03MCP serverui-craft-mcp exposes four deterministic design-quality tools over the Model Context Protocol — anti-slop, token lint, acceptance bar, and the composite score.→
- 04Design-quality scoreUICraftScore — a deterministic 0-100 composite grade from anti-slop, token discipline, and a11y. Plus UsabilityScore, the judged companion.→
- 05ui-craft-detectZero-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 references the agent loads for you when the task calls for them. Read these only if you are curious how a decision got made.
- 01Skill anatomyHow UI Craft is structured under the hood — the slim entry point, its 31 on-demand domain references, the 25 commands, and the 3 style variants.→
- 02Heuristic critiqueScore your UI against Nielsen's 10 usability heuristics + 6 design laws, with impact framing for PMs.→
- 03State-first designEvery interactive surface has 7 states. Design the unhappy path first.→
- 04Persona walkthroughsFive archetypes for walking your UI through real users — first-timer, power, low-bandwidth, screen-reader, one-thumb.→
- 05MotionDecision ladder, duration + easing token scales, choreography, motion budget, reduced-motion contract.→
- 06Component ContractsAnatomy rules for the workhorse components — buttons (including the destructive friction ladder), text links, icon labels, menus, modals, search, cards, and nav.→
- 07FormsHolistic form system design — validation timing, multi-step wizards, autosave, optimistic submit, and field-specific patterns.→
- 08UX copyVoice, tone, reading level, terminology, inclusive language, locale-aware strings, error anatomy, CTAs, empty states.→
- 09Data visualizationCleveland-McGill perceptual hierarchy, chart selection, ColorBrewer palettes, Tufte principles.→
- 10AI / chat surfacesFramework-agnostic interaction patterns for streaming UIs, tool traces, citations, and generative UI.→
- 11Recipe — SaaS DashboardBuild contract for a production SaaS dashboard — three named compositions, exact shell spec, component inventory, strict build order, and a 10-item acceptance bar.→
- 12Recipe — Landing PageBuild contract for a marketing landing page: three named compositions with ASCII layouts, section grammar, pricing block rules, and a 10-item acceptance bar.→
- 13Recipe — Auth (Sign in / Sign up)Build contract for authentication surfaces — two named compositions, form contract, sign-up deltas, and an 8-item acceptance bar.→
Spotted something out of date? Open an issue on GitHub →