component-patterns

Component-Patterns

适用于 Web 应用的现代 UI 组件模式。遵循当前标准（21st.dev SDK、Tailwind、Radix UI）的组件选择、组合、主题和令牌系统。

范围

适用于以下情况：

• 设计或选择 UI 组件
• 构建设计令牌系统
• 实现主题（深色／浅色／自定义）
• 规划复合组件或变体系统
• 设计表单架构
• 定义响应式组件策略

原则

1. 组合优于继承

通过组合小型、专用的部分来构建组件。使用 props 进行配置，使用 children 提供内容，使用插槽实现差异化。

2. 服务端优先，按需使用客户端

默认使用服务端组件。仅在需要交互性时（状态、事件处理程序、浏览器 API）使用客户端组件。

3. 基于令牌的主题

设计令牌（CSS 自定义属性）控制所有视觉效果。不要硬编码颜色、间距或字体大小。

4. 将无障碍性融入架构

ARIA 角色、键盘导航和焦点管理是组件定义的一部分，而非事后补充。

5. 可组合的基元

基础基元（Button、Input、Text、Box）不带样式且灵活性最高。设计系统组件基于这些基元构建。

规则

组件结构

• 应该：每个组件单独放在一个文件中，并提供清晰的导出。一个组件只负责一项职责。
• 应该：显式定义 props 接口的类型（TypeScript）。对需要验证的输入使用 Zod 架构。
• 应该：对复杂 UI 元素使用复合组件：

  <Card>
    <Card.Header />
    <Card.Body />
    <Card.Footer />
  </Card>
  

• 应该：使用 class-variance-authority（cva）实现变体，而非条件类名。
• 不应该：让组件拥有超过 10 个 props。职责过多时应拆分组件。
• 不应该：使用运行时 CSS-in-JS。静态样式应使用 Tailwind CSS 或 CSS Modules。
• 不应该：堆砌 div。使用语义化 HTML 元素（section、article、nav、header、footer、main）。

主题与设计令牌

• 应该：采用三级令牌系统：
  • 全局令牌：原始值（colors.blue.500、spacing.4、radius.md）
  • 语义令牌：绑定用途（color.primary、color.surface、spacing.section）
  • 组件令牌：针对具体组件（button.bg、card.padding、input.border）
• 应该：通过 CSS 自定义属性切换主题，并在 html／body 上使用 data 属性或 class。
• 应该：至少支持深色／浅色主题。可选支持高对比度主题和品牌专属主题。
• 不应该：使用内联样式设置可由主题控制的值。始终引用令牌。
• 不应该：使用描述颜色的令牌名称（--blue-500）。应使用语义名称（--color-primary）。

表单组件

• 应该：使用架构驱动表单：通过 Zod 架构定义字段和验证规则。
• 应该：使用 React Hook Form 或类似工具提升性能（非受控组件）。
• 应该：统一字段结构：标签 > 输入框 > 辅助文本 > 错误消息。
• 不应该：使用不支持键盘操作的自定义选择框。应使用原生 Select 或 Radix UI Select。
• 不应该：表单提交后缺少加载状态和成功状态。

响应式组件

• 应该：使用容器查询实现基于组件的响应式布局。
• 应该：将移动端变体作为专门的状态（聊天面板变为全屏，侧边栏变为抽屉）。
• 应该：移动端触控目标至少为 44x44px。
• 不应该：使用没有触控替代方案、依赖悬停的交互。
• 不应该：让组件在移动端出现水平滚动（轮播除外）。

扩展规则和代码示例：参见 references/implementation.md

模式

模式	用途	核心理念
三栏布局	仪表盘、聊天应用	导航（240px）+ 内容（弹性）+ 上下文（320px）
渐进式披露卡片	复杂数据、API 响应	摘要 > 详情 > 原始数据
表单与 Agent 混合模式	表单助手	左侧为表单，右侧为聊天，Agent 填充字段
实时状态仪表盘	监控、DevOps	通过 WebSocket/SSE 实时更新，并使用颜色区分的区块
技能配置面板	Agent 设置	系统提示词 + 技能库 + 部署按钮

模式详细说明：请参阅 references/patterns.md

反模式

1. 上帝组件 -- 一个组件同时负责聊天、工具、表单和导航。应将其拆分。
2. 为主题逐层传递属性 -- 主题值需要经过 5 层以上传递。请使用上下文或 CSS 自定义属性。
3. 所有内容都在客户端 -- 所有内容都使用客户端组件。静态内容应使用服务器组件。
4. 使用内联样式进行布局 -- 使用基于令牌的实用类，而不是 style={{ marginTop: 20 }}。
5. 事事使用模态框 -- 优先使用内联展开、抽屉或面板。
6. 失控的状态爆炸 -- 使用集中式状态存储或服务器状态（React Query/SWR）。
7. 硬编码断点 -- 在主题配置中定义断点令牌。
8. 缺少错误边界 -- 在关键区域周围放置 React 错误边界。

检查清单

• 每个组件都有类型化的属性接口（TypeScript）
• 复杂元素使用复合组件（Card、Dialog、Tabs）
• 使用 cva 或类似系统定义变体
• 设计令牌分为三个层级：全局、语义、组件
• 通过 CSS 自定义属性切换主题，而非使用 JS 运行时
• 表单使用 Zod 模式进行验证
• 默认使用服务器组件，仅在需要时使用客户端组件
• 使用容器查询实现基于组件的响应式布局
• 在关键 UI 区域周围设置错误边界
• 移动端触控目标至少为 44x44px
• 所有交互元素均支持键盘导航
• 为屏幕阅读器提供 ARIA 角色和标签
• 使用语义化 HTML 元素，避免 div 堆砌

交叉引用

• design-trends -- 影响组件设计的趋势（动效、深色模式）
• ui-patterns -- 以组件形式实现的 UI 模式
• visual-direction -- 令牌系统中的视觉令牌（颜色、字体排版、间距）
• agent-ui-design -- Agent 专用组件（聊天、工具、流式输出）
• accessibility -- 无障碍要求
• responsive-design -- 断点策略和容器查询