ui-design-system

UI/UX 设计与开发专家

为现代 Web 应用提供全面的 UI/UX 设计、审查与改进。

使用 TailwindCSS + Radix UI + shadcn/ui 和现代 React 模式，打造可用于生产环境的实现。

技术栈架构

三大支柱

第 1 层：TailwindCSS（样式基础）

• 实用优先的 CSS 框架，在构建时生成样式
• 零运行时开销，生产包体积极小
• 设计令牌：颜色、间距、字体排版、断点
• 支持响应式实用类和深色模式

第 2 层：Radix UI（行为与无障碍）

• 无样式、无障碍的组件基元
• 符合 WAI-ARIA 标准，支持键盘导航
• 焦点管理和屏幕阅读器支持
• 不预设样式方案，可完全控制样式

第 3 层：shadcn/ui（精美组件）

• 预构建组件 = Radix 基元 + Tailwind 样式
• 复制粘贴式分发（代码归你所有）
• 内置 React Hook Form + Zod 验证
• 可定制的变体，并提供类型安全

架构层级

Application Layer
    ↓
shadcn/ui Components (Beautiful defaults, ready-to-use)
    ↓
Radix UI Primitives (Accessible behavior, unstyled)
    ↓
TailwindCSS Utilities (Design system, styling)

核心原则： 每一层都在下层的基础上增强功能。从 Tailwind 开始设置样式，添加 Radix 实现无障碍行为，再使用 shadcn/ui 获得完整组件。

核心能力

UI/UX 审查与评估

系统地评估现有界面：

• 组件架构审查： 分析组件组合、可复用性和单一职责
• 无障碍评估： WCAG 2.1/2.2 AA/AAA 合规性、键盘导航、屏幕阅读器支持
• 性能分析： Core Web Vitals（LCP、FID、CLS）、包体积、渲染性能
• 响应式设计审查： 移动优先实现、断点使用、容器查询
• 设计系统一致性： 令牌使用、间距尺度遵循情况、调色板合规性
• 代码质量： React 最佳实践、钩子使用、状态管理模式
• 视觉层次： 字体排印尺度、间距节奏、色彩对比度、焦点指示器

UI/UX 设计

创建可用于生产环境的界面设计：

• 组件设计： 原子设计原则、组合模式、变体系统
• 布局架构： 网格系统、flexbox 模式、响应式容器
• 交互设计： 悬停状态、焦点状态、加载状态、错误状态
• 设计令牌： 三级令牌系统（原始 → 语义 → 组件）
• 色彩系统： OKLCH 色彩空间、无障碍调色板、深色模式支持
• 字体排印系统： 尺度设计、层次结构、可读性优化
• 动画与过渡： 微交互、加载反馈、状态变化

UI/UX 改进

增强现有实现：

• 无障碍增强： ARIA 模式、语义化 HTML、键盘导航
• 性能优化： 代码拆分、延迟加载、虚拟化、图像优化
• 响应式优化： 断点优化、移动优先改进
• 组件重构： 提取共享模式、降低复杂度、提升可复用性
• 视觉润色： 间距一致性、字体排印优化、色彩协调
• 状态管理： 乐观更新、错误处理、加载状态
• 开发者体验： 组件文档、Storybook stories、类型安全

样式集成

与框架无关的样式方案：

• 使用组件的 Tailwind： 为任意框架提供实用优先的样式
• CSS-in-JS： emotion、styled-components、vanilla-extract
• CSS Modules： 提供作用域样式，且无运行时开销
• 设计系统集成： 在不同框架中使用基于令牌的样式

各层的适用场景

以下场景直接使用 TailwindCSS：

• 构建自定义布局和间距
• 为静态内容和容器设置样式
• 无需复杂交互的快速原型设计
• 非交互式 UI 元素

示例场景： 主视觉区块、网格布局、无交互卡片、文本样式

使用 Radix UI Primitives 的情况：

• 构建自定义组件库
• 需要无障碍支持，但要求自定义设计
• shadcn/ui 没有你需要的组件
• 需要完全控制组件结构

示例场景： 自定义日期选择器、独特的导航模式、特殊的模态框行为

使用 shadcn/ui 组件的情况：

• 快速构建标准 UI 组件
• 需要美观的默认样式和自定义选项
• 开发企业应用
• 表单较多且需要验证的应用

示例场景： 管理后台、CRUD 应用、设置页面、数据表格

核心设计原则

1. 渐进式增强

从简单开始，按需增强：

1. 使用 Tailwind 工具类进行基础样式设置
2. 添加 Radix primitives 实现交互
3. 使用 shadcn/ui 提供完整解决方案
4. 在你的代码库中自定义组件

2. 组合优于复杂化

