Docs.

Install

npx design-fleet init                  # Cursor (default)
npx design-fleet init --target=claude  # Claude Code
npx design-fleet init --target=both    # Both

Both targets are first-class. Cursor gets native .mdc rules (globs + alwaysApply); Claude Code gets converted rules with paths: scoping — the always-on pair loads at launch and is designed to survive compaction. On your next UI edit the agent runs a one-time onboarding to learn your taste, then loads the right rule and skill for whatever you're building.

Starting from scratch — or mid-project

Either way, the first thing the fleet wants is your taste profile. The always-on design-intent rule checks for one before any UI work; if none exists it invokes design-contract, which asks permission and then runs a short structured conversation — about 12 questions on aesthetic direction, color mode, density, motion, 2–3 reference products, anti-references, and fonts. The answers become design-taste, the profile every later decision runs through. It runs once per project (or once per user, as a personal profile), and you can decline, or regenerate it later with /design-contract.

From scratch

With no UI code yet, draft mode skips code extraction and interviews you instead. The contract still ships whole: the code-derived tables — tokens, spacing, timings, canonical examples — keep their placeholders and fill in as the project grows, and reconcile tracks the gap. The lint's 10 generic checks apply from the first commit, so your first components are born on the rails. The loop: setup → build → review.

Mid-project

On an existing codebase, onboarding also scans what's already there — fonts in use, color variables, spacing patterns — and records it in the profile as Current Project DNA, so the agent extends your system instead of fighting it. From there, assess audits the design surface (global styles, theme config, tokens, the component library), rates each dimension Solid / Partial / Missing, and hands you a prioritized migration report; draft then pre-fills the contract's tables from what the code actually shows and interviews you only for what code can't reveal — 5–7 questions, and it never invents a literal to make a table look complete. The loop: assess → draft → build → review.

Existing design debt doesn't ambush you. lint [path] checks only the path you point it at, tokens declared in VISION.md suppress the generic checks' false positives, and the edit-time hook blocks new violations only. Migrate in the order the assess report gives you, not in one big bang.

What gets installed

10 rules, 4 skills, and a routing manifest. Two rules are always on — design-intent (the pre-build checklist and Reuse Gate) and ux-writing; eight activate on demand when the agent works in their domain. The four skills are agent roles: design-contract keeps design truth, frontend-design builds inside the rails and owns motion, design-review evaluates on two altitudes, and animation-vocabulary turns “the bouncy popover thing” into the exact term to prompt with.

On Cursor each skill also gets an agent-requested rule and a /-command — use /design-contract, /frontend-design, /design-review, /animation-vocabulary when you want a skill deterministically. On Claude Code the skills are native.

Update & uninstall

npx design-fleet update              # refresh to latest (keeps VISION pointers wired)
npx design-fleet uninstall --dry-run # preview what would be removed
npx design-fleet uninstall           # remove; never touches VISION.md

Add --keep-generated to uninstall to preserve your taste profile across reinstalls. The CLI never overwrites or deletes an existing VISION.md — the contract is yours.

The three layers

Precedence when they disagree: VISION.md > design-taste > package defaults. The contract wins wherever it speaks; the package fills its silences (accessibility floors, reduced motion, contrast math). Scaffold and wire the contract with npx design-fleet vision --wire, or run the design-contract skill in draft mode for a guided, filled one.

What the context costs

Rules are context your agent carries; nobody else in this category prints the bill. The always-on tax is ~2.7k tokens per edit (design-intent ~1.8k + ux-writing ~0.9k) — and it buys the two highest-measured behaviors; design-intent alone is the strongest rule at +45pp. Scoped rules load only when their files are touched; skills only when invoked; a wired VISION.md costs its own size on every edit, by design — hard rails don't work part-time. If the trade isn't right for your project, delete either always-on rule; the lint floor still enforces the contract in CI.

The deterministic lint — 10 checks

npx design-fleet lint [path]   # exit 1 on violations — CI-ready

V8, V9, A6 and C4 are the AI-tell tier, new in 7.0 — each was admitted through the same measured gate as everything else. See them fire on the examples.

Vision-aware checks

With a VISION.md at the project root, the lint parses the contract's tables and enforces project-exact rules: token literals must be in the token map (P1), error copy must match the phrasing table verbatim (P5), animation durations must be on the declared allowlist (P7 — catches CSS time literals, framer-style duration: numbers, and Tailwind duration-N utilities), and canonical example paths must exist (P12). Declared tokens suppress the generic checks' false positives — reported, never silent.

The edit-time hook

Experimental, opt-in, Claude Code only: a PreToolUse hook runs the same ten checks against proposed file content and blocks writes that would introduce new violations (exit 2, with the findings listed). Pre-existing debt never blocks an unrelated edit. It fails open on every error path — a broken hook can never block your work — and a loop-breaker downgrades the third identical denial to a warning so the agent can't wedge.

node node_modules/design-fleet/bin/hook.mjs --install   # prints the settings snippet

The goals loop

Feedback lands in FEEDBACK.md. The design-contract skill (plan mode) distills it into proposed goals — checkable statements, not vibes, with a flip test that catches features disguised as outcomes. You promote them to active; agents build to the contract; npx design-fleet verify machine-checks every goal's recipe and exits 1 the day a met goal quietly regresses. The patchboard plays these scenarios live.

Reuse over reinvention

The always-on Reuse Gate (in design-intent) makes the agent search how the codebase already solves a problem — by the problem, not the feature name — before writing anything new. npx design-fleet inventory generates COMPONENTS.md, the index the gate searches; it's generated, so it never goes stale by hand.

How routing works

npx design-fleet route "your query here"

Real agents pick a skill from each skill's description field — that's probabilistic by nature. The skill-manifest.json documents triggers and boundaries so you can reason about it, and route previews the scoring locally: trigger matches per skill, with frontend-design as the fallback below a confidence threshold of 2.0. Try it interactively on the system page.

CLI

Add --target=claude or --target=both to any install-shaped command; --global operates on the user-level install.

Honest limitations

• Skill invocation is probabilistic. Editors decide which skill matches; use route to preview. Pointers are context, not enforcement — the lint loop and the edit-time hook are the backstops.
• The lint covers what regex can reach. Everything judgment-shaped stays with the LLM-judged critique — which may only gate once calibrated.
• A filled VISION.md costs ~4–5k always-loaded tokens. Hard rails earn permanent context; keep the migration appendix in check.
• Evals cost API credits. npm run eval is deliberately not part of npm test or CI; it runs before releases.