frontend-design-system

前端设计系统

使用业界领先的设计系统和最佳实践，构建现代、无障碍且响应式的 Web 应用。

核心能力

1. 设计系统选择

当用户询问“我应该使用哪个 UI 库”，或需要设计系统方面的指导时：

阅读对比指南：

references/design-system-comparison.md

决策流程：

1. 确定项目需求（包体积、可定制性、速度）
2. 查看对比表，选择最合适的方案
3. 提供安装命令
4. 根据使用场景推荐组件集

快速建议：

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

2. 响应式布局设计

当用户需要适配移动设备的布局或响应式组件时：

阅读模式指南：

references/responsive-design-patterns.md

核心原则：

• 始终采用移动优先的方法
• 遵循标准断点：sm (640px)、md (768px)、lg (1024px)、xl (1280px)
• 卡片布局使用网格：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 模式

使用 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 组件

使用 shadcn/ui 时（大多数项目推荐）：

阅读组件参考：

references/shadcn-components.md

待办事项应用的必备组件：

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

使用提供的模板：

• 任务卡片：assets/todo-card-template.tsx
• 任务表单：assets/task-form-template.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 实现

当用户选择 Material UI 时：

阅读 MUI 模式：

references/material-ui-patterns.md

先设置主题：

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

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

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

使用 sx 属性进行样式设置：

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

6. Chakra UI 实现

当用户选择 Chakra UI 时：

阅读 Chakra 模式：

references/chakra-ui-patterns.md

主要优势：

• 样式属性：<Box bg="blue.500" p={4} borderRadius="md">
• 内置深色模式：useColorMode()、useColorModeValue()
• 响应式数组：<Box w={['100%', '50%', '33%']}>

使用 Stack 布局：

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

7. 表单设计与验证

构建带验证的表单时：

使用模板：

assets/task-form-template.tsx

模式：React Hook Form + Zod

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. 无障碍模式

务必应用：

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

9. 深色模式实现

Tailwind 方案：

<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 方案：

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

Material UI 方案：

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

10. 组件模板

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

可用模板：

1. 任务卡片（assets/todo-card-template.tsx）

   • 包含：复选框、优先级徽章、标签、截止日期、下拉菜单
   • 变体：卡片视图、列表项视图
   • 特性：悬停状态、无障碍支持

2. 任务表单（assets/task-form-template.tsx）

   • 包含：标题、描述、优先级、截止日期、标签
   • 验证：React Hook Form + Zod
   • 变体：对话框表单、内联表单

用法：

# Read template
Read: assets/todo-card-template.tsx

# Adapt to project's design system
# Modify imports and styling as needed

工作流指南

新项目

1. 选择设计系统

   • 阅读：references/design-system-comparison.md
   • 考虑：包体积、自定义需求、团队经验
   • 提供建议并说明理由

2. 设置主题/配置

   • 安装依赖
   • 配置主题（颜色、排版、间距）
   • 如有需要，设置深色模式

3. 构建核心组件

   • 从布局开始（Container、Grid）
   • 添加导航
   • 实现表单
   • 创建卡片/列表组件

4. 应用响应式模式

   • 阅读：references/responsive-design-patterns.md
   • 采用移动端优先的断点
   • 在关键视口下进行测试

5. 添加无障碍支持

   • 语义化 HTML
   • ARIA 标签
   • 键盘导航
   • 屏幕阅读器支持

针对待办事项应用

1. 选择设计系统（推荐 shadcn/ui）
2. 安装核心组件：

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

3. 使用模板：
   • 复制 assets/todo-card-template.tsx
   • 复制 assets/task-form-template.tsx
4. 自定义颜色/间距，使其符合品牌风格
5. 添加 references/responsive-design-patterns.md 中的响应式布局
6. 实现深色模式

现有项目

1. 审核当前设计系统
2. 找出痛点（包体积、自定义限制等）
3. 如果要迁移：
   • 阅读对比指南，了解替代方案
   • 规划渐进式迁移
   • 从新组件开始
4. 如果要优化：
   • 应用参考资料中的模式
   • 改善响应性
   • 添加无障碍功能

快速参考

常见任务

“让它具有响应式” → 阅读：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 → 根据具体功能进行修改

设计令牌参考

间距比例： 2、4、6、8、12、16、24、32、48、64（单位为 px，按 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）

应避免的反模式

❌ 桌面端优先的响应式设计（始终从移动端开始） ❌ 硬编码颜色（使用设计令牌/主题） ❌ 滥用 div（使用语义化 HTML） ❌ 缺少无障碍支持（始终包含 ARIA 和焦点状态） ❌ 间距不一致（使用设计系统比例） ❌ 带有 onClick 的非交互元素（使用 button/a） ❌ 移动端触控目标过小（<44px）

资源摘要

• 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