ui-component-patterns

UI 组件模式

当任务是对可复用组件问题进行分类，选择一个主要组件方案，并留下简短的组件架构说明，而不是堆砌大量 React 模式时，请使用此技能。

任务不是罗列所有可能的组件模式。 任务是：

1. 首先识别可复用组件方面的主要需求，
2. 选择一个范围明确的方案，
3. 明确共享与局部、父级与组件之间的所有权划分，
4. 将替代根节点组合与更广泛的系统或无障碍工作分开，
5. 如实转交相邻的前端问题。

请先阅读以下支持文档：

• references/intake-packets-and-route-outs.md
• references/component-api-checklist.md
• references/handoff-boundaries.md

何时使用此技能

• 团队中有太多相似的按钮、卡片、对话框、字段包装器或导航模式，需要一个共享的基础组件或组件族边界。
• 请求混合了变体、插槽、受控与非受控行为、包装器和文档要求，需要在实现前进行分流。
• 你需要判断某个组件应保留为产品局部组件、成为共享基础组件，还是拆分为基础组件加包装器。
• 组件 API 正在不断增加变通入口，需要有人将其收敛为一个合理的方案。
• 难点在于替代根节点组合（button 与 a/路由器 Link、插槽子元素、自定义包装器），而不是纯粹的样式设计。
• 已有 Storybook/示例，但状态、使用规则或边缘情况的文档/验证方案仍不明确。

何时不使用此技能

• 主要任务是令牌治理、视觉语言规则、基础组件命名策略或跨产品系统方向 → design-system
• 主要任务是键盘/焦点行为、语义、标签、播报、对比度或手动无障碍整改 → web-accessibility
• 主要任务是视口/容器适配、断点策略、重排或响应式媒体 → responsive-design
• 主要任务是更广泛的应用/工作流状态所有权、服务端/客户端边界或跨屏幕状态协调 → state-management
• 主要任务是重复渲染、注水、路由性能或包/运行时行为 → react-best-practices
• 可复用组件的边界已确定，实际工作只是实现它；在这种情况下，直接实现，不要重新讨论架构决策

说明

第 1 步：在命名属性前，先明确可复用组件任务

首先记录最小需求信息。

component_intake:
  surface: button-action | form-field | dialog-overlay | nav-menu | card-list-item | table-toolbar | mixed | unknown
  workflow_type: new-primitive | duplicate-cleanup | api-review | wrapper-split | docs-verification | unknown
  primary_packet: primitive-boundary | slot-anatomy | controlled-ownership | alternate-root-composition | docs-verification | mixed | unknown
  ownership_pressure: shared-vs-local | parent-state | wrapper-proliferation | type-safety | docs-drift | mixed | unknown
  signal_source: repeated-components | bug-report | code-review | storybook-gap | design-review | migration | mixed | unknown
  confidence: high | medium | low

规则：不要从“添加一个属性”开始。首先标明可复用组件方面的主要需求。

第 2 步：恰好选择一个主要组件方案

使用 references/intake-packets-and-route-outs.md 中的路由规则。

主要方案：

1. primitive-boundary
2. slot-anatomy
3. controlled-ownership
4. alternate-root-composition
5. docs-verification

选择能够解决当前决策的方案。将其他事项列为后续工作，而不要将它们视为同等的共同负责人。

第 3 步：明确各项不变量

每个严谨的答复都应遵循以下规则：

• 共享组件应解决重复工作，而不是为单个屏幕创建一个局部框架
• 产品专属文案、分析、工作流规则和布局特例通常应属于包装器，而非基础组件
• 变体应表达稳定含义（tone、size、density、state），而不是一次性的屏幕特例
• 插槽/子组件用于提供结构化的灵活性，而不是掩盖混乱的 API
• 如果同时提供受控和非受控行为，契约必须明确且一致
• 替代根节点组合会改变语义和无障碍责任；应明确说明这一点
• Storybook/示例是展示证据的载体，但不能证明组件边界设计合理

第 4 步：构建组件方案包

返回以下结构：

# Component Architecture Packet

## Scope
- Surface:
- Workflow type:
- Primary packet:
- Confidence: high | medium | low

## Current signal
- Main symptom:
- Ownership pressure:
- What is already known:
- What still needs direct verification:

## Recommended first slice
1. ...
2. ...
3. ...

## Component decisions
- Shared vs local:
- Primitive / wrapper split:
- Variants or slots:
- Controlled vs uncontrolled:
- Alternate-root or wrapper rules:

## Docs and verification
- Stories/examples required:
- State / variant matrix:
- Accessibility follow-up:
- Responsive follow-up:

## Ownership and route-outs
- Primary owner:
- Adjacent skills / teams:

第 5 步：使用方案包，而不是庞大的模式图库

从 references/intake-packets-and-route-outs.md 中提取方案包。

