Design Systems

This skill covers the foundational elements of design systems — design tokens, spacing scales, color systems, typography, and naming conventions that enable consistent user experiences.

Use-When

This skill activates when:

Agent creates or maintains a design system
Agent establishes theming or CSS variables
Agent builds reusable components
Agent needs consistent spacing/color/typography
Agent configures Tailwind or similar CSS frameworks

Core Rules

ALWAYS use design tokens (variables) instead of hardcoded values
ALWAYS use a consistent spacing scale (4px or 8px base)
ALWAYS use semantic color roles (primary, secondary, destructive) over color names
ALWAYS use a typography scale with limited font sizes
ALWAYS name tokens semantically (background-primary, not background-blue-500)

Common Agent Mistakes

Using arbitrary values (margin-6, color-red-500) instead of tokens
Creating new colors instead of reusing system colors
Using too many font sizes (stick to 3-4)
Hardcoding values that should be tokens

Examples

✅ Correct

// Using design tokens/variables
<div className="p-4 gap-4">
  <span className="text-primary text-sm font-medium">
    Consistent spacing and semantic colors
  </span>
</div>

// CSS variables (design tokens)
:root {
  --spacing-1: 0.25rem;  // 4px base
  --spacing-2: 0.5rem;   // 8px
  --spacing-4: 1rem;     // 16px
  --color-primary: #0f172a;
  --color-secondary: #64748b;
}

❌ Wrong

// Arbitrary values
<div className="p-6 gap-5">
  <span className="text-blue-600 text-[15px]">
    Magic numbers and hardcoded colors
  </span>
</div>

design-systems