frontend-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Design System

前端设计系统

Build modern, accessible, responsive web applications using industry-leading design systems and best practices.

使用行业领先的设计系统与最佳实践，构建现代、可访问、响应式的Web应用。

Core Capabilities

核心能力

1. Design System Selection

1. 设计系统选型

When users ask "which UI library should I use" or need design system guidance:

Read the comparison guide:

references/design-system-comparison.md

Decision workflow:

Identify project requirements (bundle size, customization, speed)
Review comparison table for best match
Provide installation commands
Recommend component set for the use case

Quick recommendations:

Todo apps / Modern SaaS: shadcn/ui + Tailwind
Quick prototypes: Chakra UI or Mantine
Enterprise dashboards: Material UI or Ant Design
Custom designs: Headless UI + Tailwind
TypeScript-heavy: Mantine

当用户询问「我应该使用哪个UI库」或需要设计系统指导时：

阅读对比指南：

references/design-system-comparison.md

决策流程：

明确项目需求（包体积、定制化程度、开发速度）
查看对比表格选择最匹配的方案
提供安装命令
根据使用场景推荐组件集

快速推荐：

待办应用/现代SaaS： shadcn/ui + Tailwind
快速原型： Chakra UI 或 Mantine
企业级仪表盘： Material UI 或 Ant Design
自定义设计： Headless UI + Tailwind
重度TypeScript项目： Mantine

2. Responsive Layout Design

2. 响应式布局设计

When users need mobile-friendly layouts or responsive components:

Read the patterns guide:

references/responsive-design-patterns.md

Core principles:

Always use mobile-first approach
Follow standard breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)

Use grid for card layouts:

grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3

Use flexbox for navigation:
```
flex flex-col md:flex-row
```
Scale typography:
```
text-sm md:text-base lg:text-lg
```

当用户需要移动端友好的布局或响应式组件时：

阅读模式指南：

references/responsive-design-patterns.md

核心原则：

始终采用移动端优先的设计思路
遵循标准断点：sm (640px)、md (768px)、lg (1024px)、xl (1280px)

使用Grid实现卡片布局：

grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3

使用Flexbox实现导航：
```
flex flex-col md:flex-row
```
缩放排版：
```
text-sm md:text-base lg:text-lg
```

3. Tailwind CSS Patterns

3. Tailwind CSS 实践模式

When building with Tailwind CSS:

Read Tailwind patterns:

references/tailwind-patterns.md

Common patterns to apply:

Cards:

rounded-lg border bg-card text-card-foreground shadow-sm p-6

Buttons:

inline-flex items-center justify-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90

Inputs:

flex h-10 w-full rounded-md border border-input bg-background px-3 py-2

Dark mode:

bg-white dark:bg-slate-950 text-slate-900 dark:text-slate-50

使用Tailwind CSS构建时：

阅读Tailwind模式文档：

references/tailwind-patterns.md

常用应用模式：

卡片：

rounded-lg border bg-card text-card-foreground shadow-sm p-6

按钮：

inline-flex items-center justify-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90

输入框：

flex h-10 w-full rounded-md border border-input bg-background px-3 py-2

深色模式：

bg-white dark:bg-slate-950 text-slate-900 dark:text-slate-50

4. shadcn/ui Components

4. shadcn/ui 组件使用

When using shadcn/ui (recommended for most projects):

Read component reference:

references/shadcn-components.md

Essential components for todo apps:

bash

npx shadcn-ui@latest add button card input form dialog badge tabs checkbox

Use provided templates:

Task card:
```
assets/todo-card-template.tsx
```
Task form:
```
assets/task-form-template.tsx
```

Pattern: Compose components

tsx

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
import { Button } from "@/components/ui/button"

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Content</p>
    <Button>Action</Button>
  </CardContent>
</Card>

当用户选择shadcn/ui（推荐用于大多数项目）时：

阅读组件参考文档：

references/shadcn-components.md

待办应用必备组件：

bash

npx shadcn-ui@latest add button card input form dialog badge tabs checkbox

使用提供的模板：

任务卡片：
```
assets/todo-card-template.tsx
```
任务表单：
```
assets/task-form-template.tsx
```

组件组合模式：

tsx

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
import { Button } from "@/components/ui/button"

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Content</p>
    <Button>Action</Button>
  </CardContent>
