Generic Design System
Design system reference adapting to any project's visual language.
Research First for New Systems
When creating a NEW design system (not following an existing one):
Skill(ui-research) # Research modern patterns first
References:
- UI Inspiration Sources - Research sources
- Design Patterns - Visual tokens
When to Use This Skill
Use for:
- Implementing UI components
- Choosing colors or typography
- Creating animations or transitions
- Ensuring visual consistency
- Setting up design tokens
- Reviewing design system compliance
Don't use when:
- UX flow design → use
generic-ux-designer - Feature architecture → use
generic-feature-developer - Code quality review → use
generic-code-reviewer
Design System Architecture
When to Build vs Reference
| Situation | Action |
|---|---|
| Existing design system | Follow it strictly |
| No design system | Use this skill to establish foundations |
| Partial system | Identify gaps, extend consistently |
Token Organization
| Layer | Example | Purpose |
|---|---|---|
| Primitive | --color-blue-500 | Raw values |
| Semantic | --color-primary | Meaning |
| Component | --button-background | Context |
Decision: Use semantic tokens in code, primitive tokens as foundation only.
Consistency Decision Tree
- Component exists? → Use existing pattern
- Similar exists? → Adapt existing (don't create competing pattern)
- New category? → Propose to user, document reasoning
Color System
Every project should define:
- Primary, Secondary, Accent
- Background, Foreground, Muted
- Destructive, Success, Warning
Contrast Requirements
| Use Case | Minimum |
|---|---|
| Body text | 4.5:1 (AA) |
| Large text | 3:1 (AA) |
| UI components | 3:1 (AA) |
Typography
Font Stack
css--font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; --font-mono: "SF Mono", Monaco, "Courier New", monospace;
Type Scale
| Name | Size | Use |
|---|---|---|
| sm | 14px | Secondary text |
| base | 16px | Body text |
| lg | 18px | Lead paragraphs |
| xl | 20px | Section headers |
| 2xl | 24px | Page headers |
Spacing System
Base unit: 4px or 8px
| Token | 4px Base | Use |
|---|---|---|
| 1 | 4px | Tight spacing |
| 2 | 8px | Default gap |
| 4 | 16px | Card padding |
| 6 | 24px | Page margins |
Animation
GPU-Accelerated Only
DO animate: transform, opacity
AVOID: width, height, top, left, margin, padding
Duration
| Token | Duration | Use |
|---|---|---|
| fast | 100ms | Micro-interactions |
| DEFAULT | 200ms | Most transitions |
| slow | 300ms | Complex animations |
Timing
css--ease-default: cubic-bezier(0.4, 0, 0.2, 1); --ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
Components
Component States
| State | Visual Treatment | Example |
|---|---|---|
| Default | Base styling | Normal button |
| Hover | Subtle feedback | Lighter/darker bg |
| Active | Pressed state | Scaled down slightly |
| Focus | Visible outline | 2px ring, offset |
| Disabled | Reduced opacity | 50% opacity, no pointer |
| Loading | Spinner/skeleton | Button with spinner |
| Error | Destructive color | Red border/text |
Touch Targets
- Minimum: 44x44px (WCAG 2.1 AAA)
- Spacing: 8px between adjacent targets
- Mobile: Consider 48x48px for primary actions
Buttons
| Variant | Use | Min Size |
|---|---|---|
| Primary | Main actions | 44x44px |
| Secondary | Alternative actions | 44x44px |
| Ghost | Subtle actions | 44x44px |
| Destructive | Delete actions | 44x44px |
Form Inputs
- Clear focus states (2px visible ring)
- Error states with messages
- Label always visible
- Required indicator
Modals
- Focus trapped inside
- Escape to close
- Dark overlay (50-70% opacity)
Responsive Breakpoints
| Token | Min Width |
|---|---|
| sm | 640px |
| md | 768px |
| lg | 1024px |
| xl | 1280px |
Dark Mode
css:root { --background: #ffffff; --foreground: #000000; } [data-theme="dark"] { --background: #000000; --foreground: #ffffff; }
See Also
- Design Patterns - Atomic Design, tokens, component docs
- Code Review Standards - Accessibility checks
generic-ux-designer- For UX flow and research decisions- Project
CLAUDE.md- Project-specific design constraints
READ references when:
- Setting up new design system → DESIGN_PATTERNS.md (full structure)
- Complex component patterns → DESIGN_PATTERNS.md (Atomic Design section)
