frontend/OPTIMIZATION_PLAN.md

# Coffee Shop Frontend - Atomic Design Optimization Plan

**Date:** 2026-04-03 **Current Branch:** `atomic_design` **Status:** Analysis &
Planning Phase

---

## Executive Summary

Your project has a solid foundation with well-organized contexts, utilities, and
components. However, the component structure doesn't follow the Atomic Design
pattern defined in `Atomic.md`. This document outlines how to restructure your
codebase to:

✅ **Improve maintainability** - Clear separation of concerns ✅ **Increase
reusability** - Components organized by complexity level ✅ **Enable
scalability** - Easy to add features following established patterns ✅ **Better
testing** - Each level has specific responsibilities

---

## Current State Analysis

### ✅ What's Working Well

1. **Context API Setup** (⭐⭐⭐⭐⭐)
   - `auth-context.tsx` - Clean user authentication
   - `cart-context.tsx` - Good shopping cart management
   - `menu-context.tsx` - Simple category state
   - `manager-context.tsx` - Manager dashboard state
   - Proper TypeScript interfaces in `lib/types.ts`

2. **Responsive Design** (⭐⭐⭐⭐)
   - Mobile-first approach with Tailwind breakpoints
   - CSS variables for theming (`--color-primary`, etc.)
   - Good use of Next.js Image component
   - Accessible ARIA attributes in modals and interactive components

3. **Code Documentation** (⭐⭐⭐⭐)
   - Comprehensive `COMPONENTS.md` with detailed prop tables
   - App routing documented in `app/APP.md`
   - Constants well-organized in `lib/constants.ts`

4. **App Router Structure** (⭐⭐⭐⭐)
   - Route groups: `(main)`, `(feed)`, `(manager)` - excellent organization
   - Proper layout nesting in Next.js 16

### ❌ What Needs Improvement

1. **Components Not Following Atomic Design** (🔴 HIGH PRIORITY)
   - **Current:** All components in `components/` root directory
   - **Problem:** No clear hierarchy between simple UI blocks and complex
     sections
   - **Current state:**
     ```
     components/
     ├── CartProduct.tsx      ← Should be: molecules/cards/ProductCard.tsx
     ├── CartFab.tsx          ← Should be: organisms/cart/CartFab.tsx
     ├── Navbar.tsx           ← Should be: organisms/navigation/Navbar.tsx
     ├── ReviewModal.tsx      ← Should be: organisms/modals/ReviewModal.tsx
     ├── COMPONENTS.md
     └── (no atoms/molecules/organisms directories)
     ```

2. **Missing Atom Components** (🔴 CRITICAL)
   - No `Button`, `TextInput`, `Text`, `Heading` atoms
   - Buttons are hardcoded inline with `<button className="...">`
   - No shared icon components
   - No badge/badge components
   - No typography system

3. **Missing Molecule Components** (🟠 MEDIUM)
   - No `ProductCard` molecule (using CartProduct directly)
   - No form fields with labels + inputs + error messages
   - No rating stars component (logic embedded in ReviewModal)
   - No search bar component (inline in page)
   - No price badge/display component

4. **Page Logic Bloat** (🟠 MEDIUM)
   - `app/(main)/page.tsx` is 192 lines with:
     - Search input UI (should be SearchInput molecule)
     - Mobile category menu (should be CategoryMenu molecule)
     - Product grid logic (should be ProductGrid organism)
     - Direct product rendering (should compose smaller components)

5. **Missing Template Layer** (🟠 MEDIUM)
   - No template components for layout structure
   - Main layout logic in `app/(main)/layout.tsx` is minimal but could benefit
     from MainLayout template
   - Missing FeedLayout, ManagerLayout, AuthLayout templates

6. **Type Definitions Scattered** (🟡 LOW)
   - Component props defined inline in each file
   - No centralized `.types.ts` files per component
   - Harder to reuse interfaces

---

## Atomic Design Mapping

### Phase 1: Atoms (New - Create These First)

