atomic-design-organisms

name	atomic-design-organisms
description	Use when building complex organisms from molecules and atoms like headers, footers, product cards, and sidebars. Organisms are distinct UI sections.
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep"]

Atomic Design: Organisms

Master the creation of organisms - complex, distinct sections of an interface composed of molecules and atoms. Organisms represent standalone UI sections that could exist independently.

What Are Organisms?

Organisms are relatively complex UI components that form distinct sections of an interface. They are:

• Composed of molecules and atoms: May include both levels
• Standalone sections: Can exist independently on a page
• Context-aware: Often tied to specific business contexts
• Stateful: May manage significant internal state
• Reusable: Used across different templates and pages

Common Organism Types

Navigation Organisms

• Header (logo + navigation + user menu)
• Footer (links + social icons + legal)
• Sidebar (navigation + user info + actions)
• Breadcrumbs (full navigation path)

Content Organisms

• Product cards (image + details + actions)
• Comment sections (comments + reply forms)
• Article previews (title + excerpt + meta)
• User profiles (avatar + bio + stats)

Form Organisms

• Login forms (fields + actions + links)
• Registration forms (multi-step fields)
• Checkout forms (payment + shipping)
• Search with filters

Data Display Organisms

• Data tables (header + rows + pagination)
• Dashboards (stats + charts + actions)
• Timelines (events + connectors)
• Galleries (images + navigation)

Header Organism Example

Complete Implementation

// organisms/Header/Header.tsx
import React, { useState } from 'react';
import { Icon } from '@/components/atoms/Icon';
import { Button } from '@/components/atoms/Button';
import { Avatar } from '@/components/atoms/Avatar';
import { NavItem } from '@/components/molecules/NavItem';
import { SearchForm } from '@/components/molecules/SearchForm';
import styles from './Header.module.css';

export interface NavLink {
  id: string;
  label: string;
  href: string;
  icon?: string;
  badge?: number;
}

export interface User {
  id: string;
  name: string;
  email: string;
  avatar?: string;
}

export   {
  
  : .;
  
  : [];
  
  ?: ;
  
  ?:  | ;
  
  ?: ;
  
  ?:  ;
  
  ?:  ;
  
  ?:  ;
  
  ?:  ;
}

  : .<> =  {
   [mobileMenuOpen, setMobileMenuOpen] = ();
   [userMenuOpen, setUserMenuOpen] = ();

   (
    
  );
};

. = ;

/* organisms/Header/Header.module.css */
.header {
  position: sticky;
  top: 0;
  z-index: 100;
  background-color: var(--color-white);
  border-bottom: 1px solid var(--color-neutral-200);
}

.container {
  display: flex;
  align-items: center;
  gap: 24px;
  max-width: 1280px;
  margin: 0 auto;
  padding: 12px 24px;
}

.logo {
  flex-shrink: 0;
}

.nav {
  display: none;
  flex: 1;
}

@media (min-width: 768px) {
  .nav {
    display: block;
  }
}

.navList {
  display: flex;
  gap: 8px;
  list-style: none;
  margin: 0;
  padding: 0;
}

.search {
  display: none;
  width: 280px;
}

@media (min-width: ) {
   {
    : block;
  }
}

 {
  : flex;
  : center;
  : ;
}

 {
  : relative;
}

 {
  : flex;
  : center;
  : ;
  :  ;
  : transparent;
  :  solid (--color-neutral-);
  : ;
  : pointer;
}

 {
  : none;
}

 (: ) {
   {
    : inline;
  }
}

 {
  : absolute;
  : ;
  : ;
  : ;
  : ;
  : (--color-white);
  :  solid (--color-neutral-);
  : ;
  :    (, , , );
  : hidden;
}

  {
  : flex;
  : center;
  : ;
  : ;
  :  ;
  : transparent;
  : none;
  : pointer;
  : left;
}

  {
  : (--color-neutral-);
}

 {
  : flex;
  : ;
  : transparent;
  : none;
  : pointer;
}

 (: ) {
   {
    : none;
  }
}

 {
  :  solid (--color-neutral-);
  : ;
}

  {
  : flex;
  : column;
  : ;
  : none;
  : ;
  : ;
}

