visual-design

Use when the user needs design-system guidance for UI implementation without loading the entire compendium. Triggers: which component to use, pick/recommend a component, component mapping, "no spec for", missing component spec, how to design or style a widget, compose components, UI pattern → design system, component gap, fuzzy matches. Behavior: **minimal** output when exact or high-confidence fuzzy: the **entire** matched component spec file (full markdown body) + motion — not a digest; **top-3** full specs + pattern synthesis + motion when fuzzy is ambiguous; **gap** mode when nothing scores. Always include **motion guidance** (from specs + design-guidelines.md). Not for visual-design-consultant (new system) or design-reviewer (QA).

Use when a visual/UI implementation step has been completed and needs design system review, or when reviewing components against requirements with visual output. Triggers on: component implementation complete, page complete, design review needed, visual quality gate, epic/milestone with UI work. Do NOT use for backend-only or CLI work with no visual output.

This skill should be used for design-system guidance during UI implementation: which component to use, specs for named components, fuzzy matches when no exact spec exists, or how to approach a component that has no spec yet — without loading the entire compendium into the caller's context. Trigger phrases: "load component spec", "component design spec", "what does the design say about [component]", "design spec for [component]", "which component should I use", "recommend a component", "pick a component from the design system", "map this UI to components", "no spec for", "missing component spec", "there's no design for", "how should I design", "how to style", "design guidance for", "component gap", "compose from existing components", "what should I use for [pattern]", "implement this against the design system", "offload component context", "get a compact spec briefing". Also when creating or editing files under components/, ui/, or widgets/ where token-aware implementation hints are needed. Prefer dispatching the visual-design:component-context agent. **Exact match or ~90%+ high-confidence fuzzy:** return the **complete** markdown body of the matched component spec (entire file), plus motion guidance — never a summary instead of the full spec. **Top-3** when fuzzy is ambiguous; **gap** when nothing fits. Never dump the whole compendium. Do NOT use for establishing a new design system from scratch (visual-design-consultant) or for post-build visual QA (design-reviewer).

This skill should be used when a major project step involving visual/UI work has been completed and needs to be reviewed against the design system. Examples: "I've finished implementing the dashboard page", "the card component is done", "implement epic 3" (when epic involves visual output). Also fires on: "review component", "design review", "check against design system", "visual review", "run design tests", "implement epic", "implement milestone", "implement feature", "perform a design review of [requirements]". Do NOT trigger for backend-only, API-only, or CLI work with no visual output. Uses **headless Playwright** (`playwright-skill-bridge.mjs`) for inspection — AFK-safe and CI-safe; no Chrome DevTools MCP. Includes Nielsen's 10 Usability Heuristics with UX scoring (0-100) and diff mode for follow-up reviews. When dispatched as the design-reviewer agent, writes granular progress to `.agent-progress/` (see `references/agent-progress.md`) and emits short parent summaries for orchestrators.

This skill should be used to regenerate the component index after manually adding, editing, or removing component spec files. Trigger phrases: "update component index", "rebuild component index", "refresh design index", "regenerate component index".

This skill should be used when the user wants to establish, extract, or update a visual design system. Trigger phrases: "design system", "visual design", "design guidelines", "extract design from site", "design tokens", "component styles", "I want it to look like [site]", "set up the design", "design interview", "update design guidelines", "add to design system". Also trigger when the user provides a URL and asks about its design, or when they describe visual preferences for a project. Codebase reverse-engineering triggers: "design system from codebase", "reverse engineer components from the repo", "extract tokens from this project", "derive design guidelines from code", "build component specs from existing UI", "motion design from codebase". Do NOT trigger for requirements gathering — that is the requirements-gatherer skill. Do NOT trigger for code review — that is the design-reviewer skill.