#### 1.1 Button Atoms

```
components/atoms/buttons/
├── Button.tsx
├── IconButton.tsx
├── Button.types.ts
└── index.ts
```

**Why:** Currently all buttons are inline `<button>` tags with duplicate
styling.

**Current Usage Patterns:**

- Primary button:
  `bg-(--color-primary) text-white hover:bg-(--color-primary-dark)`
- Secondary button:
  `border border-(--color-border) hover:bg-(--color-border-light)`
- Danger/destructive: `bg-red-500 text-white hover:bg-red-600`

**Files to Reference:**

- `components/CartProduct.tsx:73-79` - "Mua" button styling
- `components/ReviewModal.tsx:147-154, 155-163` - Modal buttons
- `components/Navbar.tsx:55-65, 75-95` - Sidebar toggle/category buttons
- `app/(main)/page.tsx:118-126` - Clear button
- Multiple inline `<button>` elements throughout

---

#### 1.2 Input Atoms

```
components/atoms/inputs/
├── TextInput.tsx
├── SearchInput.tsx
├── Textarea.tsx
├── Input.types.ts
└── index.ts
```

**Current Usage Patterns:**

- Text input: `app/(main)/page.tsx:109-127` (search with icon + clear button)
- Textarea: `components/ReviewModal.tsx:135-142` (review comment box)

---

#### 1.3 Typography Atoms

```
components/atoms/typography/
├── Heading.tsx       (h1-h6)
├── Text.tsx          (p, span - variants: body1, body2, caption)
├── Caption.tsx       (small text)
├── Typography.types.ts
└── index.ts
```

**Current Usage Patterns:**

- Headings: `<h2 class="text-xl font-bold">` (app/(main)/page.tsx:98)
- Body text: `<p class="text-sm text-(--color-text-muted)">` (various files)
- Small text: `<span class="text-xs">` (CartProduct.tsx:60-65)

---

#### 1.4 Badge Atoms

```
components/atoms/badges/
├── Badge.tsx
├── PriceBadge.tsx
├── Badge.types.ts
└── index.ts
```

**Current Usage Patterns:**

- Price: `<span class="text-sm font-bold text-(--color-primary)">`
  (CartProduct.tsx:70-71)
- Cart count badge: `<span class="absolute -top-1.5 -right-1.5 ...">`
  (CartFab.tsx:18-20)

---

#### 1.5 Icon Atoms

```
components/atoms/icons/
├── CartIcon.tsx
├── SearchIcon.tsx
├── StarIcon.tsx
├── MenuIcon.tsx
├── Icon.types.ts
└── index.ts
```

**Current State:** Using FontAwesome directly
(`<i className="fa-solid fa-...">`)

---

#### 1.6 Divider Atoms

```
components/atoms/dividers/
├── Divider.tsx
└── Divider.types.ts
```

**Current Usage:** `border-t border-(--color-border-light)` (CartProduct.tsx:69)

---

#### 1.7 Loader Atoms

```
components/atoms/loaders/
├── Spinner.tsx
├── Skeleton.tsx
└── Loader.types.ts
```

**Usage:** Not yet implemented; needed for image loading, dynamic imports

---

### Phase 2: Molecules (Create After Atoms)

#### 2.1 Form Components

```
components/molecules/form-groups/
├── FormField.tsx     (Label + Input + Error)
├── FormGroup.types.ts
└── index.ts
```

**Current State:** Form fields built inline in pages/organisms.

---

#### 2.2 Product Card

```
components/molecules/cards/
├── ProductCard.tsx   (Rename from CartProduct.tsx)
├── ReviewCard.tsx
├── Card.types.ts
└── index.ts
```

**Migration:** CartProduct → ProductCard **Status:** Just needs relocation and
prop interface extraction

---

#### 2.3 Rating Component

```
components/molecules/ratings/
├── RatingStars.tsx        (Display only)
├── RatingInput.tsx        (Interactive 5-star)
├── RatingLabel.tsx        (Label mapping: "Rất tệ", "Tốt", etc.)
├── Rating.types.ts
└── index.ts
```

