Atomic Design

Best Practice: Atomic Design

Atomic Design is a methodology, introduced by Brad Frost in his 2016 book, for creating and organizing user interfaces as a hierarchy of reusable parts. It defines five levels: atoms (basic HTML elements like buttons and inputs), molecules (small groups of atoms), organisms (larger composite sections), templates (page-level layouts without real content), and pages (templates filled with real data). The mental model gives teams a shared vocabulary and a clear path from primitives to full screens, which keeps a UI consistent and maintainable as it scales.

Step-by-Step Implementation Guidance

1. Inventory existing UI to find repeated elements and patterns.
2. Define atoms as the smallest, single-purpose components.
3. Compose molecules from atoms, such as a labeled input with a button.
4. Build organisms from molecules and atoms to form distinct interface sections.
5. Assemble templates that show layout and content structure.
6. Create pages by injecting real data into templates and test edge cases.
7. Document every level in a living component library.

Common Mistakes Teams Make When Ignoring This Practice

• Building one-off components that duplicate existing patterns.
• Arguing endlessly over whether a part is an atom or a molecule instead of shipping.
• Skipping documentation so the hierarchy is unknowable to new developers.
• Coupling atoms to specific page contexts, breaking reuse.
• Letting templates and pages drift from the underlying components.

Tools and Techniques That Support This Practice

• Storybook for cataloging components at each level.
• Pattern Lab, the reference Atomic Design tool.
• Figma component libraries mirroring the same hierarchy.
• Design tokens shared across atoms.

How This Practice Applies to Different Migration Types

• Cloud Migration: Component libraries decouple UI from hosting, easing re-platforming.
• Database Migration: Templates with mock data let UI evolve independently of schema changes.
• SaaS Migration: Map the new vendor's UI patterns to your atomic hierarchy for parity.
• Codebase Migration: Port the UI level by level, starting with atoms, to reduce risk.

Checklist

• UI inventory of repeated patterns done.
• Atoms defined as single-purpose components.
• Molecules and organisms composed from atoms.
• Templates show layout without real data.
• Pages tested with real content.
• Every level documented in a library.