Atomic Design

Atomic Design Patterns

Component Hierarchy

src/components/
├── atoms/           # Smallest building blocks
├── molecules/       # Simple component groups
├── organisms/       # Complex UI sections
├── templates/       # Page layouts
└── pages/           # Complete views

Level Definitions

Atoms

Indivisible UI elements. No dependencies on other components.

// atoms/Button/Button.tsx
export const Button: FC<ButtonProps> = ({ children, variant, size, ...props }) => (
  <button className={cn('btn', `btn--${variant}`, `btn--${size}`)} {...props}>
    {children}
  </button>
);

// atoms/Input/Input.tsx
export const Input: FC<InputProps> = ({ label, error, ...props }) => (
  <div className="input-wrapper">
    {label && <label>{label}</label>}
    <input className={cn('input', error && 'input--error')} {...props} />
    {error && <span className="input-error">{error}</span>}
  </div>
);

// atoms/Icon/Icon.tsx
export const Icon: FC<IconProps> = ({ name, size = 24 }) => (
  <svg className="icon" width={size} height={size}>
    <use href={`#icon-${name}`} />
  </svg>
);

Examples: Button, Input, Label, Icon, Avatar, Badge, Spinner, Divider

Molecules

Combine atoms into functional units with single responsibility.

// molecules/SearchField/SearchField.tsx
export const SearchField: FC<SearchFieldProps> = ({ onSearch, placeholder }) => {
  const [value, setValue] = useState('');
  
  return (
    <div className="search-field">
      <Input
        value={value}
        => setValue(e.target.value)}
        placeholder={placeholder}
      />
      <Button variant="ghost" => onSearch(value)}>
        <Icon name="search" />
      </Button>
    </div>
  );
};

// molecules/FormField/FormField.tsx
export const FormField: FC<FormFieldProps> = ({ label, error, children }) => (
  <div className="form-field">
    <Label>{label}</Label>
    {children}
    {error && <ErrorMessage>{error}</ErrorMessage>}
  </div>
);

Examples: SearchField, FormField, NavItem, Card, MenuItem, Toast

Organisms

Complex, self-contained sections with business logic.

// organisms/Header/Header.tsx
export const Header: FC<HeaderProps> = ({ user, onLogout }) => (
  <header className="header">
    <Logo />
    <Navigation />
    <SearchField />
    <UserMenu user={user} />
  </header>
);

// organisms/ProductCard/ProductCard.tsx
export const ProductCard: FC<ProductCardProps> = ({ product, onAddToCart }) => (
  <article className="product-card">
    <Image src={product.image} alt={product.name} />
    <div className="product-card__content">
      <Heading level={3}>{product.name}</Heading>
      <Price value={product.price} />
      <Rating value={product.rating} />
      <Button => onAddToCart(product)}>Add to Cart</Button>
    </div>
  </article>
);

Examples: Header, Footer, ProductCard, CommentSection, Sidebar, DataTable

Templates

Page-level layouts without real content. Define structure only.

// templates/DashboardLayout/DashboardLayout.tsx
export const DashboardLayout: FC<DashboardLayoutProps> = ({ 
  sidebar, 
  header, 
  content 
}) => (
  <div className="dashboard-layout">
    <aside className="dashboard-layout__sidebar">{sidebar}</aside>
    <div className="dashboard-layout__main">
      <header className="dashboard-layout__header">{header}</header>
      <main className="dashboard-layout__content">{content}</main>
    </div>
  </div>
);

Pages

Templates filled with real data. Connect to state/APIs.

// pages/DashboardPage/DashboardPage.tsx
export const DashboardPage: FC = () => {
  const { data: stats } = useStats();
  const { user } = useAuth();

  return (
    <DashboardLayout
      sidebar={<DashboardSidebar />}
      header={<Header user={user} />}
      content={<StatsGrid stats={stats} />}
    />
  );
};

Decision Guide

Naming Conventions

• Atoms: Single noun (Button, Input, Icon)
• Molecules: Descriptive compound (SearchField, NavItem)
• Organisms: Domain-specific (ProductCard, CheckoutForm)
• Templates: Layout suffix (DashboardLayout, AuthLayout)
• Pages: Page suffix (HomePage, ProductPage)

Export Pattern

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

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