atomic-design-fundamentals

name	atomic-design-fundamentals
user-invocable	false
description	Use when applying Atomic Design methodology to organize UI components into quarks, atoms, molecules, organisms, templates, and pages. Core principles and hierarchy.
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep"]

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:

0. Quarks - Design tokens (colors, spacing, typography scales, shadows)
1. Atoms - Basic building blocks (buttons, inputs, labels)
2. Molecules - Groups of atoms functioning together (search form, card)
3. Organisms - Complex UI sections (header, footer, sidebar)
4. Templates - Page-level layouts without real content
5. 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>
);

// Template using organisms
const MainLayout = ({ children }) => (
  <div>
    <Header />                         {/* Organism */}
    {children}
                             {/* Organism */}
  
);

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.button`
  background-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 }) => (
  <div>
    <Label>{label}</Label>
    <Input {...inputProps} />
  </div>
);

// 3. Build organisms from molecules
const LoginForm = () => (
  <form>
    <FormField label="Email" type="email" />
    <FormField label="Password" type="password" />
    <Button>Login</Button>
  </form>
);

2. 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<InputProps>;
  buttonProps?: Partial<ButtonProps>;
}

// Organisms receive domain-specific props
interface HeaderProps {
  user?: User;
  onLogout: () => void;
  navigation: NavItem[];
}

3. Avoid Business Logic in Atoms

// BAD: Atom with business logic
const PriceButton = ({ productId }) => {
  const price = useProductPrice(productId); // WRONG!
  return <Button>${price}</Button>;
};

// GOOD: Atom receives processed data
const PriceButton = ({ price, onClick }) => (
  <Button onClick={onClick}>${price}</Button>
);

// Business logic lives in organisms or higher
const ProductCard = ({ productId }) => {
  const { price } = useProduct(productId);
  return <PriceButton price={price} onClick={handleBuy} />;
};

4. Document Component Purpose

/**
 * Button - Atomic component for user actions
 *
 * @level Atom
 * @example
 * <Button variant="primary" size="md">Click me</Button>
 */
export const Button: React.FC<ButtonProps> = ({ ... }) => { ... };

/**
 * SearchForm - Search input with submit button
 *
 * @level Molecule
 * @composition Input, Button
 * @example
 * <SearchForm onSubmit={(query) => search(query)} />
 */
export const SearchForm: React.FC<SearchFormProps> = ({ ... }) => { ... };

Common Pitfalls

1. Over-Atomization

// BAD: Too granular - unnecessary atoms
const ButtonText = ({ children }) => <span>{children}</span>;
const ButtonContainer = ({ children }) => <div>{children}</div>;

// GOOD: Appropriate granularity
const Button = ({ children }) => (
  <button className="btn">{children}</button>
);

2. Under-Atomization

// BAD: Too much in one component
const MegaForm = () => (
  <form>
    <div><label>Name</label><input /></div>
    <div><label>Email</label><input /></div>
    <div><label>Message</label><textarea /></div>
    <button>Submit</button>
  </form>
);

// GOOD: Properly decomposed
const ContactForm = () => (
  <form>
    <FormField label="Name" type="text" />
    <FormField label="Email" type="email" />
    <TextAreaField = />
    Submit
  
);

3. 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';

4. 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/