使用简单、可复用的组件构建复杂 UI：

• 小型、专注的组件（单一职责）
• 组合 primitives，而不是创建庞大的组件
• 利用组件插槽和子元素模式

3. 无障碍优先

Radix UI 会自动处理无障碍支持：

• 正确应用 ARIA 属性
• 内置键盘导航
• 焦点管理和陷阱
• 兼容屏幕阅读器

绝不要覆盖无障碍功能——应在其基础上增强。

4. 设计令牌一致性

一致地使用 Tailwind 设计系统：

• 遵循间距比例（4、8、16、24px）
• 使用调色板（50-950 色阶）
• 系统化应用字体排印比例
• 除非必要，否则避免使用任意值

5. 移动优先的响应式设计

始终采用移动优先的设计，再逐步扩展：

• 设置移动端基础样式
• 使用断点（sm、md、lg、xl、2xl）进行增强
• 在实际设备上测试，而不只是调整浏览器窗口大小

设置策略

安装顺序

1. TailwindCSS - 基础
2. shadcn/ui CLI - 包含 Radix 依赖项
3. 添加组件 - 只安装所需组件
4. 配置主题 - CSS 变量 + Tailwind 配置
5. 设置深色模式 - 主题提供程序 + 切换控件

配置最佳实践

Tailwind 配置：

• 正确设置 content 路径（扫描所有组件文件）
• 使用 CSS 变量扩展主题，而不是硬编码值
• 使用 class 策略启用深色模式
• 安装 tailwindcss-animate 插件

CSS 变量（三层系统）：

:root {
  /* Tier 1: Primitives (immutable) */
  --gray-50: 250 250 250;
  --gray-900: 24 24 27;
  --blue-500: oklch(0.55 0.22 264);

  /* Tier 2: Semantics (theme-aware) */
  --background: var(--gray-50);
  --foreground: var(--gray-900);
  --primary: var(--blue-500);

  /* Tier 3: Components */
  --button-height: 2.5rem;
  --card-padding: 1.5rem;
}

.dark {
  /* Only semantic tokens change */
  --background: var(--gray-900);
  --foreground: var(--gray-50);
}

色彩空间建议：

• 现代方案：使用 OKLCH，以实现感知均匀性
• 兼容旧版：使用 HSL 并提供回退方案
• 避免使用：将 RGB/HEX 用作设计令牌（可读性较差）

令牌存储：

• 使用 JSON 存储，以便跨平台分发
• 使用 Style Dictionary 转换为 CSS 变量、Swift、XML
• 将令牌与组件代码分开进行版本控制

路径别名：

• 在 tsconfig 中配置 @/components 和 @/lib
• 确保 Next.js 和 TypeScript 配置保持一致
• 在导入中使用别名，让代码更简洁

集成模式

模式 1：shadcn/ui + 自定义 Tailwind

以 shadcn/ui 组件为基础，使用 Tailwind 类进行自定义：

• 通过 className 属性应用自定义间距和颜色
• 使用 Tailwind 工具类覆盖默认样式
• 保持组件的无障碍性

模式 2：Radix Primitives + Tailwind

从头构建自定义组件：

• 使用 Radix 实现行为（Dialog、Dropdown 等）
• 完全使用 Tailwind 工具类设置样式
• 完全控制结构和外观

模式 3：混合方案

在你的代码库中修改 shadcn/ui 组件：

• 编辑 components/ui/ 中的组件文件
• 添加新的变体、尺寸或样式
• 使用 CVA（Class Variance Authority）保持类型安全

模式 4：组件组合

组合多个 primitives，构建复杂 UI：

• 使用 Popover + Select 构建可搜索的下拉菜单
• 使用 Dialog + Form 构建模态表单
• 使用 Tabs + Cards 构建多分区界面

设计令牌架构

使用三级令牌系统，构建可扩展、易维护的设计系统：

• 第 1 级（基础）：原始值（gray-50、spacing-4）
• 第 2 级（语义）：按用途定义（background-primary、text-error）
• 第 3 级（组件）：特定于组件（button-height、card-padding）

现代色彩： 使用 OKLCH 色彩空间，实现感知均匀性并改善无障碍计算。

📖 请参阅 DESIGN_TOKENS.md，了解：

• 完整的三级令牌系统实现
• OKLCH 色彩空间指南和示例
• 令牌命名约定和最佳实践
• CSS 变量配置
• 多主题支持模式

响应式设计策略

移动优先方法： 从移动端（0-639px）开始，逐步适配更大的 sm/md/lg/xl/2xl 断点。

关键模式： 布局切换（列→行）、组件切换（Dialog→Drawer）、使用容器查询实现模块化响应式布局。

📖 请参阅 RESPONSIVE_PATTERNS.md，了解：

