Back to Details

setup-design-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design System Workflow

设计系统工作流

Initialize or extend the project's design system with properly accessible, consistent UI components using Tailwind CSS and shadcn/ui.
使用Tailwind CSS和shadcn/ui初始化或扩展项目的设计系统，创建具备完善无障碍特性、风格统一的UI组件。

Step 0: Verify Feature Branch

步骤0：验证功能分支

Ensure we are on a feature branch based on the latest 
main
:
bash
git fetch origin main
If on 
main
, create a new feature branch:
bash
git checkout -b feature/design-system origin/main
If already on a feature branch, rebase onto latest 
origin/main
:
bash
git status --porcelain
If the working tree is dirty, stash before rebasing:
bash
git stash push -m "setup-design-system: stash before rebase"
git rebase origin/main
git stash pop
If the working tree is clean, rebase directly:
bash
git rebase origin/main
确保我们处于基于最新
main
分支的功能分支上：
bash
git fetch origin main
如果当前在
main
分支，创建新的功能分支：
bash
git checkout -b feature/design-system origin/main
如果已在功能分支上，将其变基到最新的
origin/main
：
bash
git status --porcelain
如果工作区有未提交的修改，先暂存再变基：
bash
git stash push -m "setup-design-system: stash before rebase"
git rebase origin/main
git stash pop
如果工作区干净，直接变基：
bash
git rebase origin/main

Step 1: Assess Current State

步骤1：评估当前状态

Check if a design system already exists:
  • Look for 
    packages/ui/
    directory structure
  • Check for shadcn/ui configuration (
    components.json
    )
  • Check Tailwind configuration (
    src/index.css
    for 
    @theme
    directives in v4, or 
    tailwind.config.*
    for v3)
  • Identify existing components and their patterns
  • Check for design tokens (colors, spacing, typography definitions)
Ask the user:
  • Initializing a new design system or extending the existing one?
  • If extending: what components or patterns are needed?
  • Any brand guidelines, color palette, or Figma designs to reference?
  • Dark mode support needed?
检查是否已存在设计系统：
  • 查找
    packages/ui/
    目录结构
  • 检查shadcn/ui配置文件（
    components.json
    ）
  • 检查Tailwind配置（v4版本查看
    src/index.css
    中的
    @theme
    指令，v3版本查看
    tailwind.config.*
    文件）
  • 识别现有组件及其设计模式
  • 检查设计令牌（颜色、间距、排版定义）
向用户确认：
  • 是要初始化新的设计系统，还是扩展现有设计系统？
  • 如果是扩展：需要新增哪些组件或设计模式？
  • 是否有品牌指南、调色板或Figma设计稿可以参考？
  • 是否需要支持深色模式？

Step 2: Product Council Design Review (for initialization or major changes)

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

If initializing the design system or making significant structural changes, activate a Product Council subset:
Model Selection: See the Model Selection section in README.md for mapping agent model specs to Task tool parameters.
如果是初始化设计系统或进行重大结构变更，需召集产品委员会相关成员：
模型选择：请查看README.md中的模型选择章节，了解Agent模型规格与任务工具参数的对应关系。

Design Lead (Lead) — consult: ui-design

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

  • Brand Identity: Color palette, typography, visual language
  • Component Hierarchy: Primitives vs composed components
  • Design Tokens: Token architecture (colors, spacing, typography, shadows)
  • Recommendations: Design system structure and principles
  • 品牌识别：调色板、排版、视觉语言
  • 组件层级：基础组件与组合组件的划分
  • 设计令牌：令牌架构（颜色、间距、排版、阴影）
  • 建议：设计系统的结构与原则

Frontend Specialist — consult: frontend-mobile-development

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

  • Technical Architecture: Component library structure, build pipeline
  • Framework Integration: Vite + React 19 compatibility, tree-shaking
  • Recommendations: Implementation patterns, tooling choices
  • 技术架构：组件库结构、构建流水线
  • 框架集成：Vite + React 19兼容性、摇树优化
  • 建议：实现模式、工具选择

Product Strategist

产品策略师

  • User-Facing Priorities: Which components are needed first?
  • Brand Consistency: Does this align with product vision?
  • Recommendations: Prioritization of design system investment
  • 用户端优先级：首先需要哪些组件？
  • 品牌一致性：是否符合产品愿景？
  • 建议：设计系统建设的优先级排序

CHECKPOINT: Present the design system architecture proposal to the user. Wait for approval of structure and token definitions before building.

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

Step 3: Design System Infrastructure

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

If initializing a new design system:

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

Invoke 
/ui-design:design-system-setup
for initialization guidance.
Set up the foundation:
Design Tokens
  • Color palette (primary, secondary, neutral, semantic: success/warning/error/info)
  • Typography scale (font families, sizes, weights, line heights)
  • Spacing scale (consistent spacing values: 0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64)
  • Border radii (none, sm, md, lg, xl, full)
  • Shadows (sm, md, lg, xl)
  • Breakpoints (sm, md, lg, xl, 2xl)
