1# Component Architecture Rules
2 
3Use these rules for React component structure, ownership, state, props, effects, and module organization.
4 
5## Ownership
6 
7Flag:
8 
9- State, query, mutation, or handlers hoisted above the lowest component that actually uses them.
10- Parent components owning row/item actions that do not coordinate a workflow.
11- Prop drilling through multiple pass-through layers.
12- A page/tab-level section component becoming the data owner without needing a shared snapshot or shared loading/error/empty UI.
13- Feature code promoted to shared only because it appears once or might be reused later.
14 
15Accept repeated TanStack Query calls in siblings when each component independently consumes the data. Cache deduplication is not a reason to hoist by itself.
16 
17## Component Boundaries
18 
19Flag:
20 
21- React component files over 300 lines when the file mixes multiple responsibilities that can be split into focused colocated components, hooks, or utilities.
22- Shallow wrappers that only rename props or hide the real primitive.
23- Extra DOM wrappers that do not provide layout, semantics, accessibility, state ownership, or library integration.
24- Dialog/dropdown/popover hidden surfaces that obscure the parent flow when they should be extracted into a small local component.
25- Business forms, menu bodies, or one-off helpers moved away from their owner without reuse or semantic value.
26 
27Prefer colocated components split by actual data and state needs.
28 
29## Bad Component Design Patterns
30 
31Flag:
32 
33- Refactors of existing navigation, sidebar, dropdown, webapp list, or app-switching UI that do not preserve behavior-sensitive interactions such as expand/collapse arrows, hover persistence, pin/delete controls, routing, keyboard/focus handling, or open-state ownership.
34- Components that mix data fetching, mutation side effects, popup state, form validation, layout, and row rendering without a clear owner.
35- Generic components with many boolean props that encode one feature's workflow.
36- A shared component that imports feature-specific copy, routes, or API contracts.
37- A feature component that accepts pre-rendered fragments only to avoid placing ownership correctly.
38- A child component that receives both raw server data and separately derived flags for the same concept.
39- A wrapper that changes accessible semantics of the primitive it wraps.
40- A component that exposes controlled props but still keeps a competing private state for the same value.
41- A component that cannot render empty, loading, or missing optional API fields without caller-side preprocessing.
42 
43When existing components already own interaction logic, prefer reusing or extending them. If a refactor is necessary, preserve the old interaction contract and add or update focused tests for changed behavior.
44 
45## Props And Types
46 
47Flag:
48 
49- `React.FC` / `FC`.
50- Default exports outside framework-required files.
51- Named `Props` types for trivial one-off props where inline typing is clearer.
52- Props named by UI implementation instead of domain/API role.
53- API data converted too early or under a generic name that breaks traceability.
54- Callers duplicating fallback checks that the lowest rendering component already handles.
55 
56Prefer top-level `function` declarations for components and module helpers. Use arrow functions for callbacks and local lambdas.
57 
58## Effects
59 
60Flag effects that:
61 
62- Transform props/state for rendering.
63- Copy one state value into another representing the same concept.
64- Handle user actions that belong in event handlers.
65- Reset state from props when a keyed reset, stable ID, or render-time derivation would work.
66- Fetch data that belongs in framework APIs or TanStack Query.
67 
68If an effect remains, it must synchronize with a named external system: browser API, subscription, timer, analytics-on-visibility, non-React widget, or imperative DOM integration.
69 
70## State Modeling
71 
72Flag:
73 
74- Storing derived booleans, disabled flags, default tabs, or loading labels that can be calculated from current query/feature state.
75- Local state used to fake server data or generated contract fields.
76- UI state persisted to localStorage when it is live app state.
77- Feature-local mock shells wired to unrelated existing APIs before the real API is confirmed.
78 
79Prefer render-time derivation. Keep true local state for user choices, transient input, controlled popups, and feature UI state that has no server source.
80 
81## Navigation
82 
83Flag:
84 
85- Imperative router navigation for ordinary links.
86- Button semantics used for navigation.
87- Navigation state hidden in component state when URL state is required for shareable filters, tabs, or pagination.
88 
89Use `Link` for normal navigation. Use router APIs for mutation success, guarded redirects, command flows, or form submission side effects.
90