**Current State:** Star logic embedded in ReviewModal.tsx:92-124

---

#### 2.4 Price Display

```
components/molecules/price-display/
├── PriceTag.tsx       (Formatted price display)
├── PriceRange.tsx
├── Price.types.ts
└── index.ts
```

**Current State:** Price logic in CartProduct.tsx:32-35

---

#### 2.5 Search Bar

```
components/molecules/search-bar/
├── SearchInput.tsx
├── SearchBar.tsx
├── Search.types.ts
└── index.ts
```

**Current State:** Search logic in app/(main)/page.tsx:106-127

---

#### 2.6 Breadcrumb

```
components/molecules/breadcrumb/
├── Breadcrumb.tsx
└── Breadcrumb.types.ts
```

**Usage:** Not yet implemented; useful for manager routes

---

#### 2.7 Tabs

```
components/molecules/tabs/
├── TabGroup.tsx
├── Tab.tsx
├── Tabs.types.ts
└── index.ts
```

**Usage:** Not yet implemented; useful for manager dashboard sections

---

### Phase 3: Organisms (Create After Molecules)

#### 3.1 Navigation

```
components/organisms/navigation/
├── Navbar.tsx          (Existing - just move)
├── CategoryMenu.tsx    (Extract from app/(main)/page.tsx:131-153)
├── Navigation.types.ts
└── index.ts
```

**Current State:**

- Navbar: `components/Navbar.tsx` (needs moving)
- CategoryMenu: Inline in `app/(main)/page.tsx:131-153`

---

#### 3.2 Cart

```
components/organisms/cart/
├── CartFab.tsx         (Existing - just move)
├── CartSummary.tsx
├── CartList.tsx
├── Cart.types.ts
└── index.ts
```

**Current State:** CartFab exists but should be moved

---

#### 3.3 Product Grid

```
components/organisms/product-grid/
├── ProductGrid.tsx      (Extract from app/(main)/page.tsx:156-188)
├── ProductFilters.tsx   (Extract category/search filtering)
├── ProductGrid.types.ts
└── index.ts
```

**Current State:** Inline product grid in `app/(main)/page.tsx`

---

#### 3.4 Forms

```
components/organisms/forms/
├── LoginForm.tsx       (Exists in app/(main)/login/page.tsx)
├── RegisterForm.tsx    (Exists in app/(main)/register/page.tsx)
├── CheckoutForm.tsx    (Exists in app/(main)/payment/page.tsx)
├── ReviewForm.tsx      (Extract from ReviewModal.tsx:70-165)
├── Forms.types.ts
└── index.ts
```

---

#### 3.5 Modals

```
components/organisms/modals/
├── ReviewModal.tsx     (Existing - just move)
├── ConfirmModal.tsx    (Generic modal for confirmations)
├── Modal.types.ts
└── index.ts
```

---

#### 3.6 Shop Grid

```
components/organisms/shop-grid/
├── ShopGrid.tsx        (app/(feed)/feed/page.tsx)
├── ShopFilters.tsx
├── ShopGrid.types.ts
└── index.ts
```

---

#### 3.7 Featured Section

```
components/organisms/featured-section/
├── FeaturedProducts.tsx (Optional homepage section)
├── FeaturedShops.tsx
├── Featured.types.ts
└── index.ts
```

---

#### 3.8 Hero Section

```
components/organisms/hero-section/
├── HeroSection.tsx     (Optional homepage banner)
└── Hero.types.ts
```

---

### Phase 4: Templates (Create After Organisms)

#### 4.1 Main Layout

```
components/templates/main-layout/
├── MainLayout.tsx           (Extract from app/(main)/layout.tsx)
├── MainLayout.types.ts
└── index.ts
```

**Current State:** Minimal layout in `app/(main)/layout.tsx:5-25`

---

#### 4.2 Feed Layout

