# Design System Starter
>
- Skill: `frank-luongt/design-system-starter` (Agent Skill)
- Install (CLI): `npx skillmds@latest add frank-luongt/design-system-starter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frank-luongt/design-system-starter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: frank-luongt (https://skillmd.com/u/frank-luongt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/frank-luongt/design-system-starter
---
---
name: design-system-starter
description: Create and evolve design systems with design tokens, component architecture, accessibility guidelines, and theming. Use when building a new design system, setting up design tokens (colors, typography, spacing), implementing atomic design component hierarchy, ensuring WCAG 2.1 compliance, or adding dark mode support.
tags: [design-system, tokens, components, accessibility]
---
# Design System Starter
Build robust, scalable design systems with design tokens, component architecture, accessibility, and theming.
## When to Use
- Building a new design system from scratch
- Setting up design tokens (colors, typography, spacing, shadows)
- Implementing atomic design component hierarchy
- Ensuring WCAG 2.1 Level AA compliance
- Adding dark mode / theming support
## Core Principles
1. **Consistency Over Creativity** -- Predictable patterns reduce cognitive load
2. **Accessible by Default** -- WCAG 2.1 Level AA minimum, keyboard nav built-in
3. **Scalable and Maintainable** -- Tokens enable global changes, composition reduces duplication
4. **Developer-Friendly** -- Clear API contracts, comprehensive documentation
## Design Tokens
Tokens are the atomic design decisions that define your system's visual language.
### Color Tokens
**Primitive Colors** (raw values):
```json
{
"color": {
"primitive": {
"blue": {
"50": "#eff6ff", "100": "#dbeafe", "200": "#bfdbfe",
"300": "#93c5fd", "400": "#60a5fa", "500": "#3b82f6",
"600": "#2563eb", "700": "#1d4ed8", "800": "#1e40af",
"900": "#1e3a8a", "950": "#172554"
}
}
}
}
```
**Semantic Colors** (contextual meaning):
```json
{
"color": {
"semantic": {
"brand": {
"primary": "{color.primitive.blue.600}",
"primary-hover": "{color.primitive.blue.700}",
"primary-active": "{color.primitive.blue.800}"
},
"text": {
"primary": "{color.primitive.gray.900}",
"secondary": "{color.primitive.gray.600}",
"disabled": "{color.primitive.gray.400}",
"inverse": "{color.primitive.white}"
},
"background": {
"primary": "{color.primitive.white}",
"secondary": "{color.primitive.gray.50}",
"tertiary": "{color.primitive.gray.100}"
},
"feedback": {
"success": "{color.primitive.green.600}",
"warning": "{color.primitive.yellow.600}",
"error": "{color.primitive.red.600}",
"info": "{color.primitive.blue.600}"
}
}
}
}
```
**Contrast requirements (WCAG 2.1 AA)**:
- Normal text: 4.5:1 minimum
- Large text (18pt+ or 14pt+ bold): 3:1 minimum
- UI components and graphics: 3:1 minimum
### Typography Tokens
```json
{
"typography": {
"fontFamily": {
"sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
"mono": "'Fira Code', 'Courier New', monospace"
},
"fontSize": {
"xs": "0.75rem", "sm": "0.875rem", "base": "1rem",
"lg": "1.125rem", "xl": "1.25rem", "2xl": "1.5rem",
"3xl": "1.875rem", "4xl": "2.25rem", "5xl": "3rem"
},
"fontWeight": {
"normal": 400, "medium": 500, "semibold": 600, "bold": 700
},
"lineHeight": {
"tight": 1.25, "normal": 1.5, "relaxed": 1.75
}
}
}
```
### Spacing Tokens
Use a consistent scale (4px or 8px base):
```json
{
"spacing": {
"0": "0", "1": "0.25rem", "2": "0.5rem", "3": "0.75rem",
"4": "1rem", "5": "1.25rem", "6": "1.5rem", "8": "2rem",
"10": "2.5rem", "12": "3rem", "16": "4rem", "20": "5rem"
}
}
```
### Shadow & Border Radius Tokens
```json
{
"shadow": {
"sm": "0 1px 3px 0 rgba(0,0,0,0.1), 0 1px 2px -1px rgba(0,0,0,0.1)",
"md": "0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1)",
"lg": "0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)",
"xl": "0 20px 25px -5px rgba(0,0,0,0.1), 0 8px 10px -6px rgba(0,0,0,0.1)"
},
"borderRadius": {
"none": "0", "sm": "0.125rem", "base": "0.25rem",
"md": "0.375rem", "lg": "0.5rem", "xl": "0.75rem", "full": "9999px"
}
}
```
## Component Architecture
### Atomic Design Methodology
**Atoms** (Button, Input, Label, Icon, Badge, Avatar)
-> **Molecules** (SearchBar, FormField, Card)
-> **Organisms** (NavBar, ProductGrid, UserProfile)
-> **Templates** (DashboardLayout, SettingsLayout)
-> **Pages** (specific instances with real data)
### Component API Patterns
**Predictable prop names:**
```typescript
// Consistent across components
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
loading?: boolean;
children: React.ReactNode;
}
```
**Compound components (composition over configuration):**
```typescript
// Good: Composable
Title
Content
Actions
// Bad: Too many props
```
**Polymorphic components:**
```typescript
```
## Theming & Dark Mode
### Approach 1: CSS Variables
```css
:root {
--color-bg-primary: #ffffff;
--color-text-primary: #000000;
}
[data-theme="dark"] {
--color-bg-primary: #1a1a1a;
--color-text-primary: #ffffff;
}
```
### Approach 2: Tailwind Dark Mode
```tsx
Content
```
### Approach 3: ThemeProvider
```typescript
const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#1a1a1a', text: '#fff' };
```
## Accessibility
### Keyboard Navigation
All interactive elements must be keyboard accessible:
- Tab order follows logical reading order
- Focus indicators are visible (never `outline: none` without replacement)
- Modal dialogs trap focus
- Escape closes overlays
### ARIA Essentials
- `aria-label`: Accessible names for icon-only buttons
- `aria-expanded`: Communicate expanded/collapsed state
- `aria-controls`: Associate controls with controlled content
- `aria-live`: Announce dynamic content changes
- Use semantic HTML (`