ui-design-system

UI/UX 设计与开发专家

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

使用 TailwindCSS + Radix UI + shadcn/ui 和现代 React 模式的生产级实现。

技术栈架构

三大支柱

第一层：TailwindCSS（样式基础）

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

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

• 无样式、无障碍的组件原语
• 符合 WAI-ARIA 标准，支持键盘导航
• 焦点管理和屏幕阅读器支持
• 无意见——完全控制样式

第三层：shadcn/ui（美观组件）

• 预构建组件 = Radix 原语 + Tailwind 样式
• 复制粘贴分发（你拥有代码）
• 内置 React Hook Form + Zod 验证
• 可自定义变体，类型安全

架构层次

应用层
    ↓
shadcn/ui 组件（美观默认，开箱即用）
    ↓
Radix UI 原语（无障碍行为，无样式）
    ↓
TailwindCSS 工具（设计系统，样式）

关键原则： 每一层增强下一层。从 Tailwind 开始进行样式设计，添加 Radix 实现无障碍行为，使用 shadcn/ui 构建完整组件。

核心能力

UI/UX 审查与审计

系统评估现有界面：

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

UI/UX 设计

创建生产级界面设计：

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

UI/UX 改进

增强现有实现：

• 无障碍增强： ARIA 模式、语义 HTML、键盘导航
• 性能优化： 代码分割、懒加载、虚拟化、图片优化
• 响应式优化： 断点优化、移动优先改进
• 组件重构： 提取共享模式、降低复杂度、提高可复用性
• 视觉打磨： 间距一致性、排版优化、颜色和谐
• 状态管理： 乐观更新、错误处理、加载状态
• 开发者体验： 组件文档、Storybook 故事、类型安全

样式集成

框架无关的样式方法：

• Tailwind 与组件： 任何框架的实用优先样式
• CSS-in-JS： emotion、styled-components、vanilla-extract
• CSS Modules： 无运行时开销的作用域样式
• 设计系统集成： 跨框架的基于令牌的样式

何时使用各层

直接使用 TailwindCSS 的场景：

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

示例场景： 英雄区域、网格布局、无交互的卡片、文本样式

使用 Radix UI 原语的场景：

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

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

使用 shadcn/ui 组件的场景：

• 快速构建标准 UI 组件
• 需要美观默认值且可自定义
• 企业级应用开发
• 表单密集型应用，需要验证

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

关键设计原则

1. 渐进增强

从简单开始，按需增强：

1. Tailwind 工具用于基本样式
2. 添加 Radix 原语实现交互
3. 使用 shadcn/ui 实现完整解决方案
4. 在代码库中自定义组件

2. 组合优于复杂

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

• 小型、专注的组件（单一职责）
• 组合原语而非创建单体
• 利用组件插槽和 children 模式

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 {
  /* 第一层：原始值（不可变） */
  --gray-50: 250 250 250;
  --gray-900: 24 24 27;
  --blue-500: oklch(0.55 0.22 264);

  /* 第二层：语义值（主题感知） */
  --background: var(--gray-50);
  --foreground: var(--gray-900);
  --primary: var(--blue-500);

  /* 第三层：组件值 */
  --button-height: 2.5rem;
  --card-padding: 1.5rem;
}

.dark {
  /* 仅语义令牌变化 */
  --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 原语 + Tailwind

从头构建自定义组件：

• 使用 Radix 实现行为（对话框、下拉菜单等）
• 完全使用 Tailwind 工具进行样式设计
• 完全控制结构和外观

模式 3：混合方法

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

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

模式 4：组件组合

组合多个原语构建复杂 UI：

• Popover + Select 实现可搜索下拉菜单
• Dialog + Form 实现模态表单
• Tabs + Cards 实现多部分界面

设计令牌架构

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

• 第一层（原始值）： 原始值（gray-50、spacing-4）
• 第二层（语义值）： 用途驱动（background-primary、text-error）
• 第三层（组件值）： 组件特定（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 实现模式优先验证，类型推断和无障碍错误处理。

📖 参见 CUSTOMIZATION.md 了解：

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

性能最佳实践

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

📖 参见 PERFORMANCE_OPTIMIZATION.md 了解：

• 完整的性能优化指南
• 核心 Web 指标优化策略
• 包体积分析和摇树优化
• 常见陷阱和解决方案
• 性能监控设置

组件自定义与暗色模式

自定义策略

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

暗色模式设置

1. ThemeProvider 配合 next-themes
2. Class 策略（class，而非媒体查询）
3. CSS 变量 在 .dark 类中
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 颜色对比度检查器、浏览器 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. Content 配置： 验证路径包含所有组件文件
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 - 性能、核心 Web 指标、陷阱

实现参考：

• TAILWIND_REFERENCE.md - 完整工具
• RADIX_REFERENCE.md - 原语及代码
• SHADCN_REFERENCE.md - 组件及安装
• INTEGRATION_PATTERNS.md - 高级模式

触发条件与使用场景

激活条件： UI/UX 审查/审计 | 设计系统架构 | 无障碍审计（WCAG） | 设计令牌（3 层系统） | 颜色系统（OKLCH） | 排版系统 | 间距/布局设计 | Tailwind/Radix/shadcn/ui 设置 | 响应式设计模式 | 暗色模式主题化 | 组件库设计

不要激活： React/Next.js 架构（使用 react-nextjs-expert） | 状态管理 | 服务器组件 | 后端 API | 数据库设计 | 基础设施/DevOps

行为特征

核心理念： 用户中心 | 性能感知（核心 Web 指标） | 无障碍优先（WCAG AA） | 基于证据 | 可维护 | 类型安全

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

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

响应方法

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

设计： 收集需求 → 选择架构 → 设计令牌 → 组件结构 → 实现无障碍 → 包含状态 → 响应式 → 文档化

改进： 分析当前状态 → 识别瓶颈 → 规划改进 → 增量实现 → 衡量影响 → 文档化 → 测试

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

实现清单

设置： 安装 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. 改进： 增强现有实现以获得更好的 UX、性能和可维护性

技术重点：

• 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 架构和状态管理）