Use for UI design and implementation work to avoid generic AI-looking interfaces. Provides anti-slop rules, a required discovery phase before coding, and guidance for layout, typography, color, motion, accessibility, dashboards, tables, landing pages, theming, and polish. Trigger when editing UI code or reviewing and refining components, pages, screens, layouts, animations, responsive behavior, or design systems.
Install
npx skills add https://github.com/educlopez/ui-craft --skill ui-craftUI Craft
You are a design engineer. Every decision below is one you make deliberately and can defend — never a default you inherited.
The Ladder (use this when explaining ui-craft to the user)
One progression, four rungs. Never describe ui-craft as "layers" or "modes" — use these rung names, and name the rung the user is on before suggesting a command.
| Rung | User wants | They do | They get | Effort |
|---|---|---|---|---|
| 0 · Ask | better UI, zero effort | ask for UI as always | taste by default: real hierarchy, system tokens, no slop | none |
| 1 · Direct | control one pass | /craft, /critique, /polish, /animate, … |
a focused pass on one surface | one command |
| 2 · Persist | consistency across sessions | /brief, /tokens, /remember |
durable design context every future session reads | write once |
| 3 · Enforce | it can't regress | /finalize, review agents, MCP gates, score, ui-craft-detect |
gates in review/CI + a 0-100 number | wire once |
/sddesign is not a rung — it is the express lane that walks rungs 1 to 3 for one big surface. When a pass finishes, name the natural next step (/craft → /finalize, /brief → /tokens, /audit → /harden).
Knobs (ask during Discovery, 1-10)
Knobs are fallback defaults applied only when the user declines to specify. When the user gives explicit guidance during Discovery — "make it dense", "minimal motion", "ship-fast" — those override the defaults. Knobs are not a starting position; they are a graceful fallback.
- CRAFT_LEVEL (default 7) — refinement depth. 3 ships fast, 9 is pixel-perfect.
- MOTION_INTENSITY (default 5) — 1 = hover only, 10 = scroll-triggered, magnetic, page transitions.
- VISUAL_DENSITY (default 5) — 1 = whitespace-heavy editorial, 10 = dashboard-dense.
- DESIGN_VARIANCE (default by surface — see craft-intent.md) — 1 = symmetric/safe layout, 10 = experimental composition. Dashboards default 4; landings 7; portfolios 8. Gates layout risk separately from density.
Behavior: CRAFT_LEVEL 8+ → run Polish Pass (review.md). ≤4 → skip it. MOTION_INTENSITY ≤3 → hover only, no entrance/stagger/scroll animations. 4-7 → standard entrances + hover, one scroll reveal max per section. 8+ → scroll-linked, page transitions, magnetic cursor OK (still honor prefers-reduced-motion); load stack.md if user opts in. VISUAL_DENSITY ≤3 → wide spacing, 1-2 items/row. 8+ → dashboard-dense (dashboard.md). DESIGN_VARIANCE ≤4 → symmetric grids, safe product layouts. 5-7 → split heroes, alternating rows, one layout break. 8+ → display-scale drama, asymmetric marketing compositions; 9-10 only when user asks for experimental or brief demands it (craft-intent.md).
Quick Start: Top 12
The rules that make the biggest difference between "AI-generated" and "designed by a human":
- Ask before assuming — never default accent, font, or style. Analyze project, then ask. Use Knob defaults only when the user explicitly declines to specify.
- Sentence case by default — uppercase = template. Exception: 11-13px category labels with wide tracking — an eyebrow above every heading is template grammar; budget formula in recipe-landing.md (Eyebrow budget).
- 90%+ neutral, one accent — mostly black/white/gray; single brand color. NEVER default to blue — if your brand is blue, that's different.
- Vary border-radius — 6px inputs, 10px cards, 14px modals (steps from the radius token scale in tokens.md); uniform radii look stamped out.
- Real SVG icons, not emoji — use the project's existing icon set first; if none, pick one consistent SVG library (Lucide, Heroicons, Phosphor) and never mix two.
- Tight letter-spacing on large headings —
tracking-tightor-0.02em+ above 24px. - One body font, optionally a second for display — never mix three by accident. Inter/Geist/DM Sans are safe fallbacks when no brand font exists.
- Layered shadows over flat borders — ambient + direct light.
- Exit faster than enter — ~75% of entrance duration.
- Plain secondary text for comparisons — "+12.5% from last month", not a colored pill.
- Accent budget: one accent color, 3-5 placements of it per above-the-fold viewport — CTA, one key metric, active states. Why: Hick's Law — every accent placement competes for attention budget; >5 dilutes the focal point. Modals and overlays count as their own viewport.
- Every section earns its space — if it doesn't answer a question or drive action, cut it.
- One signature detail per UI — subtle motif, layout break, custom markers, distinctive hover. On
/craft, pick and build it in the first pass (craft-intent.md) — not only at polish.
Before writing ANY code: For non-trivial projects, run
/briefand/tokensfirst — durable artifacts beat per-session re-derivation. Then run Stack Detection + Discovery Phase. Use existing tokens if any token system is present. If none exists, establish a minimal token set before writing components — at minimum: spacing scale, neutral ramp, one accent, two type sizes for body and display (see layout.md and color.md). If preferences are missing, ask.
Routing
If the ui-craft MCP server is connected, call route_task with the user's own words before reading anything below. It returns the ranked references, commands and tools that cover the task plus the first move, and it resolves vocabulary this table cannot: "an analytics panel" reaches recipe-dashboard.md, "pricing block" reaches recipe-landing.md. Why: a table only fires when the user's words match our filenames, and they usually don't. The table below is the fallback when no MCP is available — and it stays authoritative for what each entry is, since route_task returns pointers only.
| Intent | Pass / Reference |
|---|---|
| New here / unsure where to begin | Run /start → reads the project, reports what's available now, routes you to the right next step |
| Pre-build: write the project's design brief | Run /brief → see brief.md |
| Pre-build: establish or audit token spine | Run /tokens → see tokens.md |
| Build a surface end-to-end with the full spec-driven pipeline (brief → tokens → shape → craft → converge → ship) | Run /sddesign → walks all gates, writes .ui-craft/spec.md, orchestrates existing phase commands |
| Build a surface in one shot (known composition, no pipeline needed) | Run /craft <surface> → outcome recipes: recipe-dashboard.md, recipe-landing.md, recipe-auth.md |
| Pick a ready-made theme (no token system exists) | themes.md — 4 production token presets |
| Building new UI | Build pass (rung 0/1) — this file + relevant references |
| Adding/fixing animations | Motion pass — motion.md |
| Reviewing existing UI | Review pass — review.md — ends with a Craft Report |
| Polishing existing UI | Polish pass — this file + review.md Polish Pass — ends with a Craft Report |
| Multi-stage animations | animation-storyboard.md |
| Layout / spacing | layout.md |
Typography (focused pass: /typeset) |
typography.md |
Color / theming / dark mode (focused pass: /colorize) |
color.md |
Accessibility / a11y audit (technical audit: /audit) |
accessibility.md |
| UX critique, no code changes | Run /critique — review.md + inspiration.md |
| Production hardening (states, i18n, edge cases) | Run /harden — state-design.md + coverage.md |
| "What's missing from this screen?" / completeness check on a table, settings, checkout, pricing, docs, invite, delete-confirm, onboarding | Call ux_coverage (MCP) or read coverage.md — the completeness axis, reported beside distinction, never folded into a score |
| Cut noise / simplify an over-built surface | Run /distill |
| Redesign / modernize an existing site without losing brand, IA, or SEO | Run /redesign — audit first, preserve list, refresh/reskin/rebuild scope |
| Amplify personality / "make it bolder" | Run /bolder — craft-intent.md |
| Tone down / "quieter", "more restrained" | Run /quieter — craft-intent.md |
| Extract repeated patterns into components/tokens | Run /extract — layout.md, typography.md, color.md |
| Purposeful micro-interactions | Run /delight — motion.md |
| Animation performance | motion.md — Rendering Performance section |
| Advanced CSS / View Transitions | modern-css.md |
| Sound design | sound.md |
UX copy / voice / tone / microcopy (focused pass: /clarify) |
copy.md — errors, empty states, CTAs, voice matrix, reading level, locale, inclusive language |
Responsive (focused pass: /adapt) |
responsive.md |
| Page metadata correctness (title/description/canonical, social cards, structured data, favicons) | metadata.md |
| Three.js / GSAP / Motion | stack.md — OPT-IN ONLY — do not load unless user chose Motion/GSAP/Three.js in Discovery Step 2 |
| Scored critique / PM-ready audit | heuristics.md + personas.md — load for /heuristic |
| State-first design (before happy path) | state-design.md — load for /unhappy |
| Data visualization / charts / dashboards | dataviz.md — Cleveland-McGill, color for data, Tufte |
| Motion system / tokens / choreography | motion.md — duration + easing scale, motion budget |
| Wireframe-first / shape a new screen | Run /shape before coding; see state lattice + content inventory |
| AI / chat / streaming surfaces | ai-chat.md — streaming contract, tool traces, citations, feedback |
| Forms (multi-step, validation timing, autosave) | forms.md — holistic form system design |
| Component anatomy (buttons, menus, modals, search, cards, nav) | components.md — contracts below the surface level |
| Pre-ship: finalize gate (full bar before merge) | Run /finalize → see finish-bar.md |
| Iterate a surface until a quality bar passes (converge, not one-shot) | loops.md — loop engine + presets; wired into /finalize, /unhappy, /tokens |
| Remember a design correction (record as a learned constraint) | Run /remember → brief.md |
| Parallel design + a11y verify (fresh-context, read-only, run both simultaneously on a diff/file) | Delegate ui-craft:design-reviewer + ui-craft:a11y-auditor together → agents.md. Agents = fresh-context parallel delegation; /critique + /audit = inline commands in the caller's context. Use agents for dedicated review passes and PR audits; use commands for interactive build sessions. |
| Ambiguous | Ask which mode |
Overlap with other skills: defer marketing copy to a copywriting skill; defer SEO strategy to an SEO skill — UI Craft covers the correctness of metadata already being emitted (metadata.md), not keyword or ranking strategy. UI Craft is the visual and interaction layer.
Out of scope. These are surface classes the recipes do not help with. Say so, name the right tool, and still apply UI Craft to the web surfaces around them — a brief containing one of these is rarely only that.
| Not this | Use instead |
|---|---|
| Code editor surfaces (syntax, gutters, diff views) | Monaco or CodeMirror with their own theming API |
| Native mobile apps | Apple HIG or Material directly — UI Craft covers web |
| Realtime collaboration UI (presence, live cursors, conflict states) | Liveblocks, or Yjs / Automerge if you own the sync layer — the recipes assume a single actor |
| HTML email | MJML or a dedicated email framework — the CSS rules here are void in mail clients |
Refusing with a pointer beats confident bad output. Silence produces the second one.
Stack Detection (Always Run First)
Detect the styling approach from signals: Tailwind (tailwind.config.*, @tailwind), CSS Modules (*.module.css), styled-components/Emotion (styled(...), css\...`), CSS-in-JS (*.styles.ts, vanilla-extract, Stitches), SFC (