Atomic Design Fundamentals

Atomic Design Fundamentals

Master Brad Frost's Atomic Design methodology (extended with quarks) for building scalable, maintainable component-based user interfaces. This skill covers the core hierarchy, principles, and organization strategies for modern design systems.

Overview

Atomic Design is a methodology for creating design systems inspired by chemistry. Just as atoms combine to form molecules, which combine to form organisms, UI components follow a similar hierarchical structure. We extend this with quarks - the sub-atomic level of design tokens:

1. Quarks - Design tokens (colors, spacing, typography scales, shadows)
2. Atoms - Basic building blocks (buttons, inputs, labels)
3. Molecules - Groups of atoms functioning together (search form, card)
4. Organisms - Complex UI sections (header, footer, sidebar)
5. Templates - Page-level layouts without real content
6. Pages - Templates with real representative content

The Six Stages

0. Quarks

The sub-atomic building blocks - design tokens and primitive values that atoms consume. Quarks are not UI components themselves; they are the raw values that define your design language.

Examples:

• Color tokens (primary-500, neutral-100)
• Spacing scales (4px, 8px, 16px)
• Typography tokens (font sizes, weights, line heights)
• Border radii
• Shadow definitions
• Animation durations and easing functions
• Breakpoints

Characteristics:

• Pure values, not visual components
• Cannot import from any other level
• Define the design language
• Enable theming and consistency
• Single source of truth for design decisions

1. Atoms

The smallest functional UI units of your interface. Atoms consume quarks for styling but cannot be broken down further without losing meaning.

Examples:

• Buttons
• Input fields
• Labels
• Icons
• Typography elements (headings, paragraphs)
• Color swatches
• Avatars

Characteristics:

• Self-contained and independent
• No business logic
• Highly reusable
• Accept styling props
• Framework-agnostic when possible

2. Molecules

Combinations of atoms working together as a unit. Molecules have a single responsibility but are composed of multiple atoms.

Examples:

• Search form (input + button)
• Form field (label + input + error message)
• Media object (avatar + text)
• Card header (icon + title + action button)
• Navigation link (icon + text)

Characteristics:

• Composed of atoms only
• Single purpose or function
• Reusable across contexts
• May have minimal internal state

3. Organisms

Complex, standalone sections of an interface. Organisms represent distinct sections that could exist independently.

Examples:

• Header (logo + navigation + user menu)
• Footer (links + social icons + copyright)
• Product card (image + title + price + add to cart)
• Comment section (avatar + content + actions)
• Sidebar navigation

Characteristics:

• Composed of molecules and atoms
• Represent distinct UI sections
• May contain business logic
• Context-specific but reusable

4. Templates

Page-level layouts that define content structure without actual content. Templates show the skeletal structure of a page.

Examples:

• Blog post template (header + content area + sidebar + footer)
• Dashboard layout (navigation + main content + widgets)
• Product page layout (gallery + details + related products)
• Landing page structure

Characteristics:

• Composed of organisms
• Define page structure
• Use placeholder content
• Establish content hierarchy

5. Pages

Specific instances of templates with real, representative content. Pages are what users actually see and interact with.

Examples:

• Homepage with actual hero content
• Product detail with real product data
• User profile with actual user information
• Blog post with real article content

Characteristics:

• Templates filled with real content
• Represent actual user experience
• Used for testing and validation
• May reveal design issues

Directory Structure

Standard Structure

src/
  quarks/                    # Design tokens
    index.ts
    colors.ts
    spacing.ts
    typography.ts
    shadows.ts
    borders.ts
  components/
    atoms/
      Button/
        Button.tsx
        Button.test.tsx
        Button.stories.tsx
        index.ts
      Input/
      Label/
      Icon/
    molecules/
      SearchForm/
      FormField/
      Card/
    organisms/
      Header/
      Footer/
      ProductCard/
    templates/
      MainLayout/
      DashboardLayout/
    pages/
      HomePage/
      ProductPage/

Alternative Flat Structure

src/
  quarks/
    colors.ts
    spacing.ts
    typography.ts
  components/
    atoms/
      Button.tsx
      Input.tsx
      Label.tsx
    molecules/
      SearchForm.tsx
      FormField.tsx
    organisms/
      Header.tsx
      Footer.tsx
    templates/
      MainLayout.tsx
    pages/
      HomePage.tsx

Feature-Based Hybrid

src/
  quarks/                    # Shared design tokens
    index.ts
    colors.ts
    spacing.ts
  features/
    products/
      components/
        atoms/
        molecules/
        organisms/
      templates/
      pages/
    checkout/
      components/
        atoms/
        molecules/
        organisms/
  shared/
    components/
      atoms/
      molecules/

Component Naming Conventions

File Naming

# PascalCase for component files
Button.tsx
SearchForm.tsx
ProductCard.tsx

# Index files for clean imports
index.ts

# Test files
Button.test.tsx
Button.spec.tsx

# Story files (Storybook)
Button.stories.tsx

Component Naming

// Atoms - simple, descriptive names
Button
Input
Label
Avatar
Icon

// Molecules - action or composition-based names
SearchForm
FormField
MediaObject
NavItem

// Organisms - section or feature-based names
Header
Footer
ProductCard
CommentSection
UserProfile

// Templates - layout-focused names
MainLayout
DashboardLayout
AuthLayout

// Pages - page-specific names
HomePage
ProductDetailPage
CheckoutPage

Import Patterns

Barrel Exports

// src/components/atoms/index.ts
export { Button } from './Button';
export { Input } from './Input';
export { Label } from './Label';
export { Icon } from './Icon';

// src/components/molecules/index.ts
export { SearchForm } from './SearchForm';
export { FormField } from './FormField';

// src/components/index.ts
export * from './atoms';
export * from './molecules';
export * from './organisms';

Usage

// Clean imports from barrel files
import { Button, Input, Label } from '@/components/atoms';
import { SearchForm, FormField } from '@/components/molecules';
import { Header, Footer } from '@/components/organisms';

// Or from unified barrel
import { Button, SearchForm, Header } from '@/components';

Composition Rules

Strict Hierarchy

Quarks     -> Used by: Atoms, Molecules, Organisms, Templates, Pages
Atoms      -> Used by: Molecules, Organisms, Templates, Pages
Molecules  -> Used by: Organisms, Templates, Pages
Organisms  -> Used by: Templates, Pages
Templates  -> Used by: Pages
Pages      -> Not used by other components

Valid Compositions

// Atom using quarks for styling
import { colors, spacing } from '@/quarks';

const Button = styled.button`
  background: ${colors.primary[500]};  {/* Quark */}
  padding: ${spacing.md};              {/* Quark */}
`;

// Molecule using atoms only
const SearchForm = () => (
  <form>
    <Input placeholder="Search..." />  {/* Atom */}
    <Button>Search</Button>            {/* Atom */}
  </form>
);

// Organism using molecules and atoms
const Header = () => (
  <header>
    <Logo />                           {/* Atom */}
    <Navigation />                     {/* Molecule */}
    <SearchForm />                     {/* Molecule */}
    <UserMenu />                       {/* Molecule */}
  </header>
);