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:
Quarks - Design tokens (colors, spacing, typography scales, shadows) Atoms - Basic building blocks (buttons, inputs, labels) Molecules - Groups of atoms functioning together (search form, card) Organisms - Complex UI sections (header, footer, sidebar) Templates - Page-level layouts without real content 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.buttonbackground: ${colors.primary[500]}; {/* Quark */}
padding: ${spacing.md}; {/* Quark */};
// Molecule using atoms only
const SearchForm = () => (
);
// Organism using molecules and atoms
const Header = () => (
);
// Template using organisms
const MainLayout = ({ children }) => (
);
Invalid Compositions (Anti-patterns) // BAD: Atom importing from molecule // atoms/Button.tsx import { FormField } from '../molecules'; // WRONG!
// BAD: Molecule importing from organism // molecules/SearchForm.tsx import { Header } from '../organisms'; // WRONG!
// BAD: Skipping levels without justification // organisms/Header.tsx import { MainLayout } from '../templates'; // WRONG!
Design Tokens Integration Token Structure // design-tokens/colors.ts export const colors = { primary: { 50: '#e3f2fd', 100: '#bbdefb', 500: '#2196f3', 900: '#0d47a1', }, neutral: { 0: '#ffffff', 100: '#f5f5f5', 900: '#212121', }, };
// design-tokens/spacing.ts export const spacing = { xs: '4px', sm: '8px', md: '16px', lg: '24px', xl: '32px', };
// design-tokens/typography.ts export const typography = { fontFamily: { sans: 'Inter, system-ui, sans-serif', mono: 'Fira Code, monospace', }, fontSize: { xs: '12px', sm: '14px', base: '16px', lg: '18px', xl: '24px', }, };
Using Tokens in Atoms import { colors, spacing, typography } from '@/design-tokens';
const Button = styled.buttonbackground-color: ${colors.primary[500]};
padding: ${spacing.sm} ${spacing.md};
font-family: ${typography.fontFamily.sans};
font-size: ${typography.fontSize.base};;
Best Practices 1. Start with Atoms
Build your design system from the ground up:
// 1. Define core atoms first const Button = ({ variant, size, children }) => { ... }; const Input = ({ type, placeholder }) => { ... }; const Label = ({ htmlFor, children }) => { ... };
// 2. Compose into molecules
const FormField = ({ label, ...inputProps }) => (
);
// 3. Build organisms from molecules
const LoginForm = () => (
);
- Props Flow Downward // Atoms receive primitive props interface ButtonProps { variant: 'primary' | 'secondary'; size: 'sm' | 'md' | 'lg'; disabled?: boolean; onClick?: () => void; children: React.ReactNode; }
// Molecules receive atoms' props via spread
interface SearchFormProps {
onSubmit: (query: string) => void;
inputProps?: Partial
// Organisms receive domain-specific props interface HeaderProps { user?: User; onLogout: () => void; navigation: NavItem[]; }
- Avoid Business Logic in Atoms // BAD: Atom with business logic const PriceButton = ({ productId }) => { const price = useProductPrice(productId); // WRONG! return ; };
// GOOD: Atom receives processed data const PriceButton = ({ price, onClick }) => ( );
// Business logic lives in organisms or higher
const ProductCard = ({ productId }) => {
const { price } = useProduct(productId);
return
- Document Component Purpose /**
- Button - Atomic component for user actions *
- @level Atom
- @example
-
*/
export const Button: React.FC
= ({ ... }) => { ... };
/*
* SearchForm - Search input with submit button
*
* @level Molecule
* @composition Input, Button
* @example
*
Common Pitfalls 1. Over-Atomization // BAD: Too granular - unnecessary atoms const ButtonText = ({ children }) => {children}; const ButtonContainer = ({ children }) =>
// GOOD: Appropriate granularity const Button = ({ children }) => ( );
- Under-Atomization
// BAD: Too much in one component
const MegaForm = () => (
);
// GOOD: Properly decomposed
const ContactForm = () => (
);
- Circular Dependencies // BAD: Atoms importing from molecules // atoms/Icon.tsx import { IconButton } from '../molecules'; // Creates circular dep!
// GOOD: Keep imports flowing downward // molecules/IconButton.tsx import { Icon } from '../atoms'; import { Button } from '../atoms';
- Inconsistent Naming // BAD: Inconsistent naming patterns atoms/btn.tsx atoms/InputField.tsx atoms/text-label.tsx
// GOOD: Consistent PascalCase atoms/Button.tsx atoms/Input.tsx atoms/Label.tsx
When to Use This Skill Setting up a new design system Organizing an existing component library Onboarding team members to atomic design Auditing component structure Planning component architecture Creating documentation for design systems Refactoring monolithic components Related Skills atomic-design-quarks - Design tokens and primitive values atomic-design-atoms - Creating atomic-level components atomic-design-molecules - Composing atoms into molecules atomic-design-organisms - Building complex organisms atomic-design-templates - Page layouts without content atomic-design-integration - Framework-specific implementation Resources Documentation Brad Frost's Atomic Design: https://atomicdesign.bradfrost.com/ Pattern Lab: https://patternlab.io/ Books "Atomic Design" by Brad Frost "Design Systems" by Alla Kholmatova Tools Storybook: https://storybook.js.org/ Pattern Lab: https://patternlab.io/ Fractal: https://fractal.build/