split-ui-components

UI component decomposition

Choose the smallest sufficient boundary based on business semantics, reasons for change, and state ownership. Do not substitute file line counts, JSX depth, or prop counts for engineering judgment.

Common Path

1. Read project facts

   • First read the project instructions, architectural conventions, the target module README, and the verification commands.
   • Examine the target component, direct callers, adjacent implementations, styles, tests, and public import patterns.
   • Confirm the framework, routing, state management, data fetching, and component library constraints.

2. Inventory responsibilities

   • Separately mark rendering structure, data fetching, state, derived computation, side effects, business interactions, accessibility semantics, styles, and assets.
   • Identify which responsibilities change together for the same business reason, and which merely happen to be written in the same file.

3. Choose boundaries

   • For non-trivial judgments, first read decision-framework.md。
   • React tasks must additionally read react.md; do not apply React's Hook, Effect,key or render tree rules to other frameworks.
   • When boundaries are still unclear or counterexamples are needed for comparison, read examples.md。

1. Choose the smallest sufficient action

   Action	Applicable situation
   Keep as is	Content is short, single-context, with no independent change or interaction boundary
   Extract a private child component	Has clear semantics, independent change, or complete interaction, but is not yet reused across contexts
   Extract a logic unit	State, side effects, or computation form a nameable logical concern and do not require new DOM
   Extract a business shared component	Multiple real consumers share the same business semantics, behavior, and accessibility contract
   Extract a design system primitive component	Reused across businesses and its API, state, theming, accessibility, and documentation are all stable

2. Act according to the requested mode

   • Analysis: report the current state, candidate boundaries, recommended actions, costs, and verification methods, without modifying files.
   • Implementation: modify only what is needed to accomplish the goal, preserving external contracts and user-observable behavior.
   • Review: prioritize pointing out under-decomposition, over-decomposition, incorrect abstraction, state ownership, and interaction completeness issues; clearly state when there are no issues.

3. Verify results

   • Run the project's existing formatting, type checking, testing, and build commands.
   • When UI behavior risk is high, verify key pages, keyboard operation, focus, loading, empty, error, and retry states.
   • Test user-observable behavior; do not treat the private component tree shape as a permanent contract.

Preserve Invariants

• Preserve DOM semantics, accessible names, keyboard behavior, focus order, and event outcomes.
• Preserve state identity, reset timing, async cancellation, and error handling semantics.
• Preserve public props, exports, import paths, and callers, unless the task explicitly requires changes.
• Preserve style scoping, responsive behavior, asset loading, and design system constraints.
• First move stable, clearly bounded code, then change abstractions; do not mix decomposition with unrelated refactoring.

Guardrails

• Do not set uniform thresholds for line counts, JSX levels, Hook counts, or prop counts.
• Do not create shared components because of a single visual box, a single duplication, or "might be reused later".
• Do not force fixed hierarchies for pages, containers, presentational components, or Atomic Design.
• Do not leave all data to parent components, nor push all state down to leaf components; decide based on actual ownership.
• Do not use CommonCard、UniversalSection and similar names to mask different business semantics.
• Do not use guessed rendering performance as the basis for splitting; first locate the problem using actual performance evidence.
• Do not expose internal implementation just to make unit testing easier; prioritize establishing stable behavioral testing seams.

Reference Routing

Need to judge	Read
Framework-agnostic boundaries, decision trees, smells, APIs, and accessibility rules	decision-framework.md
React state, Effect, Custom Hook,key, pure rendering, and composition	react.md
Positive and negative examples, incorrect abstractions, and review output shapes	examples.md