design-system-foundation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

启动新的React Native应用
启动新的Next.js项目
为新产品搭建设计系统
从零开始构建组件库
需要设计令牌和主题系统

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)

重构现有项目（请改用
```
ui-refactoring-workflow
```
）
添加单个组件（请改用
```
component-library-scaffolder
```
）
仅需生成文档（请改用
```
design-documentation-generator
```
）

Foundation Setup Process

基础搭建流程

Phase 1: Design Token Creation

阶段1：设计令牌创建

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:

typescript

// 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,
}

创建完整的令牌系统，包含：

颜色：语义化颜色系统（品牌色、UI色、反馈色）
排版：字体族、字号、字重、行高
间距：统一的间距刻度
阴影：层级阴影系统
圆角：圆角刻度
动画：时长与缓动函数

示例令牌结构：

typescript

// 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

阶段2：项目结构搭建

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

按照原子设计理念创建规整的文件夹结构：

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/           # 基础构建块
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Text/
│   │   └── ...
│   ├── molecules/       # 简单组件组合
│   │   ├── FormField/
│   │   ├── Card/
│   │   └── ...
│   ├── organisms/       # 复杂组件
│   │   ├── Header/
│   │   ├── Form/
│   │   └── ...
│   └── templates/       # 页面布局
│       ├── PageTemplate/
│       └── ...
│
├── design-system/
│   └── [带README.md的组件文件夹]
│
└── docs/
    ├── DESIGN_SYSTEM.md
    ├── COMPONENT_GUIDELINES.md
    ├── STYLE_GUIDE.md
    ├── ACCESSIBILITY.md
    └── DESIGN_TOKENS.md

Phase 3: Theme System Setup

阶段3：主题系统配置

For React Native:

typescript

// 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:

typescript

// 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

针对React Native：

typescript

// 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
}

针对搭配Tailwind的Next.js：

typescript

// 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

阶段4：文档生成

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

自动生成以下文档：

DESIGN_SYSTEM.md
- 设计理念
- 令牌系统概述
- 组件架构
- 使用指南
COMPONENT_GUIDELINES.md
- 组件创建方法
- 命名规范
- 文件结构
- 测试要求
STYLE_GUIDE.md
- 视觉设计原则
- 颜色使用规范
- 排版指南
- 间距系统说明
ACCESSIBILITY.md
- WCAG标准
- 测试清单
- 通用模式
- 最佳实践
DESIGN_TOKENS.md
- 完整令牌参考
- 使用示例
- 迁移指南

Phase 5: Preset Application

阶段5：预设样式应用

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.

用户可选择要应用的设计预设：

minimalist-modern（极简现代）
bold-brutalist（粗野主义）
soft-neumorphic（软拟态）
glass-aesthetic（玻璃态）
timeless-classic（经典永恒）
bleeding-edge-experimental（前沿实验性）

所有令牌将自动配置为匹配所选预设。

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
```

基础搭建完成后，使用
```
component-library-scaffolder
```
创建基础组件
更新文档时，使用
```
design-documentation-generator
```
选择预设时，使用
```
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

完成前请验证：

✓ 所有令牌文件已创建
✓ 文件夹结构已搭建
✓ 主题提供者已配置
✓ 文档已生成
✓ 设计预设已应用
✓ TypeScript类型已定义
✓ 示例组件可与令牌正常配合使用

Common Patterns

通用模式

Using Tokens in Components

在组件中使用令牌

React Native:

typescript

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:

tsx

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>
  )
}

React Native：

typescript

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>
  )
}

搭配Tailwind的Next.js：

tsx

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

使用该基础方案的团队反馈：

组件开发速度提升70%
样式不一致问题减少90%
设计令牌全面覆盖
设计预设切换便捷
开发者体验提升