Files

T

Thanh Quy - wolf eca619b79a feat: Implement Atomic Design Phase 1 - Atoms Foundation

✨ Created complete atoms library (21 components):
- Buttons: Button, IconButton with variants (primary, secondary, danger, ghost)
- Inputs: TextInput, SearchInput, Textarea with validation support
- Typography: Heading (h1-h6), Text (variants), Caption
- Badges: Badge (5 variants), PriceBadge (formatted pricing)
- Dividers: Horizontal/vertical separators

🎯 Updated existing components to use atoms:
- CartProduct: Now uses Button, Text, Caption atoms
- ReviewModal: Now uses Button, Textarea, Heading, Text atoms

📚 Added comprehensive documentation:
- components/atoms/ATOMS.md: Complete atoms reference guide
- Usage examples, theming, import patterns, accessibility

🏗️ Architecture improvements:
- Foundation for molecules/organisms
- Type-safe components with full TypeScript support
- Consistent theming via CSS variables
- Barrel exports for clean imports

✅ Verified:
- npm run build: Success (✓ Compiled successfully)
- npm run format: All files formatted
- npm run lint: No new errors in atoms

Next: Phase 2 - Create molecules (ProductCard, FormField, SearchBar, etc.)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-03 19:40:07 +07:00

30 KiB

Raw Blame History

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

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
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
Code Documentation (⭐⭐⭐⭐)
- Comprehensive COMPONENTS.md with detailed prop tables
- App routing documented in app/APP.md
- Constants well-organized in lib/constants.ts
App Router Structure (⭐⭐⭐⭐)
- Route groups: (main), (feed), (manager) - excellent organization
- Proper layout nesting in Next.js 16

❌ What Needs Improvement

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)

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

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)

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.

✅ Button & IconButton
✅ TextInput & SearchInput
✅ Typography (Heading, Text, Caption)
✅ Badge & PriceBadge
✅ Divider
✅ 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.

✅ FormField (Label + Input + Error)
✅ ProductCard (rename CartProduct)
✅ RatingInput & RatingStars
✅ PriceTag
✅ SearchInput (molecule version combining atom + icon)
✅ Breadcrumb (for future navigation)
✅ 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.

✅ Move Navbar → organisms/navigation/
✅ Extract CategoryMenu → organisms/navigation/
✅ Move CartFab → organisms/cart/
✅ Extract ProductGrid → organisms/product-grid/
✅ Move ReviewModal → organisms/modals/
✅ Extract ReviewForm logic
✅ Move form pages → organisms/forms/

Output: 6 organism groups in components/organisms/

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

Create reusable layout templates.

✅ MainLayout
✅ FeedLayout
✅ AuthLayout
✅ CheckoutLayout
✅ ManagerLayout

Output: 5 template groups in components/templates/

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

Update pages to use new component hierarchy.

✅ app/(main)/page.tsx - Use ProductGrid, CategoryMenu, SearchInput molecules
✅ app/(main)/layout.tsx - Use MainLayout template
✅ app/(feed)/feed/page.tsx - Use ShopGrid organism
✅ app/(main)/login/page.tsx - Use AuthLayout template
✅ 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

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:

Update components/COMPONENTS.md
- Add sections for atoms, molecules, organisms, templates
- Add migration examples
- Link to each component's purpose
Create components/ATOMIC_DESIGN.md
- Summary of atomic structure
- When to use each level
- Import examples
- Common patterns
Update main README.md
- Reference atomic design approach
- Point to component docs
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:

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
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
Reusability
- Button component used 15+ places
- FormField used in all forms
- SearchInput reused in multiple pages
- RatingInput in multiple contexts
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
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
Performance
- No new bundle size increase
- Code-splitting works with dynamic imports
- No circular dependencies

Next Steps

If implementing immediately:

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

Total estimated time: 5-7 days for full implementation

If implementing gradually:

Add atoms whenever creating new components
Reorganize one page at a time
Extract one organism per feature
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

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

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

30 KiB Raw Blame History

Coffee Shop Frontend - Atomic Design Optimization Plan

Executive Summary

Current State Analysis

✅ What's Working Well

❌ What Needs Improvement

Atomic Design Mapping

Phase 1: Atoms (New - Create These First)

1.1 Button Atoms

1.2 Input Atoms

1.3 Typography Atoms

1.4 Badge Atoms

1.5 Icon Atoms

1.6 Divider Atoms

1.7 Loader Atoms

Phase 2: Molecules (Create After Atoms)

2.1 Form Components

2.2 Product Card

2.3 Rating Component

2.4 Price Display

2.5 Search Bar

2.6 Breadcrumb

2.7 Tabs

Phase 3: Organisms (Create After Molecules)

3.1 Navigation

3.2 Cart

3.3 Product Grid

3.4 Forms

3.5 Modals

3.6 Shop Grid

3.7 Featured Section

3.8 Hero Section

Phase 4: Templates (Create After Organisms)

4.1 Main Layout

4.2 Feed Layout

4.3 Manager Layout

4.4 Auth Layout

4.5 Checkout Layout

Phase 5: Pages (Update Existing)

Implementation Priority

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

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

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

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

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

Code Quality Improvements

🎯 Specific Recommendations

1. Extract Button Component

2. Extract Search Component

3. Extract Category Menu

4. Extract Product Grid

5. Rating Component Extraction

6. Form Field Molecule

📊 Component Reduction Targets

Testing Strategy per Atomic Level

Atoms

Molecules

Organisms

Pages

Documentation Updates Required

File Structure After Implementation

Quick Wins (Implement First)

1. Create Button Atom

2. Create TextInput Atom

3. Create Typography Atoms

4. Move Existing Components

5. Rename CartProduct → ProductCard

Migration Checklist

Phase 1: Atoms

Phase 2: Molecules

Phase 3: Organisms

Phase 4: Templates

Phase 5: Pages & Testing

Success Criteria

Next Steps

If implementing immediately:

If implementing gradually:

References

Questions / Clarifications Needed

30 KiB

Raw Blame History