方案包规则：

• primitive-boundary → 确定共享范围与局部范围、原语与包装器的拆分方式，以及哪些内容绝不能纳入共享 API
• slot-anatomy → 定义子组件／插槽、变体边界、组合规则，以及可复用结构的解剖结构预期
• controlled-ownership → 确定由父级状态、工作流状态还是组件本地默认值负责生命周期
• alternate-root-composition → 当原语必须组合到其他元素上时，处理 asChild / component / 包装器根节点行为、属性展开、引用和语义约束
• docs-verification → 定义 Storybook／示例、状态矩阵、反面用法说明，以及该组件系列最小但可信的验证范围

第 6 步：将机制选择与归属选择分开

在严肃的回答中使用以下划分：

• 机制 — 变体、插槽、子组件、受控属性、多态根节点、包装器拆分、文档矩阵
• 归属 — ui-component-patterns、design-system、web-accessibility、responsive-design、state-management 或 react-best-practices

如果请求始于屏幕截图、Storybook 偏差或代码差异，请明确说明这些产物只是信号，并非最终的组件决策。

第 7 步：明确分流相邻工作

问题跨越边界时，使用以下分流方式：

• 设计令牌治理、原语命名、贡献政策或跨产品组件标准 → design-system
• 键盘／焦点修复、标签／播报问题、ARIA、对比度、减少动态效果或手动无障碍验证 → web-accessibility
• 视口／容器适配、重排、响应式媒体或密集数据布局策略 → responsive-design
• 应用／工作流状态归属、服务端／客户端状态边界、URL／表单／全局存储决策 → state-management
• 重渲染频繁、注水、包／运行时性能或路由级性能行为 → react-best-practices

出现混合请求时，让 ui-component-patterns 负责可复用组件方案包，并明确指出后续工作应分流到何处。

第 8 步：优先划清合理边界，避免过度泛化属性

当组件不断累积布尔属性、逃生舱或特定产品规则时：

1. 检查 API 是否应拆分为原语加包装器，
2. 将意外出现的变体收敛为更少的语义类别，
3. 将布局或工作流专属行为移出原语，
4. 将系统性或需要大量修复的后续工作分流出去，而不是不断扩大技能范围。

示例

示例 1：按钮系列逐渐偏离

输入：“我们有五种按钮实现，而且大家还在不断添加一次性属性。”

良好的输出方向：

• 选择 primitive-boundary 作为主要方案包
• 保留一个共享操作原语，并视需要提供更精简的图标／按钮组包装器
• 将零散的布尔属性收敛为少量变体／色调／尺寸类别
• 将分析功能和特定屏幕的布局包装器留在原语之外
• 将令牌命名问题分流到 design-system

示例 2：模态框状态归属不清

输入：“模态框应该管理自己的状态，还是始终由父级工作流控制？”

良好的输出方向：

• 选择 controlled-ownership 作为主要方案包
• 将模态框归类为可复用的复合模式
• 当工作流状态、路由或异步提交逻辑很重要时，建议由外部控制状态
• 仅当契约仍然明确时，才提供非受控的便捷用法
• 将键盘／焦点修复细节分流到 web-accessibility

示例 3：链接按钮组合

输入：“我们的设计系统按钮有时需要渲染为路由链接。如何支持这一点，同时不破坏类型或语义？”

良好输出方向：

• 选择 alternate-root-composition 作为主要方案包
• 明确属性展开、ref 转发以及语义和无障碍约束
• 将路由级导航策略或令牌治理排除在基础组件决策之外
• 留下边界明确的包装器／根组件契约，而不是含糊地回答“只需添加一个 as 属性”

示例 4：Storybook 内容偏差

输入：“组件已经存在，但各团队的用法不一致，而且 Storybook 缺少边缘情况。”

良好输出方向：

• 选择 docs-verification 作为主要方案包
• 定义最小状态／变体矩阵和示例集
• 添加避免误用说明和包装器预期
• 将仅涉及无障碍或仅涉及响应式的后续方案包转至其他方向

最佳实践

1. 优先选择能够减少重复工作、又不会凭空创建本地框架的最小可复用基础组件。
2. 明确选择方案包；一个组件决策不应悄然涵盖治理、修复、响应式策略和运行时调优。
3. 将插槽和子组件视为结构化 API 工具，而不是逃避归属决策的方式。
4. 将受控与非受控行为明确写入契约，避免意外形成半受控的混合状态。
5. 对替代根组件组合如实说明 ref、属性展开和语义方面的要求。
6. 将 Storybook／示例作为证据的一部分，但仍要写明文档／验证方案包。
7. 当使用者反复需要逃生口或特定应用的包装器才能使用组件时，重新审视抽象设计。

参考资料

• Radix UI — 组合
• Material UI — 组合
• Storybook 文档
• shadcn/ui 文档