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>

References

• Design Tokens W3C Spec
• Tailwind Theme Configuration
• Design Systems for Developers