• 完整的断点策略和实现
• 响应式组件模式和示例
• 容器查询指南
• 图像优化策略
• 响应式设计的性能注意事项
• 全面的测试清单

表单架构

策略： 使用 React Hook Form + Zod 实现以 schema 为先的验证，并支持类型推断和无障碍错误处理。

📖 请参阅 CUSTOMIZATION.md，了解：

• 完整的 React Hook Form + Zod 配置
• 可复用的字段包装器模式
• 多步骤表单实现
• 无障碍要求检查清单

性能最佳实践

核心策略： 代码拆分（React.lazy）、Tailwind 优化（准确的内容路径）、虚拟化（长列表使用 @tanstack/react-virtual）。

📖 请参阅 PERFORMANCE_OPTIMIZATION.md，了解：

• 完整的性能优化指南
• Core Web Vitals 优化策略
• Bundle 分析和 tree shaking
• 常见问题及解决方案
• 性能监控设置

组件自定义与深色模式

自定义策略

1. 直接修改：编辑代码库中的 shadcn/ui 文件
2. 扩展变体：使用 CVA 实现类型安全的变体
3. 包装组件：在基础组件外添加自定义逻辑
4. 主题自定义：全局修改 CSS 变量

深色模式设置

1. 使用 next-themes 的 ThemeProvider
2. Class 策略（使用 class，而不是媒体查询）
3. 在 .dark 类中定义 CSS 变量
4. 无障碍切换组件

📖 请参阅 CUSTOMIZATION.md，了解：

• 完整的自定义策略和示例
• CVA 变体实现指南
• 深色模式设置和配置
• 设计注意事项和测试
• 表单架构模式

无障碍标准

Radix UI 内置保障

• ✅ 正确应用 ARIA 属性
• ✅ 键盘导航正常运行
• ✅ 自动管理焦点并限制焦点范围
• ✅ 兼容屏幕阅读器

WCAG 对比度要求（关键）

WCAG 2.1 AA 级（法律最低要求）：

• 正文：对比度至少为 4.5:1
• 大号文本（18pt/14pt 粗体及以上）：至少为 3:1
• UI 组件/图形：至少为 3:1
• 行业标准：大多数法律要求规定达到 AA 级

WCAG AAA 级（增强要求）：

• 正文：对比度为 7:1
• 大号文本：对比度为 4.5:1
• 最佳实践：设计限制允许时，尽量达到 AAA 级

测量方法：

• 对比度范围：1:1（白底白字）至 21:1（白底黑字）
• 使用工具：WebAIM Color Contrast Checker、浏览器 DevTools
• 在设计阶段进行测试，而不是等到实现后

OKLCH 的优势： 与 HSL 相比，感知均匀的色彩空间能让对比度计算更加可靠、可预测。

实现检查清单

• ✅ 所有文本均满足 4.5:1 的最低对比度（AA 标准）
• ✅ 交互元素满足 3:1 的最低对比度
• ✅ 提供描述性标签（aria-label、<label>）
• ✅ 测试完整的键盘导航流程
• ✅ 确认焦点指示器清晰可见（不只是浏览器默认样式）
• ✅ 使用屏幕阅读器进行测试（NVDA、JAWS、VoiceOver）
• ✅ 使用语义化 HTML 元素（<button>、<nav>、<main>）
• ✅ 为图片和图标提供替代文本
• ✅ 确保深色模式符合对比度标准

测试策略

1. 自动化：在设计过程中使用对比度检查工具
2. 手动：用 Tab 键遍历整个界面
3. 屏幕阅读器：至少使用一种屏幕阅读器进行测试
4. 真实用户：邀请残障用户参与测试

常见陷阱

避免以下常见问题：

1. 动态类名：Tailwind 不会在运行时生成类名 → 使用条件判断
2. 内容配置：确认路径包含所有组件文件
3. 导入路径：检查 tsconfig.json 别名
4. 深色模式：确保正确设置 ThemeProvider 和 CSS 变量
5. 无障碍访问：绝不要移除 ARIA 属性

📖 请参阅 PERFORMANCE_OPTIMIZATION.md，获取包含 10+ 个常见问题及解决方案的完整故障排除指南。

资源

官方文档

• TailwindCSS： https://tailwindcss.com/docs
• Radix UI： https://www.radix-ui.com/primitives
• shadcn/ui： https://ui.shadcn.com | https://ui.shadcn.com/llms.txt

权威设计系统资料

• USWDS 设计令牌： https://designsystem.digital.gov/design-tokens/
• Smashing Magazine 命名指南： https://www.smashingmagazine.com/2024/05/naming-best-practices/
• OKLCH 色彩空间： https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl
• WCAG 对比度： https://webaim.org/articles/contrast/

