Component Architecture
Last updated:
Component architecture defines how shared UI scales — consistency without god components.
01 — Purpose
How interfaces scale over time
Component architecture defines how shared UI stays consistent as products and teams grow.
Good component architecture creates predictability — teams know where behaviour lives, how to compose screens, and what not to duplicate. Bad architecture centralises everything in a few “god” abstractions that nobody dares to change.
See design system governance, CSS architecture, and accessibility standard.
02 — Principles
What good components share
Reusable, understandable, predictable, and composable — not configurable into oblivion.
- clear responsibility — one job per component or primitive
- sensible API surface — props and options that map to real product needs
- restrained configuration — fewer variants, more composition
- accessible defaults — semantics, keyboard, and focus built in
- isolated styling — scoped CSS or tokens, not leaking globals
03 — Practice
Composition over configuration
Smaller composable pieces usually scale better than one giant configurable widget.
- prefer composition — layout + card + actions, not a mega-card with forty props
- document usage, accessibility expectations, and behavioural rules per component
- align with design tokens and state classes — see design tokens and state classes
- consider rendering cost, bundle size, and hydration — see hydration costs
- use container queries where components must reflow in narrow panels — see container queries
04 — Avoid
Architecture that collapses under growth
Giant components and prop sprawl are how design systems become legacy.
- god components — one file that owns layout, data, styling, and every edge case
- excessive prop complexity — boolean flags that multiply hidden behaviour
- duplicated variants — Button, Button2, PrimaryButton in different folders
- tightly coupled logic — components that only work inside one parent or route
- documentation-free shared UI — no guidance on when or how to use it
05 — Close
Reduce complexity, do not centralise it
Components should make the next screen easier — not add another layer of mystery.
Review new shared components for scope: can this be two primitives instead of one configurable monolith? If the answer is yes, split before adoption spreads.
See frontend documentation standards, progressive enhancement strategy, and frontend QA checklist.