| name | design-system |
| description | Activate when a user needs a written design system reference that defines tokens, component rules, layout principles, motion, accessibility, and forbidden patterns for a project. |
| version | 1 |
| category | design-strategy |
| outputs | documents |
Design System
Purpose
This skill writes a durable design reference that agents and humans can use when building or auditing a product. The document should turn visual direction into named rules, not mood notes.
When to Activate
- User wants a
DESIGN.md or similar reference before implementation
- User wants to codify an existing UI into reusable design rules
- User wants a constraint document for frontend or image-generation work
- User needs a design system brief that can guide AI output over time
When Not to Activate
- User wants code directly
- User wants a visual reference image
- User wants a full token export or component library package
- User wants a UI audit on existing code
Core Principles
-
Name roles, not appearances. Use surface, text-muted, and danger, not light gray or red text. Role names survive palette changes.
-
Write values and states, not impressions. Tokens without values are vague. Components without states are incomplete.
-
Document the system, not one screen. A design system doc should help future work stay consistent across pages and features.
-
Make forbidden patterns explicit. A clear ban list prevents the agent from drifting back to generic defaults.
-
Include accessibility and responsive behavior in the base system. These are not optional add-ons.
-
Stay framework-agnostic unless the project requires otherwise. Use markdown-first rules that can be applied in any stack.
-
Keep the document short enough to use. If it reads like a long essay, it will not guide implementation well.
Workflow
- Read the project context first. Identify the product type, audience, and visual intent before choosing any tokens.
- Define the foundations. Set color roles, type scale, spacing logic, radius, and shadow rules before components.
- Describe component anatomy. For each component, define purpose, structure, states, and any slot or variant rules.
- Set layout rules. Specify container width, grid behavior, breakpoints, spacing rhythm, and collapse behavior.
- Set motion and accessibility rules. State allowed motion, reduced-motion behavior, contrast expectations, focus behavior, and target size.
- List forbidden patterns. Call out the patterns that would make the system drift toward generic output.
- Review for completeness. Check that the document can guide implementation without another interpretation pass.
Forbidden Patterns
- Vague style words without operational detail
- Token names without semantic roles
- Color values without usage guidance
- Component descriptions that only cover the default state
- Layout rules without breakpoints or container guidance
- Motion rules without reduced-motion behavior
- Accessibility guidance added as an afterthought
- Tool-specific syntax that makes the doc hard to reuse
- A design brief that only describes the hero section
- More than one accent color without a clear reason
Output Requirements
- Generate a single markdown design document
- Include named tokens and their roles
- Include type, spacing, layout, and motion rules
- Include component states and responsive behavior
- Include accessibility constraints
- Include a clear forbidden-pattern list
- Keep the document readable without external context
Quality Gates
Failure Modes
"Mood board in prose": The doc uses adjectives instead of rules. Detection: no values, roles, or states. Fix: replace impressions with concrete token and component guidance.
"Token dump": The doc lists colors and fonts but never says how they are used. Detection: no component, layout, or state guidance. Fix: add usage rules and fallback behavior.
"Partial system": The doc covers visual style but skips accessibility or responsive behavior. Detection: missing contrast, focus, or breakpoint rules. Fix: add the missing constraints directly in the doc.
"Tool lock-in": The doc only makes sense in one design tool or framework. Detection: product-specific syntax dominates the document. Fix: rewrite in markdown-first language and keep tool-specific notes optional.
Engineering rationale: A design system document is only useful if it reduces repeated interpretation. If contributors still need a second conversation to apply it, the document is too vague.
Response Format
Generate the full design document as a single markdown block. Start with a short summary of the system, then the sections that define tokens, type, components, layout, motion, accessibility, and forbidden patterns. Do not add follow-up questions.
