Why Folders Aren't Architecture
Organizing components into /ui, /features, and /pages is a start. It doesn't tell you what a component is allowed to know — or what it must never import.
Architecture, in frontend terms, is about contracts: props shape, styling scope, and whether a piece is allowed to fetch data or only render what it's given.
Three Tiers That Work
Primitives are typed, accessible building blocks — Button, Input, Badge. No business logic, no API calls. Styled with tokens, tested once.
Composites combine primitives for a domain concept — UserCard, FilterBar, OnboardingStep. They may hold local UI state but still receive data via props.
Templates (or pages) wire routing, layout, and data. They're thin. If a template has 200 lines of JSX, something probably belongs in a composite.
“Reuse happens at the primitive and composite level — not by copy-pasting page markup.”
Shipping the Model
Introduce the tiers in a small slice first — one flow, one module catalog in Storybook or a simple docs page. Let the team see the payoff before mandating it repo-wide.
The best component systems feel boring. That's the point.
- Primitives: no domain knowledge.
- Composites: domain UI, props-driven data.
- Templates: orchestration only.