moai-domain-uiux

快速参考

核心 UI/UX 基础——企业级 UI/UX 基础，集成了设计系统（W3C DTCG 2025.10）、组件架构（React 19、Vue 3.5）、无障碍设计（WCAG 2.2）、图标库（20 万+ 图标）和主题系统。

统一能力：

• 设计系统：W3C DTCG 2025.10 设计令牌、Style Dictionary 4.0、Pencil MCP 工作流
• 组件架构：原子设计、React 19、Vue 3.5、shadcn/ui、Radix UI 基元
• 无障碍设计：符合 WCAG 2.2 AA/AAA 标准、键盘导航、屏幕阅读器优化
• 图标库：10 多个生态系统（Lucide、React Icons 3.5 万+、Tabler 5900+、Iconify 20 万+、Hugeicons 2.7 万+）
• 主题：CSS 变量、浅色/深色模式、主题提供程序、品牌自定义

适用场景：

• 基于设计系统构建现代 UI 组件库
• 实现无障碍的企业级用户界面
• 为多平台项目搭建设计令牌架构
• 集成全面的图标系统并优化打包体积
• 创建支持深色模式的可自定义主题系统

模块组织：

• 组件：modules/component-architecture.md（原子设计、组件模式、props API）
• 设计系统：modules/design-system-tokens.md（DTCG 令牌、Style Dictionary、Pencil MCP）
• 无障碍设计：modules/accessibility-wcag.md（符合 WCAG 2.2 标准、测试、导航）
• 图标：modules/icon-libraries.md（10 多个库、选择指南、性能优化）
• 主题：modules/theming-system.md（主题系统、CSS 变量、品牌自定义）
• Web 界面指南：modules/web-interface-guidelines.md（Vercel Labs 全面的 UI/UX 合规要求、前端组合规则）
• 示例：examples.md（实际实现示例）
• 参考资料：reference.md（外部文档链接）

---

实施指南

基础技术栈

核心技术：

• React 19，支持服务器组件和并发渲染
• TypeScript 5.9+，提供完整的类型安全和更准确的类型推断
• Tailwind CSS 4.x，支持 CSS 优先配置、CSS 变量和深色模式
• Radix UI，用于提供无样式的无障碍基元
• W3C DTCG 2025.10，用于设计令牌规范
• Style Dictionary 4.0，用于令牌转换
• Pencil MCP，用于设计到代码的自动化
• Storybook 8.x，用于组件文档

快速决策指南：

对于设计令牌，请使用 modules/design-system-tokens.md，其中包含 DTCG 2025.10 和 Style Dictionary 4.0。

对于组件模式，请使用 modules/component-architecture.md，其中包含原子设计、React 19 和 shadcn/ui。

对于无障碍设计，请使用 modules/accessibility-wcag.md，其中包含 WCAG 2.2、jest-axe 和键盘导航。

对于图标，请使用 modules/icon-libraries.md，其中包含 Lucide、React Icons、Tabler、Iconify 和 Hugeicons。

对于 Nova 预设和设计预设，请使用 moai-design-tools 技能（reference/pencil-renderer.md）。

对于主题，请使用 modules/theming-system.md，其中包含 CSS 变量和主题提供程序。

对于实际示例，请使用 examples.md，其中包含 React 和 Vue 实现。

---

快速入门工作流

设计系统设置

步骤 1：创建包含 DTCG 架构 URL 的 JSON 文件，初始化设计令牌。定义类型为 color、值为 primary 500 的颜色令牌。定义类型为 dimension、值为 1rem 的 md 间距令牌。

步骤 2：安装 Style Dictionary 软件包并运行 build 命令，转换令牌。

步骤 3：从 tokens 目录导入颜色和间距，并将其集成到组件中。

完整的令牌架构请参阅 modules/design-system-tokens.md。

组件库设置

步骤 1：运行初始化命令来初始化 shadcn/ui，然后添加 button、form 和 dialog 组件。

步骤 2：设置 Atomic Design 结构：创建 atoms 目录，存放 Button、Input 和 Label 组件；创建 molecules 目录，存放 FormGroup 和 Card 组件；创建 organisms 目录，存放 DataTable 和 Modal 组件。

步骤 3：通过为交互元素添加 aria-label 属性来实现无障碍访问。

有关模式和示例，请参阅 modules/component-architecture.md。

图标系统集成

步骤 1：根据需求选择图标库。安装 lucide-react 用于通用场景，安装 iconify/react 以获得最丰富的选择，或安装 tabler/icons-react 来优化仪表板。

步骤 2：通过导入特定图标并应用 className 设置大小和颜色，实现类型安全的图标。

有关图标库的比较和优化，请参阅 modules/icon-libraries.md。

主题系统设置

步骤 1：在根选择器中配置 CSS 变量，用于设置主色和背景色。定义 dark 类，并为深色模式设置反转后的值。

步骤 2：通过将应用包裹在 Theme Provider 中来实现主题提供程序，并将 attribute 设为 class、defaultTheme 设为 system。

有关完整的主题系统，请参阅 modules/theming-system.md。

---

核心原则

设计令牌优先：

