design-system

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

1. Name roles, not appearances. Use surface, text-muted, and danger, not light gray or red text. Role names survive palette changes.

2. Write values and states, not impressions. Tokens without values are vague. Components without states are incomplete.

3. Document the system, not one screen. A design system doc should help future work stay consistent across pages and features.

4. Make forbidden patterns explicit. A clear ban list prevents the agent from drifting back to generic defaults.

5. Include accessibility and responsive behavior in the base system. These are not optional add-ons.

6. Stay framework-agnostic unless the project requires otherwise. Use markdown-first rules that can be applied in any stack.

7. Keep the document short enough to use. If it reads like a long essay, it will not guide implementation well.

Workflow

1. Read the project context first. Identify the product type, audience, and visual intent before choosing any tokens.
2. Define the foundations. Set color roles, type scale, spacing logic, radius, and shadow rules before components.
3. Describe component anatomy. For each component, define purpose, structure, states, and any slot or variant rules.
4. Set layout rules. Specify container width, grid behavior, breakpoints, spacing rhythm, and collapse behavior.
5. Set motion and accessibility rules. State allowed motion, reduced-motion behavior, contrast expectations, focus behavior, and target size.
6. List forbidden patterns. Call out the patterns that would make the system drift toward generic output.
7. 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

• Semantic tokens are named and assigned roles
• Type and spacing rules are documented
• Component anatomy and states are described
• Layout includes container and breakpoint guidance
• Motion includes allowed properties and reduced-motion behavior
• Accessibility includes contrast, focus, and target size
• Forbidden patterns are explicit and checkable
• The document can be used without additional explanation

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.