Tailwind Configuration Using 
/frontend-mobile-development:tailwind-design-system
:
  • Extend the Tailwind theme with design tokens
  • Configure shadcn/ui with project-specific theme colors
  • Set up CSS custom properties for runtime theming
  • Configure dark mode strategy (class-based or media-query)
Component Structure
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)
调用
/ui-design:design-system-setup
获取初始化指导。
搭建基础架构：
设计令牌
  • 调色板（主色、辅助色、中性色、语义色：成功/警告/错误/信息）
  • 排版体系（字体族、字号、字重、行高）
  • 间距体系（统一的间距值：0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64）
  • 边框圆角（无、小、中、大、超大、全圆角）
  • 阴影（小、中、大、超大）
  • 断点（小、中、大、超大、特大）
Tailwind配置 使用
/frontend-mobile-development:tailwind-design-system
：
  • 用设计令牌扩展Tailwind主题
  • 针对项目特定主题色配置shadcn/ui
  • 为运行时主题设置CSS自定义属性
  • 配置深色模式策略（基于类名或媒体查询）
组件结构
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/            # 设计令牌定义
├── hooks/             # 共享UI钩子（useMediaQuery、useTheme）
└── utils/             # UI工具函数（cn、cva变体）

If extending an existing design system:

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

Read the existing patterns and conventions before adding new components. Match the established API patterns.
在添加新组件前，先了解现有设计模式与规范。匹配已有的API模式。

Step 4: Build Components

步骤4：构建组件

For each component needed, follow this process:
对于每个需要开发的组件，遵循以下流程：

4a. Component Design

4a. 组件设计

Invoke 
/ui-design:create-component
for guided component creation.
Define the component API:
  • Props interface: All configurable options with TypeScript types
  • Variants: Size, color, and style variants (using cva or tailwind-variants)
  • Default values: Sensible defaults that work out-of-the-box
  • Composition: How it works with child components
调用
/ui-design:create-component
获取组件创建指导。
定义组件API：
  • Props接口：所有可配置选项的TypeScript类型定义
  • 变体：尺寸、颜色和样式变体（使用cva或tailwind-variants）
  • 默认值：开箱即用的合理默认配置
  • 组合方式：与子组件的协作方式

4b. Implementation

4b. 实现开发

Build each component with:
  • Full TypeScript typing (no 
    any
    types)
  • Tailwind CSS styling with shadcn/ui patterns
  • React.forwardRef
    for ref forwarding
  • className
    prop merged with 
    cn()
    utility for style overrides
  • Responsive behavior using Tailwind breakpoints
开发每个组件时需包含：
  • 完整的TypeScript类型定义（禁止使用
    any
    类型）
  • 采用shadcn/ui模式的Tailwind CSS样式
  • 使用
    React.forwardRef
    进行ref转发
  • 合并
    className
    属性与
    cn()
    工具函数以支持样式覆盖
  • 基于Tailwind断点的响应式行为

4c. Accessibility

4c. 无障碍适配

Every component must include:
  • Semantic HTML elements (button, nav, dialog, etc.)
  • ARIA attributes (aria-label, aria-describedby, role, etc.)
  • Keyboard navigation (Tab, Enter, Escape, Arrow keys as appropriate)
  • Focus management (visible focus ring, focus trap for modals)
  • Screen reader announcements for dynamic content
  • Color contrast meeting WCAG AA (4.5:1 for text, 3:1 for large text)
  • Touch target minimum size (44x44px for interactive elements)
每个组件必须包含：
  • 语义化HTML元素（button、nav、dialog等）
  • ARIA属性（aria-label、aria-describedby、role等）
  • 键盘导航支持（Tab、Enter、Escape、方向键等，根据组件特性适配）
  • 焦点管理（可见的焦点环、模态框的焦点陷阱）
  • 动态内容的屏幕阅读器播报
  • 符合WCAG AA标准的颜色对比度（普通文本4.5:1，大文本3:1）
  • 交互元素的最小触摸目标尺寸（44x44px）

4d. Tests

4d. 测试

For each component, write:
  • Render test: Component renders without errors
  • Props test: All variants and prop combinations render correctly
  • Interaction test: Click, hover, keyboard interactions work
  • Accessibility test: ARIA attributes present, keyboard nav works
为每个组件编写以下测试：
  • 渲染测试：组件可正常渲染无错误
  • Props测试：所有变体和属性组合均可正确渲染
  • 交互测试：点击、悬停、键盘交互功能正常
  • 无障碍测试：ARIA属性存在、键盘导航正常

CHECKPOINT: After each component (or batch of related components), present the implementation to the user for visual review. Show the component API, variants, and accessibility features.

检查点：完成每个组件（或一组相关组件）后，向用户展示实现效果以进行视觉评审。展示组件API、变体及无障碍特性。

Step 5: Accessibility Audit

步骤5：无障碍审计

