Design System Architect
Master design system architecture to create consistent, maintainable, and scalable UI foundations across web and mobile applications.
When to Use This Skill
-
Creating design tokens (colors, type, spacing).
-
Establishing token hierarchies (Primitive -> Semantic -> Component).
-
Defining visual foundations (8pt grid, modular type scales).
-
Implementing light/dark theme switching.
-
Architecting consistent component libraries.
-
Brand Implementation: Translating Brand Guidelines (Colors, Voice) into code.
Core Concepts
- Token Hierarchy (The "3-Layer Cake")
Understanding the relationship between layers is critical for scalability.
Layer 1: Primitive Tokens (Raw)
-
Definition: Agnostic raw values.
-
Example: --color-blue-500: #3b82f6 , --space-4: 1rem
-
Goal: The "Palette" available to the system.
Layer 2: Semantic Tokens (Intent)
-
Definition: Contextual meaning; references primitives.
-
Example: --text-primary: var(--color-gray-900) , --status-critical: var(--color-red-500)
-
Goal: The "Voice" of the system. Allows theming (remapping).
Layer 3: Component Tokens (Specific)
-
Definition: Specific component usage.
-
Example: --button-bg-hover: var(--interactive-primary-hover)
-
Goal: Isolation. Changing a button shouldn't break a card.
- Visual Foundations
Typography Scale Use a modular scale (e.g., Major Third 1.250).
:root { --text-xs: 0.75rem; /* 12px / --text-base: 1rem; / 16px / --text-xl: 1.25rem; / 20px */ }
- Rules: Line height 1.5 for body, 1.2-1.1 for headings.
Spacing System (8pt Grid) Avoid magic numbers. Everything is a multiple of 4px or 8px.
-
--space-1 : 0.25rem (4px)
-
--space-2 : 0.5rem (8px)
-
--space-4 : 1rem (16px) - The base unit
- Aesthetics & Brand Identity
-
Styles: Support for Glassmorphism, Aurora UI, Linear/Vercel Aesthetic.
-
Framework: Refer to resources/ai-design-framework.md for specific palettes and patterns.
-
Gradients: Define brand gradients as tokens (--gradient-brand: linear-gradient(...) ).
-
Shadows: Use layered shadows for depth (--shadow-elevation-low , --shadow-elevation-high ).
- Implementation Architecture
Theming Infrastructure (React)
-
Storage: Persist in localStorage to avoid FOUC.
-
System Sync: Listen to prefers-color-scheme .
-
Injector: Apply .dark class to <html> .
Component Variants (CVA) Use class-variance-authority for type-safe variants.
const button = cva("rounded font-medium transition-colors", { variants: { intent: { primary: "bg-brand-500 text-white hover:bg-brand-600", secondary: "bg-surface-200 text-text-primary" }, // ... } });
Best Practices
-
Name by Purpose: text-danger ✅ vs text-red ❌.
-
Private Primitives: Developers should use surface-subtle , not gray-50 .
-
Accessibility: Ensure Semantic tokens meet WCAG 2.1 AA (4.5:1) by default.