Footer Organism Example

// organisms/Footer/Footer.tsx
import React from 'react';
import { Icon } from '@/components/atoms/Icon';
import { Text } from '@/components/atoms/Typography';
import styles from './Footer.module.css';

export interface FooterLink {
  label: string;
  href: string;
}

export interface FooterSection {
  title: string;
  links: FooterLink[];
}

export interface SocialLink {
  platform: string;
  href: string;
  icon: string;
}

export interface FooterProps {
  /** Footer logo */
  logo: React.ReactNode;
  /** Tagline or description */
  tagline?: string;
  /** Link sections */
  sections: FooterSection[];
  /** Social media links */
  ?: [];
  
  ?: ;
  
  ?: [];
}

  : .<> =  {
   currentYear =  ().();
   copyrightText = copyright || ;

   (
    
  );
};

. = ;

ProductCard Organism Example

// organisms/ProductCard/ProductCard.tsx
import React from 'react';
import { Button } from '@/components/atoms/Button';
import { Badge } from '@/components/atoms/Badge';
import { Icon } from '@/components/atoms/Icon';
import { Text, Heading } from '@/components/atoms/Typography';
import styles from './ProductCard.module.css';

export interface Product {
  id: string;
  name: string;
  description?: string;
  price: number;
  originalPrice?: number;
  currency?: string;
  image: string;
  rating?: number;
  reviewCount?: number;
  inStock?: boolean;
  badge?: string;
}

export interface ProductCardProps {
  
  : ;
  
  ?:  ;
  
  ?:  ;
  
  ?:  ;
  
  ?: ;
  
  ?: ;
}

  : .<> =  {
   {
    id,
    name,
    description,
    price,
    originalPrice,
    currency = ,
    image,
    rating,
    reviewCount,
    inStock = ,
    badge,
  } = product;

   discount = originalPrice
    ? .(((originalPrice - price) / originalPrice) * )
    : ;

    = () => {
     ;
  };

   (
    
  );
};

. = ;

CommentSection Organism Example

// organisms/CommentSection/CommentSection.tsx
import React, { useState } from 'react';
import { Button } from '@/components/atoms/Button';
import { Heading, Text } from '@/components/atoms/Typography';
import { MediaObject } from '@/components/molecules/MediaObject';
import { FormField } from '@/components/molecules/FormField';
import styles from './CommentSection.module.css';

export interface Comment {
  id: string;
  author: {
    name: string;
    avatar?: string;
  };
  content: string;
  createdAt: string;
  likes: number;
  replies?: Comment[];
}

export interface CommentSectionProps {
  /** Comments list */
  comments: Comment[];
  /** Total comment count */
  totalCount: ;
  
  ?: { : ; ?:  };
  
  ?:  ;
  
  ?:  ;
  
  ?:  ;
  
  ?: ;
}

  : .<> =  {
   [newComment, setNewComment] = ();
   [replyingTo, setReplyingTo] = useState< | >();
   [replyContent, setReplyContent] = ();

    = () => {
    e.();
     (newComment.() && onSubmit) {
      (newComment.());
      ();
    }
  };

    = () => {
     (replyContent.() && onSubmit) {
      (replyContent.(), parentId);
      ();
      ();
    }
  };

    = () => {
      (dateString).(, {
      : ,
      : ,
      : ,
    });
  };

    = () => (
    
  );

   (
    
  );
};

. = ;

Sidebar Organism Example

// organisms/Sidebar/Sidebar.tsx
import React from 'react';
import { Avatar } from '@/components/atoms/Avatar';
import { Text } from '@/components/atoms/Typography';
import { NavItem } from '@/components/molecules/NavItem';
import styles from './Sidebar.module.css';

export interface SidebarLink {
  id: string;
  label: string;
  href: string;
  icon: string;
  badge?: number;
}

export interface SidebarSection {
  title?: string;
  links: SidebarLink[];
}

export interface SidebarProps {
  /** User info */
  user?: {
    name: string;
    email: string;
    avatar?: string;
  };
  /** Navigation sections */
  sections: [];
  