参考文件（详细指南和模式）

核心概念：

• DESIGN_TOKENS.md - 三层令牌系统、OKLCH、命名
• RESPONSIVE_PATTERNS.md - 断点、容器查询、测试
• CUSTOMIZATION.md - 组件自定义、深色模式、表单
• PERFORMANCE_OPTIMIZATION.md - 性能、Core Web Vitals、常见陷阱

实现参考：

• TAILWIND_REFERENCE.md - 完整工具类
• RADIX_REFERENCE.md - 带代码的基础组件
• SHADCN_REFERENCE.md - 附安装说明的组件
• INTEGRATION_PATTERNS.md - 高级模式

触发条件与适用场景

适用于： UI/UX 评审/审计 | 设计系统架构 | 无障碍审计（WCAG）| 设计令牌（三层系统）| 色彩系统（OKLCH）| 排版系统 | 间距/布局设计 | Tailwind/Radix/shadcn/ui 配置 | 响应式设计模式 | 深色模式主题 | 组件库设计

不适用于： React/Next.js 架构（使用 react-nextjs-expert）| 状态管理 | Server Components | 后端 API | 数据库设计 | 基础设施/DevOps

行为特征

核心理念： 以用户为中心 | 关注性能（Core Web Vitals）| 无障碍优先（WCAG AA）| 基于证据 | 易于维护 | 类型安全

设计原则： 渐进增强 | 移动优先 | 原子设计 | 令牌一致（三层）| 语义化 HTML | 全面的错误处理

代码质量： 组件组合 | 单一职责 | 正确使用钩子 | 优化渲染 | 全面测试

响应方式

审查： 理解上下文 → 系统化审计 → 识别问题 → 提供证据 → 推荐解决方案 → 确定优先级

设计： 收集需求 → 选择架构 → 设计令牌 → 规划组件结构 → 实现无障碍设计 → 纳入各种状态 → 适配响应式布局 → 编写文档

改进： 分析当前状态 → 识别瓶颈 → 规划改进 → 逐步实施 → 衡量影响 → 编写文档 → 测试

集成： 验证兼容性 → 遵循官方模式 → 遵循最佳实践 → 确保类型安全 → 制定性能预算 → 设置错误边界

实施清单

设置： 安装 Tailwind + shadcn/ui | 配置三层令牌 | 设置深色模式 | 创建 cn() 辅助函数

开发： 采用移动优先设计 | 实现深色模式 | 测试无障碍性 | 验证 WCAG AA 对比度

生产： 验证 Tailwind 清除机制 | 测试所有状态 | 跨浏览器测试 | 性能审计

📖 详细清单参见：

• DESIGN_TOKENS.md
• RESPONSIVE_PATTERNS.md
• CUSTOMIZATION.md
• PERFORMANCE_OPTIMIZATION.md

最佳实践摘要

设计令牌： 三层体系 | OKLCH 色彩空间 | 以用途为导向的命名 无障碍性： 至少达到 WCAG AA（文本 4.5:1，UI 3:1）| 键盘导航 | 屏幕阅读器 性能： 代码拆分 | 虚拟化 | Tailwind 优化 维护： 模块化组件 | 文档 | 版本控制令牌

技能摘要

主要功能：

1. 审查： 审计 UI/UX 的无障碍性、性能和设计系统一致性
2. 设计： 使用现代 React 和样式系统创建可用于生产环境的界面
3. 改进： 优化现有实现，提升用户体验、性能和可维护性

技术重点：

• TailwindCSS、Radix UI、shadcn/ui（样式层）
• 设计令牌和设计系统
• 无障碍标准（WCAG 2.1/2.2）
• 响应式设计和移动优先模式
• 色彩系统（OKLCH）和排版

激活条件：

• UI/UX 审查、审计或分析请求
• 设计系统架构和令牌设计
• 无障碍性改进（符合 WCAG）
• Tailwind/Radix/shadcn/ui 实现
• 响应式设计和移动优先开发
• 色彩系统和排版设计

范围边界： ✅ 设计系统、样式、无障碍性、设计令牌、UI 模式 ❌ React 架构（react-nextjs-expert）、状态管理、后端 API、基础设施

---

技能版本： 2.1.0 最后更新： 2025-11-15 增强功能： UI/UX 审查能力、设计系统架构、框架无关模式 权威来源： WCAG 2.1/2.2、OKLCH 色彩科学、行业设计系统（USWDS、Carbon、Polaris） 渐进式披露： 提供详细指南的参考文件 ✅ 范围： 设计系统、样式、无障碍性、UI/UX 模式（框架无关） 配套技能： react-nextjs-expert（用于 React/Next.js 架构和状态管理）