atomic-design-fundamentals

What this skill does

# 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

```text
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

```text
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

```text
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

```text
# 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```text
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

```typescript
// 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 orga