
ui-craft
Design engineering skill + system for AI coding agents: anti-slop UI rules, outcome recipes, spec-driven design (/sddesign), design-review + a11y agents, and MCP quality gates.
- GitHub stars
- 465
Install
/plugin install ui-craft@ui-craftRun it inside Claude Code after adding the marketplace with /plugin marketplace add educlopez/ui-craft.
Contents
Discovered from sourceSkills 4
UI Craft — Dense Dashboard
Pre-committed dense style: data-first, keyboard-first, operator tools. Bloomberg, Retool, Linear issues view, admin panels. Every pixel earns its place.
Knobs (locked)
- CRAFT_LEVEL = 7 — polished but not precious; operators value speed over sheen.
- MOTION_INTENSITY = 3 — micro-only. Row hover, row active tint, inline confirm. No scroll reveals in table areas.
- VISUAL_DENSITY = 9 — tight 4/8px grid; whitespace earns its place.
Do not re-ask these in Discovery. Confirm brand accent + dark/light preference only.
Style anchors
- UI sans + mono pairing. Mono for every ID, hash, timestamp, code.
- Semantic palette required: success, warning, danger, info + one brand accent.
tabular-numson every numeric column; mono on identifiers.- Tight 4/8px spacing grid.
px-3 py-2table cells,gap-2toolbars. - Sparklines everywhere; horizontal bars for categorical; area for time-series. No pie. No 3D.
- Keyboard shortcuts visible inline (
⌘K,J/K,Eto edit). - Dense chrome: breadcrumbs + tabs + toolbars + filter chips are welcome.
- Micro-motion only. Row hover, row active, inline save. No entrance stagger.
Base rules (inherited)
All rules in ../ui-craft/SKILL.md apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
Style-specific overrides
Typography
- UI: IBM Plex Sans or Inter, 400 / 500.
- Mono: IBM Plex Mono or Geist Mono for IDs, hashes, timestamps, code, version numbers, kbd.
- Body size: 13-14px default; 12px in dense tables is fine.
tabular-numson every numeric column, metric card, timestamp, duration.font-variant-numeric: tabular-nums slashed-zerofor IDs + codes.- Headings: compact. Page title 18-20px, section 14-15px 500.
Color (semantic palette required)
- Brand accent: one — primary actions, active tab, selected row accent tint.
- Semantic, subdued OKLCH (lightness 50-60, chroma ≤ 0.15):
- success
oklch(60% 0.12 150) - warning
oklch(72% 0.13 75) - danger
oklch(58% 0.15 25) - info
oklch(62% 0.12 240)
- success
- Never saturated hues — dashboards live on screens for 8 hours.
- Status dots, badge text, chip text use semantic color; backgrounds stay neutral.
Spacing & layout
- 4/8px spacing scale — never 5, 7, 9, 10. Stick to 4 / 8 / 12 / 16 / 24.
- Table cells:
px-3 py-2default;px-2 py-1.5for ultra-dense. - Toolbar rows:
gap-2,h-9controls,text-sm. - Sidebar: narrow (200-240px), subtle bg tint, icon + label; never full dark.
- Cards:
p-4, 8px radius; 1px border over shadow.
Data display
- Every number column:
tabular-nums+ right-aligned. - Every ID / hash / commit / timestamp: monospace.
- Sparklines inline in rows for trend context. 24-40px tall, single color.
- Category charts: horizontal bars. Time-series: area with 15% → 0% fade. No pies.
- Deltas: plain text
+12.5%in semantic color, no pill. - Empty states: one-line hint + keyboard shortcut to create.
Chrome & navigation
- Breadcrumbs + tabs + sub-toolbar together is expected and fine.
- Filter chips: outline style, removable
×, no pill fill. - Global command palette:
⌘Kvisible in header search affordance. - Row actions: inline icons on hover; also available via keyboard.
- Pagination: text
Page 3 of 42+tabular-nums, plusJ/Knavigation.
Motion
- Row hover: background shift to
oklch(96% 0.002 250)light /oklch(20% 0.005 250)dark, 80ms. - Active/selected row: brand accent tint at ~6% opacity + 2px accent left border.
- Inline save / confirm: 150ms fade + check icon swap.
- No scroll-triggered reveals in table areas — they stutter long lists.
- Sort arrow, filter open, column resize: instant or <100ms.
Reference files to read first
Load these from ../ui-craft/references/:
dashboard.md— primary reference; metric cards, charts, sidebar, tablestypography.md— tabular-nums, mono pairing, scalemotion.mdRendering Performance — compositor pipeline, layer promotion, scroll-linked motionresponsive.md— tablet + laptop breakpoints, toolbar collapse
Skip inspiration.md (landing-page focused), sound.md.
Anti-patterns for THIS style
- Serif fonts anywhere in chrome or data. Editorial is a different variant.
- Proportional figures in numeric columns — always
tabular-nums. - Saturated hues — reads as consumer app, not operator tool.
- Colored pills on every delta — plain text in semantic color.
- Pie charts, donut charts, 3D charts. Ever.
- Vertical bar chart for time-series — use area/line.
- Uniform colored top borders on metric cards.
- Card grids with heavy whitespace — if it feels airy, wrong variant.
- Full-dark sidebar (common AI pattern) — subtle tint only.
- Scroll-triggered reveals or stagger animations in table areas.
- Hidden keyboard shortcuts — always surface
⌘K, row shortcuts, help trigger. - Vague loading states — show skeleton rows matching column structure, not generic spinner.
UI Craft — Editorial
Pre-committed editorial style: magazine, long-form, content-first. Typography carries the hierarchy; layout serves the reading experience.
Knobs (locked)
- CRAFT_LEVEL = 9 — editorial typography only works at high refinement; Polish Pass mandatory.
- MOTION_INTENSITY = 4 — reading-aware: fade on reveal, link hovers, no entrance stagger.
- VISUAL_DENSITY = 3 — wide reading column, generous vertical rhythm, 1 item per row for features.
Do not re-ask these in Discovery. Confirm accent + serif/sans pairing only.
Style anchors
- Serif display for headings + humanist body sans/serif for reading.
- Baseline grid feel.
leading-relaxed(1.7) on body. - Wide reading column
max-w-[65ch]. Generous vertical rhythm. - Accent used for emphasis — pull quotes, drop caps, link underlines — not decoration.
- OpenType features ON: small caps, ligatures, stylistic sets, tabular figures where relevant.
- Asymmetric, text-heavy heroes. Featured image large.
- Motion respects reading: fades only, never pulls the eye away.
- Black text, warm/ivory canvas, one accent. Color is a voice, not a decoration.
Base rules (inherited)
All rules in ../ui-craft/SKILL.md apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
Style-specific overrides
Typography (the whole point)
- Display: Playfair Display, Fraunces, Lora, or Source Serif 4 for headings and pull quotes.
- Body: Alegreya, Source Sans 3, ITC Charter, or a humanist pairing. Do NOT use Inter as primary body — it reads as product UI, not editorial.
- Max two families: one display + one body.
- Headings:
text-wrap: balance,font-optical-sizing: auto, tracking near 0 or slightly negative on large sizes. - Body:
text-wrap: pretty,line-height: 1.7,font-feature-settings: "liga", "kern". - Drop caps via
p:first-of-type::first-letter { float: left; font-size: 4.5em; line-height: 0.85; padding: 6px 10px 0 0; font-family: <display>; }. - Small caps via
font-variant-caps: small-capsfor section labels, bylines. - Opt-in OpenType:
font-feature-settings: "ss01", "cv11"when the chosen font supports them. - Pull quotes: serif, large (1.75-2.25em), one accent color, short rule above.
Color
- Canvas: ivory or warm white —
oklch(98% 0.01 85)— not pure#fff. - Text:
oklch(18% 0.01 40)warm near-black. - Restricted palette: black, ivory/warm white, ONE accent. That's it.
- Accent applied to: drop cap, pull quote, inline link underline, section rule. Not buttons that don't need it.
Spacing & layout
- Reading column:
max-w-[65ch]for body; hero and featured image can break out tomax-w-5xl. - Vertical rhythm on body: paragraph spacing = line-height × 0.6 minimum.
- Asymmetric heroes: left-aligned display headline + byline + featured image below or offset.
- Section breaks: centered ornament or a short rule, not a full-width divider.
Motion
- Fade on scroll reveal for hero/featured image only, 300-400ms ease-out.
- Inline link hover: underline-offset grows 1px, color shifts to accent, 120ms.
- No entrance stagger, no parallax, no page transitions that fight the reading flow.
- Honor
prefers-reduced-motion— cut all reveals.
Content components
- Byline: small caps, tracking-wide, secondary text color.
- Dateline + read time: tabular-nums, separated by a bullet
·. - Inline images: full-width or breakout beyond column, with italic serif caption underneath.
- Blockquote: left border in accent, serif italic,
max-w-[55ch].
Reference files to read first
Load these from ../ui-craft/references/:
typography.md— the primary reference for this stylelayout.md— reading column, rhythm, hierarchycolor.md— warm palette, accent disciplinecopy.md— editorial voice, headings, empty states
Skip dashboard.md, sound.md unless relevant.
Anti-patterns for THIS style
- Inter, Geist, DM Sans as primary body. They signal product UI, not editorial.
- Three font families. Always one display + one body.
- Pure
#fffcanvas. Warm it. - Tight
leading-tighton body copy. Reading needs 1.6-1.8. - Colored pull quote backgrounds, gradient text on headlines, emoji in section rules.
- Scroll-triggered stagger or parallax — breaks reading flow.
- Card grids for articles — use stacked list with thumbnail + dek.
- Sans-serif display headlines by default. If you need sans display, the user probably wants minimal variant.
- Uppercase headlines. Sentence case, always (small caps for bylines is the exception).
- CTAs with heavy pill backgrounds — prefer inline underlined links in the serif voice.
UI Craft — Minimal
Pre-committed minimal style: editorial clean, Linear / Notion / Vercel. Whitespace is the composition. One accent, hairline borders, almost no motion.
Knobs (locked)
- CRAFT_LEVEL = 8 — minimal aesthetics only work when executed precisely; Polish Pass is mandatory.
- MOTION_INTENSITY = 3 — hover + modal enter/exit only. No scroll reveals, no page transitions, no stagger.
- VISUAL_DENSITY = 2 — whitespace-heavy, 1-2 items per row, generous gutters.
Do not re-ask these in Discovery. Skip straight to accent + font confirmation if ambiguous.
Style anchors
- Black or near-black type on white or near-white canvas. Monochrome + ONE accent.
- Inter / Geist for body — never a display font.
- Section padding 120-200px vertical, 40-80px gutters.
- Hairline borders
1px solid oklch(92% 0.005 250)in place of shadows. - Typography is the hierarchy. No decorative gradients, patterns, or glass.
- Single-column hero default. Asymmetry via one supporting element, not layout tricks.
- Motion is punctuation, not spectacle.
- Every pixel deliberate. When in doubt, cut it.
Base rules (inherited)
All rules in ../ui-craft/SKILL.md apply. This file overrides knob defaults and adds style-specific guidance below. The anti-slop and craft tests still apply in full.
Style-specific overrides
Typography
- Body: Inter or Geist, 400 weight. UI emphasis: 500. Never 600/700 in body copy.
system-ui, -apple-systemas fallback stack.- Headings:
tracking-tight/-0.02emabove 24px, 500 or 600 max. text-wrap: balanceon headings,text-wrap: prettyon paragraphs.- No display serifs. No geometric display sans. No mixing two sans families.
Color
- Surface:
oklch(99% 0 0)(light) /oklch(14% 0.005 250)(dark). - Text:
oklch(18% 0.01 250)primary,oklch(46% 0.01 250)secondary. - Accent reserved for: primary CTA, active nav item, one key metric. That is it.
- Borders:
oklch(92% 0.005 250)light /oklch(24% 0.008 250)dark. No colored borders.
Spacing & layout
- Section vertical:
py-24 md:py-32 lg:py-40(96 / 128 / 160px) minimum; 200px for hero on large screens. - Container:
max-w-5xltypical;max-w-3xlfor reading content. - One accent placement per viewport preferred; two max.
- No card grids with more than 2 columns on desktop.
Borders & elevation
- Default chrome = 1px hairline border, no shadow.
- Elevation only for floating UI (menus, toasts, modals) — single soft ambient shadow, not layered.
- Radius: 6px inputs, 8px cards, 12px modals. Keep the scale narrow.
Motion
- Allowed: hover (opacity / border color, 120-150ms), modal + dialog enter/exit (180-220ms ease-out), focus ring.
- Forbidden at this intensity: scroll-triggered reveals, stagger, page transitions, parallax, magnetic cursor, entrance choreography.
- Any animation must honor
prefers-reduced-motion.
Composition
- Hero: left-aligned or centered headline, ONE supporting element (social proof line, screenshot, single chip). No floating badges, orbs, blobs.
- Features: stacked rows with a single real visual each. No 3-up uniform icon grids even when tempting.
- Nav: text-only links, current state = accent underline or weight 500. No pill backgrounds.
Reference files to read first
Keep the reading list tight. Load only these from ../ui-craft/references/:
layout.md— spacing, hierarchy, compositiontypography.md— scale, readability, weightcolor.md— monochrome scales, OKLCH, dark modeaccessibility.md— focus, contrast, keyboard
Skip dashboard.md, stack.md, sound.md unless explicitly relevant.
Anti-patterns for THIS style
- Multiple accent colors. One accent, period.
- Display serifs, geometric display sans, or mixing two sans families.
- Decorative gradients, mesh backgrounds, noise overlays, glass panels.
- Scroll-triggered reveals, stagger, page transitions — even "subtle" ones.
- Uniform 3-column icon-heading-text feature grids.
- Colored shadows or glows as affordances.
- Dense layouts. If density feels right, this is the wrong variant — switch to
ui-craft-dense-dashboard. - Pill backgrounds on nav links or buttons by default; prefer text + underline.
- Section padding under 96px on desktop.
UI 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 (` in Vue/Svelte/Astro), or Vanilla CSS.
Rules: never fight the project's stack; never mix approaches. The design rules hold across stacks — only the syntax changes. (Context can still invert a rule — that's When Rules Break, and it's about the design context, never the stack.) Reference files are CSS-first with Tailwind translations. When in doubt, match existing patterns.
Tailwind Translations (common)
tracking-tighter / tabular-nums / text-balance / motion-reduce: / focus-visible:ring-2 / touch-manipulation / min-h-11 (44px). Use ease-[cubic-bezier(...)] for custom easing.
Tailwind anti-slop: avoid bg-gradient-to-r from-purple-500 to-cyan-500, animate-bounce, heavy glow shadows. Tailwind makes it easier to ship slop faster.
Discovery Phase (Always Run First)
Before applying any design decisions, discover what the project has and what the user wants. Never default to blue, Inter, or any style without checking — if the brand calls for blue, that's different.
Step 1: Project Analysis
Design Memory (.ui-craft/ directory). This is the project's typed design context. It replaces the single brief.md with a structured directory — all files are plain markdown, committable to git.
Always-load on every UI task (small, define project taste/tokens):
.ui-craft/brief.md— product identity, design intent, audience, voice, constraints. See references/brief.md for the format guide..ui-craft/tokens.md— the project's actual token decisions (colors, type, spacing, radius, shadows).
Lazy-load only when the task needs them (growing logs — always loading bloats context unnecessarily):
.ui-craft/decisions.md— append-only date-stamped design decision log. Load when the user asks to reference prior rationale or past decisions..ui-craft/patterns.md— validated component/layout compositions. Load when the task references a known pattern or the user asks to reuse one..ui-craft/surfaces/<name>.md— per-surface notes (layout, components, edge cases). Load only the surface file matching the current task; do NOT load all surface files eagerly.
If .ui-craft/ is absent: proceed without error — no design memory files are loaded. Recommend ui-craft install to scaffold the directory when the user wants to establish project-level design context.
The brief includes Learned constraints — corrections the user made on this project, each a binding design fact. Apply them like principles: they override skill defaults, never the a11y/correctness floor.
Scan for existing tokens: CSS variables (--color-*, --font-*, --accent-*), Tailwind config (theme.extend.*), globals.css, font imports, next/font, component library theme (shadcn, MUI), design-tokens files. Build an inventory (accent, fonts, radius, shadows). If the project has an intentional system, respect it. Don't override.
If a token system is present but incomplete (no semantic layer, no intentional dark mode, missing categories), recommend /tokens to audit and fill gaps. Cross-ref tokens.md for the 3-layer contract.
Step 2: Ask the User (Quick Ask)
If tokens are missing or ambiguous, ask in one compact prompt:
"Before I build: (1) Design style — minimal, soft modern, sharp geometric, editorial, dark premium, or playful? (2) Accent color preference? (3) Font — clean sans-serif, geometric, humanist, monospace, or system? (4) Animation stack — Motion / GSAP / Three.js / none? (I'll load
references/stack.mdonly if you opt in.)"
Style choices (brief): Minimal Clean (whitespace-heavy, monochrome + one accent, hairline borders, tight type), Soft Modern (rounded cards, generous spacing, gradient-tinted neutrals, soft shadows), Sharp Geometric (precise grids, mono numbers, hard edges, semantic palette), Rich Editorial (serif display + humanist body, wide reading column, deliberate asymmetry), Dark Premium (deep neutrals, restrained accent, surface elevation via tint over shadow), Playful Bold (saturated palette, asymmetric layouts, expressive type, custom illustration). Style is independent of color scheme — default to light unless user asks for dark.
Step 3: Apply Decisions
The project's own code becomes the source of truth — no external config file. Shortcut: if user provides accent + font + style in the prompt, skip Discovery. See style-to-CSS mapping in layout.md.
Craft Read (full surfaces)
When building a complete surface (dashboard, landing, auth, settings shell, portfolio page) — including /craft — output the Craft Read before writing code, in exactly this form:
Craft Read: [surface kind] for [audience], [product | marketing] language, [theme/accent hint], variance [N], signature bet: [choice].
The template is here rather than only in craft-intent.md on purpose. Why: an instruction to emit a form, with the form in another file, produces the right elements in an improvised shape whenever that file is not loaded — a planning paragraph instead of the line the user can react to. A pointer to a form is not the form.
Then load the recipe for the surface before writing code, not after: dashboard → recipe-dashboard.md, landing → recipe-landing.md, auth → recipe-auth.md. Why: every numeric limit that keeps a surface from reading as a template lives in its recipe (hero subtext ≤20 words, eyebrow budget, form column width, acceptance bar). Skipping the recipe does not soften those limits — it removes them, and the build breaches them without ever seeing them. If the MCP server is connected, route_task names the recipe for you.
Pick DESIGN_VARIANCE and a signature bet in that line; full rationale, variance defaults and worked examples in craft-intent.md. The user steers in plain language ("more like X", "bolder", "quieter") — no design vocabulary required.
Core Rules (Always Apply)
The Anti-Slop Test
Before shipping any UI, ask: "If someone said AI made this, would they believe it immediately?" If yes, start over.
Critical (immediately reads as AI):
- Identical card grids (icon + heading + text, 3-6x repeated)
- ALL CAPS on headings, labels, tables, nav, buttons (exception: 11-13px category labels)
- Purple/cyan gradient everything
- Emoji as feature icons
- Bounce/elastic easing curves
- Glassmorphism on dark + neon accents
Major (designers notice):
- Colored pills on trend percentages — use plain secondary text
- Thick colored left/top borders on cards — use elevation or bg tint
- Uniform border-radius on everything — vary by element
- Gradient text on hero metrics
- Vertical bar charts for time-series — use area/line (horizontal bars OK for categorical)
transition: all— list specific properties- Decorative glow as primary affordance
- Soft blurry gradient blobs/orbs
- Generic CTAs ("Learn more", "Click here") — be specific
- Walls of text — no landing section > 2-3 sentences
- "OR" divider in caps between auth options — lowercase it: "or with email"
- Full-bleed saturated brand panel beside a sign-in form — tinted neutral surface with one proof asset (recipe-auth.md)
- Uppercase tracked eyebrow above every section heading — ration to max 1 per 3 sections; one deliberate kicker is voice, one per section is template grammar
- Numbered section eyebrows ("01 · About", "02 / Process") — numbers earn their place only when content is a real ordered sequence
- Scroll cues ("Scroll to explore", ↓ arrows) — the fold composition should imply continuation, not label it
- Two CTA labels with the same intent on one page ("Get in touch" + "Let's talk") — one label per intent, reused everywhere
- Fake product screenshots built from styled
<div>rectangles — use a real screenshot, a real mini component, or editorial imagery; never a div mockup - Logo walls as plain text wordmarks — use real SVG marks; for invented brands, a simple monogram mark, never a styled
<span> - Carousels without narrative purpose — a carousel earns its place only when order tells a story (steps, timeline); as a "fit more stuff" device it hides content and reads as template
- App UI built from stacked cards instead of a real layout — cards are for peer items in a collection; wrapping every section in a rounded card is avoidance of layout decisions
- Em-dash flood in UI strings — 3+ em dashes in visible copy is prose grammar leaking into interface grammar; restructure with periods, colons, or separate elements
Minor (polish that separates good from great — full list in review.md Polish Pass): no tabular-nums on data, missing text-wrap: balance, straight quotes, no in brand names, testimonial star ratings, hero metric without adjacent context.
The Craft Test (What TO Do)
Anti-slop says what to avoid. Craft says what to aim for.
General craft:
- One accent, 3-5 placements per above-the-fold viewport. Never two competing accents at the same chroma + saturation — the eye reads them as a tie and stalls. Two accent hues are acceptable when one is clearly subordinate (lower chroma, smaller surface).
- White backgrounds with barely-there borders or whitespace. Numbers large, undecorated,
tabular-nums. - Comparisons plain secondary text. One chart color at different opacities. Area fill fades ~15% → 0%.
- Functional color only — dots for status, flags for countries. Real content, not placeholders.
Landing pages (detail in inspiration.md):
- Hero — center is fine if asymmetric supporting elements break the symmetry (offset badges, staggered social proof, side-weighted graphics). Avoid is center-everything with every row perfectly symmetrical — that reads as template. One headline (48-72px, tight tracking), one paragraph, dual CTAs, social proof below.
- Features: 2-3 asymmetric rows with real visuals (chart, timeline, funnel). NEVER uniform 3-column icon grids.
- Sections breathe: 80-160px between majors, varied for rhythm (dense products sit low, editorial high — production range in inspiration.md). Every section answers one question.
- Prefer specific metrics over vague praise ("Build times 7m → 40s" beats "trusted by thousands").
Dashboards (detail in dashboard.md):
- Sidebar: subtle bg tint, NOT full dark (common AI pattern).
- Metric cards: primary gets accent tint; others neutral. Sparklines on all. NEVER identical colored top borders.
- At least 3 content types per dashboard viewport (e.g., chart + table + metric). Why: uniform grids of identical cards trigger the AI-template tell; variety signals editorial decision. Chart type matches data story (area/horizontal bar/sparkline). Never pie or 3D.
When Rules Break
Every rule above has a context where it inverts. Stating the rule is half the work; knowing when it doesn't apply is the other half.
- "Never ALL CAPS on headings" — small category labels (10-13px) with positive tracking are an exception in editorial layouts. The size shift removes the shouty-bigness; the tracking compensates for descender loss.
- "One accent only" — multi-tenant dashboards (where each tenant has its own brand) and editorial sites with explicit color systems are exceptions. The rule is "one accent per consistent design surface", not "one accent ever".
- "Avoid pie charts" — for two-segment proportional comparisons (e.g., used vs. free storage on a single device), a donut with center label is acceptable. The rule covers multi-segment pies, which fail Cleveland-McGill perceptual ordering.
- "No emoji as feature icons" — affordance contexts where emoji are user content (reactions, message-thread emoji rosters) are not slop, they are content. The rule covers decorative emoji standing in for designed icons.
- "Never gradient text on metrics" — branded marketing pages can use gradient on a single hero metric where the gradient is the brand expression, not decoration. Inside-the-product metrics still follow the rule.
- "Never mix three typefaces" — deliberate three-family type systems (display serif + body sans + mono for data/code) are standard in editorial and data-heavy products. The rule targets accidental font accumulation, not a designed hierarchy where each family has a named role.
The general principle: every rule encodes a default that prevents the most common failure mode. When the context inverts the failure mode, the rule may invert too. The work is recognizing the inversion, not memorizing exceptions.
Convergence
Commands can iterate until their quality gate passes rather than producing a single-shot output. The engine never fakes a render and always reports honest confidence. See loops.md.
Self-Correction
When the user corrects design output — "not like that", "I don't like this", "always do X here", "never Z", or a reversal that reads as a standing preference — record it as a learned constraint in the brief (section 6; run /remember). Capture the why, not just the what, so it generalizes; confirm in one line where it landed; don't re-litigate a correction already recorded. Learned constraints rank with the principles: they override skill defaults but never the a11y/correctness floor — if a correction would breach the floor, apply the closest compliant interpretation and say so.
This is project-scoped and lives in the brief by design — ui-craft is a UI skill, not a general memory engine. Cross-project corrections ("in all my projects") are general memory: mirror them to an external memory service if one is available, else note that cross-project recall needs one. Full behavior → brief.md (Self-Correction).
Animation Decision Ladder
Should this animate? → High-frequency? No. Not communicating hierarchy/state/space? Cut it. Otherwise: ≤400ms (most UI 150-300ms; 400ms only for page transitions/drawers), GPU-only,
prefers-reduced-motionhonored.
Full ladder, easing, springs, stagger, interaction contract → motion.md (Decision Ladder).
Design Rules (core)
Layered shadows (ambient + direct). Semi-transparent borders + shadows for crisp edges. Hue-consistent borders/shadows/text on colored surfaces. APCA over WCAG 2. Interactions increase contrast. color-scheme + theme-color match theme. OKLCH for scales. Full detail in layout.md and color.md.
Review Format (Required)
When reviewing UI code, use a markdown table. Never use "Before:"/"After:" on separate lines.
| Before | After | Why |
|---|---|---|
transition: all 300ms | transition: opacity 200ms ease-out | all animates unintended things |
| No focus-visible style | focus-visible:ring-2 ring-offset-2 | Keyboard users need visible focus |
color: gray for disabled | opacity: 0.5 + cursor: not-allowed | Multiple signals, not just color |
Prioritize findings by impact:
- Critical — blocks usability/a11y (missing focus, broken keyboard nav, no reduced-motion)
- High-impact — immediately noticeable (wrong font, default blue, identical card grids, no hover states)
- Quick wins — big polish (tabular-nums, letter-spacing, curly quotes,
)
Quick Decision Frameworks
Should This Animate?
| Frequency | Decision |
|---|---|
| High (keyboard, toggles, typing) | No animation. Speed is the feature. |
| Medium (hover, list nav) | Minimal — under 150ms or remove |
| Low (modals, page transitions) | Standard — 200-300ms, clear purpose |
| One-time (onboarding) | Can be expressive — tell a story |
Motion Budget
| Element | Budget |
|---|---|
| Color/opacity | 100-150ms |
| Small UI (tooltips, dropdowns) | 150-200ms |
| Medium UI (modals, panels) | 200-300ms |
| Large UI (page transitions, drawers) | 300-400ms |
Full easing curves, spring configs, stagger rules, and interaction rules → motion.md.
Reference Files
Tiered by signal. Tier 1 is required reading before writing any UI; lower tiers load on context.
Tier 1 — Always load before writing UI
Two entries, because two is what a build actually loads. This list used to hold seven; build evals showed a passing dashboard opened one of them and a passing landing opened two, while both reached for the surface recipe that was filed a tier below. A required list that nobody reads is not a standard, it is a wish — so the list now names what carries the build, and everything else below states the trigger that pulls it in.
| Reference | When to Read |
|---|---|
| craft-intent.md | Craft Read, DESIGN_VARIANCE, signature bets, product + marketing build patterns. The one reference every full-surface build needs. |
| The surface recipe | recipe-dashboard.md · recipe-landing.md · recipe-auth.md — whichever matches what you are building. Every numeric limit that keeps a surface off template grammar lives here (hero subtext ≤20 words, eyebrow budget, form column width, acceptance bar). Skipping it does not soften those limits, it removes them. |
Tier 1b — Load on trigger
Same references as before, same weight when their trigger fires. Only the claim changed: these are conditional, and pretending otherwise made the whole Tier-1 label unreliable — including for the two above.
| Reference | Trigger |
|---|---|
| brief.md | .ui-craft/brief.md exists — then read it first, it anchors every decision and its learned constraints override skill defaults. Absent: run /brief or proceed from Discovery. |
| tokens.md | The project has a token system to respect or extend, or you are establishing one. With neither, themes.md gives a production preset in one step. |
| accessibility.md | Any form, any custom interactive control, any focus or keyboard work. The a11y floor in Core Rules is the minimum; this is the detail. |
| color.md | Choosing or changing a palette, building dark mode, or auditing accent budget. Not needed to apply a preset. |
| layout.md | Composing a surface from scratch, or a spacing/hierarchy pass. Not needed when a recipe already prescribes the composition. |
| inspiration.md | Highest-signal reference in the skill. Read it when the build needs an archetype or a signature detail, and whenever the result feels generic. |
What this measured, and what it did not. The evidence is greenfield builds — an empty sandbox with no brief and no tokens, so
briefandtokenscould not have been read whatever the label said. It shows the label was not causing loads. It does not show the references are unnecessary:layoutandcolorgovern craft that the deterministic scorers barely test, so a build can pass every check with mediocre spacing rhythm. Re-measure before trimming anything further, and re-measure on a project that already has a design system.
Tier 2 — Surface-specific (read when building this surface)
| Reference | When to Read |
|---|---|
| spec.md | Durable composition spec at .ui-craft/spec.md — the "what". Written by /shape Step 6, walked by /sddesign. Read after brief.md when a spec exists for the surface being built. |
| Outcome recipes | Promoted to Tier 1 — see Always load. Listed there and not here so the recipe has one home; two descriptions of the same requirement is how one of them goes stale. |
| themes.md | 4 named production token presets (Graphite, Porcelain, Carbon, Signal). Load when no token system exists. |
| dashboard.md | Dashboards, metric cards, charts, tables, sidebar, filters. |
| forms.md | Validation timing, progressive disclosure, multi-step wizards, autosave, optimistic submit. |
| components.md | Component anatomy contracts: buttons (padding ratio, icon-side semantics), menus (5-option threshold, scroll affordance), modals (verb labels, ways out), search, content cards, nav bar. |
| ai-chat.md | Streaming contract, 7-state affordance model for AI surfaces, tool traces, citations, generative UI. |
| review.md | Critique methodology, Polish Pass, common issues, component craft. Load when reviewing or refining. |
| finish-bar.md | 10-pass finishing protocol. Load on /finalize or CRAFT_LEVEL ≥ 8. |
| loops.md | Loop engine: read→evaluate→fix-one→re-evaluate→stop contract + 3 presets. Load when converging /finalize, /unhappy, or /tokens audit. |
| principles-catalog.md | 42 example design principles across 8 product categories. Load during /brief principles workshop branch as conversation seed. |
Tier 3 — Foundations (read for the relevant discipline)
| Reference | When to Read |
|---|---|
| typography.md | Scale, font choice, readability, weight — scoped per script and role. |
| motion.md | Decision ladder, duration + easing scales with perceptual grounding, interaction rules, motion-gap audit. |
| modern-css.md | View Transitions, scroll timelines, container queries, @starting-style. |
| responsive.md | Mobile/tablet/desktop, breakpoints, touch zones. |
| metadata.md | Title/description/canonical consistency, deterministic metadata, social cards, noindex on staging, structured data honesty, favicons. |
| copy.md | Voice/tone matrix, reading level (Flesch ≥70), terminology, inclusive language, errors, empty states, CTAs. |
| sound.md | Web Audio, UI sound, appropriateness matrix. Rare — load when explicitly building audio feedback. |
Tier 4 — Opt-in (only on explicit request or specific commands)
| Reference | When to Read |
|---|---|
| stack.md | Three.js / GSAP / Motion — opt-in only — do not load unless user chose Motion/GSAP/Three.js in Discovery Step 2. |
| heuristics.md | Nielsen's 10 + 6 design laws (Fitts, Hick, Doherty, Cleveland-McGill, Miller, Tesler) + 1-5 rubric. Load for /heuristic. |
| personas.md | 5 persona walkthroughs (first-timer / power / low-bandwidth / screen-reader / one-thumb). Load for /heuristic --persona=<name>. |
| state-design.md | State lattice — idle / loading / empty / error / partial / conflict / offline. Load for /unhappy. |
| coverage.md | UX coverage — the parts 12 screen archetypes need to be complete (data table, settings, search, detail view, first-run, billing, pricing, docs, checkout, onboarding, destructive confirm, invite). The completeness axis, not distinction. Load for /harden, or when asked what a screen is missing. Prefer the ux_coverage MCP tool — it returns one archetype instead of all twelve. Generated from mcp/src/coverage-data.mjs; do not edit by hand. |
| dataviz.md | Cleveland-McGill perceptual hierarchy, chart selection matrix, ColorBrewer/Okabe-Ito palettes, Tufte, direct labeling. Load when designing charts. |
| agents.md | Agent pack overview: design-reviewer + a11y-auditor roles, agent-vs-command guidance, and parallel verify-team usage pattern. Load when setting up or describing the verify team. |
Commands 25
Adapt the UI at $ARGUMENTS across devices. Load the ui-craft skill and read references/responsive.md.
Work mobile-first. Don't shrink desktop; grow from mobile.
Checklist:
- Breakpoints — use project's existing system (Tailwind:
sm md lg xl; CSS: container queries preferred over media queries for components). No magic widths. - Touch — tap targets ≥ 44×44px (
min-h-11 min-w-11). Touch zones don't overlap.touch-action: manipulationon interactive elements. - Safe areas —
padding-top: env(safe-area-inset-top)etc. on fixed headers/footers/FAB. Check iOS notch and Android gesture bar. - No horizontal scroll at 320px. Test with devtools device mode.
- Fluid type —
clamp(1rem, 0.9rem + 0.5vw, 1.125rem)for body where scale matters; fixed px for small UI text (labels, captions). - Container queries — prefer
@containerover viewport media queries for component-level responsiveness. Components that live in sidebars and main content behave differently at the same viewport width. - Hover-less devices — every hover affordance has a non-hover equivalent.
@media (hover: hover)to scope desktop-only effects. - Density shifts with viewport — honor
VISUAL_DENSITYdifferently per breakpoint:VISUAL_DENSITY ≤ 3→ fewer columns and wider spacing even at desktop widths.VISUAL_DENSITY 8+→ honor dashboard density, but still respect touch/hover distinctions (touch targets stay ≥ 44px on mobile, hover affordances gated behind@media (hover: hover)).- Mobile always trends toward 1 column and wider spacing regardless of the knob value.
- Images —
aspect-ratioset;srcset+sizesfor different viewports;loading="lazy"below the fold;fetchpriority="high"on hero. - Nav pattern — desktop horizontal → mobile collapses (sheet, drawer, or bottom tabs). Never a hamburger on desktop unless the nav has > 7 top-level items.
Output: edit code directly. Print the Review Format table of changes. Flag any responsive bugs you can't fix without more info (missing design for a breakpoint, unclear nav pattern).
Next step: /audit — verify the responsive pass against a11y, performance and touch targets (rung 1).
Add or fix animations in $ARGUMENTS. Load the ui-craft skill.
Step 1 — Decision Ladder: run the Decision Ladder from references/motion.md first. Anything that fails it gets removed, not improved.
Step 2 — Pick the library:
- If user opted into a stack during Discovery → read
references/stack.md. Use the matching section (Motion, GSAP, or Three.js). Never mix libraries on the same property. - Otherwise → CSS transitions /
@keyframes/animation-timeline: view()only.
Step 3 — Apply motion budget:
| Element | Budget |
|---|---|
| Color/opacity | 100-150ms |
| Small UI (tooltips, dropdowns) | 150-200ms |
| Medium UI (modals, panels) | 200-300ms |
| Large UI (page transitions, drawers) | 300-400ms |
Exit ≈ 75% of entrance duration (shorter, same ease-out — or a flatter tail like cubic-bezier(0.4, 0, 1, 1) for a softer exit). Never ease-in on UI (see references/motion.md). cubic-bezier(0.22, 1, 0.36, 1) is a safe spring-like default.
Step 4 — Multi-stage sequences → read ../examples/animation-storyboard.md. Stagger 30-80ms, not 200ms.
Step 5 — Respect the knobs:
MOTION_INTENSITY ≤ 3→ hover states only, no entrances, no scroll-triggered.MOTION_INTENSITY 4-7→ standard entrances + hover, one scroll reveal max per section.MOTION_INTENSITY 8+→ scroll-linked, page transitions, magnetic cursor OK (still honor reduced-motion).
Output: edit code directly. After each file, print the Review Format table. Flag any animation you removed and why.
Next step: /polish — the compound details around the motion you just added (rung 1).
Run a technical audit of the UI at $ARGUMENTS. Load the ui-craft skill and apply the audit lens.
Step 0: Visual capture (mandatory)
Code-only review is insufficient. Every audit/critique starts with the surface as the user sees it. Try the following in order; use the first one available:
- Playwright MCP — if
playwrightMCP server is available, use it. Capture full-page screenshots at three viewports: desktop (1280×800), tablet (768×1024), mobile (375×812). Capture dark mode if the app supports it. - Browser DevTools / Chrome MCP — second choice; same viewport set.
- Other browser automation (
agent-browser,cursor-ide-browser) — third choice. - Ask the user — last resort. If no automation is available, request screenshots from the user before proceeding. Be specific:
- "Visual review needs screenshots. Please provide:
- Full-page at 1280px (desktop)
- Full-page at 768px (tablet)
- Full-page at 375px (mobile)
- Dark mode of each, if supported."
- "Visual review needs screenshots. Please provide:
Do not begin the review until visuals are captured or provided. State this explicitly to the user when no automation succeeds — don't silently fall back to code-only review.
If the user declines to provide screenshots, run a code-only pass and clearly mark the report [CODE-ONLY REVIEW — visual issues not assessed] at the top so the limitation is explicit.
Note: audit is knob-agnostic — accessibility and performance are not tunable.
Scope (non-negotiable checks):
- Accessibility — read
references/accessibility.md:- Visible
:focus-visibleon every interactive element - Keyboard reachable, no focus traps
- Touch targets ≥ 44px (mobile)
- Color not the only signal for state
- Form labels, error association, required indication
prefers-reduced-motionhonored for all animations
- Visible
- Performance — read
references/motion.mdRendering Performance section:- Only
transform/opacityanimated (nowidth/top/height) - No
transition: all will-changescoped to active interaction, removed after- Images have
width/heightoraspect-ratio(CLS) - No layout thrash in scroll/resize handlers
- Only
- Responsive — read
references/responsive.md:- Mobile-first breakpoints, no fixed-width components
env(safe-area-inset-*)respected on fixed elements- Touch zones don't overlap
- No horizontal scroll at 320px
Output format — the Review Format table from SKILL.md:
| Before | After | Why |
|---|
Group findings by priority: Critical (blocks usability/a11y) → High-impact (immediately noticeable) → Quick wins (polish).
Do NOT rewrite code unless asked. Report findings first; wait for approval before editing.
Close with a Craft Report (references/review.md → Craft Report), wrapping the findings table above — Checked states scope (a11y/perf/responsive, at which viewports), Passed carries anything inspected and found sound, Changed stays empty pre-approval, Verdict names the top priority. Produce it even on a clean audit — a11y/perf/responsive coming back clean is the finding.
Next step: /harden — turn the findings into real production coverage (rung 1).
Make the UI at $ARGUMENTS bolder. Load the ui-craft skill and read references/craft-intent.md.
This is amplitude, not decoration. Increase editorial confidence while staying anti-slop clean.
Apply in order (edit code directly):
- Declare an updated Craft Read — one line: what changed (variance, motion, signature).
- Raise DESIGN_VARIANCE by +1–2 (cap 10). Product surfaces: asymmetric offset, stronger metric hierarchy, or display moment in shell. Marketing: stronger hero composition, section rhythm break, or typographic scale — per
references/craft-intent.mdvariance table. - Raise MOTION_INTENSITY by +1 (cap 10) if below 8 — add one purposeful entrance or hover choreography on the focal element only. Honor
prefers-reduced-motion. - Typography — increase display weight or size one step; tighten tracking on headlines; ensure numbers stay
tabular-nums. - Accent — strengthen focal accent placement (within 3–5 viewport budget); tint primary card or CTA — never add a second accent hue.
- Signature — add or strengthen the one signature bet if missing or weak (see craft-intent §3).
Never add: purple-cyan gradients, bounce easing, glassmorphism stacks, emoji, ALL CAPS headings, three equal icon-card grids, confetti.
Knob gating: if already at variance ≥9 or MOTION ≥9, strengthen signature and typography instead of pushing further.
Output: edit code. Print Review Format table. End with the updated Craft Read line.
Next step: /critique — confirm the added personality did not cost hierarchy or become slop (rung 1).
Load references/brief.md for the brief format before proceeding.
Step 1: Detect existing brief
Check whether .ui-craft/brief.md exists. Use Read or ls on .ui-craft/.
If it exists: load its contents. If $ARGUMENTS names a specific update ("update principles", "shift target user", "add out of scope"), focus the session there and skip unchanged sections. Otherwise summarize what's in the brief and ask: "What do you want to change?"
If it doesn't exist: proceed to Step 2. Also check the repo root for a DESIGN.md or design-tokens.json (an ecosystem convention some teams already maintain) — if present, read it and pre-fill the brief's answers from it instead of re-asking; note the source. The brief complements an existing design contract, never contradicts it.
Step 2: Draft a new brief (absent case)
Walk the user through the five required sections in a single pass. Ask ONE compact question per section. Do not open five separate prompts unless the user asks for depth.
Compact prompt template:
"To write your design brief I need five things — answer as tersely as you like, I'll fill in structure:
- Product purpose — what does it do, in one sentence?
- Primary user — who, by role and context?
- Principles — what does this product believe? Give me three to five stances it takes. (If you don't have these yet, say so — I'll run the principles workshop.)
- Success metric — what does 'the user succeeded on this surface' look like in observable behavior?
- Out of scope — three to five things this surface deliberately does NOT do."
Principles workshop case: if the user says "I don't have principles yet" or gives vague answers ("make it good", "keep it simple"), do NOT fabricate principles from vague input. Load references/principles-catalog.md first. The catalog has 42 worked example principles across 8 product categories — use them as conversation seeds, not as templates to adopt literally. Show 2-3 from the closest category to the user's product, then ask which resonate or which they'd flip. Then run the principles workshop from references/brief.md as a focused sub-flow: ask for three past design decisions that were debated, then derive candidate principles from the patterns. Refuse to accept platitudes — push back and prompt for substance.
Parsing long input: if the user provides a product description or PRD, parse it into the five sections rather than re-asking for information already given. State what you extracted and ask for confirmation or corrections.
Thin answers: if an answer is too vague to constrain a design decision, ask one targeted follow-up. Maximum two follow-ups per section before flagging it as incomplete and moving on.
Step 3: Show before writing
Always show the proposed brief in full before writing the file. Ask: "Does this look right, or anything to adjust?"
Do not write until confirmed.
Step 4: Write the file
Create .ui-craft/ if it doesn't exist. Write the confirmed content to .ui-craft/brief.md.
The file must contain all five sections with the exact headings from references/brief.md. No omissions.
Step 5: After writing
Tell the user the file is at .ui-craft/brief.md. Suggest committing it:
"Commit
.ui-craft/brief.mdto the repo — it's documentation, not config. The agent reads it every session."
Do not auto-commit. Per project rules, commits require explicit user instruction.
Constraints
- All five sections are required. If one is genuinely unknown, write it as a dated placeholder with
[TO DEFINE — YYYY-MM-DD]so the gap is visible. - The brief is append-mostly on updates. Never delete past content — mark deprecated with date and reason.
- No brand names, product examples, or generic SaaS language inside the user's brief. The brief describes their product, not the template.
Next step: /tokens — the brief decides the intent, the tokens encode it (rung 2).
Clarify the copy in $ARGUMENTS. Load the ui-craft skill.
Default mode: critique, not edit. Return the copy diff in a Review Format table. Only apply changes if the user says "apply".
Checklist — walk the UI and flag every instance:
- Button labels — verb + object. "Send invite" > "Submit". "Delete project" > "Delete". Never "OK", "Submit", "Click here".
- Errors — inline, specific, actionable. "Email already in use — sign in or use another address." Never "Something went wrong."
- Empty states — one line explaining why empty + one CTA. "No projects yet. Create your first." not "It's empty here!"
- Form hints — below the field, persistent, not just validation-triggered. "Must include a number and a symbol" as helper text, not as an error after submit.
- Confirmation language — past tense, subject-first. "Project deleted." > "Successfully deleted project."
- Destructive actions — the noun lives in the button. "Delete {projectName}" > "Delete". The dialog confirms; the button commits.
- Case — sentence case by default. Title Case only for branded product names. Never ALL CAPS (exception: 11-13px category labels, already in SKILL.md).
- Voice — clear > clever. Active voice. Short sentences. Real words ("cancel" not "discontinue", "start" not "initiate").
Knob-agnostic — clarity is not tunable. Run the full checklist regardless of CRAFT_LEVEL.
References to read: references/copy.md (microcopy voice + patterns), references/accessibility.md (error message expectations for screen readers).
Output format — the Review Format table:
| Before | After | Why |
|---|
Prioritize by impact (errors and destructive actions first, then CTAs, then helper copy). End with a one-paragraph summary of the overall voice shift. If the user says "apply", edit the code and re-print the table with file paths.
Next step: /critique — copy changes shift hierarchy; re-read the surface after (rung 1).
Add color to the UI at $ARGUMENTS. Load the ui-craft skill.
The rule (from SKILL.md): 90%+ neutral, one accent, 3-5 placements per viewport. Reinforce this before adding anything. More color is not more design.
Before you touch anything — ask about brand. If a brand color exists, use it. If not, offer 2-3 options in OKLCH — include one warm (e.g., oklch(0.67 0.19 45)) and one cool (e.g., oklch(0.60 0.18 250)). Never default to blue.
Where color EARNS its place:
- Primary CTA background.
- One key metric tint — accent at ~8% opacity as a subtle background, accent at full strength on the number itself.
- Active state of the current nav item (underline, dot, or subtle tint — pick one).
- Status dots (success / warning / danger), 6-8px, no pills.
- Focus ring (
:focus-visible).
Where color does NOT go (anti-slop territory):
- Heading gradient text.
- Colored left or top borders on every card.
- Uniform chips on every tag/label.
- Emoji-as-icons to inject "color."
- Trend arrows in green/red when a plain
↑/↓+tabular-numswould read cleaner.
Knob gating (VISUAL_DENSITY):
≤ 4→ single accent only, max 3 placements.5-7→ single accent, 3-5 placements, status dots allowed.8+→ semantic palette (success/warning/danger) allowed beyond the single accent — dashboards and data UIs earn this.
Over-colored? Reduce.
If the UI is already shouting with color, this command also removes color.
- Count accents per viewport. Cut to 1-3. The primary CTA keeps its accent; everything else goes neutral unless it's a true semantic state (success/warning/danger on a real status).
- Mute decorative color. Background patterns, tinted cards without meaning, colored left borders on every list item, heading gradients, colored pills on every tag → gone.
- Keep semantic, cut decorative. Status dots, focus rings, active-nav underlines stay. Color as ornament goes.
References to read: references/color.md (OKLCH, tokens, dark mode, contrast), references/accessibility.md (contrast ratios for AA/AAA).
Output: edit code directly. Lift any literal hex into CSS variables (--color-accent, --color-accent-tint) — respect existing token naming if present. Print the Review Format table. One row per placement, with the ratio check (AA/AAA) on text uses.
Next step: /tokens — promote the color decisions into the durable token spine so they survive the session (rung 2).
Load the ui-craft skill. This command BUILDS — it ends with working code that passes the recipe's acceptance bar.
Recipes available: dashboard → references/recipe-dashboard.md · landing → references/recipe-landing.md · auth (sign-in/sign-up) → references/recipe-auth.md. If $ARGUMENTS names a surface with no recipe yet (settings, docs, e-commerce), say so and fall back to standard Build mode with the closest references — do not improvise a fake recipe.
Step 0 — Load spec (if present)
Before anything else: if .ui-craft/spec.md exists and contains a ## Surface: <name> section whose name matches $ARGUMENTS, load that section now. Its chosen composition, component inventory, state lattice, and acceptance bar take precedence over the recipe defaults for all downstream steps. Note which acceptance bar items came from the spec vs. recipe defaults.
Step 1 — Inputs
Run Stack Detection + Discovery Step 1 (existing tokens, .ui-craft/brief.md).
Load references/craft-intent.md.
Ask the recipe's Step 0 questions in ONE compact prompt, pre-filling anything $ARGUMENTS or the brief already answers. If the user declines, says "you decide", or has answered before in this session: apply the recipe defaults silently and say which were applied. Never ask twice; never block.
Set DESIGN_VARIANCE from craft-intent defaults for this surface type unless the user or brief specifies otherwise.
Step 2 — Craft Read + lock the plan
Output the Craft Read (one line, craft-intent §1) before any code. Include: surface kind, audience, product vs marketing language, theme/accent, variance, signature bet.
From the answers: composition + theme preset (or existing tokens) + density + variance + signature bet. If no brand direction, rotate one axis (craft-intent §6) and name it.
Landing surfaces — draw the fold, do not pick it. Call the fold_candidates MCP tool, passing every composition class already listed under ## Fold classes used in .ui-craft/brief.md as used. Commit to one of the three it returns, and state the sacrifice that class demands out loud, because that sacrifice is what will make this page look like itself.
Do not average the candidates together, and do not fall back to a text-left/visual-right split because it fits everything. It fits everything because it commits to nothing: ten blind builds of this skill produced that fold ten times out of ten, across two unrelated products, while only 3 of 18 reference landing pages use it.
If the MCP server is not wired, say so and pick a class from scripts/fold/classes.mjs that the brief has not spent yet — the point is the draw, not the tool.
Print a short plan (5–7 lines): Craft Read, composition class and its sacrifice, theme, signature bet, what's above the fold, what's deferred — then proceed unless the user objects.
Step 3 — Build
Follow the recipe's Build order EXACTLY (tokens → shell → hero tier → primary region → remaining tiers → states → keyboard → finish). Load the references each step names plus craft-intent.md patterns for this surface type. Build the signature bet in this pass — not later.
States and keyboard are build steps, not polish — a surface without empty/loading/error states is not done.
Step 4 — Acceptance bar
Run the recipe's acceptance checklist against the built surface. Fix every unchecked item before reporting — the bar is the definition of done, not a suggestion.
Visual self-check (when a screenshot tool is reachable): if a Playwright/browser MCP or similar is available, capture the built surface at desktop width and look at it before reporting — a render exposes spacing collisions, hierarchy ties, and dead zones that code review can't. Run the similar-prompt self-test (craft-intent §1) against the screenshot: would this exact page pass for a different brand in the category? If yes, strengthen the signature before reporting. No tool available → skip silently, never block.
Landing surfaces — check the fold you actually built. Serve the page and call check_fold with the URL, the class you drew as expected_class, and the costly detail you committed to. It renders in a browser you already have and returns the screenshot alongside its reading. Two things there are worth acting on: drift, which means you drew one class and built another — usually the split, since that is the fold the model returns to unprompted — and a population reading that says the fold stands out nowhere, which is a prompt to look at the screenshot rather than a fault, since it also flags 7 of 18 reference landing pages.
Everything else it returns is measurement without a verdict, and should be read that way. Only two of its invariants are judged, and neither is geometric.
Record what was spent: append the class you built to ## Fold classes used in .ui-craft/brief.md, creating the section if it is missing. That list is what makes the next /craft in this project draw something else. Without it the draw has no memory and the project converges again.
Report to the user:
- The Craft Read (repeat)
- The composition class drawn, and the sacrifice it demanded
- Which signature bet was built
- Checklist results
- Any item the user explicitly waived
Lead with intent, not a findings dump. Use the Review Format table only for fixes made in this pass.
At CRAFT_LEVEL ≥ 8, finish with the full /finalize gate instead of the recipe's minimum passes.
Next step: /finalize — run the pre-ship gate (rung 3). If this project has no brief yet, /brief first (rung 2).
Critique the UI at $ARGUMENTS through a design lens. Load the ui-craft skill.
Step 0: Visual capture (mandatory)
Code-only review is insufficient. Every audit/critique starts with the surface as the user sees it. Try the following in order; use the first one available:
- Playwright MCP — if
playwrightMCP server is available, use it. Capture full-page screenshots at three viewports: desktop (1280×800), tablet (768×1024), mobile (375×812). Capture dark mode if the app supports it. - Browser DevTools / Chrome MCP — second choice; same viewport set.
- Other browser automation (
agent-browser,cursor-ide-browser) — third choice. - Ask the user — last resort. If no automation is available, request screenshots from the user before proceeding. Be specific:
- "Visual review needs screenshots. Please provide:
- Full-page at 1280px (desktop)
- Full-page at 768px (tablet)
- Full-page at 375px (mobile)
- Dark mode of each, if supported."
- "Visual review needs screenshots. Please provide:
Do not begin the review until visuals are captured or provided. State this explicitly to the user when no automation succeeds — don't silently fall back to code-only review.
If the user declines to provide screenshots, run a code-only pass and clearly mark the report [CODE-ONLY REVIEW — visual issues not assessed] at the top so the limitation is explicit.
Knob awareness (CRAFT_LEVEL sets the bar for what counts as "needs work"):
CRAFT_LEVEL 3→ flag only anti-slop Critical items. Skip Minor polish.CRAFT_LEVEL 5-7→ flag Critical + Major. Mention Minor polish as optional.CRAFT_LEVEL 9+→ flag everything, including Minor polish and missing signature detail.
Run these lenses in order:
- Anti-Slop Test (from SKILL.md): flag every item present. Critical first (ALL CAPS, purple gradients, identical card grids, bounce easing, emoji icons, glassmorphism + neon). Then major (colored pills on trends, thick colored borders, uniform radii, gradient text, walls of text). Then minor (straight quotes, missing
tabular-nums, generic CTAs). - Craft Test (from SKILL.md): where does the design fall short of "one accent, 3-5 placements; plain secondary text for comparisons; functional color only; every section earns its space"?
- Hierarchy: can the user tell what's primary, secondary, tertiary at a glance? Or does everything shout equally?
- Clarity: is the value prop legible in 5 seconds? Are CTAs specific (not "Learn more")?
- Signature detail: is there one memorable element that makes this feel designed, not assembled? If not, suggest one (motif, layout break, custom marker, distinctive hover).
- Inspiration gap — read
references/inspiration.md: which observed pattern from the archetypes / signature details applies here, and how does the current state diverge from it?
Output format — the Review Format table:
| Before | After | Why |
|---|
Prioritize by impact, not by file order. End with a one-paragraph summary of the top 3 changes that would raise this from "AI-generated" to "designed".
Do NOT edit code. This is a critique.
Close with a Craft Report (references/review.md → Craft Report) as the final wrapper around the findings table and top-3 summary — Checked names the lenses actually run (Anti-Slop, Craft Test, Hierarchy, Clarity, Signature, Inspiration gap) and at what CRAFT_LEVEL bar, Passed carries whatever held up under those lenses, Changed stays empty (critique doesn't edit), Left alone covers anything flagged but out of scope, Verdict is the one-sentence state. Produce it even when the surface passes clean — that's the validation the user is asking for.
Next step: /polish — apply the fixes this critique named (rung 1).
Add delight to the UI at $ARGUMENTS. Load the ui-craft skill.
Delight is specificity, not decoration. The goal is one or two moments a user would screenshot — not confetti, not bounce, not emoji.
Candidates, ordered by safety (start at the top):
- Copy specificity — confirmation toasts name the thing ("3 members invited — Alex, Sam, Jordan", not "Invites sent"). Empty states with wit but no cringe ("Nothing here yet — add your first project" > "Oops! Looks like it's empty 😅").
- Hover choreography — multi-property hover (transform + color + shadow) that moves together on one shared duration/easing. One card, not every card.
- State transitions — optimistic UI + tiny success micro-animation (checkmark stroke draw, count-up on a number, subtle scale-and-settle on the updated row).
- One signature detail — custom list markers tied to the domain, asymmetric column offset on a single section, scroll-linked progress that tracks something real (reading progress, form completion).
Never add:
- Bounce easing (
cubic-bezier(0.68, -0.55, 0.27, 1.55)) — flagged in anti-slop. - Confetti on mundane actions (file saved, field updated).
- Emoji spam or "🎉 SUCCESS!" in ALL CAPS.
- Idle float/bob/shimmer on elements that aren't waiting for anything.
Knob gating (MOTION_INTENSITY):
≤ 3→ copy-only delight. No animated delight. Candidate 1 only.4-7→ copy + hover + state transitions (candidates 1-3).8+→ all four, including the signature detail.
References to read: references/motion.md (Decision Ladder + interaction rules), references/copy.md (microcopy voice), ../examples/animation-storyboard.md (if multi-stage).
Output: edit code directly. Print the Review Format table. Flag every candidate you chose not to add and why.
Next step: /finalize — delight is the last additive pass; gate it before shipping (rung 3).
Distill the UI at $ARGUMENTS to its essence. Load the ui-craft skill.
The test for every section, component, prop, and word:
Does this answer a question the user is asking or drive an action they need to take? If not — cut it.
Knob gating (CRAFT_LEVEL):
≤ 4→ be more aggressive with cuts; strip anything that doesn't directly drive action.5-7→ standard cuts per the test below.8+→ preserve signature details even if they don't directly drive action — the one memorable element that makes this feel designed stays.
Apply ruthlessly:
- Content — walls of text → 2-3 sentences max per landing section. Vague testimonials → specific metrics or cut. "Features" lists with 12 items → pick the 4 that matter. Placeholder copy → real or removed.
- Structure — identical card grids → asymmetric rows with real visuals. Three competing CTAs → one primary + one secondary. Breadcrumbs + title + subtitle + description + icon → pick the two that are load-bearing.
- Visuals — decorative gradient blobs → gone. Background patterns that don't carry meaning → gone. Duplicate iconography → gone.
- Visual weight reduction — if headings are shouting at weight 800 / 72px / tracking -0.04em, compress: 800 → 600, 72 → 56, -0.04 → -0.02. Don't remove hierarchy; tighten the range. Replace hard drop shadows with ambient + direct (
references/modern-css.md) or 1px borders — never both. If every section is full-bleed and high-contrast, let some breathe. - Code — unused props, dead branches, commented-out blocks,
console.log, TODO notes without tickets — gone. - Anti-slop overlap — if you see anything on the Anti-Slop Test (SKILL.md), cut it first.
Overlapping commands: for color overload (too many accents, decorative color), use /colorize. For motion noise, use /animate with MOTION_INTENSITY ≤ 3.
Output:
- Edit code directly.
- Report what was cut and why in a table:
| Cut | Why |
|---|
- End with a one-line delta: "Before: N sections / M components / X lines. After: …".
Guardrail: do not cut accessibility affordances (labels, focus styles, error text, reduced-motion fallbacks) — those always earn their space.
Next step: /polish — what survived the cut deserves the details (rung 1).
Extract reusable pieces from $ARGUMENTS. Load the ui-craft skill.
Step 1 — Scan the target for extraction candidates:
- Repeated Tailwind class combos — any class string that appears ≥3 times becomes a component (or a
cva/tvvariant if the project uses one — check first). - Magic values — hex colors, pixel sizes, shadow definitions, font sizes, z-index values appearing in literal form. Lift into CSS variables or
theme.extend. - Repeated markup — blocks that differ only by text/props collapse into a single component with props.
Step 2 — Match the project's conventions, don't impose new ones:
- Naming — look at neighboring components. PascalCase file? kebab-case file? Named export vs default export? Match exactly.
- Location — check
components/ui/,ui/,primitives/,src/components/before creating a new directory. Reuse. - Tokens — respect existing CSS variable naming (
--color-*,--space-*,--font-*,--radius-*). Don't introduce a parallel system.
Step 3 — Anti-Slop Test on every new component (from SKILL.md):
- Component name must be domain-specific, not generic.
MetricCard/PricingTier/InviteRowbeatsCard/Box/Item. - If the component is generic ("a card with a title and description"), ask yourself whether it should instead be an inline composition — premature abstraction is worse than repetition.
Step 4 — Update every call-site. No half-migrations.
Knob-agnostic — DRY is not tunable.
References to read: references/layout.md (composition patterns), references/typography.md and references/color.md (token naming), plus the project's existing component library (scan before writing).
Output:
- The new component file(s) + any token additions.
- A table showing every call-site update:
| File | Before | After |
|---|
- A one-line delta: "Extracted N components, M tokens. Call-sites updated: X."
Next step: /tokens — lift the values you just centralized into the token spine (rung 2).
Load the ui-craft skill. This command produces findings only — do NOT edit code.
Step 1 — Brief check (gate)
Look for .ui-craft/brief.md.
- Absent: STOP. Output: "No brief found. Run
/brieffirst./finalizerequires a design brief to distinguish intentional decisions from findings." Do not proceed. - Present: load it. Extract principles (numbered, in conflict-resolution order). These are the override registry for Steps 4–5.
Step 2 — Detector
Run npx ui-craft-detect on $ARGUMENTS (or current working surface if no argument).
Capture all output. Every Critical detector finding maps directly to a block-ship finding in the report. Preserve detector source labels.
Step 3 — Token check
Quick three-question audit (no deep read required):
- Are all three token layers present (primitives → semantic → component)?
- Are both light and dark modes explicitly authored (not inverted)?
- Are all seven token categories represented (color, spacing, radius, shadow, typography, motion, z-index)?
Any "no": flag as Major. Do not block ship. Append a recommendation: "Run /tokens to close the gap at [category]."
Step 3b — Craft-intent check (full surfaces only)
Applies only when the target is a complete surface (dashboard, landing, auth, settings shell, portfolio) — skip for single components.
- Signature bet present? Scan for exactly one memorable decision from
references/craft-intent.md§3 (product / auth / marketing lists). Zero → Major ("no signature — surface is competent but anonymous; run/bolderor/polish"). Two or more competing → Major ("signature bets stack — keep the strongest, cut the rest"). - Variance matches surface? Layout risk visibly inconsistent with the surface's DESIGN_VARIANCE default (e.g. experimental asymmetry on an auth form, or a landing that is one centered symmetric column) → Major, unless the brief or spec records the deviation.
- Craft Read recorded? If a
.ui-craft/spec.mdsection or session declared a Craft Read, verify the built surface matches it (theme, variance, signature). Mismatch → Major with the specific delta.
These findings are Major, never Critical — they gate NOT READY, not BLOCKED.
Step 3c — Copy self-audit + mechanical counts (marketing surfaces only)
Applies to landings, portfolios, and campaign pages — skip for product shells.
Load references/recipe-landing.md and run its Acceptance-bar mechanical checks against the built surface — thresholds (eyebrow count, layout-family budget, hero discipline) live there, not here; this step only names which checks apply and where a violation lands.
- Copy self-audit. Read every visible string (headlines, eyebrows, buttons, captions, alt text, footer). Grammatically broken copy, unclear referents, forced-clever labels ("Field notes" over testimonials, "Quietly trusted by"), or fake-precise numbers with no source → Major per
references/copy.mdCopy Self-Audit. - Eyebrow count (mechanical) — per
references/recipe-landing.mdEyebrow budget. Over budget → Major ("eyebrow flood — delete labels until the count passes"). - Layout-family count (mechanical) — per
references/recipe-landing.mdLayout-family budget. Any repeat or consecutive-split overrun → Major. - CTA intent (mechanical) — per
references/copy.mdCTAs & Buttons (one label per intent; CTA fits one line at desktop). Violation → Major. - Hero discipline — per
references/recipe-landing.mdHero discipline. Over budget → Major.
Step 4 — Finish bar
Load references/finish-bar.md. Run all 10 passes in document order. Do not reorder.
Knob behavior (apply before running):
CRAFT_LEVEL ≤ 6AND user did not explicitly invoke/finalize: run Passes 1, 6, 8 only; mark remaining as N/A (knob-gated).CRAFT_LEVEL ≥ 7OR user explicitly invoked/finalize: run all 10 passes.MOTION_INTENSITY ≤ 3: Pass 7 = motion-gap audit only; do not fail on absent entrance animations.VISUAL_DENSITY ≥ 8AND brief documents compressed rhythm: Pass 4 accepts compressed spacing values.
For each pass:
- Collect findings.
- Assign severity per the severity map in
finish-bar.md(Critical / Major / Minor). - If a finding conflicts with a recorded principle in
brief.md: downgrade to "Deferred per brief" and cite the exact principle. If no brief principle covers it, it remains a finding regardless. - Record file:line when available.
Step 5 — Feedback hierarchy filter
Load references/review.md Feedback Hierarchy section.
Group all findings (detector + token + finish-bar) into three tiers:
- Value — does the surface solve the problem the brief defines?
- Ease of Use — can the user accomplish the primary task?
- Delight — is it polished?
If any Value findings exist: surface them first in the report and add a standing recommendation to defer all Delight findings until Value findings are resolved. This prevents polish work masking broken functionality.
Step 6 — Output
Print this report. Do not add preamble.
## Finalize report — <surface name>
**Ship verdict:** READY / NOT READY / BLOCKED
> BLOCKED = any Critical finding present.
> NOT READY = any Major finding present, no Critical.
> READY = zero Critical, zero Major (Minor explicitly accepted).
### Block-ship findings (must fix before merge)
- [Pass / detector source] — [finding] — [file:line if available]
### Major findings (fix or defer with recorded reason)
- [...]
### Minor findings (polish; ship-okay if explicitly accepted)
- [...]
### Deferred per brief
- [finding] — [principle from brief.md that defers it]
### Recommended next actions
- [ordered, 3–5 items max]
If a tier has no findings, omit the section header entirely.
Step 6b — Convergence mode (explicit opt-in only)
Convergence mode activates ONLY when the user explicitly says "run in convergence mode", "converge until the bar passes", or uses a --converge flag. A vague "keep going", "fix it", or "make it pass" does NOT trigger convergence — the default remains findings-only (Step 7 hard-stop applies).
When explicitly triggered: load skills/ui-craft/references/loops.md and run preset visual-anti-slop (budget the default loop budget defined in loops.md, hard cap 5). Emit the pre-flight cost notice before iteration 1. After each single highest-impact fix, re-run finalize Steps 2–6 (this command's own steps) until READY or budget exhausted. Note: finalize's findings-only hard-stop (Step 7) is lifted ONLY inside convergence mode — fixes are applied during iteration.
Step 7 — Hard stops
Do not edit any file. Do not propose code changes inline. The verdict is the output. If the user asks for fixes after reading the report, respond to that as a separate request.
Next step: Ship. If the gate is red, the findings name the pass to re-run — /polish, /harden or /clarify.
Harden the UI at $ARGUMENTS for production. Load the ui-craft skill.
Coverage matrix — check every key surface:
- Loading — skeletons match the final layout (no CLS on resolve), shown after ~200ms to avoid flash on fast responses. Never a generic centered spinner when a skeleton is possible.
- Empty — purposeful: one line explaining why it's empty + one clear primary action. Illustration optional, CTA mandatory.
- Error — inline, actionable. "Save failed. Try again / Copy error / Contact support" — never just "Something went wrong." Surface the what and the next step.
- Partial data —
—(em dash) for missing metrics, neverN/Aornullor0when the value is truly unknown. - Long content — truncation with
titletooltip,text-overflow: ellipsis, container queries for constrained regions. Test with a 120-character name. - i18n — no hardcoded strings, ~1.3× text expansion slack for German, narrower glyphs for CJK, RTL flip consideration for icons with direction.
- Offline / slow — optimistic UI with reconciliation on failure; skeleton persists past timeout with a "still loading…" affordance.
- Permission — what happens when the user lacks access: disabled vs hidden. Always surface a "why" (tooltip, inline helper) when disabled.
- Zero-state → first-run — inline hints beat 5-step tours. Guide within the surface, not over it.
Knob-agnostic — correctness is not tunable. Run the full matrix regardless of CRAFT_LEVEL / MOTION_INTENSITY / VISUAL_DENSITY.
Then run the archetype's coverage parts. The nine items above are cross-cutting; they do not know what kind of screen this is. Name the archetype (data table, settings, search, detail view, first-run, billing, pricing, docs page, checkout, onboarding, destructive confirm, invite/share) and pull its parts:
- MCP connected → call
ux_coveragewith the archetype. It returns that archetype's parts and the reporting contract. - No MCP → read the matching section of
references/coverage.md. - No archetype matches → skip this step and say so in one line. Coverage is deliberately partial; an unlisted surface is not a failure.
Each part carries what present looks like, the ui-craft rule for building it, and what the user loses without it. Report the cost, not just the absence — "no export" is a status, "the user expects the 24 rows on screen and receives 10,000" is the reason it matters.
References to read: references/accessibility.md (keyboard + screen reader paths), references/copy.md (error and empty-state voice), references/motion.md Rendering Performance section (skeleton motion + reduced-motion).
Output: two sections, reported side by side and never combined.
- Hardening matrix — the 9 items above, each marked present / partial / missing.
- Coverage — the archetype's parts, each marked present / partial / missing / not-needed / unknown.
not-neededrequires a stated reason; if you cannot say why it does not apply here, it is missing.unknownsays whether more input would settle it.
No score, no count, no percentage on either section. "7 of 9" makes not-needed read as a failure and turns a hardening pass into a grade. Coverage never gates: it reports, and the build still ships.
Then edit the code to fix what's missing. Print the Review Format table showing fixes. End with a "still at risk" list for anything you couldn't safely auto-fix (requires backend, requires design decision, requires translation files).
Next step: /finalize — the pre-ship gate (rung 3).
Score the UI at $ARGUMENTS against Nielsen's 10 + 6 design laws. Load the ui-craft skill.
Step 1 — Load the methodology. Read references/heuristics.md for the full rubric, scoring definitions, design law details, and the required output format. Do NOT invent a new format or a new scale.
Step 2 — Walk Nielsen's 10 heuristics. Score each 1-5 per the rubric:
- 1 blocks users · 2 severe friction · 3 works but confusing · 4 works, minor polish · 5 best-in-class
For every heuristic, write a concrete finding — quote text, count elements, name the broken flow. Vague findings are rejected.
Step 3 — Audit the 6 design laws. PASS / FAIL each with a specific detail:
- Fitts's Law — touch target sizing, CTA placement
- Hick's Law — choice density, nav + select sizing
- Doherty Threshold — perceived latency, optimistic UI
- Cleveland-McGill — chart encoding choice
- Miller's Law — nav depth, form section counts
- Tesler's Law — where complexity lives
Step 4 — Persona walkthrough (if --persona= present). If the args include --persona=<name>, load references/personas.md and run the matching walkthrough checklist. Supported: priya, jordan, adaeze, kwame, margo, all. Output the walkthrough as a | Checklist item | Pass/Fail | Finding | Impact | table. Without the flag, skip this step.
Step 5 — Rank findings by impact tag. Impact order: blocks-conversion > adds-friction > reduces-trust > minor-polish. Include at most 5 findings in the ranked list; cut anything at minor-polish unless there are no higher-impact findings.
Step 6 — Compute the UsabilityScore. Roll the scorecard into a 0-100 number + grade per the UsabilityScore formula in references/heuristics.md: heuristic_base = round(((mean(nielsen_scores) − 1) / 4) × 100), minus 5 × (failed design laws), clamped [0,100]. Same A/B/C/D/F bands as UICraftScore. Always label it (judged) — it is not deterministic and must never gate CI. If the args include --json, also emit the machine-readable block. If the user asks for the full picture, build the Extended quality report by fetching the deterministic UICraftScore (node scripts/eval.mjs <path> --json or the score_ui MCP tool) and placing both side by side — never average them.
Step 7 — Output. Use the exact scorecard format in references/heuristics.md:
## Heuristic Scorecardtable## Design Law Audittable## Persona Walkthroughtable (only if--persona=was passed)## Top findings (ranked by impact)— numbered list, 3-5 items## UsabilityScoreblock — the 0-100 score + grade + component breakdown
Knob awareness: knob-agnostic. Usability is not a knob — a 2 is a 2 whether CRAFT_LEVEL is 3 or 9. Do not soften scores based on CRAFT_LEVEL.
Output contract:
- This command produces a critique artifact, not code. No edits unless the user explicitly asks in a follow-up.
- The scorecard is machine-parseable markdown. A PM can paste it into any issue tracker and file tickets row-by-row. Frame it that way in any preamble.
- No "First Impressions" paragraph, no hedging, no praise padding. Tables + ranked list only.
Do NOT edit code. This is a scored critique.
Next step: Fix the findings, then /finalize — the scorecard is the input to a gated ship (rung 3).
Polish the UI at $ARGUMENTS. Load the ui-craft skill.
Source of truth: read references/review.md → Polish Pass (Compound Details) section. Apply every item on that list to the target. Do not re-derive the list here — review.md owns it.
Then the signature detail: surfaces built via /craft already carry exactly one signature bet, chosen in the Craft Read and built in the first pass (references/craft-intent.md). Polish verifies it survived and strengthens it — never stacks a second. Only if the surface predates craft-intent (no signature anywhere) do you propose and add one: a subtle motif, an asymmetric layout break, a custom list marker, a distinctive hover — one thing someone would remember.
Knob gating (CRAFT_LEVEL):
≤ 4→ skip the Polish Pass. Ask the user first before running it.5-7→ apply everything on the list, leave the signature as-built unless asked.8+→ apply everything + verify/strengthen the signature detail (add one only if the surface has none).
Output: edit the code directly (polish is implementation, not critique). After each file, print the Review Format table from SKILL.md showing what changed and why. No full diffs — one row per change.
Close every run with a Craft Report (references/review.md → Craft Report). The table above is the per-file diff log; the Craft Report is the run's receipt — Checked / Passed / Changed / Left alone / Verdict. Produce it even when the Polish Pass found nothing to change — that is itself the finding.
Next step: /finalize — the pre-ship gate (rung 3).
Make the UI at $ARGUMENTS quieter. Load the ui-craft skill and read references/craft-intent.md.
Reduce amplitude without gutting hierarchy. Calm ≠ boring.
Apply in order (edit code directly):
- Declare an updated Craft Read — one line: what softened.
- Lower DESIGN_VARIANCE by −1–2 (floor 2). Simplify asymmetric breaks; return to clearer grid rhythm where layout was experimental.
- Lower MOTION_INTENSITY by −1–2 (floor 2). Remove scroll reveals and stagger; keep hover/focus only.
- Visual weight — compress display sizes one step (e.g. 56→48px); reduce shadow depth to hairline or ambient-only; fewer bordered containers.
- Color — pull accent placements toward the 3 minimum; neutralize decorative tints; no new hues.
- Cut decorative motion — idle animations, parallax, floating elements with no job.
Preserve: primary hierarchy, one CTA level, accessibility, states, signature detail only if it carries meaning (else simplify it).
Overlap: for structural cuts (sections, copy), also apply /distill logic. For color strategy, see /colorize.
Output: edit code. Print Review Format table. End with the updated Craft Read line.
Next step: /critique — confirm restraint did not flatten the hierarchy (rung 1).
Redesign $ARGUMENTS. Load the ui-craft skill and read references/craft-intent.md. A redesign is not a greenfield build wearing the old content — most of its value is in what you deliberately keep.
Step 1 — Audit what exists (before any opinion):
- Run the detector on the current source (
npx ui-craft-detect <path>) or live page (npx ui-craft-detect <url>) and note findings. - Inventory: pages/routes, section order, heading hierarchy (h1–h3), nav structure, conversion paths (CTAs and where they lead), forms, imagery assets, fonts, color values actually in use.
- Read
.ui-craft/brief.mdif present — prior constraints still bind.
Step 2 — Classify what to preserve. Wrong-to-change unless the user explicitly asks:
- Brand equity — logo, name, an established palette the business already uses in the wild. Committed brand color stays; you may re-tune tints/shades into a proper token scale.
- IA + SEO — URLs/routes, page set, heading semantics, title/meta, alt text, structured data. A redesign that tanks organic traffic is a failure regardless of how it looks.
- Content + voice — existing copy is data about the business. Restructure freely; rewrite voice only with permission.
- Conversion paths — every CTA and form that exists today exists for a reason. Relocate, restyle, but never silently drop one.
Step 3 — Pick the scope and say it out loud:
| Scope | What changes | When |
|---|---|---|
| Refresh | Tokens only: type scale, spacing rhythm, radii, shadows, color tuning | Site is structurally fine, looks dated |
| Reskin | Visual layer + component styling; layout skeleton and section order stay | Bones are good, skin is generic or old |
| Rebuild | Layout and composition too; content, IA, and brand carry over | Layout itself is the problem |
Default to the smallest scope that fixes the stated complaint. For rebuild, print a short before/after section map and get a nod before writing code.
Step 4 — Declare the Craft Read (surface kind, audience, theme, DESIGN_VARIANCE, signature bet) per references/craft-intent.md. Redesigns default to variance 4–5: the brand is already committed, so spend boldness on typography and composition, not on a new identity.
Step 5 — Modernize with levers, in this order: typography (scale + pairing per references/typography.md) → spacing rhythm → color tokens (references/color.md) → imagery treatment → motion (entrance/hover only where focal). Fix every detector finding from Step 1 along the way.
Never: invent a new brand palette over a committed one, drop routes or pages, flatten heading semantics for looks, rewrite copy voice unasked, or ship the redesign with more detector findings than the original had.
Output: edit code directly (refresh/reskin) or section map first (rebuild). Print the Review Format table, the detector before/after counts, and end with the Craft Read line.
Next step: /critique — check the modernized surface against hierarchy and anti-slop before shipping (rung 1).
Load references/brief.md (sections 6 + Self-Correction) before proceeding.
Step 1: Capture the constraint
From the argument (or the immediately preceding correction in the conversation), capture:
- What changed or is preferred — the concrete rule.
- Why — the reason. Mandatory; without it the constraint can't generalize. If it isn't stated, ask one short question.
- Phrase the rule so a future build can apply it without this conversation's context.
Step 2: Write it to the brief
Append a dated entry to section 6 (Learned constraints) of .ui-craft/brief.md:
- **YYYY-MM-DD** — <the rule>. *Why:* <reason>.
Create the brief (run /brief) or the section 6 heading if absent. If the new constraint contradicts an existing principle or constraint, mark the old one deprecated with a dated reason (brief is append-mostly) rather than deleting it. Never store a rule that breaches the accessibility/correctness floor — record the closest compliant interpretation and say so.
Step 3: Cross-project reach (optional)
If the user signals this should apply to all their projects ("in all my projects", "whenever you work with me"), that's general memory, outside the brief's project scope:
- If an external memory service is available to the agent, mirror the constraint there so other projects inherit it.
- If not, record it in this brief and note that cross-project recall would need such a service.
Step 4: Confirm
Report in one line where it landed and what it changes, e.g.:
Recorded in the brief (learned constraint): never gradients on a hero here.
Next step: Keep working. The constraint now lives in the brief, so every future session reads it (rung 2).
Run the spec-driven design pipeline for $ARGUMENTS. Load the ui-craft skill.
ORCHESTRATE-ONLY RULE
This command sequences existing phase commands. It MUST NOT re-implement or duplicate any logic from them. Every composition rule, wireframe algorithm, craft rule, and convergence engine lives in the phase commands. This command contributes only:
- Gate detection (does the artifact exist?)
- Offer prompts (run phase X or skip?)
- Progress reporting (the checklist)
- Degraded-mode honesty (what was skipped and what that costs)
When in doubt: call the phase command, don't inline its steps.
Progress Checklist
Print this at the start and update it after each gate resolves:
[ ] brief [ ] tokens [ ] shape (spec) [ ] craft (build) [ ] converge [ ] ship
Use [✓] for completed/skipped-with-artifact, [>] for the current gate, [–] for skipped-without-artifact (degraded).
Pipeline Gates
Gate 1 — Brief
Check: does .ui-craft/brief.md exist?
If yes: mark [✓] brief. Note that brief §6 learned constraints and the a11y/correctness floor are in effect for all downstream gates — they take precedence over any spec.md composition choice.
If no: offer to run /brief now.
- User confirms → run
/brief. When it completes, mark[✓] brief. - User declines → mark
[–] brief. Note downstream impact: "no brief → craft will use skill defaults; composition will not be anchored to project principles."
Gate 2 — Tokens
Check: does a token spine exist? (Look for CSS variables --color-*, --font-*, --accent-*, a Tailwind theme.extend with tokens, or a token file.)
If yes: mark [✓] tokens.
If no: offer to run /tokens now.
- User confirms → run
/tokens. When it completes, mark[✓] tokens. - User declines → mark
[–] tokens. Note downstream impact: "no token spine → craft will establish a minimal inline token set; it won't match an existing system."
Gate 3 — Shape (spec)
Existing-surface guard: Before running /shape, check if .ui-craft/spec.md already contains a ## Surface: <name> block for this surface. If it does, do NOT re-run shape and blindly append a duplicate section — offer to update the existing section or skip shape (the spec already exists).
Run /shape for the surface described in $ARGUMENTS. Shape produces its full five-step output (content inventory, ASCII layout, state list, open questions).
Persist in pipeline (default): Inside the /sddesign pipeline, shape's Step 6 spec persist is the default — it is auto-confirmed unless the user explicitly opts out of the spec gate. The persist writes .ui-craft/spec.md (or appends the surface section). This is the whole point of the pipeline.
- Persist completes →
.ui-craft/spec.mdis written (or the surface section is appended). Mark[✓] shape (spec). - User explicitly opts out of persist → mark
[–] shape (spec, unsaved). Note downstream impact: "no spec.md → craft (build) will build against shape's printed output; acceptance bar will not be persisted."
Gate 4 — Craft (build)
Run /craft <surface> where <surface> matches the description in $ARGUMENTS.
/craft declares the Craft Read (references/craft-intent.md) before building — surface kind, audience, theme/accent, DESIGN_VARIANCE, and the one signature bet. The signature bet is built inside this gate, not deferred to converge or polish. If the spec section names a composition, the Craft Read must be consistent with it.
/craft loads .ui-craft/spec.md before building. If [✓] shape (spec) was set, the spec's chosen composition, component inventory, state lattice, and acceptance bar take precedence over recipe defaults — every acceptance bar item from the spec must be green before craft reports done.
If [–] shape (spec, unsaved), craft builds against the shape output printed to the terminal. Note in the checklist.
Mark [✓] craft (build) when the build completes.
Gate 5 — Converge
Run the visual-anti-slop preset from ../skills/ui-craft/references/loops.md. This iterates — evaluate → fix one → re-evaluate — until the zero-critical gate passes or the budget is exhausted (default budget: 3 iterations).
- If the loop gate passes (zero critical findings) → mark
[✓] converge. - If budget exhausted with open findings → mark
[>] converge (open findings). List unresolved findings from the loop report.
Gate 6 — Ship
Run /finalize verdict. Finalize reports READY / NOT READY / BLOCKED based on the 10-pass finish bar and the brief/token gate.
Print the final verdict and the complete resolved checklist:
[✓] brief [✓] tokens [✓] shape (spec) [✓] craft (build) [✓] converge [✓] ship
Degraded-mode honesty. If any gate was marked [–], list them in the ship verdict with their downstream impacts:
"Skipped gates: tokens (skipped) → token spine not validated; shape (spec, unsaved) → acceptance bar not persisted. These gaps reduce the ship verdict's confidence."
Precedence
Brief §6 learned constraints and the a11y/correctness floor take precedence over spec.md composition choices at every gate. If a constraint conflicts with a spec.md decision, the constraint wins — update the spec section to reflect the winning choice and note the brief §6 reference.
Next step: Ship. The pipeline already walked rungs 1 to 3; .ui-craft/spec.md is the record for the next session.
Shape the UI for $ARGUMENTS before writing code. Load the ui-craft skill.
This command produces a shape artifact, not JSX. The point is to force low-fi thinking — content inventory, layout regions, state coverage, open questions — before any component is written. Skipping this step is how generic AI UIs get built: straight to hi-fi, no discovery, every screen looks the same.
Step 1 — Clarify (3-5 questions). Ask the user before shaping. Don't guess. Minimum questions:
- What's the primary user action on this screen? (One verb, one object.)
- What data is visible by default vs hidden behind a click or tab?
- What does success look like — a state, a redirect, a toast?
- Who's the primary user — first-timer, power user, mobile-first?
Step 2 — Content inventory. Bullet list of every piece of content that will appear. Annotate each by priority:
- P0 — must be visible on first paint. Cut it and the screen fails.
- P1 — one click away (tab, accordion, drawer).
- P2 — settings-level; rarely accessed.
Example:
- P0 Headline (one line, the value prop)
- P0 Primary CTA
- P0 Hero chart / metric
- P1 Secondary nav tabs
- P1 Recent activity list
- P2 Export / integrations menu
Step 3 — ASCII layout. Low-fi sketch showing regions. No specific copy, no colors, no font sizes. One desktop variant + one mobile variant. Use box characters:
Desktop
┌──────────────────────────────────────────────┐
│ [logo] [nav] [user] │
├──────────────────────────────────────────────┤
│ ┌────────────────┐ ┌───────────────────┐ │
│ │ Headline + sub │ │ │ │
│ │ │ │ Hero visual │ │
│ │ [Primary CTA] │ │ │ │
│ └────────────────┘ └───────────────────┘ │
│ │
│ ── Social proof row ── │
│ │
│ ┌─── Feature 1 ───┐ ┌─── Feature 2 ───┐ │
│ └─────────────────┘ └─────────────────┘ │
└──────────────────────────────────────────────┘
Mobile
┌──────────────────┐
│ [logo] [☰] │
├──────────────────┤
│ Headline + sub │
│ │
│ [Primary CTA] │
│ │
│ ┌── Hero ──┐ │
│ └──────────┘ │
│ │
│ Social proof │
│ │
│ Feature 1 │
│ Feature 2 │
└──────────────────┘
Asymmetry is fine and often better — don't force center-everything.
Step 4 — State list. Enumerate the states this screen must handle. Point at references/state-design.md for the contracts.
- idle — default state, data present.
- loading — skeletons that mirror final layout, 200ms delay before showing.
- empty — first-run or no data; doubles as onboarding.
- error — specific cause + recovery action + support ID.
- partial — some data loaded, some failed (e.g., one widget erred).
- conflict — user-edit collision (rare but load-bearing on collaborative surfaces).
- offline — queue writes, reconcile on reconnect.
- success — confirmation state after the primary action completes.
Mark each as required / optional (why) / N/A.
Step 5 — Open questions. Do NOT start coding until these are answered. Default set:
- Accent color — brand-defined, or to be chosen? (See Discovery in
SKILL.md.) - Typography — existing tokens, or new system? (Reference
typography.md.) - Responsive breakpoints — what's the minimum supported width?
- Stack — CSS only, or Motion / GSAP / Three.js? (Only load
stack.mdif the user opts in.) - Data source — real API ready, or mock for shape?
- Keyboard / a11y requirements — anything beyond the baseline from
accessibility.md?
Knob awareness.
- At
CRAFT_LEVEL ≥ 7, add two more sections:- Motion shape — which elements enter, in what order, with what stagger. Pick from the duration scale in
references/motion.md. - Typography hierarchy plan — display / headline / body / label sizes and weights, before code.
- Motion shape — which elements enter, in what order, with what stagger. Pick from the duration scale in
- At
CRAFT_LEVEL ≤ 4, strip Step 4 toidle / loading / erroronly. Skip the motion shape.
Step 6 — Offer to persist to .ui-craft/spec.md (opt-in).
After printing all five steps, offer to write the output as a spec section:
"Write this shape to
.ui-craft/spec.mdas## Surface: <name>? (Persists the composition choice, layout, and acceptance bar for the build phase.)"
- User confirms → format the output as a
## Surface: <name>section following the template in../skills/ui-craft/references/spec.md, then write or append to.ui-craft/spec.md. Confirm in one line: "Written to.ui-craft/spec.md→## Surface: <name>." - User declines → do not write any file. The printed output stands. Note: "spec.md not written — the pipeline continues without a persisted acceptance bar."
Print-only is the default when /shape is run standalone. Step 6 is the offer; it does not execute unless the user explicitly confirms.
Output contract.
- Produce a single Markdown block with all five steps, in order. Step 6 is the optional offer that follows.
- Do NOT write JSX, CSS, or component code in this command.
- End the output with: "Ready to build? Review the shape, confirm the open questions, then run
/ui-craft:audit(or use Build mode) once the code exists."
Next step: /craft — build the surface you just wireframed (rung 1).
Orient the user. Load the ui-craft skill, read the current project, and report what ui-craft can do right now for it. This is the front door — most people run it first.
ORCHESTRATE-ONLY RULE
This command detects state and routes. It MUST NOT build, edit, audit, or re-implement any phase logic. It contributes only:
- Project detection (read-only).
- A "what's available now" map across the three usage layers.
- One recommended next step + the command to run for it.
When the user wants to act, hand off to the real command (/brief, /tokens, /sddesign, /craft, /finalize, the review agents, etc.). Do not inline their steps.
Step 1 — Detect (read-only)
Scan the project. Do not write anything. Gather:
| Signal | How to detect | Used for |
|---|---|---|
| Framework / styling | package.json deps, config files, file extensions — Tailwind, CSS Modules, styled-components/Emotion, vanilla CSS, Vue/Svelte/Astro SFC | Confirm ui-craft adapts to this stack |
| Token spine | CSS vars (--color-*, --accent-*, --font-*), Tailwind theme.extend, a token file | Gate: is /tokens needed? |
| Brief | .ui-craft/brief.md exists? | Gate: is /brief needed? |
| External design contract | DESIGN.md or design-tokens.json at repo root (ecosystem convention some teams use) | Treat as brief + token input — read it, honor it, don't duplicate it |
| Spec | .ui-craft/spec.md exists? which surfaces? | Is there work in flight? |
| Harness | Claude Code (plugin/skill) vs .codex/.cursor/.gemini/.opencode/.agents mirror | Which layers are reachable (agents/MCP are Claude Code / MCP-client only) |
| Existing UI | are there components/pages already, or is this greenfield? | Build-new vs review/polish framing |
Keep detection fast and quiet — a few reads, no deep traversal. Report findings as a short table.
Step 2 — Report the three layers
Print what's available now, mapped to how people actually use ui-craft. Mark each layer ● active / ○ available / – not reachable in this harness.
ui-craft is a design engineering SYSTEM. You're set up for:
● Layer 1 — Just ask
Describe any UI and the agent designs with taste (anti-slop, system tokens,
real hierarchy). No command needed. This is the default and the point.
○ Layer 2 — Drive it
Slash commands for focused passes. Given THIS project:
<tailored list — see Step 3>
○ Layer 3 — Verify it
design-reviewer + a11y-auditor agents · ui-craft-mcp gates · UICraftScore · ui-craft-detect CLI.
<mark – if the harness can't reach agents/MCP, and say so>
Tailor the bullets to the detected state — don't print the generic catalog.
Step 3 — Recommend ONE next step
Pick the single highest-value next action from detected state. Use this decision order:
- No brief, non-trivial project → recommend
/brief("anchor every later decision to your product's principles — 5 min, writes.ui-craft/brief.md"). - Brief exists, no token spine → recommend
/tokens("establish the 3-layer token spine so builds match a system, not inline guesses"). - Brief + tokens exist, building something net-new → recommend
/sddesign <surface>(full pipeline) or/craft <surface>(one-shot) — ask which. - Existing UI to improve → route by intent: review →
ui-craft:design-reviewer+ui-craft:a11y-auditor(Claude Code) or/critique+/audit; polish →/polish; simplify →/distill; flat/generic →/bolder; loud/busy →/quieter; dated site to modernize →/redesign. - About to ship / merge → recommend
/finalize(10-pass gate) and, for CI,npx ui-craft-detector thescore_uiMCP tool.
Print it as one clear line:
Recommended next:
…— .
Then offer the full menu only if asked: "Want the full command list, or shall I run that now?"
Step 4 — Hand off
If the user confirms, run the recommended command. Otherwise stop — /start never acts on its own. Its job is done once the user knows where they are and where to go.
Notes
- Read-only.
/startwrites nothing and changes no code. The artifacts (brief.md,spec.md, tokens) are written by their own commands. - Harness honesty. If the project is in a non-Claude-Code harness (
.codex,.cursor, etc.), Layer 3 agents and the MCP server may not be reachable from that agent — say so plainly and point to the CLI (ui-craft-detect) as the portable verify path. - Craft-intent routing. Full-surface builds (
/craft,/sddesign) declare a Craft Read before code. If the user describes a built UI as "generic", "template-y", or "too safe", route to/bolder; if "too loud" or "too busy", route to/quieter. - Don't re-run Discovery. If a brief or spec already exists, don't interrogate the user for preferences — read the artifacts and report.
Next step: Follow the rung this run named. /start is read-only — the value is in doing the one command it picked.
Read references/tokens.md before proceeding. The 3-layer contract (primitive → semantic → component) and the intentional-dark test are defined there.
Step 1: Detect existing tokens
Scan for token definitions in the project:
- CSS variables in
:root,[data-theme],[data-mode], or theme wrapper selectors - Tailwind config (
tailwind.config.js/ts) undertheme.extendortheme - CSS-in-JS theme objects (
theme.ts,*.styles.ts,styled.d.ts,ThemeProvider) design-tokens.jsonortokens.json(Style Dictionary / Theo)globals.css,variables.css,tokens.css
Build an inventory: which of the 7 categories exist (color / spacing / type / radii / shadows / motion / z-index), which layers are present (primitive / semantic / component), and whether both light and dark are defined.
Step 2: Route based on $ARGUMENTS and inventory
- "audit" → run audit only (Step 3). No proposals.
- "establish" → skip audit, go to Step 4.
- "color" / "spacing" / "type" / "radii" / "shadows" / "motion" / "z-index" → focus the audit and any proposal on that one category.
- empty → if tokens exist: audit. If nothing found: establish.
Step 3: Audit (tokens exist)
Evaluate against the contract in references/tokens.md. Output a severity-ranked gap list — don't propose code yet.
Check:
- 3-layer coverage — are primitive, semantic, and component layers all present? Missing semantics is the most common gap: primitives exist but nothing switches for dark mode and no surface stack is defined.
- 7-category coverage — any of (color / spacing / type / radii / shadows / motion / z-index) missing? Flag each absent category.
- Intentional dark mode — run the intentional-dark test: does dark mode do more than invert
--text-primary? Is--surface-canvasa tinted near-black (not#000)? Is accent chroma reduced 10-15%? Are shadows replaced with border rings? - Naming discipline — are primitives named for values (
--gray-500) not roles (--button-bg)? Are semantics named for roles (--text-primary) not values (--gray-900-text)? - No arbitrary values — inline colors, spacing, or z-index values that bypass the token system.
Output format:
| Severity | Category | Finding |
|---|---|---|
| Critical | Dark mode | --surface-canvas is #000 — runs the intentional-dark test |
| High | Semantics | No surface stack — components use raw primitives |
| Medium | Shadows | Single-layer shadows — ambient layer missing |
| Low | Z-index | Arbitrary values (z-index: 999) in 3 components |
Show what's missing. Do not propose code during audit unless the user asks.
Step 3b — Converge mode (explicit opt-in)
Load skills/ui-craft/references/loops.md preset token-consistency (budget = the default loop budget defined in loops.md). Emit the pre-flight cost notice. After fixing the top off-system value (raw hex color, arbitrary radius, or magic spacing), re-scan until zero off-system values or budget exhausted.
Step 4: Establish (no tokens found)
Propose a minimal spine inline. Cover all 7 categories. Always include both light and dark blocks — both intentional.
Minimal spine order:
- Primitives — neutral ramp (gray-50 to gray-950), one accent ramp, semantic color bases, spacing scale, type scale, radii, shadows, motion, z-index.
- Semantics — surface stack (5 levels), text roles, border roles, accent roles, status roles (success / warning / error / info).
- Component tokens — defer unless a specific component is already being built.
Use OKLCH for color unless the project uses sRGB across the board — in that case flag the gap, propose OKLCH, but don't auto-convert.
Before writing to a file, ask which file to write to. Detect from project structure and suggest one:
- Tailwind project →
globals.css(CSS variables inside:root) - CSS-in-JS →
theme.ts(exported theme object) - Vanilla CSS →
tokens.css(standalone variables file) - Cross-platform / multi-consumer →
design-tokens.json(Style Dictionary format)
Confirm with the user before writing.
Step 5: Never overwrite
If the project has an existing token file, propose additions as patches — show what would change in a diff block:
:root {
+ /* ── Semantic surface stack (new) ── */
+ --surface-canvas: var(--gray-50);
+ --surface-raised: var(--gray-100);
+ --surface-overlay: #fff;
+ --surface-sunken: var(--gray-200);
+ --surface-inverse: var(--gray-900);
}
Let the user apply. Don't write directly unless they approve.
Constraints
- Don't impose Tailwind on a vanilla CSS project. Match the project's existing syntax.
- Don't impose OKLCH if the project uses sRGB consistently — flag it, suggest migration, don't force it.
- Respect existing naming conventions — if the project uses
--color-primaryover--accent-500, extend that pattern rather than introducing a parallel naming scheme.
Next step: /craft — build on the spine you just established (rung 1).
Typeset the UI at $ARGUMENTS. Load the ui-craft skill and read references/typography.md.
Note: typeset is knob-agnostic — typography rules (no ALL CAPS on headings, tracking-tight ≥24px, one body font, etc.) are not tunable.
Apply, in order:
-
Font inventory — what's loaded? If Inter is the default choice with no reason, ask before accepting it (Inter is the #1 AI-tell). Good alternatives: Geist, DM Sans, Plus Jakarta Sans, system stack. One body font, optionally one display font. Never three.
-
Scale — is there a scale or are sizes ad hoc? Anchor to a modular scale (1.125 / 1.2 / 1.25). Sizes: 12 / 14 / 16 / 20 / 24 / 32 / 48 / 64 / 72. No 13px / 15px / 17px one-offs unless optical.
-
Tracking (letter-spacing):
- ≥ 24px →
tracking-tight(-0.02em) or tighter for 40px+ - 14-20px body → default
- 11-13px category labels →
tracking-wide(+0.06em) + uppercase IS allowed here (the one exception) - Never ALL CAPS on headings, nav, buttons, tables
- ≥ 24px →
-
Leading (line-height):
- Headings: 1.05-1.15
- Body: 1.5-1.65
- UI (buttons, labels): 1.2-1.3
-
Weight hierarchy — pick 2-3 weights max. Common: 400 body, 500 UI/labels, 600-700 headings. Never load 9 weights "just in case".
-
Micro-typography (the compound details):
tabular-numson every number you align (tables, stats, timestamps, prices)text-wrap: balanceon headlines,text-wrap: prettyon body- Curly quotes (
'/"), em dashes (—), en dashes (–), no double hyphens in brand names, between number + unit, and before final short words in headlines- Real apostrophes in contractions
font-feature-settingsorfont-variant-*for opt-in features (ligatures, ss01, fractions)- Straight prime marks (
′,″) for units, not quotes
-
Hierarchy check — can you tell primary / secondary / tertiary at a glance? If every line has the same weight or size, collapse or amplify.
Amplifying hierarchy
If the UI is technically correct but forgettable, use typography as the weapon. Pick ONE element to carry signature (never two); boldness is typography, not color or decoration:
- Hero headline — push size to 80-120px, weight to 700-800, tracking to -0.04em. Tight leading (0.95-1.0).
- Hierarchy jump — widen the gap between H1 and body. If H1 is 32px and body is 16px, the UI is whispering; if H1 is 48px+, the ratio reads. Compress or expand the range deliberately.
- Micro-motif — one custom detail that repeats: a hand-drawn underline, numeric counters (
01,02), an asymmetric supporting element, a distinctive list marker.
Knob gating for amplification (CRAFT_LEVEL):
≤ 4— skip. Boldness is a craft layer, not a baseline.5-7— apply the type amplification only. No signature motif unless asked.8+— type amplification + one signature detail (chosen at/craftfirst pass perreferences/craft-intent.md;/polishand/bolderstrengthen it — never stack a second).
Pre-check: if an accent is already overused or hierarchy is already loud, you don't have a tameness problem — you have a noise problem. Route to /distill (cut) or /colorize (reduce accents) instead.
Output: edit code directly. Print the Review Format table. Call out the single highest-impact change (usually: "font choice" or "tracking-tight on hero").
Next step: /polish — micro-details land best right after the type system is set (rung 1).
Design every non-happy state for the UI at $ARGUMENTS. Load the ui-craft skill and read references/state-design.md.
Step 1 — Inventory. List every data source and interactive surface in the target. For each, enumerate its states:
| Surface | idle | loading | empty | error | partial | conflict | offline |
|---|
Mark each cell as designed (exists in code), missing (must add), or N/A (not applicable — e.g., a read-only view has no conflict state).
Step 2 — Fill the missing states. For each missing state, either stub it inline or add a follow-up task comment. Use references/state-design.md for:
- Skeleton sizing (match final layout, 200ms delay, 5s upper bound)
- Empty-state copy (why empty + next action + visual)
- Error-state contract (specific cause + one-click recovery + support ID)
- Offline handling (queue writes + reconcile on reconnect)
Step 3 — Audit the happy path. Flag every spot where the happy path assumes resource presence without checking. Fix with early-returns, state guards, or discriminated-union state handling. Booleans like isLoading && !error && data that allow impossible states are findings — refactor to a proper state machine or reducer.
Step 4 — Optimistic UI + reconciliation. For offline-likely actions (saves, sends, edits, toggles), implement optimistic UI with reconciliation on reconnect. Queue writes locally. Surface any rejected writes — never swallow them.
Knob gating (CRAFT_LEVEL):
| CRAFT_LEVEL | Required states to stub |
|---|---|
| ≤ 4 | idle, loading, error |
| 5-7 | idle, loading, empty, error, success |
| 8+ | all six — add partial, conflict, offline |
If CRAFT_LEVEL is unknown, default to 7.
Convergence note: To iterate until all required states are present, load skills/ui-craft/references/loops.md and run preset state-coverage (budget = the default loop budget defined in loops.md): after stubbing the highest-priority missing required state, re-inventory until all knob-required states are present or budget exhausted. Emit the pre-flight cost notice before iteration 1.
Output: edit the code directly. After each file, print the Review Format table from SKILL.md:
| Before | After | Why |
|---|---|---|
no loading state on <ProjectList> | skeleton rows matching final layout, 200ms delay | prevents "is it broken?" perception; avoids CLS |
| generic "Error" toast | inline error with specific cause + retry + support ID | recoverability (heuristic 9) |
One row per state added. No full diffs.
Next step: /harden — implement the states you just designed (rung 1).
Agents 2
You are a read-only accessibility auditor. You are part of a parallel verify team — your counterpart is ui-craft:design-reviewer. Both agents run independently on the same target; neither depends on the other's output.
Role
Accessibility audit with an a11y lens. Your job is to find what violates or risks accessibility, not to fix it. You make NO edits and use NO write tools.
On load — read this reference in full before auditing
In the ui-craft plugin these paths are relative to the plugin root. After a CLI install they are relative to your Claude Code config: ~/.claude/ (or $CLAUDE_CONFIG_DIR) for a global install, .claude/ in the project for a project install.
skills/ui-craft/references/accessibility.md— WAI-ARIA, keyboard navigation, focus management, touch targets, APCA contrast, reduced-motion, and WCAG criteria
Do NOT restate the rules from this reference in your output. The reference is the authority; point to it by name if relevant.
Audit lens
Apply every accessibility axis defined in skills/ui-craft/references/accessibility.md exactly as written there — keyboard, focus-visible, contrast (APCA), ARIA, touch targets, reduced-motion. Do not restate, filter, or add thresholds here; the reference is the single source of truth.
Output contract
Return a severity-tagged findings table. No fixes. No edits. No code changes.
| Severity | Finding | Location |
|---|---|---|
| Critical | … | file:line |
| Warning | … | file:line |
| Suggestion | … | file:line |
Severity definitions:
- Critical — WCAG 2.1 AA or APCA failure, keyboard trap, missing essential ARIA, focus not visible; blocks a user from completing a task
- Warning — best-practice violation, borderline contrast, missing enhancement (e.g., reduced-motion not covered); degrades experience for affected users
- Suggestion — exceeds minimum bar; WCAG AAA opportunity, enhanced ARIA, or motion polish for reduced-motion users
If a target is clean, return an empty table with a one-line note. Do not manufacture findings.
Constraints
- Read, Grep, Glob only — no Edit, no Write
- Do not suggest code fixes inline
- Do not restate reference rules — cite the loaded reference by name if needed
- If asked to apply a fix, decline and record the request as a Critical finding: "Caller requested edit — agent is read-only"
You are a read-only design reviewer. You are part of a parallel verify team — your counterpart is ui-craft:a11y-auditor. Both agents run independently on the same target; neither depends on the other's output.
Role
Adversarial design critique. Your job is to find what is wrong, not to fix it. You make NO edits and use NO write tools.
On load — read these references in full before reviewing
In the ui-craft plugin these paths are relative to the plugin root. After a CLI install they are relative to your Claude Code config: ~/.claude/ (or $CLAUDE_CONFIG_DIR) for a global install, .claude/ in the project for a project install.
skills/ui-craft/references/review.md— systematic critique methodology, feedback hierarchy, anti-slop detection, Polish Passskills/ui-craft/SKILL.mdsections The Anti-Slop Test and The Craft Test — the critical/major/minor slop signals and what craft aims forskills/ui-craft/references/heuristics.md— Nielsen's 10 heuristics + Fitts/Hick/Doherty/Cleveland-McGill/Miller/Tesler, scoring rubric, impact framing
Do NOT restate the rules from these references in your output. The references are the authority; point to them by name if relevant.
Output contract
Return a severity-tagged findings table. No fixes. No edits. No code changes.
| Severity | Finding | Location |
|---|---|---|
| Critical | … | file:line |
| Warning | … | file:line |
| Suggestion | … | file:line |
Severity definitions:
- Critical — immediately reads as AI-generated, blocks design quality, or fails a core heuristic (e.g., slop signals from the Anti-Slop Test, Value-layer failures from review.md)
- Warning — designers will notice; degrades polish or usability (Major signals, heuristic violations)
- Suggestion — polish that separates good from great (Minor signals, Craft Test opportunities)
If a target is clean, return an empty table with a one-line note. Do not manufacture findings.
Constraints
- Read, Grep, Glob only — no Edit, no Write
- Do not suggest code fixes inline
- Do not restate reference rules — cite the loaded reference by name if needed
- If asked to apply a fix, decline and record the request as a Critical finding: "Caller requested edit — agent is read-only"
Hooks 1
MCP servers 1
Sponsors
Details
- Marketplace
- educlopez/ui-craft
- Category
- Community
- License
- MIT
- Keywords
- ui, design, accessibility, css, frontend, design-system, anti-slop