frontend-components

Atomic Design Placement

• atoms/ — smallest reusable UI, no custom component children (e.g. EmptyState, StatusBadge)
• molecules/ — reusable compositions of atoms, single responsibility (e.g. SearchBar, ConfirmDialog)
• organisms/ — large reusable sections composing multiple molecules/atoms (e.g. DataTable, Sidebar)
• global/ — app-wide: layouts, providers, nav, footer
• ui/ — shadcn/ui primitives — DO NOT move or edit
• Components specific to a single route go in routes/{route}/components/ — not in the atomic system regardless of size

File Splitting

• Target: ~300 lines per file. Hard max: 400 lines — split immediately when reached.
• Minimum sub-component size: 150 lines — never extract smaller pieces.
• Split priority (mandatory order): hook → data → schema → types → sub-components (last resort only, after steps 1–4 are exhausted)

Folder Rule

When a component has any co-located partition (hook, schema, data, types), it moves into a kebab-case folder with a barrel index.ts. The main .tsx lives inside the folder. Sub-components go in a components/ subfolder — never directly beside the parent.

Route-Scoped Components

• Single-route components live in routes/{group}/{route}/components/
• Promote when shared: if used by 2+ routes → move to components/atoms|molecules|organisms/, add props, export from barrel
• Recursive nesting: route-scoped sub-components follow the same folder rule — if a sub-component needs a hook/schema/data partition, it gets its own kebab-case folder with barrel index.ts inside the parent's components/ dir

Key Rules

• Reusability-first: a genuinely generic component (works with any data on any page) belongs in atomic design from day one — even if only one route uses it today
• One hook per file: .hook.ts exports a single hook consolidating all data fetching, mutations, state, and handlers for that view
• No export default — always named exports
• Max 5 props — if 6+, move logic into the component's own hook or a Zustand store; never prop-drill through 2+ levels
• Barrel exports are mandatory — every folder containing components must have an index.ts
• No private named sub-components — ever. Do NOT define helper components like const Row = () => <li>...</li> or const TodoItem = ... inside a .tsx file alongside the exported component. There is NO exception to this rule, regardless of file size. "Inline them instead" means: delete the named component entirely and write its JSX directly inside the parent's render — no extraction to separate files, no private const, just flat JSX. If the JSX repetition is too large to inline (file would exceed 400 lines), ONLY THEN extract to a separate file in components/. Never create a named component in the same file as another exported component.
• No thin orchestrator components — a component whose entire body is just <ChildA /><ChildB /> with no logic is forbidden. Merge its JSX into the real parent.
• @/ alias for imports — use @/components/..., @/hooks/... etc.; relative paths only for siblings in the same folder
• PascalCase for component files — EmptyState.tsx, SearchBar.tsx, TopNav.tsx. Partitions use PascalCase prefix: AuthForm.hook.ts, AuthForm.schema.ts, AuthForm.data.ts
• Co-location applies to route pages — Landing.page.tsx can have Landing.hook.ts, Landing.data.ts, Landing.schema.ts beside it in the same folder