• 为设计决策提供唯一事实来源
• 使用 color.primary.500 格式进行语义化命名，而不是 blue-500
• 支持浅色和深色模式的多主题
• 与平台无关的转换

默认保障无障碍访问：

• 至少符合 WCAG 2.2 AA，文本对比度为 4.5:1
• 所有交互元素均支持键盘导航
• 为屏幕阅读器提供 ARIA 属性
• 管理焦点并显示焦点指示器

组件组合：

• 从 Atoms 到 Molecules 再到 Organisms 的 Atomic Design 层级
• 使用 Props API 实现可复用性
• 使用基于变体的样式，而不是创建独立组件
• 使用 TypeScript 保证类型安全

性能优化：

• 通过导入特定图标而非全部图标来实现图标摇树优化
• 对大型组件进行懒加载
• 对开销较大的渲染使用 React.memo
• 监控包体积

---

最佳实践

必需实践：

所有颜色、间距和排版值都必须使用设计令牌。设计令牌提供唯一事实来源，可实现一致的主题、多平台支持和可扩展的设计系统。硬编码值会增加维护负担，并破坏主题切换。

为所有仅含图标的交互元素添加 ARIA 标签。屏幕阅读器无法解读没有文本替代内容的视觉图标。缺少 ARIA 标签不符合 WCAG 2.2 AA 标准。

单独导入图标，而不要使用命名空间导入。命名空间导入会打包整个库，从而无法进行摇树优化。每个图标库都会使包体积增加 500KB-2MB。

在浅色和深色模式下测试所有组件。主题切换会影响颜色对比度、可读性和无障碍访问合规性。

为所有交互组件实现键盘导航。仅使用键盘的用户需要支持 Tab、Enter、Escape 和方向键。

为所有可聚焦元素提供可见的焦点指示器。焦点指示器可在导航时显示当前键盘焦点位置，并提升无障碍访问体验。

使用 Tailwind 实用类，而不是内联样式。Tailwind 提供一致的间距刻度、响应式设计，并可自动清除未使用的样式，从而优化包体积。

为所有异步操作提供加载状态。加载状态可在获取数据时提供反馈，避免用户感到不确定。

---

配合良好的工具

技能：

• moai-lang-typescript - TypeScript 和 JavaScript 最佳实践
• moai-foundation-core - TRUST 5 质量验证
• moai-library-nextra - 文档生成
• moai-library-shadcn - shadcn/ui 专用模式

Agent：

• code-frontend - 前端组件实现
• design-uiux - 设计系统架构
• mcp-pencil - Pencil MCP 设计工作流
• core-quality - 无障碍与质量验证

命令：

• /moai:2-run - DDD 实现周期
• /moai:3-sync - 文档生成

---

资源

详细的模块文档请参阅 modules 目录。

实用代码示例请参阅 examples.md。

外部文档链接请参阅 reference.md。

官方资源：

• W3C DTCG：https://designtokens.org
• WCAG 2.2：https://www.w3.org/WAI/WCAG22/quickref/
• React 19：https://react.dev
• Tailwind CSS：https://tailwindcss.com
• Radix UI：https://www.radix-ui.com
• shadcn/ui：https://ui.shadcn.com
• Storybook：https://storybook.js.org
• Pencil：https://docs.pencil.dev
• Style Dictionary：https://styledictionary.com
• Lucide Icons：https://lucide.dev
• Iconify：https://iconify.design
• Vercel Web Interface Guidelines：https://github.com/vercel-labs/web-interface-guidelines

---

最后更新：2026-03-11 状态：已可用于生产环境 版本：3.0.0

常见的合理化说辞

合理化说辞	事实
“无障碍是锦上添花，而非必需项”	在许多司法管辖区，符合 WCAG 是法律要求。它也是核心质量维度，并非可选项。
“暗色模式就是反转颜色”	简单地反转颜色会破坏对比度、图像可见性和语义颜色含义。暗色模式是一项设计工作。
“设计系统太死板了，我需要自定义样式”	绕过设计系统的自定义样式会造成不一致。应扩展系统，而不是绕开它。
“图标不需要标签，它们一看就懂”	图标脱离上下文会产生歧义。屏幕阅读器无法描述未标注的图标。务必添加 aria-label。
“我会在最后处理响应式设计”	事后补做响应式设计会破坏布局。应先针对最小视口进行设计，再逐步增强。

危险信号

• 交互元素没有可见的焦点指示器
• 普通文本的颜色对比度低于 4.5:1
• 使用图标时没有 aria-label 或配套文本
• 使用硬编码的颜色或间距值，绕过设计令牌
• 新组件未定义暗色模式变体
• 新布局组件缺少响应式断点

验证

• 颜色对比度符合 WCAG AA（普通文本为 4.5:1，大号文本为 3:1）（显示对比度检查输出）
• 所有交互元素都有可见的焦点指示器
• 图标有无障碍名称（aria-label 或配套的可见文本）
• 颜色、间距和排版均使用设计令牌（无硬编码值）
• 暗色模式渲染正常，没有对比度异常或元素不可见的问题
• 在移动设备（320px）、平板（768px）和桌面设备（1280px）宽度下测试布局