Design System Foundation
Overview
Establishes complete design system foundation for greenfield projects, including token system, folder structure, and base component architecture.
When to Use
-
Starting new React Native app
-
Starting new Next.js project
-
Establishing design system for new product
-
Setting up component library from scratch
-
Need design tokens and theme system
When NOT to Use
-
Refactoring existing projects (use ui-refactoring-workflow instead)
-
Adding single component (use component-library-scaffolder instead)
-
Just documentation (use design-documentation-generator instead)
Foundation Setup Process
Phase 1: Design Token Creation
Creates complete token system with:
-
Colors: Semantic color system (brand, UI, feedback)
-
Typography: Font families, sizes, weights, line heights
-
Spacing: Consistent spacing scale
-
Shadows: Elevation system
-
Border Radius: Rounding scale
-
Animation: Timing and easing functions
Example Token Structure:
// tokens/colors.ts export const colors = { // Brand colors brand: { primary: '#0066FF', secondary: '#00D9FF', accent: '#FF3366', },
// UI colors ui: { background: { primary: '#FFFFFF', secondary: '#F8F9FA', tertiary: '#E9ECEF', }, border: { light: '#DEE2E6', medium: '#CED4DA', dark: '#ADB5BD', }, text: { primary: '#212529', secondary: '#495057', tertiary: '#6C757D', inverse: '#FFFFFF', } },
// Feedback colors feedback: { success: '#28A745', warning: '#FFC107', error: '#DC3545', info: '#17A2B8', } }
// tokens/spacing.ts export const spacing = { 0: 0, 1: 4, 2: 8, 3: 12, 4: 16, 5: 20, 6: 24, 8: 32, 10: 40, 12: 48, 16: 64, 20: 80, 24: 96, }
// tokens/typography.ts export const typography = { fontFamily: { sans: 'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto', mono: 'JetBrains Mono, Menlo, Monaco, "Courier New"', }, fontSize: { xs: 12, sm: 14, base: 16, lg: 18, xl: 20, '2xl': 24, '3xl': 30, '4xl': 36, '5xl': 48, }, fontWeight: { light: '300', normal: '400', medium: '500', semibold: '600', bold: '700', black: '900', }, lineHeight: { tight: 1.25, normal: 1.5, relaxed: 1.75, } }
// tokens/shadows.ts export const shadows = { sm: { shadowColor: '#000', shadowOffset: { width: 0, height: 1 }, shadowOpacity: 0.05, shadowRadius: 2, elevation: 1, }, md: { shadowColor: '#000', shadowOffset: { width: 0, height: 4 }, shadowOpacity: 0.07, shadowRadius: 6, elevation: 3, }, lg: { shadowColor: '#000', shadowOffset: { width: 0, height: 10 }, shadowOpacity: 0.1, shadowRadius: 15, elevation: 6, }, }
// tokens/radius.ts export const radius = { sm: 4, md: 8, lg: 12, xl: 16, full: 9999, }
Phase 2: Project Structure
Creates organized folder structure following atomic design:
src/ ├── theme/ │ ├── tokens/ │ │ ├── colors.ts │ │ ├── spacing.ts │ │ ├── typography.ts │ │ ├── shadows.ts │ │ ├── radius.ts │ │ ├── animation.ts │ │ └── index.ts │ ├── ThemeProvider.tsx │ ├── useTheme.ts │ └── createTheme.ts │ ├── components/ │ ├── atoms/ # Basic building blocks │ │ ├── Button/ │ │ ├── Input/ │ │ ├── Text/ │ │ └── ... │ ├── molecules/ # Simple combinations │ │ ├── FormField/ │ │ ├── Card/ │ │ └── ... │ ├── organisms/ # Complex components │ │ ├── Header/ │ │ ├── Form/ │ │ └── ... │ └── templates/ # Page layouts │ ├── PageTemplate/ │ └── ... │ ├── design-system/ │ └── [Component folders with README.md] │ └── docs/ ├── DESIGN_SYSTEM.md ├── COMPONENT_GUIDELINES.md ├── STYLE_GUIDE.md ├── ACCESSIBILITY.md └── DESIGN_TOKENS.md
Phase 3: Theme System Setup
For React Native:
// theme/ThemeProvider.tsx import React, { createContext, useContext } from 'react' import { tokens } from './tokens'
interface Theme { colors: typeof tokens.colors spacing: typeof tokens.spacing typography: typeof tokens.typography shadows: typeof tokens.shadows radius: typeof tokens.radius }
const ThemeContext = createContext<Theme | undefined>(undefined)
export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => { const theme: Theme = { colors: tokens.colors, spacing: tokens.spacing, typography: tokens.typography, shadows: tokens.shadows, radius: tokens.radius, }
return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider> }
export const useTheme = () => { const context = useContext(ThemeContext) if (!context) { throw new Error('useTheme must be used within ThemeProvider') } return context }
For Next.js with Tailwind:
// tailwind.config.ts import type { Config } from 'tailwindcss' import { tokens } from './src/theme/tokens'
const config: Config = { content: ['./src/**/*.{js,ts,jsx,tsx}'], theme: { extend: { colors: { brand: tokens.colors.brand, ui: tokens.colors.ui, feedback: tokens.colors.feedback, }, spacing: tokens.spacing, fontSize: tokens.typography.fontSize, fontWeight: tokens.typography.fontWeight, borderRadius: tokens.radius, }, }, }
export default config
Phase 4: Documentation Generation
Automatically generates:
DESIGN_SYSTEM.md
-
Design philosophy
-
Token system overview
-
Component architecture
-
Usage guidelines
COMPONENT_GUIDELINES.md
-
How to create components
-
Naming conventions
-
File structure
-
Testing requirements
STYLE_GUIDE.md
-
Visual design principles
-
Color usage
-
Typography guidelines
-
Spacing system
ACCESSIBILITY.md
-
WCAG standards
-
Testing checklist
-
Common patterns
-
Best practices
DESIGN_TOKENS.md
-
Complete token reference
-
Usage examples
-
Migration guide
Phase 5: Preset Application
User selects design preset to apply:
-
minimalist-modern
-
bold-brutalist
-
soft-neumorphic
-
glass-aesthetic
-
timeless-classic
-
bleeding-edge-experimental
All tokens automatically configured to match selected preset.
Integration with Other Skills
-
After foundation setup, use component-library-scaffolder to create base components
-
For documentation updates, use design-documentation-generator
-
For preset selection, use design-preset-system
Quality Checklist
Before completing, verify:
-
✓ All token files created
-
✓ Folder structure established
-
✓ Theme provider configured
-
✓ Documentation generated
-
✓ Design preset applied
-
✓ TypeScript types defined
-
✓ Example components work with tokens
Common Patterns
Using Tokens in Components
React Native:
import { useTheme } from '@/theme'
const MyComponent = () => { const theme = useTheme()
return ( <View style={{ backgroundColor: theme.colors.ui.background.primary, padding: theme.spacing[4], borderRadius: theme.radius.md, ...theme.shadows.md, }}> <Text style={{ fontSize: theme.typography.fontSize.lg, fontWeight: theme.typography.fontWeight.semibold, color: theme.colors.ui.text.primary, }}> Hello World </Text> </View> ) }
Next.js with Tailwind:
const MyComponent = () => { return ( <div className="bg-ui-background-primary p-4 rounded-md shadow-md"> <h2 className="text-lg font-semibold text-ui-text-primary"> Hello World </h2> </div> ) }
Real-World Impact
Teams using this foundation report:
-
70% faster component development
-
90% reduction in style inconsistencies
-
Complete design token coverage
-
Easy design preset switching
-
Better developer experience