Skill anatomy

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.

This page is engine internals. You do not need it to use UI Craft — the four rungs in Getting started are the whole user-facing model. Read on if you want to know how a decision gets made.

Three files, not three rungs

Careful: this is the file structure, not the ladder. The rungs describe what you get; these are the files the agent reads to deliver it.

1. Main skill — skills/ui-craft/SKILL.md. ~36 KB. Dials, Discovery phase, anti-slop rules, the routing table, and the few always-needed rules.
2. References — skills/ui-craft/references/*.md. 34 domain files. Loaded on demand based on intent.
3. Commands — commands/*.md. 25 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, 7 MCP tools, a deterministic design-quality score, and a cross-harness CLI installer.

The main skill

SKILL.md is deliberately scoped — ~36 KB, against 34 references it can pull in on demand. Always-needed rules stay in SKILL.md. Depth lives in references. The file contains:

• Knobs block (CRAFT_LEVEL, MOTION_INTENSITY, VISUAL_DENSITY, DESIGN_VARIANCE)
• Discovery phase (4 questions)
• Reference tiers — what always loads, and what waits for a trigger
• Anti-slop list (the checklist applied to every UI)
• Routing table (intent → reference file)

Which references load, and when

Two references always load before a full-surface build: craft-intent.md, and the recipe for the surface being built (recipe-dashboard.md, recipe-landing.md, recipe-auth.md). Everything else states the trigger that pulls it in — a brief when .ui-craft/brief.md exists, accessibility.md for forms and custom controls, color.md for palette work, layout.md for composing from scratch.

That list used to be seven references labelled “required before writing UI”. Agent-backed build evals measured what a passing build actually opens: a dashboard opened one of the seven, a landing opened two, and both reached for the surface recipe that was filed a tier below. A required list nobody reads is not a standard — and an unreliable label discredits the entries that matter alongside the ones that do not. So the always-load list now names what carries a build, and the rest are honest about being conditional.

Nothing was removed. The measurement shows the label was not causing loads; it does not show the references are unnecessary.

There is no mode enum to learn. What used to be described as “modes” is just the routing table doing its job at rung 0: a prompt arrives, the table decides which references to load and which pass to run.

Read on GitHub →

The 34 domains

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

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:

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

The 25 commands

Focused passes. Each loads a single lens. Grouped by rung, because the rung tells you what a command costs before you read what it does — full reference in Commands:

• Front door — start
• Rung 1 · Direct — craft, shape, redesign, animate, adapt, typeset, colorize, clarify, distill, delight, polish, bolder, quieter, extract, critique, heuristic, audit, unhappy, harden
• Rung 2 · Persist — brief, tokens, remember
• Rung 3 · Enforce — finalize
• Express lane — sddesign (walks rungs 1 to 3 in one run)

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-mirrors.mjs (npm run sync) and committed to the repo so npx skills add installs the right tree for each harness. Note that this path installs the skill only — no MCP gates, review agents, or hooks; see Getting started for the full-system installer. CI does not regenerate them — scripts/check-mirror-copies.mjs fails the build if a mirror drifts from its canonical source, so run the sync before pushing.

npm run sync
# then verify
npm run check:mirrors

More in the README →

File layout

ui-craft/
  skills/
    ui-craft/
      SKILL.md                     # slim entry point (~33 KB)
      references/                  # 34 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/                        # 25 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-mirrors.mjs               # mirror generator
    check-mirror-copies.mjs        # mirror drift guard (CI)
    validate.mjs                   # manifest + frontmatter validator

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