designer-skill

designer-skill

A small plug-and-play MCP that gives your agent UI superpowers: design, refactor, and ship interfaces that don't look AI-made.

This file is the router. The substance lives in thirteen reference files under reference/; read this, then open the file(s) the task needs. Do not work from memory — open the owner file and use its concrete values.

MCP bootstrap (run on skill load)

When the designer-skill MCP server is connected, use it to fetch the latest, task-relevant design guidance before writing any UI code. Do not rely on memory or a stale copy of this skill — always pull fresh content from MCP.

1. Load project context — call load_project_context to read PRODUCT.md / DESIGN.md. If it returns NO_PRODUCT_MD, call get_command({ verb: "setup" }) and follow the setup flow before any other UI work.
2. Load the router — call get_design_system or fetch the designer://skill resource.
3. Route the user's request — call dispatch_intent with the user's request (or your best paraphrase) to get the matching design verb(s) and which reference files to read. For a known verb, get_command returns the full command guidance plus its reference files.
4. Fetch the references — for every file dispatch_intent or get_command recommends (and any others the preflight below requires), call get_reference or fetch designer://reference/{name}. Load 2–4 files in parallel when possible. Use the returned text as the authoritative source — not your training-data recall of these files.
5. Deterministic checks (check/review) — when reviewing existing UI, call detect_antipatterns on the target file or directory for 44 rule-based findings (no LLM). Combine with the anti-slop checklist.
6. Greenfield palette — when no committed brand colors exist, call get_palette_seed for an OKLCH anchor before composing the palette.
7. Find contemporary UI references (when the task is visually-led or net-new) — if the user is building, redesigning, or seeking inspiration for a surface (landing page, dashboard, pricing, onboarding, component library, etc.), use available web-search MCP tools (e.g. Tavily) to find recent, high-quality real-world UI examples relevant to the surface type, register (brand vs product), industry, and aesthetic direction. Extract structure, hierarchy, spacing rhythm, and interaction patterns — do not copy layouts wholesale. Filter findings through this skill's anti-slop discipline and one-aesthetic-system rule.
8. Ship gate at the end — call anti_slop_checklist before declaring any UI work done.

If MCP is unavailable, read the local reference/ files directly using the routing map below. Run node scripts/context.mjs once per session for PRODUCT.md / DESIGN.md.

How to use it (session preflight)

After MCP bootstrap (when available), run this order before writing UI code:

0. Check for project context files. If PRODUCT.md / DESIGN.md exist at the project root, they are authoritative: DESIGN.md wins visual decisions, PRODUCT.md wins strategic/voice decisions, and PRODUCT.md anti-references beat the user's one-off prompt (they are the brand's standing position; the prompt is one moment). On greenfield work, offer to create them.
1. Scope the surface and register. What is it — landing page, marketing site, dashboard, product UI, component, form? Decide the register: brand (design is the product: marketing, landing, campaign, portfolio — distinctiveness is the bar) vs product (design serves the product: app, admin, dashboard, tool — earned familiarity is the bar). Infer from concrete signals — brand: routes like /, /about, /pricing, /blog/*, hero sections, big typography, scroll-driven sections; product: /app/*, /dashboard, /settings, auth routes, forms, data tables, app-shell components. Pick by first match: task cue → the surface in focus → the persisted register; the project default can be overridden per task (a product can still have a brand-register landing page). Write one sentence of physical scene (who uses this, where, under what light, in what mood) and let it force light-vs-dark and tone.
2. Read at least one representative project file (tokens, theme, global CSS, or a core component) before any UI code — even on net-new work, and even after loading a reference file. Learn the system that's already there; don't reinvent it.
3. Commit to ONE aesthetic system from reference/aesthetic-systems.md (Minimalist / Brutalist / Soft / High-end-Stitch / Brand-identity). One language per surface — never mix two systems' signatures.
4. Run the category-reflex check in reference/avoid-ai-slop.md (first-order + second-order) before committing to a palette/type direction.
5. Build on the neutral baseline (reference/design-principles.md) + the engineering layer (reference/engineering-and-performance.md), add motion last (reference/motion-and-interaction.md).
6. For existing UI, follow the audit → diagnose → redesign loop in reference/refactor-and-redesign.md instead of building from scratch — preserve functionality, change presentation surgically.
7. Verify before done (see the ship gate below).

To map a specific user request ("make it pop", "it feels off", "production-ready") to the right move, read reference/command-playbook.md — the intent→verb dispatch table. If the request clearly matches one verb ("fix the spacing" → layout, "rewrite this error" → copy), load that verb's guidance and proceed as if it were invoked; if two verbs plausibly fit, ask once which one; with no clear match, run the general preflight above.

Project context files

PRODUCT.md and DESIGN.md at the project root persist design decisions across sessions — read them in preflight step 0, offer to create them on greenfield work:

• PRODUCT.md — strategy: register (brand|product), users, product purpose, a 3-word brand personality, anti-references (named bad examples), 3-5 strategic design principles (strategic, never visual rules), accessibility commitments.
• DESIGN.md — the visual system: design tokens plus named rules. The full authoring recipe lives in reference/refactor-and-redesign.md.

The reference files (routing map)

Open this	When the task is about
reference/design-principles.md	Visual fundamentals — typography, spacing & rhythm, color & contrast, layout & grid, hierarchy, depth. The aesthetic-neutral baseline.
reference/aesthetic-systems.md	Choosing or executing a specific look — the 5 opinionated design languages and when to use which. Concrete palettes, fonts, shadow tokens.
reference/motion-and-interaction.md	What to animate, how fast, which curve; springs, micro-interactions, gestures, scroll, perceived performance, reduced-motion.
reference/engineering-and-performance.md	Component architecture, design tokens/CSS vars, hardware acceleration, responsive/fluid, accessibility, Core Web Vitals, framework-honest output, real-data hardening.
reference/avoid-ai-slop.md	Not looking "AI-made" — the cross-register ban-list, category-reflex checks, and the output-completeness contract.
reference/refactor-and-redesign.md	Improving existing UI without breaking it — audit, diagnose generic patterns, the redesign loop, image/reference-to-code.
reference/command-playbook.md	Which verb/move maps to the user's intent (build, finish, amplify, calm, motion, ship, refresh, …).
reference/interaction-design.md	Cognitive laws (Fitts, Hick, Miller, Doherty), state machines, form design, navigation patterns, error UX, feedback loops, loading states, gestures, emotional timing.
reference/visual-critique.md	Seven-dimension critique instrument: visual hierarchy, composition, color, typography, affordance, information density, brand consistency.
reference/design-systems.md	Token architecture (global→semantic→component), motion system, component specs, naming conventions, theming, pattern library, color/type/spacing scales.
reference/project-init.md	One-time project setup: discovery interview, PRODUCT.md, optional DESIGN.md, live-mode pre-config, next-command routing.
reference/craft-flow.md	Full shape-then-build pipeline with user gates, framework detection, visual iteration loop.
reference/live-mode.md	Interactive browser variant mode: element selection, HMR hot-swap, poll/steer/accept contract.

Precedence rule (read before treating any rule as absolute)

reference/design-principles.md is the aesthetic-neutral baseline — the default lean. When you commit to an aesthetic system, its scoped rules in reference/aesthetic-systems.md override the baseline. Examples: Inter is discouraged by default but required for Brutalist macro-type; pure white is discouraged by default but is the Minimalist canvas; blanket shadows are a cheap default but Soft requires diffused ambient shadows. Never treat a baseline "expensive vs cheap" verdict as law once a system is chosen — the system wins within its own surface.

There is a second axis: the aesthetic system beats the baseline, and existing brand identity beats both. Every reflex-reject list (fonts, lanes, palettes) governs new design choices only — on a variant or edit of a shipped surface, never second-guess the committed font, lane, or palette; identity preservation wins.

Cross-file ownership (don't re-derive, read the owner)

Each fact has one home; cross-reference instead of duplicating.

• Contrast ratios, type ramp, spacing scale, layout model → design-principles.md
• Concrete palettes, fonts, shadow tokens, per-system rules → aesthetic-systems.md
• Easing curves, durations, spring config → motion-and-interaction.md
• GPU/hardware-accel, will-change, tokens, responsive, a11y engineering, CWV → engineering-and-performance.md
• Cognitive laws, state machines, form/nav patterns, error UX, loading states, emotional timing → interaction-design.md
• Dimensional critique scoring (7 dimensions) → visual-critique.md
• Token architecture, component specs, naming conventions, theming, color/type/spacing scales → design-systems.md

The always-run ship gate

reference/avoid-ai-slop.md is the gate every task passes before you declare it done:

• Run its Anti-Slop Checklist (category-reflex, color, layout, type, eyebrows, fake content, copy, emoji, completeness, and the register-matched slop test: brand = "could a viewer say AI made that?", product = "would a user fluent in Linear/Figma/Notion trust this?").
• The output-completeness contract is binding for all code generation: deliver the full file/all components/all sections. No // rest of code, no placeholders, no "for brevity", no skeleton when a full implementation was asked for. Partial, placeholder, or truncated output is a hard failure.
• Verify accessibility and responsiveness against real values: text ≥4.5:1 (AA), focus-visible rings, reduced-motion alternative, no horizontal scroll, touch targets ≥44×44px, tested at 375/768/1440px.