```
components/templates/feed-layout/
├── FeedLayout.tsx
└── FeedLayout.types.ts
```

---

#### 4.3 Manager Layout

```
components/templates/manager-layout/
├── ManagerLayout.tsx
└── ManagerLayout.types.ts
```

---

#### 4.4 Auth Layout

```
components/templates/auth-layout/
├── AuthLayout.tsx
└── AuthLayout.types.ts
```

---

#### 4.5 Checkout Layout

```
components/templates/checkout-layout/
├── CheckoutLayout.tsx
└── CheckoutLayout.types.ts
```

---

### Phase 5: Pages (Update Existing)

**Status:** Already following good patterns; will just be updated to use new
components

- `app/(main)/page.tsx` - Main product grid page
- `app/(feed)/feed/page.tsx` - Shop discovery page
- `app/(main)/login/page.tsx` - Authentication
- `app/(main)/payment/page.tsx` - Checkout
- `app/(manager)/manager/page.tsx` - Manager dashboard

---

## Implementation Priority

### 🔴 **Phase 1: Atoms** (Critical Foundation - ~2-3 days)

These must be created first as molecules depend on them.

1. ✅ Button & IconButton
2. ✅ TextInput & SearchInput
3. ✅ Typography (Heading, Text, Caption)
4. ✅ Badge & PriceBadge
5. ✅ Divider
6. ✅ Icon components (CartIcon, SearchIcon, StarIcon)

**Output:** 7 new component groups in `components/atoms/`

---

### 🟠 **Phase 2: Molecules** (High Value - ~2-3 days)

These increase code reusability and component sharing.

1. ✅ FormField (Label + Input + Error)
2. ✅ ProductCard (rename CartProduct)
3. ✅ RatingInput & RatingStars
4. ✅ PriceTag
5. ✅ SearchInput (molecule version combining atom + icon)
6. ✅ Breadcrumb (for future navigation)
7. ✅ Tabs (for future sections)

**Output:** 7 new molecule groups in `components/molecules/`

---

### 🟡 **Phase 3: Organisms** (Code Extraction - ~2-3 days)

Extract existing component/page logic into organisms.

1. ✅ Move Navbar → organisms/navigation/
2. ✅ Extract CategoryMenu → organisms/navigation/
3. ✅ Move CartFab → organisms/cart/
4. ✅ Extract ProductGrid → organisms/product-grid/
5. ✅ Move ReviewModal → organisms/modals/
6. ✅ Extract ReviewForm logic
7. ✅ Move form pages → organisms/forms/

**Output:** 6 organism groups in `components/organisms/`

---

### 🟡 **Phase 4: Templates** (Layout Structure - ~1-2 days)

Create reusable layout templates.

1. ✅ MainLayout
2. ✅ FeedLayout
3. ✅ AuthLayout
4. ✅ CheckoutLayout
5. ✅ ManagerLayout

**Output:** 5 template groups in `components/templates/`

---

### 🟢 **Phase 5: Update Pages** (Final Integration - ~1 day)

Update pages to use new component hierarchy.

1. ✅ `app/(main)/page.tsx` - Use ProductGrid, CategoryMenu, SearchInput
   molecules
2. ✅ `app/(main)/layout.tsx` - Use MainLayout template
3. ✅ `app/(feed)/feed/page.tsx` - Use ShopGrid organism
4. ✅ `app/(main)/login/page.tsx` - Use AuthLayout template
5. ✅ `app/(main)/payment/page.tsx` - Use CheckoutLayout template

**Output:** All pages use new component hierarchy

---

## Code Quality Improvements

### 🎯 Specific Recommendations

#### 1. Extract Button Component

**Location:** `components/atoms/buttons/Button.tsx`

Current inline button from CartProduct.tsx:

```tsx
<button
  onClick={onBuy}
  className="flex cursor-pointer items-center gap-1.5 rounded-lg border-none bg-(--color-primary) px-3 py-1.5 text-xs font-semibold whitespace-nowrap text-white transition-all duration-150 hover:bg-(--color-primary-dark) active:scale-95"
>
  <i className="fa-solid fa-cart-plus"></i>
  Mua
</button>
```

