Design Fleet

By Quintessential. A fleet of design agents for Cursor and Claude Code — six skills, ten rules, a project contract, and a deterministic lint that together keep your project's design hygiene sane, inject the knowledge models actually lack, and wire the harness properly on both platforms.

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.

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, 6 skills, and a routing manifest. 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 — 6 skills

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

| Agent | Role | Trigger phrasing | |-------|------|------------------| | design-onboarding | The interviewer — learns your taste once, writes the design-taste profile every later decision consults | "Set up design" — runs once per project | | design-vision | The keeper of the contract — assess rates the codebase, draft writes a filled VISION.md, reconcile catches it drifting from reality | "Audit my codebase", "Draft the vision" | | frontend-design | The builder — production-grade components, pages, layouts; reads the contract first | "Build a component", "Implement this UI" | | ui-patterns | The motion & technique specialist — easing, springs, exits, plus the delta patterns models miss (View Transitions hygiene, container animation lifecycle, predictive prefetch) | "Animate this", "Use a view transition" | | design-critique | The critic — visual + behavioral critique of a screenshot, file, or URL; formal Nielsen mode on request | "Critique my page", "Heuristic review" | | design-lint | The inspector — validates output against the rules and the contract; deterministic checks + judgment, pass/fail with fixes | "Lint my UI", "Does this follow the contract" |

Skills compose. Greenfield: design-onboarding → frontend-design → design-lint. Existing project: design-vision (assess) → design-vision (draft) → build → lint.

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-vision 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 6 base checks (pure-black shadows and defaults, spacing scale, banned default fonts, reduced motion, focus-visible). With one, 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-lint skill layers LLM judgment on top: layout conformance against the canonical reference file, signature-technique coverage, selection semantics, app-shell protocol.

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