split-ui-components · diff
git:20260730.da34dd5 to git:20261018.4caf5d8
23 added, 53 removed. Audit A to A.
---
name: split-ui-components
- description: "Analyze, plan, implement, and review frontend UI component boundaries across component-based frameworks, with React-specific guidance. Use when Codex is asked to split or refactor components, review oversized or over-abstracted UI, decide state ownership, extract Hooks or Composables, design component APIs, preserve behavior during UI refactors, or handle requests about 组件拆分、组件边界、前端重构、过大组件或过度抽象."
+ description: "Choose or refactor UI component boundaries and state ownership. Use for oversized components, over-abstraction or behavior-preserving component extraction."
---
# UI 组件拆分
- 按业务语义、变化原因和状态所有权选择最小充分边界。不要用文件行数、JSX 深度或 props 数量代替工程判断。
-
- ## Common Path
-
- 1. **读取项目事实**
- - 先读项目指令、架构约定、目标模块 README 和验证命令。
- - 查看目标组件、直接调用方、相邻实现、样式、测试和公开导入方式。
- - 确认框架、路由、状态管理、数据获取和组件库约束。
-
- 2. **盘点职责**
- - 分别标记渲染结构、数据获取、状态、派生计算、副作用、业务交互、无障碍语义、样式和资源。
- - 识别哪些职责因同一个业务原因一起变化，哪些只是恰好写在同一文件。
+ 按业务语义、变化原因和状态所有权选择边界。文件行数、JSX 深度和 props 数量不能代替工程判断。
- 3. **选择边界**
- - 非平凡判断先读 [decision-framework.md](references/decision-framework.md)。
- - React 任务必须再读 [react.md](references/react.md)；其他框架不要套用 React 的 Hook、Effect、`key` 或渲染树规则。
- - 边界仍不清晰或需要对照反例时读 [examples.md](references/examples.md)。
+ ## 选择动作
- 4. **选择最小充分动作**
+ 检查目标组件、相关调用方及影响本次改动的项目约定。区分一起变化的职责与仅处在同一文件的代码，不预读整套架构或框架文档。
- | 动作 | 适用情况 |
- | --- | --- |
- | 保持原状 | 内容短小、单一语境、没有独立变化或交互边界 |
- | 提取私有子组件 | 有清晰语义、独立变化或完整交互，但尚无跨语境复用 |
- | 提取逻辑单元 | 状态、副作用或计算形成可命名逻辑关注点，不需要新增 DOM |
- | 提取业务共享组件 | 多个真实消费者共享同一业务语义、行为和可访问性契约 |
- | 提取设计系统基础组件 | 跨业务复用且 API、状态、主题、无障碍和文档均已稳定 |
+ | 事实 | 动作 |
+ | --- | --- |
+ | 单一语境且没有独立变化或交互边界 | 保持原状 |
+ | 有清晰语义和独立职责，尚无跨语境复用 | 提取私有组件或逻辑单元 |
+ | 多个实际消费者共享同一业务契约 | 提取业务共享组件 |
+ | 跨业务契约、主题和无障碍要求均已稳定 | 考虑设计系统基础组件 |
- 5. **按请求模式行动**
- - 分析：报告现状、候选边界、建议动作、代价和验证方法，不修改文件。
- - 实施：只修改完成目标所需内容，保持外部契约和用户可观察行为。
- - 评审：优先指出欠拆、过拆、错误抽象、状态所有权和交互完整性问题；没有问题时明确说明。
+ 分析请求只给建议；实施请求完成边界调整和相关验证；评审请求优先指出有证据的欠拆、过拆、错误抽象或状态问题。不要把局部拆分扩大为全仓迁移。
- 6. **验证结果**
- - 运行项目已有的格式、类型检查、测试和构建命令。
- - UI 行为风险较高时验证关键页面、键盘操作、焦点、加载、空、错误和重试状态。
- - 测试用户可观察行为，不把私有组件树形状当成永久契约。
+ ## 保持的契约
- ## Preserve Invariants
+ - DOM 语义、可访问名称、键盘操作、焦点和事件结果。
+ - 状态身份、重置时机、异步取消及错误处理。
+ - 公开 props、导出、导入路径及调用方，除非任务明确要求变更。
+ - 样式作用域、响应式行为和资源加载。
- - 保持 DOM 语义、可访问名称、键盘行为、焦点顺序和事件结果。
- - 保持状态身份、重置时机、异步取消和错误处理语义。
- - 保持公开 props、导出、导入路径和调用方，除非任务明确要求变更。
- - 保持样式作用域、响应式行为、资源加载和设计系统约束。
- - 先移动稳定、边界清楚的代码，再改变抽象；不要把拆分和无关重构混在一起。
+ 先移动边界清楚的代码，再做必要抽象。按实际所有权放置状态；不因视觉框、一次重复或可能的未来复用创建通用组件。不为方便测试暴露内部实现，也不以猜测的性能问题驱动拆分。
- ## Guardrails
+ ## 按需参考与验证
- - 不设置统一的行数、JSX 层数、Hook 数或 props 数阈值。
- - 不因一个视觉框、一次重复或“以后可能复用”创建共享组件。
- - 不强制页面、容器、展示组件或 Atomic Design 的固定层级。
- - 不把所有数据留给父组件，也不把所有状态下放给叶子组件；按实际所有权决定。
- - 不用 `CommonCard`、`UniversalSection` 等名称掩盖不同业务语义。
- - 不以猜测的渲染性能作为拆分依据；先用实际性能证据定位问题。
- - 不为了让单元测试容易而暴露内部实现；优先建立稳定的行为测试缝。
+ - 边界或共享 API 存在真实取舍时读 [decision-framework.md](references/decision-framework.md)。
+ - React 状态身份、Effect、Hook 或组合语义受影响时读 [react.md](references/react.md)；其他框架不套用 React 规则。
+ - 需要辨别具体错误抽象时读 [examples.md](references/examples.md)。
- ## Reference Routing
+ 根据变更运行相关类型、行为或构建检查，遵守项目强制门禁。状态、交互和生命周期变化需要验证对应的页面操作与失败路径；单纯代码移动不自动要求所有状态或全量构建。测试用户可观察行为，不固定私有组件树。
- | 需要判断 | 读取 |
- | --- | --- |
- | 框架无关的边界、决策树、异味、API 和无障碍规则 | [decision-framework.md](references/decision-framework.md) |
- | React 状态、Effect、Custom Hook、`key`、纯渲染和组合 | [react.md](references/react.md) |
- | 正反示例、错误抽象和评审输出形状 | [examples.md](references/examples.md) |
+ 完成范围内修复、相关复验和临时资源清理，再说明结果和剩余验证缺口。