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} onChange={(e) => setValue(e.target.value)} placeholder={placeholder} /> <Button variant="ghost" onClick={() => 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 onSearch={handleSearch} /> <UserMenu user={user} onLogout={onLogout} /> </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 onClick={() => 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

Question Atom Molecule Organism

Has child components? No Yes Yes

Has business logic? No Minimal Yes

Reusable across projects? Yes Usually Sometimes

Contains API calls? No No Possible

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