After all components are built, run a comprehensive accessibility audit:
Invoke 
/ui-design:accessibility-audit
on all new/modified components.
Check for:
  • WCAG 2.1 AA compliance (minimum standard)
  • Color contrast: All text meets contrast ratios
  • Keyboard navigation: Complete keyboard operability
  • Screen reader: All interactive elements announced correctly
  • Focus management: Logical focus order, visible focus indicators
  • Motion: Respect 
    prefers-reduced-motion
    media query
  • Touch targets: Minimum 44x44px on mobile
所有组件开发完成后，运行全面的无障碍审计：
调用
/ui-design:accessibility-audit
对所有新增/修改的组件进行审计。
检查内容包括：
  • WCAG 2.1 AA合规性（最低标准）
  • 颜色对比度：所有文本均符合对比度要求
  • 键盘导航：完整的键盘可操作性
  • 屏幕阅读器：所有交互元素均可被正确播报
  • 焦点管理：合理的焦点顺序、可见的焦点指示器
  • 动画：遵循
    prefers-reduced-motion
    媒体查询
  • 触摸目标：移动端最小尺寸为44x44px

CHECKPOINT: Present accessibility audit findings. User approves the accessibility posture or requests changes.

检查点：向用户展示无障碍审计结果。用户需确认无障碍达标或提出修改要求。

Step 6: Design Review

步骤6：设计评审

Invoke 
/ui-design:design-review
to review the overall design system for:
  • Consistency: All components follow the same patterns
  • Naming: Props, variants, and CSS classes follow conventions
  • API patterns: Consistent prop interfaces across components
  • Visual coherence: Components look like they belong together
  • Completeness: Common use cases are covered
Address any findings from the review.
调用
/ui-design:design-review
对整体设计系统进行评审，检查内容包括：
  • 一致性：所有组件遵循相同的设计模式
  • 命名规范：Props、变体和CSS类名符合约定
  • API模式：组件间的Props接口保持一致
  • 视觉连贯性：组件风格统一，视觉上属于同一体系
  • 完整性：覆盖常见使用场景
处理评审中发现的问题。

Step 7: Documentation

步骤7：文档编写

Document the design system:
  • Component catalog: Each component with props table, usage examples, and do/don't patterns
  • Design tokens: Complete reference of colors, typography, spacing
  • Accessibility guide: Per-component accessibility notes and testing instructions
  • Getting started: How to import and use components in the app
为设计系统编写文档：
  • 组件目录：每个组件包含Props表格、使用示例及最佳实践/禁忌模式
  • 设计令牌：完整的颜色、排版、间距参考
  • 无障碍指南：每个组件的无障碍说明及测试方法
  • 快速开始：如何在应用中导入和使用组件

Step 8: Commit

步骤8：提交代码

Commit with conventional commit format:
For new design system:
feat(ui): initialize design system with core components
For new components:
feat(ui): add <component-name> component
For design token changes:
feat(ui): update design tokens for <change-description>
使用约定式提交格式提交：
新设计系统初始化：
feat(ui): initialize design system with core components
新增组件：
feat(ui): add <component-name> component
设计令牌变更：
feat(ui): update design tokens for <change-description>

Step 9: Hand Off — STOP Here

步骤9：交接工作——到此为止

[!CAUTION] This skill's work is done. Do NOT proceed to create a pull request, push to remote, or run a code review. Those are separate skills with their own workflows and checkpoints.
Present the next step to the user:
  • Recommended: Run 
    /review-code
    for multi-perspective quality and accessibility review before submitting
  • If building a feature that uses these components: Continue with 
    /build-feature
    to implement the feature, then run 
    /review-code
  • If this is standalone design system work: Run 
    /review-code
    → 
    /submit-pr
[!TIP] Pipeline: 
/plan-feature
→ 
/build-feature
or 
/build-api
→ 
/review-code
→ 
/submit-pr
/setup-design-system
 can be run at any point in the pipeline or independently. You are here — proceed to 
/review-code
when ready.
Do not push the branch, create a PR, or invoke 
/submit-pr
from within this skill.
[!CAUTION] 本Skill的工作已完成。请勿继续执行创建拉取请求、推送到远程仓库或运行代码评审的操作。这些属于独立Skill的范畴，有各自的工作流和检查点。
向用户展示下一步建议：
  • 推荐：在提交前调用
    /review-code
    进行多维度的质量与无障碍评审
  • 如果是开发使用这些组件的功能：继续调用
    /build-feature
    实现功能，之后再调用
    /review-code
  • 如果是独立的设计系统工作：调用
    /review-code
    → 
    /submit-pr
[!TIP] 流水线：
/plan-feature
→ 
/build-feature
或
/build-api
→ 
/review-code
→ 
/submit-pr
/setup-design-system
 可在流水线的任意阶段运行，也可独立执行。当前已完成此步骤，准备就绪后请调用
/review-code
。
请勿在本Skill内推送分支、创建PR或调用
/submit-pr
。