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:

<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:

<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:

<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:

<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

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

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

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

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
• 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