setup-design-system

设计系统工作流

使用 Tailwind CSS 和 shadcn/ui 初始化或扩展项目的设计系统，并构建无障碍、风格一致的 UI 组件。

步骤 0：确认功能分支

确保当前位于基于最新 main 的功能分支上：

git fetch origin main

如果当前位于 main，请创建新的功能分支：

git checkout -b feature/design-system origin/main

如果当前已位于功能分支，请 rebase 到最新的 origin/main：

git status --porcelain

如果工作区有未提交的更改，请在 rebase 前 stash：

git stash push -m "setup-design-system: stash before rebase"
git rebase origin/main
git stash pop

如果工作区干净，请直接 rebase：

git rebase origin/main

步骤 1：评估当前状态

检查是否已有设计系统：

• 查找 packages/ui/ 目录结构
• 检查 shadcn/ui 配置（components.json）
• 检查 Tailwind 配置（v4 中检查 src/index.css 的 @theme 指令，或 v3 中检查 tailwind.config.*）
• 识别现有组件及其模式
• 检查设计令牌（颜色、间距、排版定义）

询问用户：

• 是要初始化新的设计系统，还是要扩展现有设计系统？
• 如果是扩展：需要哪些组件或模式？
• 是否有可供参考的品牌指南、调色板或 Figma 设计？
• 是否需要支持深色模式？

步骤 2：产品委员会设计评审（适用于初始化或重大变更）

如果要初始化设计系统或进行重大结构性变更，请启用产品委员会的部分成员：

模型选择：请参阅 README.md 中的模型选择部分，了解如何将 Agent 模型规格映射到 Task 工具参数。

设计负责人（负责人）——咨询：ui-design

• 品牌形象：调色板、排版、视觉语言
• 组件层级：基础组件与组合组件
• 设计令牌：令牌架构（颜色、间距、排版、阴影）
• 建议：设计系统结构与原则

前端专家——咨询：frontend-mobile-development

• 技术架构：组件库结构、构建流水线
• 框架集成：与 Vite + React 19 的兼容性、tree-shaking
• 建议：实现模式、工具选择

产品策略师

• 面向用户的优先级：哪些组件应优先开发？
• 品牌一致性：是否符合产品愿景？
• 建议：设计系统投入的优先级

检查点：向用户展示设计系统架构提案。开始构建前，等待用户批准结构和令牌定义。

步骤 3：设计系统基础设施

如果要初始化新的设计系统：

调用 /ui-design:design-system-setup 获取初始化指导。

搭建基础：

设计令牌

• 调色板（主色、辅助色、中性色、语义色：成功/警告/错误/信息）
• 排版比例（字体系列、字号、字重、行高）
• 间距比例（一致的间距值：0、1、2、3、4、6、8、12、16、24、32、48、64）
• 边框圆角（无、sm、md、lg、xl、full）
• 阴影（sm、md、lg、xl）
• 断点（sm、md、lg、xl、2xl）

Tailwind 配置 使用 /frontend-mobile-development:tailwind-design-system：

• 使用设计令牌扩展 Tailwind 主题
• 使用项目专属的主题颜色配置 shadcn/ui
• 设置 CSS 自定义属性，以支持运行时主题切换
• 配置深色模式策略（基于 class 或媒体查询）

组件结构

packages/ui/src/
├── components/
│   ├── primitives/    # Button, Input, Badge, Label, Switch
│   ├── layout/        # Container, Grid, Stack, Spacer, Divider
│   ├── navigation/    # Navbar, Sidebar, Breadcrumb, Tabs
│   ├── feedback/      # Alert, Toast, Modal, Dialog, Skeleton
│   ├── data-display/  # Card, Table, List, Avatar, Tooltip
│   └── forms/         # Form, FormField, Select, Checkbox, Radio
├── tokens/            # Design token definitions
├── hooks/             # Shared UI hooks (useMediaQuery, useTheme)
└── utils/             # UI utilities (cn, cva variants)

如果要扩展现有设计系统：

添加新组件前，先阅读现有模式和约定。与既定的 API 模式保持一致。

步骤 4：构建组件

对每个所需组件，遵循以下流程：

