gh-xtone-ai-development-tools-frontend-nextjs-development/skills/figma-design-analyzer/references/atomic-design-classification.md

# Atomic Design Classification Guide

This guide provides criteria for classifying React components according to Atomic Design principles when extracting from Figma designs.

## Atomic Design Overview

Atomic Design is a methodology for creating design systems with five distinct levels:

1. **Atoms** - Basic building blocks
2. **Molecules** - Simple combinations of atoms
3. **Organisms** - Complex combinations of molecules and atoms
4. **Templates** - Page-level layouts (wireframes)
5. **Pages** - Specific instances of templates with real content

For component libraries, focus primarily on Atoms, Molecules, and Organisms.

## Classification Criteria

### Atoms

**Definition:** The smallest, indivisible UI components that cannot be broken down further without losing meaning.

**Characteristics:**
- Single responsibility
- No internal state (usually)
- Highly reusable
- Self-contained
- Cannot be broken down further

**Examples:**
- Button
- Input field
- Label
- Icon
- Image
- Heading (h1, h2, etc.)
- Paragraph
- Link
- Checkbox
- Radio button
- Badge
- Avatar
- Spinner/Loader

**Figma Indicators:**
- Figma components with no nested components
- Simple, single-purpose elements
- Elements that appear repeatedly across designs
- Base design tokens (colors, typography, spacing)

**React Example:**
```tsx
// Button Atom
export const Button = ({ children, onClick, variant = 'primary' }: Props) => (
  <button
    onClick={onClick}
    className={`px-4 py-2 rounded ${variant === 'primary' ? 'bg-blue-500 text-white' : 'bg-gray-200'}`}
  >
    {children}
  </button>
);
```

### Molecules

**Definition:** Simple combinations of atoms that work together as a unit.

**Characteristics:**
- Composed of 2-5 atoms
- Has a single, clear purpose
- Still relatively simple
- Reusable across contexts
- May have simple internal logic

**Examples:**
- Search bar (Input + Button)
- Form field (Label + Input + Error message)
- Card header (Heading + Badge)
- Social share buttons (Multiple icon buttons)
- Breadcrumb navigation (Multiple links + separators)
- Input with icon
- Select dropdown with label
- Toast notification (Icon + Text + Close button)

**Figma Indicators:**
- Figma components containing 2-5 child components
- Grouped elements that always appear together
- Repeated patterns across different pages

**React Example:**
```tsx
// SearchBar Molecule
export const SearchBar = ({ onSearch, placeholder }: Props) => (
  <div className="flex gap-2">
    <Input placeholder={placeholder} onChange={handleChange} />
    <Button onClick={onSearch}>Search</Button>
  </div>
);
```

### Organisms

**Definition:** Complex UI components composed of molecules and atoms, forming distinct sections of an interface.

**Characteristics:**
- Composed of multiple molecules and/or atoms
- Complex structure
- May have significant internal logic and state
- Represents a distinct section of the UI
- Often context-specific

**Examples:**
- Header (Logo + Navigation + Search bar + User menu)
- Footer (Multiple link groups + Social icons + Copyright)
- Product card (Image + Title + Description + Price + Button)
- Comment section (Avatar + Name + Timestamp + Text + Action buttons)
- Navigation menu (Multiple links + dropdown menus)
- Form (Multiple form fields + Submit button)
- Modal dialog (Header + Content + Footer with buttons)
- Table with pagination (Table + Pagination controls)
- Sidebar (Logo + Navigation links + User profile)

**Figma Indicators:**
- Figma components with multiple nested components
- Large, complex frames
- Represents a complete UI section
- Contains both structure and content

**React Example:**
```tsx
// ProductCard Organism
export const ProductCard = ({ product }: Props) => (
  <div className="flex flex-col gap-4 p-6 border rounded">
    <Image src={product.image} alt={product.name} />
    <Heading level={3}>{product.name}</Heading>
    <Paragraph>{product.description}</Paragraph>
    <div className="flex items-center justify-between">
      <Badge>{product.price}</Badge>
      <Button onClick={() => addToCart(product)}>Add to Cart</Button>
    </div>
  </div>
);
```

### Templates (Optional)

**Definition:** Page-level layouts that define content structure without actual content.

**Characteristics:**
- Arranges organisms into page layouts
- Uses placeholder content
- Defines grid and spacing
- Reusable across multiple pages

**Examples:**
- Blog post layout template
- Dashboard layout template
- Product page layout template

**Figma Indicators:**
- Full-page frames
- Uses placeholder content (Lorem ipsum, sample images)
- Defines overall page structure

**React Example:**
```tsx
// BlogPostTemplate
export const BlogPostTemplate = ({ header, content, sidebar }: Props) => (
  <div className="grid grid-cols-12 gap-6">
    <header className="col-span-12">{header}</header>
    <main className="col-span-8">{content}</main>
    <aside className="col-span-4">{sidebar}</aside>
  </div>
);
```

### Pages (Optional)

**Definition:** Specific instances of templates with real content.

**Characteristics:**
- Uses actual content
- Represents a specific page in the application
- May include page-specific logic (data fetching, etc.)

**Note:** Pages are typically not part of a component library. They are application-specific implementations.

## Classification Decision Tree

When analyzing a Figma component, ask these questions:

### Is it an Atom?

1. ✅ Can it be broken down further?
   - **NO** → It's an Atom
   - **YES** → Continue

2. ✅ Does it have a single, indivisible purpose?
   - **YES** → It's an Atom
   - **NO** → Continue

### Is it a Molecule?

3. ✅ Is it composed of 2-5 atoms?
   - **YES** → Likely a Molecule
   - **NO** → Continue

4. ✅ Does it serve a single, simple purpose?
   - **YES** → It's a Molecule
   - **NO** → Continue

### Is it an Organism?

5. ✅ Is it composed of multiple molecules and/or atoms?
   - **YES** → It's an Organism

6. ✅ Does it represent a distinct section of the interface?
   - **YES** → It's an Organism

### Special Cases

**Ambiguous cases:**
- If a component could be either an Atom or Molecule, prefer **Atom** if it's highly reusable
- If a component could be either a Molecule or Organism, prefer **Molecule** if it's simple

**Context matters:**
- Classification can vary based on project scope
- What's an Organism in one project might be a Molecule in another (with larger scale)

## Naming Conventions

Follow consistent naming patterns for each category:

### Atoms
```
Button
Input
Label
Icon
Badge
Avatar
Heading
Paragraph
```

### Molecules
```
SearchBar
FormField
InputWithIcon
SocialShareButtons
Breadcrumb
```

### Organisms
```
Header
Footer
ProductCard
CommentSection
NavigationMenu
Sidebar
```

## Directory Structure

Organize components by Atomic Design category:

```
src/
  components/
    atoms/
      Button/
        Button.tsx
        Button.test.tsx
        Button.stories.tsx
    molecules/
      SearchBar/
        SearchBar.tsx
        SearchBar.test.tsx
        SearchBar.stories.tsx
    organisms/
      Header/
        Header.tsx
        Header.test.tsx
        Header.stories.tsx
```

## Analysis Workflow

When extracting components from Figma:

1. **Identify component boundaries**
   - Look for logical groupings
   - Check Figma component instances
   - Identify repeated patterns

2. **Count the atoms**
   - How many basic elements does it contain?
   - 1 atom → Atom
   - 2-5 atoms → Molecule candidate
   - 6+ atoms → Organism candidate

3. **Assess complexity**
   - Simple structure → Atom or Molecule
   - Complex structure → Organism

4. **Check purpose**
   - Single, simple purpose → Atom or Molecule
   - Multiple purposes or section of UI → Organism

5. **Verify reusability**
   - Highly reusable across contexts → Atom or Molecule
   - Context-specific → Organism

6. **Make classification decision**
   - Use the decision tree above
   - Document reasoning if ambiguous

## Common Patterns and Classifications

### Forms

- **Atoms**: Input, Label, Checkbox, Radio, Button
- **Molecules**: FormField (Label + Input + Error)
- **Organisms**: LoginForm (Multiple FormFields + Button)

### Navigation

- **Atoms**: Link, Icon
- **Molecules**: NavItem (Link + Icon)
- **Organisms**: NavigationMenu (Multiple NavItems + Dropdown)

### Cards

- **Atoms**: Image, Heading, Paragraph, Button, Badge
- **Molecules**: CardHeader (Image + Badge), CardFooter (Button)
- **Organisms**: ProductCard (CardHeader + Content + CardFooter)

### Lists

- **Atoms**: ListItem (single item)
- **Molecules**: ListItemWithIcon (Icon + ListItem)
- **Organisms**: UserList (Multiple ListItemWithIcon + Header + Pagination)

## Edge Cases and Guidelines

### When a component feels too simple for Molecule

If a "Molecule" only combines 2 atoms without adding meaningful functionality:
- Consider if it should be an Atom
- Or, accept it as a simple Molecule for consistency

**Example:**
```tsx
// This might feel too simple for a Molecule, but it's valid
const IconButton = ({ icon, onClick }: Props) => (
  <Button onClick={onClick}>
    <Icon name={icon} />
  </Button>
);
```

### When a component feels too complex for Organism

If an "Organism" is extremely complex with many nested components:
- Consider breaking it down into smaller Organisms
- Or, accept it as a complex Organism if it represents a single, cohesive UI section

### Reusing components across categories

It's normal for:
- Organisms to use Molecules
- Molecules to use Atoms
- Organisms to use Atoms directly (skip Molecules if simpler)

**Don't force categorization** - the goal is organization and reusability, not rigid adherence.

## Benefits of Proper Classification

1. **Better organization**: Easy to find components
2. **Improved reusability**: Atoms and Molecules are highly reusable
3. **Easier testing**: Smaller components are easier to test
4. **Consistent design**: Enforces design system patterns
5. **Team communication**: Shared vocabulary for discussing components
6. **Scalability**: Easier to maintain as the system grows

## Tips

- **Start small**: Begin with Atoms, then build up to Molecules and Organisms
- **Be consistent**: Once you classify a pattern, stick with it
- **Document decisions**: If classification is ambiguous, document why you chose a category
- **Iterate**: It's okay to reclassify components as you learn more about the system
- **Prioritize reusability**: When in doubt, prefer smaller, more reusable components
- **Don't over-engineer**: Not every UI element needs to be a separate Atom
- **Use Figma components as hints**: Figma component structure often maps to Atomic Design