Should become:

```tsx
<Button variant="primary" size="sm" icon="fa-cart-plus" onClick={onBuy}>
  Mua
</Button>
```

**Benefit:**

- Reuse button styling across all components
- Consistent hover/active states
- Easy theme updates
- Better accessibility (built-in aria-labels)

---

#### 2. Extract Search Component

**Location:** `components/molecules/search-bar/SearchInput.tsx`

Current inline from app/(main)/page.tsx:

```tsx
<div className="relative w-full sm:max-w-xs">
  <i className="fa-solid fa-magnifying-glass ..."></i>
  <input type="text" ... />
  {searchQuery && <button ...><i className="fa-solid fa-xmark"></i></button>}
</div>
```

Should become:

```tsx
<SearchInput
  value={searchQuery}
  onChange={setSearchQuery}
  placeholder="Tìm kiếm món..."
/>
```

**Benefit:**

- Consistent search UX across app
- Icon management centralized
- Clear button behavior standardized

---

#### 3. Extract Category Menu

**Location:** `components/organisms/navigation/CategoryMenu.tsx`

Current inline from app/(main)/page.tsx:lines 131-153

This is UI logic that belongs in a component, not the page.

**Benefit:**

- Reusable in mobile view and elsewhere
- Easier to test category selection logic
- Decouples page from component internals

---

#### 4. Extract Product Grid

**Location:** `components/organisms/product-grid/ProductGrid.tsx`

Current inline from app/(main)/page.tsx:lines 156-188

Move the grid rendering and product mapping logic.

**Benefit:**

- Page becomes 30 lines instead of 192
- Grid responsive logic isolated
- Easy to add virtualization/pagination later

---

#### 5. Rating Component Extraction

**Location:** `components/molecules/ratings/RatingInput.tsx`

Current embedded in ReviewModal.tsx:lines 82-125

Extract star rating logic to molecule.

**Benefit:**

- Reuse rating input in product reviews, manager forms
- Simpler ReviewModal component
- Easier to test rating logic

---

#### 6. Form Field Molecule

**Location:** `components/molecules/form-groups/FormField.tsx`

Create generic FormField combining:

- Label
- Input (text, email, password, etc.)
- Error message
- Validation state (success, error, loading)

Used by:

- LoginForm
- RegisterForm
- CheckoutForm
- ManagerForms

---

### 📊 Component Reduction Targets

**Current state:**

- 5 components in `components/` root
- 1 template-like layout in `app/(main)/layout.tsx`
- Logic scattered across pages

**Target state:**

- 0 components in `components/` root
- 20+ atoms/molecules/organisms organized by type
- 5 template components
- Clean, focused pages (< 100 lines each)

---

## Testing Strategy per Atomic Level

### Atoms

```bash
npm test components/atoms/
# ✓ Button - all variants (primary, secondary, danger)
# ✓ Button - all sizes (sm, md, lg)
# ✓ Button - disabled state
# ✓ Button - with and without icon
# ✓ TextInput - focus/blur states
# ✓ TextInput - disabled/loading states
```

### Molecules

```bash
npm test components/molecules/
# ✓ ProductCard - renders image, name, price, button
# ✓ ProductCard - onAddToCart callback
# ✓ SearchInput - clear button appears/disappears
# ✓ FormField - error message displays
# ✓ RatingInput - click/hover behavior
```

### Organisms

```bash
npm test components/organisms/
# ✓ ProductGrid - filters by category
# ✓ ProductGrid - filters by search query
# ✓ Navbar - toggle expand/collapse
# ✓ CategoryMenu - category selection
# ✓ CartFab - shows/hides based on cart items
```

### Pages

```bash
npm test app/
# ✓ Main page - renders ProductGrid with Navbar
# ✓ Main page - category filter works end-to-end
# ✓ Payment page - ReviewModal appears
# ✓ Manager page - only accessible to managers
```

