Getting Started with Atomic Design

Every frontend team eventually faces the same problem: components multiply, naming conventions drift, and what started as a clean codebase becomes a patchwork of one-off solutions. Atomic Design solves this by giving your component architecture a clear, repeatable structure inspired by chemistry. Instead of guessing where a new component belongs, you follow a hierarchy that scales from a single button to an entire application.

What is Atomic Design?

Brad Frost introduced Atomic Design in 2013 as a mental model for building user interfaces. The core idea is simple: just as matter in nature is composed of atoms that combine into molecules, then into complex organisms, user interfaces can be decomposed into five hierarchical levels.

The five levels are Atoms, Molecules, Organisms, Templates, and Pages. Each level builds on the one below it. The critical rule: dependencies only flow downward — atoms import nothing, molecules import only atoms, organisms import molecules, and so on. This single constraint eliminates circular dependencies and makes every component predictable.

The Five Levels Explained

Level 1: Atoms

The smallest meaningful UI elements. Buttons, inputs, labels, headings, icons, badges, images, and links. They cannot be broken down further without losing their purpose. Think of them as the periodic table of your design system. Atoms are self-contained — they receive all data through props and style themselves using design tokens.

Level 2: Molecules

Small groups of atoms working together as a functional unit. A SearchBar (Input + Button), a FormField (Label + Input + Error), a NavLink (Link + Icon), a Card (Image + Heading + Text). The key test: does this group serve a single, clear purpose? If yes, it is a molecule.

Level 3: Organisms

Complex, self-contained sections of a page. A Header (Logo + Nav + SearchBar + LanguageSwitcher), a Hero section, a Footer, a ContactForm, a BlogSidebar, a PricingTable. Organisms are the first level that feels like a real "section" of a website. They manage layout and coordination of their children.

Level 4: Templates & Pages

Templates define the page structure — where organisms go, how the layout flows. In Astro, templates map to layout files (BaseLayout, BlogLayout). Pages are templates filled with real content — the actual route files in src/pages/ that users see. Pages handle data fetching and pass it down to layouts and organisms.

Atoms in Practice

Atoms must be self-contained. They receive all their data through props and never fetch data or import other components. They style themselves using design tokens (CSS custom properties), never hardcoded values.

---
interface Props {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
}
const { variant = 'primary', size = 'md', disabled = false } = Astro.props;
---
<button
  class:list={['btn', `btn--${variant}`, `btn--${size}`]}
  disabled={disabled}
>
  <slot />
</button>

---
interface Props {
  type?: 'text' | 'email' | 'search' | 'password';
  name: string;
  placeholder?: string;
  required?: boolean;
}
const { type = 'text', name, placeholder, required = false } = Astro.props;
---
<input
  type={type}
  name={name}
  placeholder={placeholder}
  required={required}
  class="input"
/>

---
interface Props {
  level?: 1 | 2 | 3 | 4 | 5 | 6;
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl';
}
const { level = 2, size = 'lg' } = Astro.props;
const Tag = `h${level}`;
---
<Tag class:list={['heading', `heading--${size}`]}>
  <slot />
</Tag>

Molecules: The Functional Glue

Molecules combine two or more atoms into a functional unit. The key distinction: a molecule does something that its individual atoms cannot do alone.

The Molecule Test

Ask yourself: “Does this group of atoms serve a single, clear purpose?” If yes, it is a molecule. If it serves multiple purposes or contains other molecules, it is probably an organism.

Organisms: Real Page Sections

Organisms are the first level that feels like a “section” of a page. They are complex, self-contained components made of molecules and atoms.

Folder Structure in Astro

src/
├── components/
│   ├── atoms/        → Button, Input, Heading, Icon, Badge, Image, Link
│   ├── molecules/    → SearchBar, FormField, NavLink, Card, Breadcrumbs
│   ├── organisms/    → Header, Footer, Hero, ContactForm, BlogSidebar
│   └── seo/          → SEO.astro, Schema components
├── layouts/          → BaseLayout, BlogLayout (= Templates)
├── pages/            → index.astro, blog/[slug].astro (= Pages)
├── styles/
│   ├── global.css
│   └── tokens/       → colors.css, typography.css, spacing.css
├── lib/              → utils.ts, constants.ts
└── types/            → TypeScript definitions

The Golden Rule

Every atom needs: proper prop interfaces, accessible markup, complete state coverage (hover, focus, active, disabled, error), and design token integration. A poorly designed atom propagates its problems everywhere.

Evolution of a Project

Common Pitfalls

Why Atomic Design Wins

After applying Atomic Design across more than 30 production projects, these are the benefits that consistently emerge. If you want to see how this methodology plays out in a real codebase with over 45 components, read Atomic Design in Practice.