</Card>

5. Material UI Implementation

5. Material UI 实现方案

When users choose Material UI:

Read MUI patterns:

references/material-ui-patterns.md

Setup theme first:

tsx

import { ThemeProvider, createTheme } from '@mui/material/styles'

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
  },
})

<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

Use sx prop for styling:

tsx

<Box sx={{ p: 2, mt: 4, borderRadius: 2 }}>

当用户选择Material UI时：

阅读MUI实践模式：

references/material-ui-patterns.md

先配置主题：

tsx

import { ThemeProvider, createTheme } from '@mui/material/styles'

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
  },
})

<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

使用sx属性进行样式定制：

tsx

<Box sx={{ p: 2, mt: 4, borderRadius: 2 }}>

6. Chakra UI Implementation

6. Chakra UI 实现方案

When users choose Chakra UI:

Read Chakra patterns:

references/chakra-ui-patterns.md

Key advantages:

Style props:

<Box bg="blue.500" p={4} borderRadius="md">

Dark mode built-in:
```
useColorMode()
```
,
```
useColorModeValue()
```
Responsive arrays:
```
<Box w={['100%', '50%', '33%']}>
```

Layout with Stack:

tsx

<VStack spacing={4} align="stretch">
  <Card>Item 1</Card>
  <Card>Item 2</Card>
</VStack>

当用户选择Chakra UI时：

阅读Chakra实践模式：

references/chakra-ui-patterns.md

核心优势：

样式属性：

<Box bg="blue.500" p={4} borderRadius="md">

内置深色模式：
```
useColorMode()
```
、
```
useColorModeValue()
```
响应式数组：
```
<Box w={['100%', '50%', '33%']}>
```

使用Stack布局：

tsx

<VStack spacing={4} align="stretch">
  <Card>Item 1</Card>
  <Card>Item 2</Card>
</VStack>

7. Form Design & Validation

7. 表单设计与验证

When building forms with validation:

Use template:

assets/task-form-template.tsx

Pattern: React Hook Form + Zod

tsx

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"

const schema = z.object({
  title: z.string().min(3),
})

const form = useForm({
  resolver: zodResolver(schema),
})

Always include:

Field labels (
```
<FormLabel>
```
)
Error messages (
```
<FormMessage>
```
)
Helper text (
```
<FormDescription>
```
)
Disabled states for loading
Proper accessibility attributes

构建带验证的表单时：

使用模板：

assets/task-form-template.tsx

React Hook Form + Zod 模式：

tsx

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"

const schema = z.object({
  title: z.string().min(3),
})

const form = useForm({
  resolver: zodResolver(schema),
})

必须包含的元素：

字段标签（
```
<FormLabel>
```
）
错误提示（
```
<FormMessage>
```
）
辅助文本（
```
<FormDescription>
```
）
加载状态下的禁用状态
符合规范的无障碍属性

8. Accessibility Patterns

8. 无障碍设计模式

Always apply:

Semantic HTML:
```
<button>
```
not
```
<div onClick>
```
ARIA labels:
```
aria-label="Delete task"
```
Screen reader text:
```
<span className="sr-only">Hidden</span>
```
Keyboard navigation: Focus states, tab order
Color contrast: WCAG AA minimum (4.5:1)
Touch targets: Minimum 44x44px

必须遵循的规则：

使用语义化HTML：用
```
<button>
```
而非
```
<div onClick>
```
ARIA标签：
```
aria-label="Delete task"
```
屏幕阅读器文本：
```
<span className="sr-only">Hidden</span>
```
键盘导航：焦点状态、Tab键顺序
颜色对比度：符合WCAG AA最低标准（4.5:1）
触摸目标：最小44x44px

9. Dark Mode Implementation

9. 深色模式实现

Tailwind approach:

tsx

<div className="bg-white dark:bg-slate-950">
<p className="text-slate-900 dark:text-slate-50">

// Theme toggle
import { useTheme } from "next-themes"
const { theme, setTheme } = useTheme()

Chakra UI approach:

tsx

const { colorMode, toggleColorMode } = useColorMode()
const bg = useColorModeValue('white', 'gray.800')

Material UI approach:

tsx

const theme = createTheme({
  palette: {
    mode: prefersDarkMode ? 'dark' : 'light',
  },
})

Tailwind 实现方式：

tsx

