component-colocation

description	Use after migrating/refactoring features (especially tables/data grids) when reviewing component structure - enforces merging over-split components, colocating files where used, removing unused code, following vertical slice architecture. Prevents premature abstraction and over-engineering.
name	component-colocation
metadata	{"skiller":{"source":".agents/rules/component-colocation.mdc"}}

Component Colocation & Refactoring

Overview

React Compiler removes many performance-only reasons to split components where it is enabled, including the canonical example app. Merge related code, colocate files where they are used, and delete unused files. Split only for genuine reuse, package boundaries, independent testing, or hook decoupling.

Kitcn Boundary

• Apply this to example/**, www/**, and package UI modules after checking whether the affected app actually enables React Compiler.
• Do not merge across public package exports, runtime entrypoints, generated boundaries, CLI template ownership, or React/Solid framework boundaries.
• Scaffolded fixture output is generated. Improve its source template, then regenerate fixtures; never colocate by editing committed fixture output first.

When to Use

• After implementing a new feature (especially tables/data grids)
• When reviewing component structure during refactoring
• When you notice files spread across multiple folders that are only used in one place
• When cleaning up after removing a context/state management migration

Core Principles

1. Don't Over-Split Components

React Compiler handles memoization automatically. You don't need to split components into smaller pieces for performance.

// ❌ Over-split: separate files for each button group
FormDraftActionButtons.tsx;
FormEsignPendingActionButtons.tsx;
FormSignedActionButtons.tsx;
// ↑ Each file has similar hooks, similar logic, different render

// ✅ Single file with all logic colocated
ReportHistoryActionButtons.tsx;
// ↑ One component, switch/conditional for different states

2. Large Files Are Fine

Don't fear 300-500 line components. Splitting creates:

• More files to navigate
• Props drilling between components
• Harder-to-follow data flow
• Redundant hook calls

3. Colocate Where Used

Vertical slice architecture: Keep feature code together.

// ❌ Scattered across shared folders
src/components/shared/ActionButtons.tsx
src/components/shared/StatusBadge.tsx
src/hooks/useReportActions.ts

// ✅ Colocated in feature folder
src/app/(protected)/report-history/
  _components/
    report-history-action-buttons.tsx
    report-history-columns.tsx
    report-history-table.tsx

4. Ask Before Splitting

Only split components when:

1. Hook decoupling: Component needs different hook contexts
2. Genuine reuse: Used in 2+ unrelated features
3. Explicit request: User asks for separation

Never split for:

• "Readability" (large files are readable)
• "Performance" (React Compiler handles it)
• "Single responsibility" (SRP doesn't mean tiny files)

Post-Feature Checklist

After implementing a feature, review:

• Unused files: Delete components/hooks no longer referenced
• Over-split components: Merge files that are only used together
• Scattered locations: Move files to feature's _components folder if only used there
• Prop drilling: If passing 5+ props between split components, merge them
• Duplicate hooks: If multiple components call same hooks, merge components

Common Mistakes

Pattern	Problem	Fix
One component per file for "each variant"	7 files instead of 1	Merge into single component with conditionals
Shared folder for feature-specific code	Hard to find, pollutes shared space	Move to feature's _components
Keeping deleted context's components	Dead code, confusion	Delete immediately
Splitting for "testability"	Tests can test large components	Keep together, test the whole thing

Red Flags - Merge Instead

• Creating new file for component used in only one place
• Passing props through 2+ levels just to reach a split component
• Multiple small components with identical hook calls
• "Shared" folder containing feature-specific code
• Components named *Part1, *Section, *Inner

Example: Action Buttons Refactor

Before (over-split):

report-history-table/
  ActionButtons.tsx           # Router wrapper
  FormDraftActionButtons.tsx  # Draft state buttons
  FormEsignPendingActionButtons.tsx
  FormISOActionButtons.tsx
  FormMarkedCompleteActionButtons.tsx
  FormRefusedActionButtons.tsx
  FormSignedESignedActionButtons.tsx
  RefusedButton.tsx          # Single button extracted

After (colocated):

_components/
  report-history-action-buttons.tsx  # All logic in one file

Single 400-line file with switch statement for each form status. All hooks called once, no prop drilling, easy to follow.