Atomic Design - atoms, molecules, organisms, templates, pages
Build design systems from small, reusable pieces. Components compose into larger patterns.
Each level builds on the previous:
ATOMS (HTML elements + styles)
↓
MOLECULES (simple component groups)
↓
ORGANISMS (complex, standalone sections)
↓
TEMPLATES (page layouts, content-agnostic)
↓
PAGES (templates + real content)
Before building, catalog what exists. Consistency comes from constraint.
Design the components, not the pages. Pages are just assemblies.
Smallest units. Cannot be broken down further.
<!-- Button atom -->
<button class="btn btn-primary">Label</button>
<!-- Input atom -->
<input type="text" class="input" placeholder="Enter text">
<!-- Label atom -->
<label class="label">Field name</label>
<!-- Icon atom -->
<svg class="icon icon-search">...</svg>
Groups of atoms functioning together as a unit.
<!-- Search molecule: input + button + icon -->
<div class="search-field">
<svg class="icon icon-search"></svg>
<input type="search" class="input" placeholder="Search...">
<button class="btn btn-primary">Search</button>
</div>
<!-- Form field molecule: label + input + error -->
<div class="form-field">
<label class="label" for="email">Email</label>
<input class="input" type="email" id="email">
<span class="error-message">Please enter a valid email</span>
</div>
Complex components that form a distinct section of interface.
<!-- Header organism -->
<header class="site-header">
<a href="/" class="logo">Logo</a>
<nav class="main-nav">
<a href="/products">Products</a>
<a href="/about">About</a>
</nav>
<div class="search-field">...</div>
<div class="user-menu">...</div>
</header>
<!-- Card organism -->
<article class="card">
<img class="card-image" src="..." alt="...">
<div class="card-body">
<h3 class="card-title">Title</h3>
<p class="card-description">Description text...</p>
<button class="btn btn-primary">Action</button>
</div>
</article>
Page layouts without real content. Structure, not data.
<!-- Article template -->
<main class="article-template">
<header class="article-header">
<h1>{{ title }}</h1>
<p class="byline">By {{ author }} on {{ date }}</p>
</header>
<article class="article-body">
{{ content }}
</article>
<aside class="article-sidebar">
{{ relatedPosts }}
</aside>
</main>
Templates with real content. Where everything comes together.
<!-- Article page (template + data) -->
<main class="article-template">
<header class="article-header">
<h1>How to Build Design Systems</h1>
<p class="byline">By Brad Frost on January 15, 2024</p>
</header>
<article class="article-body">
<p>Design systems help teams work more efficiently...</p>
</article>
<aside class="article-sidebar">
<h4>Related Posts</h4>
<ul>
<li><a href="/atomic-design">Atomic Design</a></li>
</ul>
</aside>
</main>
components/
├── atoms/
│ ├── button/
│ │ ├── button.html
│ │ ├── button.css
│ │ └── button.stories.js
│ ├── input/
│ ├── label/
│ └── icon/
├── molecules/
│ ├── search-field/
│ ├── form-field/
│ └── card/
├── organisms/
│ ├── header/
│ ├── footer/
│ └── product-grid/
├── templates/
│ ├── article/
│ ├── product-list/
│ └── dashboard/
└── pages/
└── (assembled from templates)
Each component needs:
# button.yml