Design Fleet

By Quintessential. Design contracts your agents can't drift from — enforced at edit-time and in CI. A fleet of design agents for Cursor and Claude Code: a machine-checkable project contract (VISION.md), a deterministic lint that fails builds on violations (and can block bad edits before they land), four role-aligned skills that own the loop (contract → build → review, plus a motion-naming glossary), and the delta knowledge frontier models still lack — measured, not assumed.

The fleet makes three promises:

1. Hygiene stays sane. The contract (VISION.md) pins your tokens, type ramp, exact error copy, and timings; the deterministic lint enforces them in CI; reconcile catches the doc drifting from reality. Models know good defaults but apply them stochastically — we measured it with an 88-run cold-baseline audit — so the fleet enforces instead of hoping.
2. Knowledge that's actually knowledge. Content is curated against cold frontier-model baselines: what the model already does is cut or compressed; what it reliably misses (recent platform APIs, build-time gotchas, fine-grained craft) is labeled delta knowledge and kept sharp. New content needs a failing baseline eval to get in — that is the admission rule.
3. The harness is proper. Native delivery per platform — Cursor gets real .mdc rules, Claude Code gets launch-loaded and paths:-scoped rules that survive compaction, and the contract is wired with thin pointers the CLI manages (vision --wire), never hand-glue.

Measured, not asserted

Every claim above is backed by the eval harness (npm run eval), with a generator and an independent judge (different models — the harness refuses to self-grade):

• Skills: +22 to +41pp per skill over a cold frontier model (latest full runs: frontend-design +41pp, design-review +39pp, design-contract +29pp, animation-vocabulary +22pp); rules: +15 to +33pp per rule suite.
• The gate rejects our own content: knowledge whose cold baseline already passes never ships — two typography rules were retired before release when the baseline aced their eval at 100%.
• Placebo-controlled: a content-free "you have world-class taste" prompt of the same length moves scores by ≈0pp — the uplift is the content, not priming.
• Judge noise: 1.6pp mean disagreement when the same response is judged twice.
• The subjective critique may only gate when calibrated: it must first separate a committed corpus of reference-good vs reference-slop screens by a margin (lib/calibration.mjs). First live run: separation 0.38 vs the required 0.15.
• Content that a new model generation absorbs gets retired, per the admission rule in CONTRIBUTING.md.

What it costs (context honesty)

Rules are context your agent carries. Nobody in this category prints the bill; here is ours (≈ tokens, chars/4):

| Artifact | When it loads | Cost | |---|---|---| | design-intent (always-on) | every UI edit | ~1.8k tokens | | ux-writing (always-on) | every UI edit | ~0.9k tokens | | 8 scoped rules | only when editing matching files | ~0.9k each | | Skills | only when invoked | 2–4k + references on demand | | Wired VISION.md | every edit, by design — hard rails don't work part-time | ≈ the contract's size (template ~5.3k) |

The always-on tax is ~2.7k tokens per edit, and it buys the two highest-measured-value behaviors (design-intent is the single strongest rule at +45pp). If that trade isn't right for your project, delete either rule — the lint floor still enforces the contract in CI.

Install

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

That installs 10 rules, 4 skills, and a routing manifest. On Cursor each skill also gets a native agent-requested rule + a /-command (Cursor has no skills auto-loader); on Claude Code the skills are native. On Cursor, treat the /-commands (/design-contract, /frontend-design, /design-review, /animation-vocabulary) as the primary way to invoke a skill deterministically — the agent-requested rules make auto-selection likely, but description matching is best-effort by nature. On the next UI edit your agent runs a one-time onboarding to learn your taste, then loads the right rule and skill for whatever you're building.

Both targets are first-class: Cursor gets native .mdc rules (globs + alwaysApply); Claude Code gets converted .md rules (paths: scoping, always-on rules load at launch and are designed to survive compaction in current Claude Code versions).

The three layers

| Layer | What it is | Owner | |-------|-----------|-------| | Rules + skills | Generic design knowledge — strong defaults | The package | | design-taste | Your aesthetic profile, from a 12-question onboarding | You (generated) | | VISION.md | The project's hard-rails contract — tokens, type ramp, exact error strings, canonical layouts, animation timings | You (the project) |

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).

10 Rules

Cursor .mdc rules in rules/. Two are always on; eight activate on demand when the agent works in their domain.

| Rule | Governs | Always on | |------|---------|-----------| | design-intent | Pre-build checklist — feel, hierarchy, references, the AI-slop sniff test; defers to VISION.md's checklist on existing surfaces | yes | | ux-laws | 23 UX psychology laws (Fitts, Hick, Doherty, Gestalt, …) | on demand | | ux-writing | Button labels, error messages, empty states, terminology, tone | yes | | visual-design | Shadows, radius, spacing scale, borders, button layering | on demand | | color-contrast | OKLCH palettes, WCAG contrast, dark mode, token architecture | on demand | | typography | Type scale, font selection, numeric formatting, OpenType, wrapping | on demand | | responsive-design | Mobile-first, container queries, input detection, safe areas | on demand | | layout-composition | Page composition, rhythm, density, visual primitive reuse | on demand | | data-visualization | Charts, tables, encoding hierarchy, number formatting | on demand | | keyboard-shortcuts | Keyboard conventions, focus management, cross-platform mapping | on demand |

The fleet — 4 skills