4a. 组件设计

调用 /ui-design:create-component 获取组件创建指导。

定义组件 API：

• Props 接口：使用 TypeScript 类型定义所有可配置选项
• 变体：尺寸、颜色和样式变体（使用 cva 或 tailwind-variants）
• 默认值：合理且开箱即用的默认值
• 组合方式：组件如何与子组件协作

4b. 实现

构建每个组件时，请做到：

• 使用完整的 TypeScript 类型（不使用 any 类型）
• 使用 Tailwind CSS 样式，并遵循 shadcn/ui 模式
• 使用 React.forwardRef 转发 ref
• 使用 cn() 工具函数合并 className 属性，以支持样式覆盖
• 使用 Tailwind 断点实现响应式行为

4c. 无障碍

每个组件都必须包含：

• 语义化 HTML 元素（button、nav、dialog 等）
• ARIA 属性（aria-label、aria-describedby、role 等）
• 键盘导航（视情况支持 Tab、Enter、Escape、方向键）
• 焦点管理（可见的焦点环、模态框的焦点陷阱）
• 对动态内容进行屏幕阅读器播报
• 满足 WCAG AA 的颜色对比度（文本为 4.5:1，大号文本为 3:1）
• 交互元素的触控目标最小尺寸（44x44px）

4d. 测试

为每个组件编写：

• 渲染测试：组件可以无错误地渲染
• 属性测试：所有变体和属性组合都能正确渲染
• 交互测试：点击、悬停和键盘交互均正常
• 无障碍测试：存在 ARIA 属性，且键盘导航正常

检查点：完成每个组件（或一批相关组件）后，将实现呈现给用户进行视觉审查。展示组件 API、变体和无障碍功能。

第 5 步：无障碍审计

构建完所有组件后，进行全面的无障碍审计：

对所有新增或修改的组件调用 /ui-design:accessibility-audit。

检查以下方面：

• 符合 WCAG 2.1 AA（最低标准）
• 颜色对比度：所有文本都符合对比度要求
• 键盘导航：可通过键盘完成所有操作
• 屏幕阅读器：正确播报所有交互元素
• 焦点管理：焦点顺序合理，焦点指示器清晰可见
• 动效：遵循 prefers-reduced-motion 媒体查询
• 触控目标：移动端最小尺寸为 44x44px

检查点：呈现无障碍审计结果。由用户确认当前无障碍状况，或提出修改要求。

第 6 步：设计审查

调用 /ui-design:design-review，审查整体设计系统的以下方面：

• 一致性：所有组件都遵循相同的模式
• 命名：属性、变体和 CSS 类遵循约定
• API 模式：各组件的属性接口保持一致
• 视觉协调性：组件风格协调统一
• 完整性：涵盖常见用例

解决审查中发现的所有问题。

第 7 步：文档

为设计系统编写文档：

• 组件目录：每个组件的属性表、用法示例以及推荐和不推荐的模式
• 设计令牌：颜色、字体排版和间距的完整参考
• 无障碍指南：各组件的无障碍说明和测试说明
• 入门指南：如何在应用中导入和使用组件

第 8 步：提交

使用 Conventional Commits 格式提交：

新建设计系统：

feat(ui): initialize design system with core components

新增组件：

feat(ui): add <component-name> component

修改设计令牌：

feat(ui): update design tokens for <change-description>

第 9 步：交接 — 到此为止

注意

**本技能的工作到此结束。**请勿继续创建拉取请求、推送到远程仓库或运行代码审查。这些属于其他技能，有各自的工作流和检查点。

向用户说明下一步：

• 推荐：提交前运行 /review-code，从多个角度审查质量和无障碍性
• 如果要构建使用这些组件的功能：继续运行 /build-feature 实现该功能，然后运行 /review-code
• 如果这是独立的设计系统工作：运行 /review-code → /submit-pr

提示

流程：/plan-feature → /build-feature 或 /build-api → /review-code → /submit-pr

可以在流程中的任意阶段运行 /setup-design-system，也可以单独运行。你目前正在此步骤；准备就绪后，继续运行 /review-code。

请勿在本技能中推送分支、创建 PR 或调用 /submit-pr。