Component Composition

Component Composition (Atomic Design)

Overview

All web UI follows Atomic Design on top of a shared component library. The quality bar is reuse and correct placement: a new screen is assembled from existing atoms and molecules, and anything genuinely new is added at the right level so the next screen reuses it too.

Core principle: Reuse before you build, and place new components at the level the import-direction rule expects — ui → atoms → molecules → organisms → templates → pages.

No design system yet in this repo (no tokens, no components/ levels, no INVENTORY.md)? Lay the foundation with web-design-system-foundation first — this skill assumes it already exists.

The Levels

The reuse procedure (every time, before writing a component)

1. Read src/components/INVENTORY.md.
2. Grep the level folders for the noun (grep -ri button src/components).
3. Found a close match → reuse it, or extend it with a new variant backward-compatibly (add a cva variant, don't change an existing one's output).
4. Nothing close → create it at the right level (see placement below) and add its INVENTORY.md line in the same commit.

Placement decision list

• Does it fetch data or own app state? → page (or a container that wraps a page-level hook).
• Is it a page skeleton with no content, owning only the grid/breakpoints? → template.
• Several molecules/atoms forming a page section (pricing grid, contact form, header)? → organism.
• Label + input + error, or icon + text pairing — two or three atoms as one reusable unit? → molecule.
• A single element with variants and no composition (one button, one badge)? → atom.
• A generated/wrapped Radix or shadcn primitive with no app-specific variants of its own? → ui/.

Import direction

ui ← atoms ← molecules ← organisms ← templates ← pages. A level imports only from levels to its left, plus lib/. Same-level imports are allowed ONLY for organisms (an organism may contain another organism). hooks/ and api/ are imported only by pages/. Where the repo runs ui-guard (from web-design-system-foundation), it enforces this on every build — a violation fails npm run build, it isn't a style note.

Atom API rules

• No outer margin or absolute positioning — the parent lays out with gap-*; an atom that sets its own margin breaks every layout that reuses it.
• Variants through cva, never a pile of boolean props; className is merged last via cn() and callers use it for layout only (width, grid placement, alignment) — never to restyle the atom; a new look is a new variant.
• Every interactive state is styled: hover, focus-visible, active, disabled, aria-invalid, loading where relevant.
• Accepts ref as a plain prop (React 19) or forwardRef (React 18) — a shared atom that can't take a ref breaks the first caller that needs to measure or focus it.

Composition over prop explosions

Three or more isX booleans on one component is a sign it's actually two components, or that it needs children/named slots instead. Prefer:

// ❌ boolean-prop explosion
<Card isHighlighted isCompact hasFooter footerText="Save" />

// ✅ composition: the variant is a real prop, content is children/slots
<Card variant="highlighted" size="compact">
  <Card.Footer>Save</Card.Footer>
</Card>

An explicit variant component (PrimaryCard vs <Card variant="primary">) is fine when the two really don't share markup — don't force one component to branch internally just to avoid two small ones.

Templates and organisms are container-aware

A template owns the grid and the breakpoints (sm:/md:/lg: live here) — organisms placed inside it should not assume a specific viewport width. Where an organism's internal layout depends on the space it's given rather than the screen, use a @container query or let the parent grid/flex sizing drive it, so the same organism works in a full-width template and a narrower sidebar slot.