Atomic Design

Concept#

The 5 Stages of Atomic Design#

Atomic Design, created by Brad Frost, structures components by analogy to chemical scales:

  ┌───────────────────────────────────────────────────────────┐
  │  Atoms ──▶ Molecules ──▶ Organisms ──▶ Templates ──▶ Pages│
  └───────────────────────────────────────────────────────────┘

1. Atoms: Basic building blocks of matter. Cannot be broken down further without losing their function.
   • Examples: Button, Input, Label, Avatar.
2. Molecules: Groups of atoms bonded together. Smallest fundamental units of a compound.
   • Examples: SearchForm (Label + Input + Button), UserChip (Avatar + Name).
3. Organisms: Complex components composed of molecules and/or atoms. Join features together.
   • Examples: Navbar (Logo + SearchForm + UserChip + LinkList), ProductCard.
4. Templates: Page-level layouts showing component arrangements (skeletons). They focus on content structures rather than final copy/data.
   • Examples: DashboardLayout (Sidebar + MainView + Header).
5. Pages: Specific instances of templates showing the actual content (live React components populated with actual state and API data).
   • Examples: /settings page, /checkout page.

Strict Boundaries & State Placement#

Atomic design enforces where state, effects, and API fetching reside:

• Atoms & Molecules: Must be strictly stateless (controlled via props) and presentation-focused. They do not invoke fetch requests or read global state contexts.
• Organisms: Can read context or trigger hooks to fetch/manage local domain state.
• Pages: Manage server data fetching, router transitions, and error boundary resolution.

Common Mistakes#

1. Putting business state inside Atoms#

Giving a button component direct access to a database fetching hook makes the button impossible to use in a different area. Keep atoms pure.

2. Ambiguity between Molecules and Organisms#

A navbar is an organism because it comprises multiple disparate units. A search bar is a molecule because its children are directly bound to serve one unified, basic input requirement.

Best Practices#

• Create a strict prop model: Ensure atoms accept generic HTML element properties so they are drop-in substitutes.
• Document with Storybook: Test each atom and molecule in isolation under various viewports and themes.
• Avoid deep component drilldown: Instead of passing props down 5 levels, use slot patterns or context variables.