Skills in skills/*/SKILL.md. Each is an agent role, aligned to a stage of the loop, that loads on demand when a request matches its description, and ships with its own evals.

| Agent | Role | Trigger phrasing | |-------|------|------------------| | design-contract | The keeper of design truth — five modes: setup interviews for your taste once (writes design-taste), assess rates the codebase, draft writes a filled VISION.md, reconcile catches it drifting from reality, plan turns feedback into proposed goals (with a flip test that catches features disguised as outcomes) | "Set up design", "Audit my codebase", "Draft the vision" | | frontend-design | The builder — production-grade components, pages, layouts honoring the contract; owns motion too (easing, springs, gesture/drag physics, exits, clip-path animation, View Transitions, container animation, translucent materials, predictive prefetch) | "Build a component", "Animate this" | | design-review | The evaluator — two altitudes: a deterministic floor (validates output against the rules + contract, pass/fail with fixes) and a subjective ceiling (visual + behavioral critique, formal Nielsen mode, a Motion Review Mode for animation diffs, and a calibrated scored gate with per-target trend memory) | "Lint my UI", "Critique my page", "Heuristic review" | | animation-vocabulary | The namer — reverse-lookup motion glossary: turns "the bouncy thing when a popover opens" into Pop in, so your next prompt asks for exactly the right effect | "What's it called when…", "Name of that effect" |

Skills compose. Greenfield: design-contract (setup) → frontend-design → design-review. Existing project: design-contract (assess) → design-contract (draft) → build → review.

VISION.md — the project contract

For real projects, taste isn't enough: you need hard rails — this token map, these exact error strings, this canonical layout. That's VISION.md, a contract at your project root that every agent edit must respect.

npx design-fleet vision --wire    # scaffold from template + wire both pointers
npx design-fleet vision           # status: per-section fill state, pointer health
npx design-fleet vision --unwire  # remove pointers (never touches VISION.md)

Or run the design-contract skill in draft mode for a guided, filled contract: it extracts what code can tell it (tokens, type ramp, timings, canonical files), pulls your taste profile, and interviews you for the rest (north star, ALWAYS/NEVER rules, exact error strings).

Wiring is native per platform: a thin always-on rule at .cursor/rules/vision.mdc, and a marker-delimited block in CLAUDE.md importing @VISION.md. The CLI never overwrites or deletes an existing VISION.md — vision --wire only scaffolds the blank template when none exists. The contents are yours.

Deterministic lint

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

Without a VISION.md: the 10 base checks — pure-black shadows and defaults, spacing scale, banned default fonts, reduced motion, focus-visible, plus the AI-tell tier: thick colored side-tab borders, gradient text, overshoot easing caught by cubic-bezier math (not just keywords; gesture contexts pass), and the stock cream/brass "premium" palette by exact hex. With a VISION.md, the lint becomes vision-aware: it parses the contract's tables and enforces project-exact P-checks — 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), canonical example paths must exist (P12). Declared tokens suppress the generic checks' false positives — reported, never silent.

The design-review skill layers LLM judgment on top: layout conformance against the canonical reference file, signature-technique coverage, selection semantics, app-shell protocol.

Edit-time enforcement (experimental, opt-in)

The same checks can run before an edit lands instead of after: a PreToolUse hook for Claude Code inspects the proposed file content and blocks writes that introduce new violations (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 repeated denials of the same finding to a warning so the agent can't wedge. Setup and semantics: docs/edit-hook.md; print the settings snippet with node node_modules/design-fleet/bin/hook.mjs --install.

Update / Uninstall

npx design-fleet update              # Update to latest (refreshes VISION pointers)
npx design-fleet uninstall --dry-run # Preview what would be removed
npx design-fleet uninstall           # Remove (keeps custom files; never touches VISION.md)

Add --target=claude or --target=both to any command. Add --keep-generated to uninstall to preserve your taste profile across reinstalls (--keep-taste still works as an alias).

How routing works

Real agents pick a skill from each SKILL.md's description field. A skill-manifest.json documents triggers and boundaries so you can reason about routing — preview locally:

npx design-fleet route "your query here"

The router scores trigger matches and falls back to frontend-design when no skill clears a confidence threshold of 2.0.

Honest limitations

• Skill invocation is probabilistic. Cursor and Claude Code decide which skill matches a request. They may pick the wrong one or skip entirely. Use route to preview locally.
• Pointers are context, not enforcement. An agent can still skip the contract; the lint loop is the backstop, and hooks are the right tool for must-run behavior.
• Deterministic lint covers the contract's tables and ~5 generic checks. Everything judgment-shaped stays with the LLM-judged design-review skill.
• A filled VISION.md costs ~4-5K always-loaded tokens. Hard rails earn permanent context; keep the optional Migration appendix in check.
• npm run eval costs Anthropic API credits. Intentionally not part of npm test.

Precedence (when rules conflict with reality)

1. Product constraints — deadlines, existing code, team decisions
2. Accessibility / legal — WCAG, forced-colors, screen reader support
3. VISION.md — the project's hard-rails contract
4. Brand requirements — palette, fonts, voice
5. design-taste profile
6. Design Fleet defaults

Strong defaults, not mandates. Override when the project demands it — and record the override in VISION.md so the next edit inherits it.

Development

npm install
npm test            # unit tests + skill validation
npm run lint:design # deterministic design lint (vision-aware when VISION.md exists)
npm run eval        # LLM-as-judge eval (needs ANTHROPIC_API_KEY)

lib/ holds pure modules (design-tokens, converters, lint-rules, vision-parser, lint-runner, claude-md, uninstall, validate-skill) used by the CLI, the scripts, and the test suite. Run npm test before pushing.