---

## Documentation Updates Required

After implementation:

1. **Update `components/COMPONENTS.md`**
   - Add sections for atoms, molecules, organisms, templates
   - Add migration examples
   - Link to each component's purpose

2. **Create `components/ATOMIC_DESIGN.md`**
   - Summary of atomic structure
   - When to use each level
   - Import examples
   - Common patterns

3. **Update main `README.md`**
   - Reference atomic design approach
   - Point to component docs

4. **Create component-level `.md` files**
   - `components/atoms/buttons/Button.md`
   - `components/molecules/cards/ProductCard.md`
   - `components/organisms/product-grid/ProductGrid.md`

---

## File Structure After Implementation

```
components/
├── atoms/
│   ├── buttons/
│   │   ├── Button.tsx
│   │   ├── IconButton.tsx
│   │   ├── Button.types.ts
│   │   └── index.ts
│   ├── inputs/
│   │   ├── TextInput.tsx
│   │   ├── SearchInput.tsx
│   │   ├── Textarea.tsx
│   │   ├── Input.types.ts
│   │   └── index.ts
│   ├── typography/
│   │   ├── Heading.tsx
│   │   ├── Text.tsx
│   │   ├── Caption.tsx
│   │   ├── Typography.types.ts
│   │   └── index.ts
│   ├── badges/
│   │   ├── Badge.tsx
│   │   ├── PriceBadge.tsx
│   │   ├── Badge.types.ts
│   │   └── index.ts
│   ├── icons/
│   │   ├── CartIcon.tsx
│   │   ├── SearchIcon.tsx
│   │   ├── StarIcon.tsx
│   │   ├── Icon.types.ts
│   │   └── index.ts
│   ├── dividers/
│   │   ├── Divider.tsx
│   │   ├── Divider.types.ts
│   │   └── index.ts
│   ├── loaders/
│   │   ├── Spinner.tsx
│   │   ├── Skeleton.tsx
│   │   ├── Loader.types.ts
│   │   └── index.ts
│   ├── index.ts
│   └── README.md
├── molecules/
│   ├── cards/
│   │   ├── ProductCard.tsx
│   │   ├── ReviewCard.tsx
│   │   ├── Card.types.ts
│   │   └── index.ts
│   ├── form-groups/
│   │   ├── FormField.tsx
│   │   ├── FormGroup.types.ts
│   │   └── index.ts
│   ├── ratings/
│   │   ├── RatingStars.tsx
│   │   ├── RatingInput.tsx
│   │   ├── RatingLabel.tsx
│   │   ├── Rating.types.ts
│   │   └── index.ts
│   ├── price-display/
│   │   ├── PriceTag.tsx
│   │   ├── PriceRange.tsx
│   │   ├── Price.types.ts
│   │   └── index.ts
│   ├── search-bar/
│   │   ├── SearchBar.tsx
│   │   ├── Search.types.ts
│   │   └── index.ts
│   ├── breadcrumb/
│   │   ├── Breadcrumb.tsx
│   │   ├── Breadcrumb.types.ts
│   │   └── index.ts
│   ├── tabs/
│   │   ├── TabGroup.tsx
│   │   ├── Tab.tsx
│   │   ├── Tabs.types.ts
│   │   └── index.ts
│   ├── index.ts
│   └── README.md
├── organisms/
│   ├── navigation/
│   │   ├── Navbar.tsx
│   │   ├── CategoryMenu.tsx
│   │   ├── Navigation.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── cart/
│   │   ├── CartFab.tsx
│   │   ├── CartSummary.tsx
│   │   ├── CartList.tsx
│   │   ├── Cart.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── product-grid/
│   │   ├── ProductGrid.tsx
│   │   ├── ProductFilters.tsx
│   │   ├── ProductGrid.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── forms/
│   │   ├── LoginForm.tsx
│   │   ├── RegisterForm.tsx
│   │   ├── CheckoutForm.tsx
│   │   ├── ReviewForm.tsx
│   │   ├── Forms.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── modals/
│   │   ├── ReviewModal.tsx
│   │   ├── ConfirmModal.tsx
│   │   ├── Modal.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── shop-grid/
│   │   ├── ShopGrid.tsx
│   │   ├── ShopFilters.tsx
│   │   ├── ShopGrid.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── hero-section/
│   │   ├── HeroSection.tsx
│   │   ├── Hero.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── featured-section/
│   │   ├── FeaturedProducts.tsx
│   │   ├── FeaturedShops.tsx
│   │   ├── Featured.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── index.ts
│   └── README.md
├── templates/
│   ├── main-layout/
│   │   ├── MainLayout.tsx
│   │   ├── MainLayout.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── feed-layout/
│   │   ├── FeedLayout.tsx
│   │   ├── FeedLayout.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── manager-layout/
│   │   ├── ManagerLayout.tsx
│   │   ├── ManagerLayout.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── checkout-layout/
│   │   ├── CheckoutLayout.tsx
│   │   ├── CheckoutLayout.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── auth-layout/
│   │   ├── AuthLayout.tsx
│   │   ├── AuthLayout.types.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── index.ts
│   └── README.md
├── ATOMIC_DESIGN.md
├── COMPONENTS.md (updated)
└── README.md (updated)
```