<div className="bg-white dark:bg-slate-950">
<p className="text-slate-900 dark:text-slate-50">

// 主题切换
import { useTheme } from "next-themes"
const { theme, setTheme } = useTheme()

Chakra UI 实现方式：

tsx

const { colorMode, toggleColorMode } = useColorMode()
const bg = useColorModeValue('white', 'gray.800')

Material UI 实现方式：

tsx

const theme = createTheme({
  palette: {
    mode: prefersDarkMode ? 'dark' : 'light',
  },
})

10. Component Templates

10. 组件模板使用

When building todo apps or similar UIs:

Available templates:

Task Card (
```
assets/todo-card-template.tsx
```
)
- Includes: Checkbox, priority badges, tags, due dates, dropdown menu
- Variants: Card view, list item view
- Features: Hover states, accessibility
Task Form (
```
assets/task-form-template.tsx
```
)
- Includes: Title, description, priority, due date, tags
- Validation: React Hook Form + Zod
- Variants: Dialog form, inline form

Usage:

bash

undefined

构建待办应用或类似UI时：

可用模板：

任务卡片（
```
assets/todo-card-template.tsx
```
）
- 包含：复选框、优先级徽章、标签、截止日期、下拉菜单
- 变体：卡片视图、列表项视图
- 特性：悬停状态、无障碍支持
任务表单（
```
assets/task-form-template.tsx
```
）
- 包含：标题、描述、优先级、截止日期、标签
- 验证：React Hook Form + Zod
- 变体：弹窗表单、内联表单

使用方法：

bash

undefined

Read template

读取模板

Read: assets/todo-card-template.tsx

Adapt to project's design system

适配项目的设计系统

Modify imports and styling as needed

根据需要修改导入和样式

undefined

undefined

Workflow Guide

工作流程指南

For New Projects

新项目流程

Select Design System
- Read:
```
references/design-system-comparison.md
```
- Consider: Bundle size, customization needs, team experience
- Provide recommendation with rationale
Setup Theme/Config
- Install dependencies
- Configure theme (colors, typography, spacing)
- Setup dark mode if needed
Build Core Components
- Start with layout (Container, Grid)
- Add navigation
- Implement forms
- Create card/list components
Apply Responsive Patterns
- Read:
```
references/responsive-design-patterns.md
```
- Mobile-first breakpoints
- Test at key viewports
Add Accessibility
- Semantic HTML
- ARIA labels
- Keyboard navigation
- Screen reader support

选择设计系统
- 阅读：
```
references/design-system-comparison.md
```
- 考虑因素：包体积、定制化需求、团队经验
- 提供带有理由的推荐方案
配置主题/基础设置
- 安装依赖
- 配置主题（颜色、排版、间距）
- 按需设置深色模式
构建核心组件
- 从布局开始（容器、Grid）
- 添加导航组件
- 实现表单
- 创建卡片/列表组件
应用响应式模式
- 阅读：
```
references/responsive-design-patterns.md
```
- 采用移动端优先的断点设置
- 在关键视口进行测试
添加无障碍支持
- 语义化HTML
- ARIA标签
- 键盘导航
- 屏幕阅读器支持

For Todo App Specifically

待办应用专属流程

Choose design system (recommend shadcn/ui)

Install core components:

bash

npx shadcn-ui@latest add button card input form dialog badge tabs checkbox

Use templates:

Copy
```
assets/todo-card-template.tsx
```
Copy
```
assets/task-form-template.tsx
```

Customize colors/spacing to match brand

Add responsive layouts from

references/responsive-design-patterns.md

Implement dark mode

选择设计系统（推荐shadcn/ui）

安装核心组件：

bash

npx shadcn-ui@latest add button card input form dialog badge tabs checkbox

使用模板：

复制
```
assets/todo-card-template.tsx
```
复制
```
assets/task-form-template.tsx
```

自定义颜色/间距以匹配品牌风格

从

references/responsive-design-patterns.md

中添加响应式布局

实现深色模式

For Existing Projects

现有项目优化流程

Audit current design system
Identify pain points (bundle size, customization limits, etc.)
If migrating:
- Read comparison guide for alternatives
- Plan incremental migration
- Start with new components
If optimizing:
- Apply patterns from references
- Improve responsiveness
- Add accessibility features

