---
name: design-system-architecture
description: Build scalable design systems with design tokens, component APIs, and documentation. Use when creating or evolving component libraries.
keywords:
- design system
- design tokens
- component library
- ui components
- theming
triggers:
- design system
- component library
- design tokens
- theme architecture
- ui kit
---
# Design System Architecture
Comprehensive guide to building scalable design systems with proper token architecture, component APIs, and documentation strategies.
## When to Use This Skill
- Creating a new design system from scratch
- Evolving an existing component library
- Defining token architecture
- Establishing component API patterns
- Setting up design system documentation
## Token Architecture
### Three-Tier Token System
```
┌─────────────────────────────────────┐
│ Component Tokens │ → button-primary-bg
│ (Specific to components) │
├─────────────────────────────────────┤
│ Semantic Tokens │ → color-action-primary
│ (Purpose-based naming) │
├─────────────────────────────────────┤
│ Primitive Tokens │ → blue-500
│ (Raw values) │
└─────────────────────────────────────┘
```
### Token Categories
```css
/* Primitive Tokens */
--color-blue-500: #3b82f6;
--spacing-4: 1rem;
--font-size-base: 16px;
--radius-md: 8px;
/* Semantic Tokens */
--color-action-primary: var(--color-blue-500);
--color-text-primary: var(--color-gray-900);
--spacing-component-gap: var(--spacing-4);
/* Component Tokens */
--button-bg: var(--color-action-primary);
--button-padding-x: var(--spacing-4);
--card-radius: var(--radius-md);
```
### Theme Support
```typescript
// tokens/themes.ts
export const lightTheme = {
'color-bg-primary': 'var(--color-white)',
'color-text-primary': 'var(--color-gray-900)',
'color-border': 'var(--color-gray-200)',
}
export const darkTheme = {
'color-bg-primary': 'var(--color-gray-900)',
'color-text-primary': 'var(--color-gray-100)',
'color-border': 'var(--color-gray-700)',
}
```
## Component API Patterns
### Prop API Design
```typescript
// ✅ Good: Clear, typed, with sensible defaults
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'ghost';
size?: 'sm' | 'md' | 'lg';
isLoading?: boolean;
isDisabled?: boolean;
leftIcon?: React.ReactNode;
children: React.ReactNode;
onClick?: () => void;
}
// ✅ With defaults
const Button = ({
variant = 'primary',
size = 'md',
isLoading = false,
isDisabled = false,
...props
}: ButtonProps) => { ... }
```
### Compound Component Pattern
```typescript
// Compound components for complex UIs
const Tabs = ({ children, defaultValue }) => { ... }
Tabs.List = ({ children }) => { ... }
Tabs.Tab = ({ value, children }) => { ... }
Tabs.Panel = ({ value, children }) => { ... }
// Usage
First
Second
Content 1
Content 2
```
### Polymorphic Components
```typescript
// Component that can render as different elements
interface BoxProps {
as?: C;
children?: React.ReactNode;
}
type PolymorphicProps =
BoxProps & Omit, keyof BoxProps>;
const Box = ({
as,
...props
}: PolymorphicProps) => {
const Component = as || 'div';
return ;
};
// Usage
Content
Click me
```
## Component Categories (Atomic Design)
### Atoms (Primitives)
- Button, Input, Label, Icon
- Typography (Text, Heading)
- Box, Flex, Grid (layout primitives)
### Molecules (Compositions)
- FormField (Label + Input + Error)
- SearchInput (Input + Icon + Button)
- Card (Box + padding + border)
### Organisms (Features)
- Header (Logo + Nav + UserMenu)
- DataTable (Table + Pagination + Filters)
- Modal (Overlay + Card + Actions)
## Documentation Strategy
### Component Documentation
```markdown
# Button
Buttons trigger actions or navigate users.
## Usage
\`\`\`jsx
import { Button } from '@/components/ui'
\`\`\`
## Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Size preset |
## Examples
### Variants
[Interactive examples]
### With Icons
[Interactive examples]
## Accessibility
- Uses `