component-architecture

组件架构

将杂乱的一次性组件转变为可组合的系统：审查现有组件，将其划分为原子级别，然后把问题最严重的组件重构为精简、类型明确且有文档说明的组件。**首要原则：组件只有在职责单一、且其属性接口能让无效状态无法表示时，才有存在的价值。**交付可运行的重构代码，以及用户可以据此采取行动的审查结果——绝不只提供建议。

何时使用／何时不使用

适用于：组件拆分、属性接口设计、变体系统、提取共享库、决定采用受控还是非受控模式、组件文档编写。

以下情况应转交给其他技能：

• 视觉设计令牌（间距、颜色、字体比例）→ skills/frontend-design/design-foundation
• 组件内的动画／反馈 → skills/frontend-design/interaction-physics
• 组件的键盘／ARIA 行为 → skills/frontend-design/accessibility-excellence
• 渲染性能（记忆化、重复渲染）→ skills/frontend-design/performance-optimization
• 不确定该从整个前端的何处着手 → skills/frontend-design/frontend-orchestrator

步骤 0 — 检查代码库，然后只询问尚未明确的信息

在提出任何建议之前，先根据实际代码清点组件：

1. 找出组件目录（components/、ui/、src/app/**、lib/）。记录所用的框架和样式方案（Tailwind、CSS Modules、CSS-in-JS、原生 CSS），并沿用现有方案；未经允许，绝不引入新的样式系统。
2. 统计组件数量并标记：超过约 200 行的文件、同时获取数据并渲染详细标记语言的组件、重复的 UI（多种按钮／输入框／卡片实现）、重复使用相同值的内联样式、基于类的继承。
3. 检查是否已有设计系统或 UI 套件（shadcn/ui、MUI、Chakra、内部包）。如果有，就遵循其约定进行扩展——不要另建一套平行系统。

向用户询问（一次问完，只问代码无法回答的问题）：范围（整个应用、某项功能，还是一个棘手的组件？）以及目标是建立共享库／包，还是只整理本地结构。如果请求已明确范围（例如“重构这个文件”），就不要询问——说明假设后继续。

工作流

1. 将清点结果划分为原子级别

• 原子 — 不可再分，不依赖其他组件：Button、Input、Label、Icon、Badge、Spinner。
• 分子 — 由原子组成、用途单一的小型组合：FormInput（Label+Input+Error）、SearchBar。
• 有机体 — 具有业务用途且通常包含状态的区块：NavBar、Card、Modal、Form。
• 模板 — 用于排列有机体的页面布局；不适用于不同类型页面之间的复用。
• 页面 — 包含真实数据的模板；可用来发现边缘情况。

判断规则：如果无法对组件归类，说明它承担的职责过多——它应该成为重构对象，而不是分类体系的问题。

2. 按影响力确定重构优先级

顺序：（1）重复的原子（先合并——其他一切都以它们为基础），（2）违反单一职责原则的巨型组件，（3）允许无效状态的属性接口，（4）缺少变体而迫使复制粘贴的情况。列出优先级最高的 3–5 项重构，并各用一句话说明收益；大范围重写前，请用户确认范围。对于单个组件的请求，无需征求确认，直接重构。

3. 按照以下决策规则重构

• 拆分规则： 同时负责获取数据、管理表单状态并渲染详细标记的组件，应拆分为一个协调组件和多个职责明确的子组件。按职责拆分，而非按行数拆分。
• 始终优先组合，而非继承。 变体通过属性实现（variant、size），预设则使用轻量封装——绝不使用子类。
• 受控与非受控： 如果编辑时其他 UI 需要响应值的变化（实时校验、依赖字段、字符计数），则使用受控模式。只在提交时读取一次、读取后不再处理的输入，使用非受控模式即可。绝不在同一组件中混用两种模式。
• 属性接口规则： 使用联合类型，而非可能冲突的布尔属性（例如使用 variant: 'primary' | 'danger'，而非 isPrimary + isDanger）；将选项限制为有效值；透传 className 和 ARIA 属性；回调命名为 on<Event>。如果两个布尔属性可以组合成无效状态，就重新设计接口。
• 提取阈值： 在第 2～3 次重复时提取共享组件，前提是这些副本确实属于同一概念。两个看起来相似、但因不同原因而变化的事物应保持独立——错误的抽象比重复更昂贵。

原子组件的规范结构（完整示例见 references/patterns.md）：

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

export const Button = ({ variant = 'primary', size = 'md', disabled, loading, ...rest }: ButtonProps) => (
  <button
    className={`button button--${variant} button--${size}`}
    disabled={disabled || loading}
    {...rest}
  />
);

4. 记录所构建的内容

每个提取或重构的共享组件都要有文档：用途、属性表、变体及其适用场景、状态、无障碍说明和边界情况。使用 references/patterns.md 中的模板。将文档放在团队能够看到的地方（如果存在 Storybook，则使用 Storybook 故事；否则使用同目录下的 README.md 或 JSDoc）。

必需的输出格式

交付以下两项：

1. 代码 — 就地编辑重构或新建的组件文件，遵循项目现有的样式和命名约定。更新所有调用位置；应用必须仍能编译。

2. 组件架构审计（Markdown）：

## Component Inventory
| Component | File | Level | Verdict | Issue |
| Button (x3 impls) | src/... | atom | consolidate | 3 duplicate implementations |
| UserProfile | src/... | ??? | split | fetches + validates + renders (412 lines) |
| Card | src/... | organism | keep | — |

## Refactors applied
1. [name] — what changed, files touched, why (one line each)

## Refactors recommended (not applied)
1. [name] — payoff, estimated blast radius

## Conventions going forward
- Directory structure: [atoms/molecules/organisms or project's own scheme]
- Prop rules adopted: [union variants, no conflicting booleans, ...]
- When to extract: [the 2–3 rule as applied to this codebase]

质量标准（交付前检查）

• 每个重构后的组件都只有一个职责，并且能用一句话说明
• 没有属性接口会产生无效状态（没有相互冲突的布尔属性，也没有不受约束的变体字符串）
• 交付代码中的任何变体都不使用继承
• 每个共享组件都明确采用受控或非受控模式，绝不两者兼有
• 交互式组件保持键盘可操作性和可见焦点（不要移除已有功能）
• 已更新所有调用位置；导入路径有效；遵循现有样式系统
• 每个新建的共享组件都有文档（用途、属性、变体、状态）
• 审计表涵盖检查范围，而不只是改动过的文件

严格禁止：未经说明就重命名用户的公开组件 API；附带引入新的状态管理或样式库；过早拆分——职责连贯的 40 行组件无需拆分。

集成

• skills/frontend-design/design-foundation → 为此技能提供组件应使用的设计令牌词汇（间距／颜色／字体变量）。
• skills/frontend-design/interaction-physics ← 使用你的组件状态（悬停／激活／加载）并为其添加动画。
• skills/frontend-design/loading-states 和 skills/frontend-design/error-handling-recovery ← 使用你的组件清单，系统化添加加载／错误变体。
• skills/frontend-design/accessibility-excellence ← 审查你产出的组件；使用语义化元素进行构建，以减少后续修正。

参考资料

• references/patterns.md — 各原子层级的完整代码示例、单一职责的重构前后对比、受控／非受控实现、组件文档模板和尺寸约定。编写重构代码或文档时请阅读。