审计当前设计系统
识别痛点（包体积、定制化限制等）
如需迁移：
- 阅读对比指南选择替代方案
- 规划增量式迁移
- 从新组件开始迁移
如需优化：
- 应用参考文档中的模式
- 提升响应式体验
- 添加无障碍功能

Quick Reference

快速参考

Common Tasks

常见任务处理

"Make this responsive" → Read:

references/responsive-design-patterns.md

→ Apply mobile-first breakpoints → Use grid/flexbox patterns

"Add dark mode" → For Tailwind: Use

dark:

prefix → For Chakra: Use

useColorMode()

→ For MUI: Configure theme palette mode

"Which UI library?" → Read:

references/design-system-comparison.md

→ Provide recommendation based on requirements

"Build a form with validation" → Use:

assets/task-form-template.tsx

→ Adapt to project's design system → Add custom fields as needed

"Create task card" → Use:

assets/todo-card-template.tsx

→ Modify for specific features

「让这个适配移动端」 → 阅读：

references/responsive-design-patterns.md

→ 应用移动端优先的断点设置 → 使用Grid/Flexbox模式

「添加深色模式」 → Tailwind项目：使用

dark:

前缀 → Chakra项目：使用

useColorMode()

→ MUI项目：配置主题调色板模式

「应该用哪个UI库？」 → 阅读：

references/design-system-comparison.md

→ 根据需求提供推荐方案

「构建带验证的表单」 → 使用：

assets/task-form-template.tsx

→ 适配项目的设计系统 → 按需添加自定义字段

「创建任务卡片」 → 使用：

assets/todo-card-template.tsx

→ 根据特定功能进行修改

Design Tokens Reference

设计令牌参考

Spacing scale: 2, 4, 6, 8, 12, 16, 24, 32, 48, 64 (px in 4px increments)

Typography scale: xs (12px), sm (14px), base (16px), lg (18px), xl (20px), 2xl (24px), 3xl (30px)

Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)

Border radius: sm (4px), md (8px), lg (16px), full (9999px)

间距尺度： 2、4、6、8、12、16、24、32、48、64（以4px为增量的像素值）

排版尺度： xs (12px)、sm (14px)、base (16px)、lg (18px)、xl (20px)、2xl (24px)、3xl (30px)

断点： sm (640px)、md (768px)、lg (1024px)、xl (1280px)、2xl (1536px)

圆角： sm (4px)、md (8px)、lg (16px)、full (9999px)

Anti-Patterns to Avoid

需避免的反模式

❌ Desktop-first responsive design (always start mobile) ❌ Hardcoded colors (use design tokens/theme) ❌ Div soup (use semantic HTML) ❌ Missing accessibility (always include ARIA, focus states) ❌ Inconsistent spacing (use design system scale) ❌ Non-interactive elements with onClick (use button/a) ❌ Tiny touch targets on mobile (<44px)

❌ 桌面端优先的响应式设计（始终从移动端开始） ❌ 硬编码颜色（使用设计令牌/主题） ❌ 冗余Div嵌套（使用语义化HTML） ❌ 缺失无障碍支持（始终包含ARIA、焦点状态） ❌ 不一致的间距（使用设计系统尺度） ❌ 非交互元素使用onClick（使用button/a标签） ❌ 移动端触摸目标过小（<44px）

Resources Summary

资源汇总

Tailwind patterns:
```
references/tailwind-patterns.md
```
shadcn/ui components:
```
references/shadcn-components.md
```
Material UI patterns:
```
references/material-ui-patterns.md
```
Chakra UI patterns:
```
references/chakra-ui-patterns.md
```
Design system comparison:
```
references/design-system-comparison.md
```

Responsive patterns:

references/responsive-design-patterns.md

Task card template:
```
assets/todo-card-template.tsx
```
Task form template:
```
assets/task-form-template.tsx
```

Tailwind实践模式：
```
references/tailwind-patterns.md
```
shadcn/ui组件：
```
references/shadcn-components.md
```
Material UI实践模式：
```
references/material-ui-patterns.md
```
Chakra UI实践模式：
```
references/chakra-ui-patterns.md
```
设计系统对比：
```
references/design-system-comparison.md
```

响应式模式：

references/responsive-design-patterns.md

任务卡片模板：
```
assets/todo-card-template.tsx
```
任务表单模板：
```
assets/task-form-template.tsx
```