atomic-design

What this skill does

# Atomic Design

**Version:** 1.0.0
**Portability:** Universal

---

## Objective

Teaches Brad Frost's Atomic Design methodology for building scalable, maintainable UI component systems through compositional hierarchy.

**Purpose:** Create consistent, reusable UI components organized from simple to complex, enabling efficient development and maintenance of user interfaces.

**Scope:**
- **Included:** Component hierarchy (atoms/molecules/organisms/templates), composition patterns, design tokens, component organization
- **Excluded:** Specific framework implementations, visual design choices, styling approaches

---

## Core Principles

### Principle 1: Hierarchical Composition (Atoms → Molecules → Organisms → Templates)

**The Principle:** Build UI components in layers of increasing complexity, where each layer is composed of elements from the layer below.

**Why this matters:** Bottom-up composition creates consistency and reusability. Changing an atom cascades improvements through all molecules and organisms that use it.

**The Four Levels:**
1. **Atoms:** Basic building blocks (buttons, inputs, labels, icons)
2. **Molecules:** Simple combinations of atoms (form fields, cards, search bars)
3. **Organisms:** Complex components (navigation bars, data tables, complete forms)
4. **Templates:** Page-level layouts (dashboard, list view, detail view)

**How to apply:**
- Start with atoms (smallest reusable pieces)
- Combine atoms into molecules
- Compose molecules into organisms
- Arrange organisms into templates
- Never skip levels (don't build organisms directly from raw HTML)

**Example:**
```
Atom: Button component
  ↓
Molecule: Search bar (Input atom + Button atom + Icon atom)
  ↓
Organism: Header navigation (Logo atom + Search bar molecule + Navigation menu molecule)
  ↓
Template: Dashboard layout (Header organism + Sidebar organism + Content area)
```

### Principle 2: Single Responsibility per Component

**The Principle:** Each component should do one thing well. Atoms are indivisible, molecules combine for a single purpose, organisms encapsulate a complete feature.

**Why this matters:** Single-responsibility components are easier to test, reuse, and maintain. Over-loaded components become brittle and hard to change.

**How to apply:**
- Atoms: One visual element (a button, not a button with a dropdown)
- Molecules: One interaction pattern (search bar for searching, not search-and-filter-and-sort)
- Organisms: One feature area (navigation, not navigation-and-footer-and-sidebar)

**Example:**
```
❌ Bad: "SuperButton" - Button that can be primary/secondary/icon/dropdown/link
✓ Good: Button (atom), IconButton (molecule), DropdownButton (molecule) - each focused

❌ Bad: "FormControls" - Handles all form logic, validation, submission, layout
✓ Good: Input (atom), FormField (molecule), Form (organism) - clear responsibilities
```

### Principle 3: Design Tokens for Consistency

**The Principle:** Extract design decisions (colors, typography, spacing) into reusable tokens referenced by all components.

**Why this matters:** Centralized design tokens ensure visual consistency and make theme changes simple. Without tokens, design changes require editing hundreds of components.

**How to apply:**
1. Define tokens first (colors, fonts, sizes, spacing)
2. Components reference tokens, never hard-code values
3. Changing a token updates all components that use it

**Example:**
```css
/* Design Tokens */
--color-primary: #0066cc;
--color-danger: #cc0000;
--spacing-sm: 8px;
--spacing-md: 16px;
--font-size-body: 16px;
--font-size-heading: 24px;

/* Atom: Button uses tokens */
.button-primary {
  background-color: var(--color-primary);  /* Not #0066cc */
  padding: var(--spacing-sm);              /* Not 8px */
  font-size: var(--font-size-body);        /* Not 16px */
}

/* Changing --color-primary updates ALL primary buttons */
```

### Principle 4: Composition Over Inheritance

**The Principle:** Build complex components by composing simpler ones, not by inheriting or extending base components.

**Why this matters:** Composition is more flexible than inheritance. You can combine components in novel ways without modifying their source code.

**How to apply:**
- Pass atoms/molecules as props/children to organisms
- Use container/presentational patterns
- Avoid deep component hierarchies (prefer flat composition)

**Example (React):**
```jsx
// ❌ Bad: Inheritance
class FancyButton extends Button {
  render() {
    return <Button className="fancy" {...this.props} />;
  }
}

// ✓ Good: Composition
const FancyButton = ({ children, ...props }) => (
  <Button className="fancy" {...props}>
    <Icon name="star" />
    {children}
  </Button>
);

// ✓ Good: Flexible composition
<Card>
  <CardHeader>
    <Heading level={2}>Title</Heading>
    <Button variant="icon">⋯</Button>
  </CardHeader>
  <CardBody>
    <Text>Content</Text>
  </CardBody>
</Card>
```

---

## Constraints and Boundaries

### DO:
- Start with atoms, build up to templates (bottom-up)
- Extract design decisions into tokens
- Keep components focused (single responsibility)
- Compose complex components from simpler ones
- Document the hierarchy and relationships
- Test components in isolation

### DON'T:
- Skip levels (e.g., build organisms directly from raw markup)
- Hard-code design values (use tokens instead)
- Create "god components" that do everything
- Use inheritance when composition works
- Build templates before you have organisms
- Couple components to specific data fetching logic (keep presentational)

**Rationale:** These constraints ensure maintainable, consistent, reusable component systems.

---

## Usage Patterns

### Pattern 1: Building a Form System

**Scenario:** Creating a consistent form UI across an application.

**Approach:**

**1. Atoms:**
```
- Input (text input element)
- Label (text label element)
- ErrorMessage (error text element)
- Button (submit button)
```

**2. Molecules:**
```
- FormField (Label + Input + ErrorMessage)
- FormActions (Cancel button + Submit button)
```

**3. Organisms:**
```
- Form (Collection of FormFields + FormActions)
- LoginForm (Form with specific email + password fields)
- RegistrationForm (Form with email + password + confirm fields)
```

**4. Templates:**
```
- AuthPage (Page layout with LoginForm or RegistrationForm)
```

**Benefits:**
- Change Input styling → All forms update
- Validation logic in FormField → Consistent everywhere
- Reuse LoginForm in modal, page, sidebar

### Pattern 2: Design Token Extraction

**Scenario:** Existing app with inconsistent styling needs design system.

**Approach:**

**1. Audit existing UI:**
- Find all unique colors: #0066cc, #0055bb, #0044aa, #0033cc (4 blues!)
- Find all unique spacings: 5px, 8px, 10px, 12px, 15px, 16px, 20px
- Find all unique font sizes: 12px, 14px, 15px, 16px, 18px, 20px, 24px

**2. Standardize into tokens:**
```css
/* Colors: Reduce to semantic scale */
--color-primary: #0066cc;
--color-primary-dark: #0044aa;
--color-primary-light: #3388dd;

/* Spacing: Standard scale */
--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 16px;
--spacing-lg: 24px;
--spacing-xl: 32px;

/* Typography: Modular scale */
--font-size-sm: 14px;
--font-size-base: 16px;
--font-size-lg: 20px;
--font-size-xl: 24px;
```

**3. Refactor components to use tokens:**
- Replace hard-coded values
- Document token usage
- Verify consistency

### Pattern 3: Cross-Platform Design System

**Scenario:** Building for web (React), mobile (React Native), and desktop (Electron).

**Approach:**

**1. Define platform-agnostic hierarchy:**
```
Atoms: Button, Input, Text, Icon
Molecules: SearchBar, Card, MenuItem
Organisms: Navigation, DataTable, Form
Templates: Dashboard, ListPage, DetailPage
```

**2. Implement per platform:**
```
web/atoms/Button.tsx       - Web implementation
mobile/atoms/Button.tsx    - React Native implementation
desktop/atoms/Button.tsx   - Electron implementation
```

**3. Shared design tokens:**
```javascript
// to