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
--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
--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
: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)