---

## Quick Wins (Implement First)

These provide immediate value with minimal effort:

### 1. Create Button Atom

- 50 lines of code
- Removes ~100 lines of inline styling
- Unblocks other components
- **Est. 30 minutes**

### 2. Create TextInput Atom

- 40 lines of code
- Removes search input duplication
- **Est. 20 minutes**

### 3. Create Typography Atoms

- Heading, Text, Caption
- 60 lines of code
- Standardizes font sizes/weights
- **Est. 45 minutes**

### 4. Move Existing Components

- Navbar → `organisms/navigation/Navbar.tsx`
- CartFab → `organisms/cart/CartFab.tsx`
- ReviewModal → `organisms/modals/ReviewModal.tsx`
- Just directory restructuring
- Update imports
- **Est. 30 minutes**

### 5. Rename CartProduct → ProductCard

- Move to `molecules/cards/ProductCard.tsx`
- Extract interface to `Card.types.ts`
- **Est. 15 minutes**

**Total: ~2.5 hours → 5 quick wins → solid foundation**

---

## Migration Checklist

### Phase 1: Atoms

- [ ] Create `components/atoms/` directory structure
- [ ] Create Button.tsx, Button.types.ts
- [ ] Create TextInput.tsx, Input.types.ts
- [ ] Create Typography atoms (Heading, Text, Caption)
- [ ] Create Badge, PriceBadge atoms
- [ ] Create icon components (CartIcon, SearchIcon, StarIcon)
- [ ] Create Divider atom
- [ ] Create barrel exports (`atoms/index.ts`)
- [ ] Update `components/COMPONENTS.md`
- [ ] Verify all atoms have TypeScript interfaces
- [ ] Test: No console errors, styling matches

### Phase 2: Molecules

- [ ] Create `components/molecules/` directory structure
- [ ] Move CartProduct → ProductCard
- [ ] Extract interface to Card.types.ts
- [ ] Create FormField molecule
- [ ] Create RatingInput, RatingStars molecules
- [ ] Create PriceTag molecule
- [ ] Create SearchBar molecule
- [ ] Create Breadcrumb, Tabs molecules
- [ ] Create barrel exports
- [ ] Update imports in organisms
- [ ] Test: All molecules render with atom composition

### Phase 3: Organisms

- [ ] Create `components/organisms/` directory structure
- [ ] Move Navbar → organisms/navigation/
- [ ] Extract CategoryMenu → organisms/navigation/
- [ ] Move CartFab → organisms/cart/
- [ ] Extract ProductGrid logic
- [ ] Move ReviewModal → organisms/modals/
- [ ] Extract ReviewForm from ReviewModal
- [ ] Move form pages logic → organisms/forms/
- [ ] Create barrel exports
- [ ] Update page imports
- [ ] Test: All organisms use molecule composition

