Skill anatomy

How UI Craft is structured — the main skill, its 31 domain references, the 22 slash commands, and the 3 style variants.

Updated 2026-06-26

UI Craft is not one long file. It is a slim entry point plus a routing table pointing to depth references — so agents only load the knowledge they need for the current task.

Three layers

Main skill — skills/ui-craft/SKILL.md. ~16 KB. Knobs, Discovery phase, anti-slop rules, the routing table, and the few always-needed rules.
References — skills/ui-craft/references/*.md. 31 domain files. Loaded on demand based on intent.
Commands — commands/*.md. 22 focused passes that apply a single lens from the skill.

Plus 3 sibling variants — pre-committed styles that lock the knobs. See Style variants. Playful and brutalist ship as style presets under examples/presets/, not full siblings.

The skill is the install format, not the ceiling. The same system also ships 2 read-only review agents, 4 MCP quality gates, a deterministic design-quality score, and a cross-harness CLI installer.

The main skill

SKILL.md is deliberately scoped. ~16 KB after v0.16/v0.17 (judgment layer + tiered routing + decision spine integration). Always-needed rules stay in SKILL.md. Depth lives in references. The file contains:

Knobs block (CRAFT_LEVEL, MOTION_INTENSITY, VISUAL_DENSITY)
Discovery phase (4 questions)
Anti-slop list (the checklist applied to every UI)
Routing table (intent → reference file)
Four modes: Build, Animate, Review, Polish

Read on GitHub →

The 31 domains

Each domain is one file. Agents load them based on intent.

Domain	File	Covers
Motion	`motion.md`	Decision ladder, duration + easing token scales, interaction rules, choreography, motion budget, reduced-motion contract. Rendering performance (compositor pipeline, FLIP, scroll timelines, will-change lifecycle, blur cost)
Layout	`layout.md`	Spacing systems, optical alignment, layered shadows, visual hierarchy
Typography	`typography.md`	`text-wrap: balance`, tabular-nums, font scale, curly quotes
Color	`color.md`	OKLCH, design tokens, dark mode, APCA contrast
Accessibility	`accessibility.md`	WAI-ARIA, keyboard nav, focus management, touch targets
Modern CSS	`modern-css.md`	View Transitions, Anchor Positioning, Popover, `<dialog>`, `interpolate-size`, `color-mix()`, scroll-driven, container queries
Responsive	`responsive.md`	Fluid sizing, mobile-first, touch zones, safe areas
Sound	`sound.md`	Web Audio API, feedback sounds, appropriateness matrix
UX Copy	`copy.md`	Voice / tone matrix, reading level, terminology, locale-aware strings, inclusive language, error / empty / CTA tactics
UI Review	`review.md`	Systematic critique methodology, anti-slop detection, Polish Pass
Dashboard	`dashboard.md`	Signal-to-noise hierarchy (hero / supporting / context / deep-dive), sidebar, metric cards, data tables
Inspiration	`inspiration.md`	Pattern archetypes and signature details from observed mature SaaS
Stack	`stack.md`	Motion, GSAP, Three.js — decision tree, patterns, perf gotchas, anti-patterns (opt-in)
Heuristics	`heuristics.md`	Nielsen’s 10 + Fitts / Hick / Doherty / Cleveland-McGill / Miller / Tesler with 1–5 scoring rubric and impact framing
Personas	`personas.md`	5 archetypes (first-timer, power user, low-bandwidth, screen-reader, one-thumb) with walkthrough checklists
State design	`state-design.md`	Idle / loading / empty / error / partial / conflict / offline — design the unhappy path first
Data viz	`dataviz.md`	Cleveland-McGill perceptual hierarchy, chart selection matrix, ColorBrewer + Okabe-Ito palettes, direct labeling, Tufte
AI / chat surfaces	`ai-chat.md`	Streaming contract, 7-state model, tool traces, citations, feedback affordances, generative UI, conversation layout
Forms	`forms.md`	Validation timing, progressive disclosure, multi-step wizards, autosave, optimistic submit, field-specific patterns
Brief	`brief.md`	Durable design brief format — product purpose, primary user, 3-5 ranked principles, success metric, out of scope. Persists at `.ui-craft/brief.md` across sessions
Tokens	`tokens.md`	3-layer token spine (primitive → semantic → component). Both light and dark intentionally crafted, not just inverted. 7 required categories
Finish bar	`finish-bar.md`	10-pass finishing protocol with measurable criteria. Hierarchy / type system / surface stack / spacing rhythm / iconography / state coverage / motion / microcopy / pixel honesty / data formatting
Principles catalog	`principles-catalog.md`	42 example design principles across 8 product categories. Seed material for the `/brief` workshop
Components	`components.md`	Component contracts — props, states, slots, accessibility surface for the recurring UI primitives
Themes	`themes.md`	Ready-made theme presets layered on the token spine — light/dark crafted per theme
Spec	`spec.md`	The `.ui-craft/spec.md` artifact — per-surface composition, layout skeleton, component inventory, state lattice, acceptance bar. Written by `/sddesign` and `/shape`
Loops	`loops.md`	The loop engine — iterate-until-converged contract + presets (`visual-anti-slop`, `state-coverage`, `token-consistency`) wired into `/finalize`, `/unhappy`, `/tokens`
Agents	`agents.md`	The two-agent verify team — `design-reviewer` + `a11y-auditor`. Agent-vs-command guidance and the parallel verify pattern. See Design agents
Recipe — Dashboard	`recipe-dashboard.md`	Full build contract for a SaaS dashboard — composition, build order, acceptance bar. Loaded by `/craft dashboard`
Recipe — Landing	`recipe-landing.md`	Full build contract for a landing page. Loaded by `/craft landing`
Recipe — Auth	`recipe-auth.md`	Full build contract for sign-in / sign-up / reset surfaces. Loaded by `/craft auth`

Stack is opt-in

stack.md is the only reference that is not loaded by default. It only loads when:

MOTION_INTENSITY ≥ 8, and
The user opted into Motion / GSAP / Three.js during Discovery

This is deliberate. The file is large. Loading it for a static button animation would be noise.

The routing table

SKILL.md contains a routing table that maps user intent to reference files. Agents match the intent and load only the relevant files. Examples:

User intent	Loads
“Build a pricing page”	`layout.md`, `typography.md`, `color.md`, `responsive.md`, `copy.md`
“Audit this component”	`accessibility.md`, `motion.md`, `responsive.md`, `review.md`
“Animate this modal”	`motion.md`, `accessibility.md`
“Build a dashboard”	`layout.md`, `dashboard.md`, `typography.md`, `responsive.md`, `state-design.md`
“Polish this page”	`review.md`, `typography.md`, `layout.md`, `motion.md`

Agents never load all 31 references at once. That defeats the point of progressive disclosure.

The 22 commands

Focused passes. Each command loads a single lens. See Commands for the full reference. They are grouped by intent:

Start here — start
Outcome recipes — craft, sddesign
Decision spine & finalize — brief, tokens, finalize, remember
Review & ship — heuristic, audit, critique, polish, harden, unhappy
Plan & transform — shape, animate, adapt, typeset, colorize, clarify, extract
Taste dial — distill, delight

Only Claude Code understands slash commands natively. In other harnesses they are materialized as peer sub-skills with their own name + description frontmatter. Same content, different invocation surface.

Harness mirrors

Source of truth: skills/ui-craft/ + commands/. Never edit .codex/, .cursor/, .gemini/, .opencode/, or .agents/ directly.

The mirrors are generated by scripts/sync-harnesses.mjs and committed to the repo so npx skills add installs the right tree for each harness. CI re-runs the sync on every push to main.

node scripts/sync-harnesses.mjs
# or
npm run sync

File layout

ui-craft/
  skills/
    ui-craft/
      SKILL.md                     # slim entry point (~16 KB)
      references/                  # 31 domain files
        accessibility.md
        agents.md                  # the design-reviewer + a11y-auditor verify team
        ai-chat.md
        brief.md
        color.md
        components.md              # component contracts
        copy.md                    # voice/tone + microcopy (unified)
        dashboard.md
        dataviz.md
        finish-bar.md
        forms.md
        heuristics.md
        inspiration.md
        layout.md
        loops.md                   # iterate-until-converged loop engine
        modern-css.md
        motion.md                  # unified motion + rendering performance reference
        personas.md
        principles-catalog.md
        recipe-auth.md
        recipe-dashboard.md
        recipe-landing.md
        responsive.md
        review.md
        sound.md
        spec.md                    # the .ui-craft/spec.md artifact
        stack.md
        state-design.md
        themes.md
        tokens.md
        typography.md
    ui-craft-minimal/SKILL.md
    ui-craft-editorial/SKILL.md
    ui-craft-dense-dashboard/SKILL.md
  agents/                          # 2 read-only review agents (Claude Code + OpenCode)
    design-reviewer.md
    a11y-auditor.md
  mcp/                             # ui-craft-mcp — 4 deterministic quality gates
  cli/                             # ui-craft — cross-harness Go installer
  commands/                        # 22 source-of-truth slash commands
  examples/
    animation-storyboard.md        # multi-stage animation pattern
    presets/
      playful.md                   # Clay / Gumroad / Duolingo / Arc preset
      brutalist.md                 # Swiss print / Nothing / terminal preset
  scripts/
    detect.mjs                     # anti-slop detector
    sync-harnesses.mjs             # mirror generator
    validate.mjs                   # manifest + frontmatter validator

Spotted something out of date? Open an issue on GitHub →