## 1. Atomic Design Methodology

Components are organized in three levels of complexity, inspired by atomic design principles:

#### ⚛️ Atoms

Basic building blocks

- Button
- Input
- Icon
- Label
- Avatar

#### 🔗 Molecules

Combinations of atoms

- Search Bar (Input + Button)
- Form Field (Label + Input)
- Card (Image + Text + Button)
- Menu Item (Icon + Label)

#### 🏗️ Organisms

Complex components

- Navigation Bar
- Hero Section
- Product Grid
- Footer

#### Example: Building a Card Component

Atoms used: Image, Heading, Paragraph, Button, Icon

Classification: Molecule (combines multiple atoms)

Can be used in: Organism (e.g., Product Grid contains multiple Cards)

## 2. Component Anatomy

Every component is broken down into its structural parts.

### Button Anatomy Example

Container
Icon (optional)
Label

#### Anatomy Documentation Format:

    ## Anatomy

    **Parts:**
    1. **Container** - The button's outer wrapper
    2. **Icon** (optional) - Leading or trailing icon
    3. **Label** - The button text
    4. **Loading Indicator** (optional) - Replaces icon during loading state

## 3. Slots (Content Placeholders)

Key Principle: Structure is shared, content is page-specific.

Slots define where content goes, not what the content is.

### Card Component Slots Example

#### [title slot]

[description slot]

Structure (shared)

#### Premium Plan

Unlock all features

Content (page-specific)

#### Slots Documentation Format:

    ## Slots

    1. **image** - Visual content (photo, illustration, icon)
    2. **title** - Main heading
    3. **description** - Supporting text
    4. **action** - Call-to-action button

## 4. Props (Configuration Options)

Props control how a component looks and behaves.

### Button Props Example

Prop | Type | Options | Default
--- | --- | --- | ---
`variant` | string | primary | secondary | ghost | primary
`size` | string | small | medium | large | medium
`disabled` | boolean | true | false | false
`fullWidth` | boolean | true | false | false

#### Props Documentation Format:

    ## Props

    | Prop | Type | Options | Default | Description |
    |------|------|---------|---------|-------------|
    | variant | string | primary, secondary, ghost | primary | Visual style |
    | size | string | small, medium, large | medium | Button size |
    | disabled | boolean | true, false | false | Disable interactions |
    | fullWidth | boolean | true, false | false | Stretch to container width |

## 5. States (Interactive Behavior)

States define how components respond to user interaction.

### Button States Example

Default - Idle state

Hover - Mouse over

Disabled - Not interactive

Loading - Processing

#### Common States:

- `default` - Idle/resting state
- `hover` - Mouse/pointer over component
- `active` - Currently pressed/clicked
- `focus` - Keyboard focus (accessibility)
- `disabled` - Not interactive
- `loading` - Awaiting response
- `error` - Invalid/failed state
- `success` - Completed successfully

## 6. Variants (Visual Styles)

Variants are different visual styles of the same component structure.

### Button Variants Example

Primary - Main actions

Secondary - Less emphasis

Ghost - Minimal style

#### When to Create Variants

Same structure, different appearance

- ✅ Primary vs Secondary button (same anatomy, different colors)
- ✅ Card with shadow vs Card without shadow
- ✅ Input with border vs Input with underline only

Different structure = Different component

- ❌ Button with icon vs Button without icon → Use props/slots
- ❌ Horizontal nav vs Vertical nav → Separate components

## 7. Specifications (Technical Measurements)

Precise measurements for implementation.

### Button Specifications Example

Property | Small | Medium | Large
--- | --- | --- | ---
Height | 32px | 40px | 48px
Padding (horizontal) | 12px | 16px | 24px
Font Size | 14px | 16px | 18px
Border Radius | 4px | 6px | 8px
Icon Size | 16px | 20px | 24px

#### Specification Categories:

- Dimensions - Width, height, min/max sizes
- Spacing - Padding, margin, gap between elements
- Typography - Font size, weight, line height
- Colors - Background, text, border colors (reference to color system)
- Effects - Border radius, shadows, transitions

## 8. Pattern Recognition (Freya's Workflow)

Rule: Document a component in the design system on its SECOND occurrence.

### Incremental Building Process

Page 1.1: Uses Button (first occurrence)

→ Freya notes it, continues without creating design system entry

Page 1.2: Uses Button again (second occurrence)

→ Freya: "I've used 'Button' twice now. Should I document this in the design system?"

→ User: "Yes"

→ Freya creates E-Design-System/atoms/button/ with full documentation

Page 1.3: Uses Button + Card

→ Button: Already documented, reference existing spec

→ Card: Second occurrence → Ask to document

Page 2.1: Uses Button (primary variant) + new Ghost variant

→ Freya: "New variant detected! I'll add 'Ghost' to the Button variants."

→ Updates E-Design-System/atoms/button/05-variants.md

### Why Second Occurrence?

#### Prevents Premature Abstraction

❌ Problem with "first occurrence": You document something that never gets reused.

✅ Solution with "second occurrence": You only document actual patterns.

#### Natural Pattern Emergence

Components earn their place in the design system by being actually reused, not by being potentially reusable.

### Freya's Tracking System

    Component Usage Tracking:

    Button:
      - Page 1.1 (first occurrence)
      - Page 1.2 (second occurrence) ← TRIGGER: Create design system entry
      - Page 1.3 (third occurrence) ← Reference existing

    Card:
      - Page 1.2 (first occurrence)
      - Page 1.3 (second occurrence) ← TRIGGER: Create design system entry

    Input:
      - Page 2.1 (first occurrence)
      [No second occurrence yet, no design system entry]