  ?: ;
  
  ?: ;
  
  ?:  ;
}

  : .<> =  {
   (
    
  );
};

. = ;

DataTable Organism Example

// organisms/DataTable/DataTable.tsx
import React, { useState } from 'react';
import { Checkbox } from '@/components/atoms/Checkbox';
import { Button } from '@/components/atoms/Button';
import { Icon } from '@/components/atoms/Icon';
import { Text } from '@/components/atoms/Typography';
import { ListItem } from '@/components/molecules/ListItem';
import styles from './DataTable.module.css';

export interface Column<T> {
  id: string;
  header: string;
  accessor: keyof T | ((row: T) => React.ReactNode);
  sortable?: boolean;
  width?: string;
}

export interface DataTableProps<T extends { id: string }> {
  /** Table columns */
  : <T>[];
  
  : T[];
  
  ?: [];
  
  ?:  ;
  
  ?: ;
  
  ?:  | ;
  
  ?:  ;
  
  ?:  ;
  
  ?: ;
  
  ?: ;
}

  <T  { :  }>({
  columns,
  data,
  selectedIds = [],
  onSelectionChange,
  sortField,
  sortDirection,
  onSort,
  onRowClick,
  isLoading = ,
  emptyMessage = ,
}: <T>) {
   allSelected = data. >  && selectedIds. === data.;
   someSelected = selectedIds. >  && !allSelected;

    = () => {
     (onSelectionChange) {
      (allSelected ? [] : data.( row.));
    }
  };

    = () => {
     (onSelectionChange) {
      (
        selected
          ? [...selectedIds, id]
          : selectedIds.( selectedId !== id)
      );
    }
  };

    = () => {
     ( column. === ) {
       column.(row);
    }
     row[column.]  .;
  };

   (
    
  );
}

. = ;

Best Practices

1. Keep Business Logic Contained

// GOOD: Organism manages its own related state
const ProductCard = ({ product, onAddToCart }) => {
  const [isAdding, setIsAdding] = useState(false);

  const handleAddToCart = async () => {
    setIsAdding(true);
    await onAddToCart(product.id);
    setIsAdding(false);
  };

  return <Button onClick={handleAddToCart} isLoading={isAdding}>Add</Button>;
};

// BAD: State managed externally for no reason
const ProductCard = ({ product, isAdding, onAddToCart }) => {
  return <Button onClick={() => onAddToCart(product.id)} isLoading={isAdding}>Add</Button>;
};

2. Accept Data Objects

// GOOD: Accept domain objects
interface HeaderProps {
  user: User;
  navigation: NavLink[];
}

// BAD: Flat props explosion
interface HeaderProps {
  userName: string;
  userEmail: string;
  userAvatar: string;
  navItem1Label: string;
  navItem1Href: string;
  // ...endless props
}

3. Compose with Clear Hierarchy

// GOOD: Clear molecule/atom composition
const Header = () => (
  <header>
    <Logo />                    {/* Atom */}
    <Navigation>                {/* Molecule */}
      <NavItem />
      <NavItem />
    </Navigation>
    <SearchForm />              {/* Molecule */}
    <UserMenu />                {/* Molecule */}
  </header>
);

Anti-Patterns to Avoid

1. Organisms Within Organisms

// BAD: Nesting organisms
const Dashboard = () => (
  <div>
    <Header />                  {/* Organism */}
    <Sidebar />                 {/* Organism */}
    <MainContent>
      <DataTable />             {/* Another organism */}
    </MainContent>
  </div>
);

// This should be a template, not an organism!

2. Too Generic Organisms

// BAD: Generic "Section" organism
const Section = ({ children }) => <section>{children}</section>;

// GOOD: Specific, purposeful organisms
const ProductSection = ({ products }) => { ... };
const CommentSection = ({ comments }) => { ... };

When to Use This Skill

• Building page sections like headers and footers
• Creating complex interactive components
• Assembling product or content cards
• Building data display components
• Creating form containers with validation

Related Skills

• atomic-design-fundamentals - Core methodology overview
• atomic-design-molecules - Composing atoms into molecules
• atomic-design-templates - Page layouts without content