A React app sprawls when components, styles, hooks, and API calls are organized
by type (all hooks here, all styles there). We want each feature to be a
self-contained unit that’s easy to find, move, and reason about.
Decision
Feature-based vertical slices. Each page owns its full slice:
The authoritative, current operational detail is in each app repo’s CLAUDE.md; this ADR records the structural decision and its rationale.
Consequences
A feature is one folder you can read top-to-bottom; deleting/moving it is clean.
index.tsx/styles.ts separation keeps JSX readable and styling greppable.
More folders/files per feature, accepted for locality and consistency.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
// index.tsx — zero styled.X declarationsimport { StyledLabel } from './styles';export type LabelKind = 'personal' | 'team' | 'academic' | 'progress' | 'public';export function StatusLabel({ kind, children }: StatusLabelProps) { return <StyledLabel $kind={kind}>{children}</StyledLabel>;}export { LabelRow } from './styles';
The pair, every time: index.tsx holds JSX and nothing else, styles.ts holds every styled.X. Not a style preference — it means JSX stays readable and styling stays
greppable, and a component is one folder you can move or delete cleanly.
styles.ts is .ts, not .tsx, because tagged templates are not JSX. The separation is
enforceable rather than remembered:
# should always print nothinggrep -rln "styled\." src/ --include="index.tsx"
Transient props carry the $ prefix — $kind — so style-only props never reach the DOM
and React never warns about an unknown attribute.
The same shape nests: a page-specific subcomponent lives under that page’s components/,
and pages never reach into another page’s internals.