# Design System Starter

A comprehensive Claude Code skill for creating and evolving production-ready design systems with design tokens, component architecture, accessibility guidelines, and documentation templates.

## Purpose

This skill helps you build robust, scalable design systems that ensure visual consistency and exceptional user experiences across your products. It provides structured guidance for:

- Defining and organizing design tokens (colors, typography, spacing, shadows)
- Architecting components using atomic design methodology
- Implementing theming and dark mode support
- Ensuring WCAG 2.1 Level AA accessibility compliance
- Creating comprehensive component documentation
- Establishing maintainable design system workflows

## When to Use

Use this skill when you need to:

- Create a new design system from scratch
- Standardize UI patterns across multiple products
- Implement design tokens for consistent styling
- Structure components using atomic design principles
- Ensure accessibility compliance (WCAG 2.1 AA)
- Set up theming and dark mode support
- Document component libraries effectively
- Migrate from inconsistent UI patterns to a unified system

## How It Works

The skill provides comprehensive guidance and templates organized around five core areas:

### 1. Design Tokens
Structured JSON templates for defining foundational design decisions:
- **Color systems**: Primitive colors (50-950 scale) and semantic tokens (brand, text, background, feedback)
- **Typography**: Font families, sizes, weights, line heights, letter spacing
- **Spacing**: Consistent scale based on 4px or 8px units
- **Border radius**: Reusable corner rounding values
- **Shadows**: Elevation system for depth

### 2. Component Architecture
Atomic design methodology for building UI:
- **Atoms**: Primitive components (Button, Input, Label, Icon)
- **Molecules**: Simple compositions (FormField, SearchBar, Card)
- **Organisms**: Complex compositions (Navigation, Modal, ProductGrid)
- **Templates**: Page layouts
- **Pages**: Specific instances with real content

### 3. Accessibility
Built-in WCAG 2.1 Level AA compliance:
- Color contrast validation (4.5:1 for normal text, 3:1 for large text)
- Keyboard navigation patterns
- ARIA attributes and screen reader support
- Focus management

### 4. Theming
Multiple approaches for light/dark mode:
- CSS custom properties
- Tailwind CSS dark mode utilities
- Styled Components ThemeProvider

### 5. Documentation
Standards for component documentation:
- Component purpose and usage
- Props API with types and defaults
- Accessibility notes
- Common examples

## Key Features

### Design Token System
- W3C design tokens format
- Primitive and semantic color systems
- Typography scales with accessibility in mind
- Consistent spacing based on mathematical scale
- Shadow system for elevation

### Component Templates
- TypeScript-first component templates
- Polymorphic component patterns
- Compound component API design
- Variant and size systems
- Complete accessibility support

### Bundled Resources
The skill includes ready-to-use templates and references:
- `templates/design-tokens-template.json` - Complete token structure
- `templates/component-template.tsx` - React component boilerplate
- `references/component-examples.md` - Full implementations with variants
- `checklists/design-system-checklist.md` - Audit checklist

### Accessibility First
- WCAG 2.1 Level AA compliance by default
- Color contrast guidelines and testing recommendations
- Keyboard navigation patterns
- ARIA best practices
- Screen reader support patterns

## Usage Examples

### Example 1: Create a New Design System

```
Create a design system for my React app with dark mode support
```

The skill will guide you through:
1. Setting up design tokens (colors, typography, spacing)
2. Creating atomic components (Button, Input, Card)
3. Implementing dark mode with CSS variables
4. Ensuring accessibility compliance
5. Setting up documentation structure

### Example 2: Add Design Tokens

```
Set up design tokens for colors and spacing using the 8px scale
```

Provides:
- Color token structure (primitive + semantic)
- Spacing scale based on 8px units
- JSON format compatible with Style Dictionary
- CSS variable implementation

### Example 3: Component Architecture

```
Design component structure using atomic design for my dashboard
```

Delivers:
- Breakdown of atoms, molecules, organisms needed
- Component hierarchy and relationships
- Props API design patterns
- Composition guidelines

### Example 4: Accessibility Audit

```
Ensure WCAG 2.1 compliance for my button components
```

Checks:
- Color contrast ratios
- Keyboard navigation support
- ARIA attributes
- Focus states
- Screen reader announcements

### Example 5: Theming Implementation

```
Implement theming with dark mode using CSS variables
```

Provides:
- CSS custom property structure
- Light/dark theme definitions
- Theme switching logic
- Component integration patterns

## Triggers

The skill activates on these common phrases:

| Trigger Phrase | What It Does |
|---------------|--------------|
| "Create a design system" | Full design system setup |
| "Set up design tokens" | Token structure and implementation |
| "Design component structure" | Atomic design architecture |
| "Ensure WCAG compliance" | Accessibility guidelines and patterns |
| "Implement dark mode" | Theming and dark mode support |
| "Component architecture" | Component organization patterns |
| "Accessibility guidelines" | WCAG 2.1 AA compliance |

## Output Examples

### Design Tokens Output
Complete JSON structure with:
- Color primitives (50-950 scale for each hue)
- Semantic color tokens mapped to primitives
- Typography scale (xs to 5xl)
- Spacing scale (0 to 24)
- Border radius and shadow tokens

### Component Architecture Output
- Atomic design hierarchy diagram
- Component inventory by category
- Props interface definitions
- Implementation examples with TypeScript
- Accessibility notes for each component

### Theming Output
- Theme structure interface
- Light and dark theme definitions
- CSS variable mapping
- Theme provider setup
- Component integration patterns

### Accessibility Checklist Output
- Color contrast validation results
- Keyboard navigation requirements
- ARIA attribute recommendations
- Screen reader testing notes
- Focus management patterns

## Design Philosophy

The skill is built on four core principles:

1. **Consistency Over Creativity**: Predictable patterns reduce cognitive load and help users learn once, apply everywhere

2. **Accessible by Default**: WCAG 2.1 Level AA compliance minimum, keyboard navigation built-in, screen reader support from the start

3. **Scalable and Maintainable**: Design tokens enable global changes, component composition reduces duplication

4. **Developer-Friendly**: Clear API contracts, comprehensive documentation, easy to integrate and customize

## Integration

Works seamlessly with popular tools and frameworks:
- **React/TypeScript**: Primary target with complete TypeScript support
- **Style Dictionary**: Compatible token format for multi-platform output
- **Tailwind CSS**: Design token mapping to Tailwind config
- **Styled Components**: Theme provider integration
- **Storybook**: Documentation templates and story patterns
- **Figma**: Token naming aligned with Figma variables

## Related Skills

- `landing-page-guide-v2`: Uses design system principles for landing pages
- `nextjs15-init`: Can initialize projects with design system structure
- `mui`: Material-UI specific patterns (alternative approach)

## License

MIT

## Version

1.0.0