### Phase 4: Templates

- [ ] Create `components/templates/` directory structure
- [ ] Create MainLayout template
- [ ] Create FeedLayout template
- [ ] Create AuthLayout template
- [ ] Create CheckoutLayout template
- [ ] Create ManagerLayout template
- [ ] Create barrel exports
- [ ] Update page imports
- [ ] Test: All templates wrap pages correctly

### Phase 5: Pages & Testing

- [ ] Update `app/(main)/page.tsx`
- [ ] Update `app/(main)/layout.tsx`
- [ ] Update `app/(feed)/feed/page.tsx`
- [ ] Update `app/(main)/login/page.tsx`
- [ ] Update `app/(main)/payment/page.tsx`
- [ ] Update `app/(manager)/manager/page.tsx`
- [ ] Run `npm run lint`
- [ ] Run `npm run format`
- [ ] Manual testing: responsive, accessibility, functionality
- [ ] Update `COMPONENTS.md` with new structure
- [ ] Commit all changes

---

## Success Criteria

✅ **After implementation, verify:**

1. **Code Organization**
   - [ ] All atoms in `components/atoms/`
   - [ ] All molecules in `components/molecules/`
   - [ ] All organisms in `components/organisms/`
   - [ ] All templates in `components/templates/`
   - [ ] Pages use only templates, organisms, molecules

2. **Code Quality**
   - [ ] No inline `<button className="...">` tags (use Button atom)
   - [ ] No duplicate styling across files
   - [ ] All components have `.types.ts` interface files
   - [ ] All components have barrel exports
   - [ ] No `any` types in TypeScript

3. **Reusability**
   - [ ] Button component used 15+ places
   - [ ] FormField used in all forms
   - [ ] SearchInput reused in multiple pages
   - [ ] RatingInput in multiple contexts

4. **Documentation**
   - [ ] `components/ATOMIC_DESIGN.md` created
   - [ ] `components/atoms/README.md` with usage guide
   - [ ] `components/molecules/README.md` with examples
   - [ ] Each organism has component-specific docs
   - [ ] Main `README.md` references new structure

5. **Testing**
   - [ ] All pages responsive (mobile, tablet, desktop)
   - [ ] No lint errors: `npm run lint`
   - [ ] Code formatted: `npm run format`
   - [ ] All interactive components work correctly
   - [ ] Accessibility: keyboard nav, aria labels

6. **Performance**
   - [ ] No new bundle size increase
   - [ ] Code-splitting works with dynamic imports
   - [ ] No circular dependencies

---

## Next Steps

### If implementing immediately:

1. Start with **Quick Wins** section (1-2 hours)
2. Create atoms foundation (1-2 days)
3. Extract existing components to molecules (1 day)
4. Move/refactor to organisms (1 day)
5. Create templates (0.5 days)
6. Update pages and test (1 day)

**Total estimated time:** 5-7 days for full implementation

### If implementing gradually:

1. Add atoms whenever creating new components
2. Reorganize one page at a time
3. Extract one organism per feature
4. Update docs as you go

---

## References

- **Atomic Design Book:**
  [Brad Frost's Atomic Design](https://atomicdesign.bradfrost.com/)
- **Your project:** `Atomic.md` - comprehensive guide already in repo
- **Current structure:** See "Current State Analysis" section above
- **Implementation examples:** Sections 1-5 in this document

---

## Questions / Clarifications Needed

1. **Scope:** Implement all 5 phases at once or gradually?
2. **Timeline:** Sprint-based or continuous refactoring?
3. **Testing:** Should we add unit tests for new components?
4. **Storybook:** Would you like Storybook setup for component documentation?
5. **Breaking changes:** OK to update imports across entire codebase?

---

**Document Version:** 1.0 **Last Updated:** 2026-04-03 **Status:** Ready for
Review & Implementation Planning