diff --git a/AGENTS.md b/AGENTS.md index 61d3928..56e2499 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,59 +1,193 @@ -# AGENTS GUIDE +# AGENTS GUIDE (Updated with Atomic Design) ## 1) Kiến trúc project -Dự án sử dụng **Next.js App Router** với cấu trúc chính: +Dự án sử dụng **Next.js App Router** với **Atomic Design Pattern** cho UI +components. ### `app/` - Routes & Pages + Chứa route/page/layout theo Next.js App Router. + - **`layout.tsx`** - Root layout toàn app (Header + Providers + Footer wrapper) -- **`providers.tsx`** - Client component gắn 3 providers: AuthProvider, MenuProvider, CartProvider +- **`providers.tsx`** - Client component gắn 3 providers: AuthProvider, + MenuProvider, CartProvider - **`globals.css`** - Global styles + CSS variables + Tailwind imports - **Route groups:** - - **`(main)/`** - Main shopping interface (duyệt menu, đăng nhập, đăng ký, thanh toán) + - **`(main)/`** - Main shopping interface (duyệt menu, đăng nhập, đăng ký, + thanh toán) - **`(feed)/`** - Feed/discovery page (khám phá quán) - - **`(manager)/`** - Manager dashboard (quản lý sản phẩm, đơn hàng) - **[ĐANG PHÁT TRIỂN]** + - **`(manager)/`** - Manager dashboard (quản lý sản phẩm, đơn hàng) - **[ĐANG + PHÁT TRIỂN]** - **Tài liệu:** `app/APP.md` - Chi tiết routes, pages, CSS tokens -### `components/` - Reusable UI Components -Chứa các UI component tái sử dụng: -- **`CartProduct.tsx`** - Product card (image, name, price, buy button) -- **`Navbar.tsx`** - Left sidebar với category filter (collapsible 64px/240px) -- **`CartFab.tsx`** - Floating action button hiển thị số item giỏ + tooltip giá -- **`ReviewModal.tsx`** - Modal đánh giá 5 sao + textarea -- **Tài liệu:** `components/COMPONENTS.md` - Props, behavior, styling của từng component +### `components/` - Reusable UI Components (Atomic Design) + +Chứa UI components được tổ chức theo **Atomic Design Pattern** với 5 cấp độ: + +#### **ATOMS** (`components/atoms/`) + +**Khối xây dựng cơ bản, không chia nhỏ hơn được.** + +Các component cơ bản, tái sử dụng cao, không logic phức tạp: + +- **`buttons/`** - Button, IconButton +- **`inputs/`** - TextInput, NumberInput, Checkbox +- **`badges/`** - Badge, PriceBadge, StatusBadge +- **`icons/`** - StarIcon, CartIcon, SearchIcon, etc. +- **`typography/`** - Heading, Text, Caption +- **`dividers/`** - Divider +- **`loaders/`** - Spinner, Skeleton + +**Đặc điểm:** + +- ✅ Pure props-based, no logic +- ✅ Full TypeScript typing +- ✅ Reusable across entire project +- ✅ No context/hooks +- 📄 Tài liệu: `components/atoms/ATOMS.md` + +#### **MOLECULES** (`components/molecules/`) + +**Nhóm atoms đơn giản hoạt động cùng nhau.** + +Kết hợp multiple atoms, có thể có state đơn giản (open/close): + +- **`form-groups/`** - FormField (input + label + error) +- **`cards/`** - ProductCard, ShopCard, ReviewCard +- **`ratings/`** - RatingStars, RatingInput +- **`price-display/`** - PriceTag, PriceRange +- **`search-bar/`** - SearchInput, SearchBar +- **`breadcrumb/`** - Breadcrumb +- **`tabs/`** - TabGroup, Tab + +**Đặc điểm:** + +- ✅ Combines atoms +- ✅ Simple state (useState for UI) +- ✅ No business logic +- ✅ Reusable in multiple contexts +- ❌ No global context (useAuth, useCart) +- 📄 Tài liệu: `components/molecules/MOLECULES.md` + +#### **ORGANISMS** (`components/organisms/`) + +**Khu vực UI phức tạp, riêng biệt, có logic riêng.** + +Sections phức tạp kết hợp molecules + atoms, có logic, data filtering: + +- **`navigation/`** - Navbar, CategoryMenu +- **`cart/`** - CartFab, CartSummary, CartList +- **`product-grid/`** - ProductGrid, ProductFilters +- **`forms/`** - LoginForm, RegisterForm, CheckoutForm, ReviewForm +- **`modals/`** - ReviewModal, ConfirmModal +- **`shop-grid/`** - ShopGrid, ShopFilters +- **`hero-section/`** - HeroSection +- **`featured-section/`** - FeaturedProducts, FeaturedShops + +**Đặc điểm:** + +- ✅ Complex UI sections +- ✅ Can use contexts (useAuth, useCart, useMenu) +- ✅ Business logic (filtering, sorting) +- ✅ Always "use client" +- ❌ Not directly reusable (section-specific) +- 📄 Tài liệu: `components/organisms/ORGANISMS.md` + +#### **TEMPLATES** (`components/templates/`) + +**Bố cục cấp trang, cấu trúc nội dung.** + +Page layouts, không có data cụ thể, children composition: + +- **`main-layout/`** - MainLayout (header + sidebar + content + footer) +- **`feed-layout/`** - FeedLayout +- **`manager-layout/`** - ManagerLayout +- **`checkout-layout/`** - CheckoutLayout +- **`auth-layout/`** - AuthLayout + +**Đặc điểm:** + +- ✅ Page-level layout structure +- ✅ Composition of organisms +- ✅ No data fetching +- ✅ Children prop pattern +- ❌ No hardcoded data +- 📄 Tài liệu: `components/templates/TEMPLATES.md` + +#### **PAGES** (`app/*/page.tsx`) + +**Phiên bản cụ thể với dữ liệu thật.** + +Route-specific pages, sử dụng templates + organisms: + +- **`app/(main)/page.tsx`** - Main shopping page +- **`app/(main)/checkout/page.tsx`** - Checkout page +- **`app/(feed)/page.tsx`** - Feed/discovery page +- **`app/(manager)/products/page.tsx`** - Manager dashboard + +**Đặc điểm:** + +- ✅ Route-specific logic +- ✅ Data integration +- ✅ Context usage +- ✅ State orchestration +- ❌ No UI component definitions + +**Tài liệu chi tiết:** + +- `components/ATOMIC_DESIGN.md` - Full Atomic Design structure guide +- `components/atoms/ATOMS.md` - Atoms inventory & props +- `components/molecules/MOLECULES.md` - Molecules inventory & usage +- `components/organisms/ORGANISMS.md` - Organisms inventory & logic +- `components/templates/TEMPLATES.md` - Templates structure ### `layouts/` - Layout Components -Chứa layout dùng chung: + +Chứa layout cấp root (không phải Atomic Design templates): + - **`header.tsx`** - Sticky top bar với brand (logo + shop name) + auth status - **`footer.tsx`** - Footer với 3 sections: brand info, social links, WiFi card -- **Tài liệu:** `layouts/LAYOUTS.md` - Responsive design, CSS variables, responsive patterns +- **Tài liệu:** `layouts/LAYOUTS.md` - Responsive design, CSS variables ### `lib/` - Shared Logic & Data + Chứa logic dùng chung, context, constants, types: -- **`types.ts`** - TypeScript interfaces: User, Product, MenuCategory, Shop, ShopInfo -- **`constants.ts`** - Mock data: MOCK_PRODUCTS (18 items), MOCK_SHOPS (5), MOCK_USERS, MENU_CATEGORIES (8), SHOP_INFO, SOCIAL_LINKS -- **`auth-context.tsx`** - AuthProvider + useAuth() hook (login, logout, register) -- **`cart-context.tsx`** - CartProvider + useCart() hook (add, remove, quantity operations) + +- **`types.ts`** - TypeScript interfaces: User, Product, MenuCategory, Shop, + ShopInfo +- **`constants.ts`** - Mock data: MOCK_PRODUCTS (18 items), MOCK_SHOPS (5), + MOCK_USERS, MENU_CATEGORIES (8), SHOP_INFO, SOCIAL_LINKS +- **`auth-context.tsx`** - AuthProvider + useAuth() hook (login, logout, + register) +- **`cart-context.tsx`** - CartProvider + useCart() hook (add, remove, quantity + operations) - **`menu-context.tsx`** - MenuProvider + useMenu() hook (category state) -- **Tài liệu:** `lib/LIB.md` - Chi tiết types, constants, contexts, integration guide +- **Tài liệu:** `lib/LIB.md` - Chi tiết types, constants, contexts ### `public/` - Static Assets + Chứa static assets: + - **`favicon/`** - Favicon files - **`imgs/`** - Logo, product images (organized in `products/` subfolder) ### `scripts/` - Internal Scripts + Chứa script nội bộ: + - **`release.ts`** - Semantic release script ### `types/` - Global Types + Chứa type dùng chung cấp project: + - **`css.d.ts`** - TypeScript declarations cho CSS modules ### Root Config Files -- **`package.json`** - Dependencies (Next.js 16.1.7, React 19.2.3, Tailwind 4.2.2, TypeScript) -- **`pnpm-lock.yaml`, `package-lock.json`** - Lock files + +- **`package.json`** - Dependencies (Next.js 16.1.7, React 19.2.3, Tailwind + 4.2.2, TypeScript) - **`tsconfig.json`** - TypeScript config - **`next.config.ts`** - Next.js config - **`tailwind.config.ts`** - Tailwind CSS config (v4) @@ -61,20 +195,55 @@ Chứa type dùng chung cấp project: - **`eslint.config.ts`** - ESLint rules - **`.prettierrc`** - Prettier formatting - **`release.config.ts`** - Semantic release config -- **`.gitignore`** - Git ignored files -- **`.blackboxrules`** - Custom rules for blackbox AI + +--- ## 2) Code convention (Naming, format, style guide) ### Naming & File Organization -- **React components:** `PascalCase` (e.g., `CartProduct.tsx`, `Navbar.tsx`) -- **Context/util files:** `kebab-case` (e.g., `auth-context.tsx`, `menu-context.tsx`) + +- **React components:** `PascalCase` (e.g., `Button.tsx`, `ProductCard.tsx`) +- **Context/util files:** `kebab-case` (e.g., `auth-context.tsx`, + `menu-context.tsx`) +- **Type files:** `ComponentName.types.ts` (e.g., `Button.types.ts`) - **Variables/functions:** `camelCase` - **Types/Interfaces:** `PascalCase` - **Routes:** Follow folder structure in `app/` (URL = folder path) -- **Imports:** Use absolute paths with `@/` alias (e.g., `import { useAuth } from "@/lib/auth-context"`) +- **Imports:** Use absolute paths with `@/` alias (e.g., + `import { Button } from "@/components/atoms/buttons/Button"`) + +### Atomic Design File Structure + +``` +components/ +├── atoms/ +│ ├── buttons/ +│ │ ├── Button.tsx +│ │ └── Button.types.ts +│ ├── typography/ +│ │ ├── Text.tsx +│ │ └── Text.types.ts +│ └── index.ts (barrel export) +├── molecules/ +│ ├── cards/ +│ │ ├── ProductCard.tsx +│ │ └── Card.types.ts +│ └── index.ts +├── organisms/ +│ ├── product-grid/ +│ │ ├── ProductGrid.tsx +│ │ └── ProductGrid.types.ts +│ └── index.ts +├── templates/ +│ ├── main-layout/ +│ │ ├── MainLayout.tsx +│ │ └── MainLayout.types.ts +│ └── index.ts +└── ATOMIC_DESIGN.md +``` ### Format & Linting + - **Language:** TypeScript (.ts, .tsx) for all files - **Formatter:** Prettier (config: `.prettierrc`) - Import sorting: `@trivago/prettier-plugin-sort-imports` @@ -85,155 +254,308 @@ Chứa type dùng chung cấp project: - Separate concerns by module/file - Avoid code duplication - Keep imports clean (no dead code) - - Use `"use client"` directive only where needed (interactive components) + - Use `"use client"` only where needed (interactive components) ### Styling & UI + - **Framework:** Tailwind CSS v4.2.2 - **CSS Variables:** Defined in `globals.css` at `:root` - - Colors: `--color-primary`, `--color-primary-dark`, `--color-accent`, `--color-bg-*`, `--color-text-*`, `--color-border-*`, `--color-shadow-*` + - Colors: `--color-primary`, `--color-primary-dark`, `--color-accent`, + `--color-bg-*`, `--color-text-*`, `--color-border-*`, `--color-shadow-*` - Spacing: `--spacing-header-height` (72px) - - Use in Tailwind: `bg-[color:var(--color-primary)]`, `text-[color:var(--color-text-primary)]` + - Use in Tailwind: `bg-[color:var(--color-primary)]`, + `text-[color:var(--color-text-primary)]` - **Icons:** FontAwesome (free CDN icons via ``) - **Images:** Next.js `Image` component from `next/image` -- **Dark mode:** CSS variables support dark mode (can override `:root` values in `@media (prefers-color-scheme: dark)`) +- **Dark mode:** CSS variables support dark mode (can override `:root` values in + `@media (prefers-color-scheme: dark)`) ### Responsive Design -- **Breakpoints (Tailwind):** sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px) + +- **Breakpoints (Tailwind):** sm (640px), md (768px), lg (1024px), xl (1280px), + 2xl (1536px) - **Every new UI feature must be responsive:** - Mobile (<640px): Single column, stacked layout, collapsed sidebar - Tablet (640px-1024px): 2-column layout, adjusted grid - Desktop (1024px+): Multi-column, expanded sidebar, comfortable spacing -- **Mobile-first approach:** Write base styles for mobile, then add `sm:`, `md:`, `lg:`, `xl:` prefixes for larger screens +- **Mobile-first approach:** Write base styles for mobile, then add `sm:`, + `md:`, `lg:`, `xl:` prefixes for larger screens - **Example:** `className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4"` +--- + ## 3) Quy tắc quan trọng ### Markdown Documentation Updates + **Luôn update các file markdown trong folder liên quan khi hoàn thành task:** -| Folder Modified | Update File | Content to Add/Update | -|---|---|---| -| `app/` | `app/APP.md` | Routes, pages, layouts, CSS tokens, responsive behavior | -| `components/` | `components/COMPONENTS.md` | Component props, behavior, styling, dependencies, usage examples | -| `layouts/` | `layouts/LAYOUTS.md` | Layout structure, responsive patterns, CSS variables, integration | -| `lib/` | `lib/LIB.md` | New types, constants, contexts, integration guide, best practices | +| Folder Modified | Update File | Content to Add/Update | +| ----------------------- | ----------------------------------- | ------------------------------------------- | +| `components/atoms/` | `components/atoms/ATOMS.md` | Atom props, variants, usage examples | +| `components/molecules/` | `components/molecules/MOLECULES.md` | Molecule props, composition, usage | +| `components/organisms/` | `components/organisms/ORGANISMS.md` | Organism logic, contexts used, features | +| `components/templates/` | `components/templates/TEMPLATES.md` | Template structure, responsive layout | +| `app/` | `app/APP.md` | Routes, pages, CSS tokens | +| `layouts/` | `layouts/LAYOUTS.md` | Layout structure, responsive patterns | +| `lib/` | `lib/LIB.md` | New types, constants, contexts | +| **Root** | `ATOMIC_DESIGN.md` | Overall structure, patterns, best practices | **Quy trình:** + 1. Hoàn thành task/feature 2. Update file `.md` tương ứng trong folder 3. Commit code + markdown updates cùng lúc 4. Push to branch ### Type Safety & Data Flow + - **Always use TypeScript** - no plain `any` types -- **Mock data first** - Use `lib/constants.ts` for development, replace with API later +- **Mock data first** - Use `lib/constants.ts` for development, replace with API + later - **Contexts for state sharing:** - `AuthContext` (lib/auth-context.tsx) - User state + auth operations - `CartContext` (lib/cart-context.tsx) - Shopping cart + operations - `MenuContext` (lib/menu-context.tsx) - Active category state -- **localStorage keys:** `coffee-shop-user`, `coffee-shop-cart` (defined in contexts) +- **localStorage keys:** `coffee-shop-user`, `coffee-shop-cart` (defined in + contexts) -### Component Development -- **Client vs Server Components:** - - Use `"use client"` only for interactive components (forms, state, event handlers) - - Server components by default (layouts, static content) -- **Props pattern:** Always define prop interfaces, no unnamed parameters -- **Reusable components:** Place in `components/`, not scattered in `app/` -- **Styling:** Use Tailwind + CSS variables, not inline styles or CSS files +### Component Development (Atomic Design) + +#### Creating an Atom + +1. Identify the basic building block needed (button, input, text, icon) +2. Create `atoms/category/ComponentName.tsx` +3. Create `atoms/category/ComponentName.types.ts` with props interface +4. No business logic, pure props-based +5. Add to `atoms/index.ts` barrel export +6. Document in `atoms/ATOMS.md` + +```tsx +// Example: atoms/buttons/Button.tsx +import type { ButtonProps } from "./Button.types"; + +export default function Button({ variant = "primary", ...props }: ButtonProps) { + return + + ); +} +``` + +#### Creating an Organism + +1. Identify complex section (product grid, form, modal content) +2. Create `organisms/section-type/ComponentName.tsx` +3. Create `organisms/section-type/ComponentName.types.ts` +4. Can use contexts (useAuth, useCart, useMenu) +5. Contains business logic (filtering, sorting, validation) +6. Always use `"use client"` +7. Add to `organisms/index.ts` barrel export +8. Document in `organisms/ORGANISMS.md` + +```tsx +// Example: organisms/product-grid/ProductGrid.tsx +"use client"; +import { useCart } from "@/lib/cart-context"; +import { useMenu } from "@/lib/menu-context"; +import ProductCard from "@/components/molecules/cards/ProductCard"; + +export default function ProductGrid() { + const { activeCategory } = useMenu(); + const { addToCart } = useCart(); + + const filtered = products.filter(p => + activeCategory === "all" || p.category === activeCategory + ); + + return ( +
+ {filtered.map(p => )} +
+ ); +} +``` + +#### Creating a Template + +1. Identify page-level layout structure +2. Create `templates/layout-type/TemplateName.tsx` +3. Create `templates/layout-type/TemplateName.types.ts` +4. No data fetching, purely structural +5. Compose organisms + layout sections +6. Use children prop pattern +7. Add to `templates/index.ts` barrel export +8. Document in `templates/TEMPLATES.md` + +```tsx +// Example: templates/main-layout/MainLayout.tsx +import Navbar from "@/components/organisms/navigation/Navbar"; +import Header from "@/layouts/header"; + +import type { MainLayoutProps } from "./MainLayout.types"; + +export default function MainLayout({ children }: MainLayoutProps) { + return ( +
+
+
+ +
{children}
+
+
+ ); +} +``` + +### Client vs Server Components + +- **Atoms:** Server by default, `"use client"` if interactive (Button, Input) +- **Molecules:** `"use client"` if state needed, server if pure display +- **Organisms:** Always `"use client"` (logic, contexts) +- **Templates:** Server by default (layout), children can be client +- **Pages:** Depends on needs (route-specific logic = client) ### Testing & Quality -- **Responsive testing:** Test on mobile (< 640px), tablet (768px), desktop (1024px+) -- **Accessibility:** Images have alt text, buttons have semantic HTML, sufficient contrast -- **Performance:** Use Next.js Image component, optimize imports, lazy-load where needed -- **Error handling:** Validate user input at system boundaries, not internally trusted code + +- **Responsive testing:** Test on mobile (< 640px), tablet (768px), desktop + (1024px+) +- **Accessibility:** Images have alt text, buttons have semantic HTML, + sufficient contrast +- **Performance:** Use Next.js Image component, optimize imports, lazy-load + organisms +- **Error handling:** Validate user input at system boundaries ### Git & Commits -- **Commit message:** Follow conventional commits (`feat:`, `fix:`, `docs:`, `style:`, `refactor:`) + +- **Commit message:** Follow conventional commits (`feat:`, `fix:`, `docs:`, + `style:`, `refactor:`) - **Before pushing:** Ensure `npm run lint` and `npm run format` pass locally - **Markdown updates:** Include in same commit as code changes -- **Branch naming:** Feature branches = `feature_` (e.g., `feature_manager_page`) +- **Branch naming:** Feature branches = `feature_` (e.g., + `feature_atomic_refactor`) --- ## 4) Quick Reference Guide for AI -### Creating a New Component -1. Create file in `components/ComponentName.tsx` (PascalCase) -2. Use TypeScript with proper prop interfaces -3. Export default component -4. Add section to `components/COMPONENTS.md` +### Atomic Design Cheat Sheet -### Creating a New Page -1. Create folder: `app/(group-name)/page-name/page.tsx` -2. Add `"use client"` if interactive -3. Use context hooks as needed: `useAuth()`, `useCart()`, `useMenu()` -4. Document in `app/APP.md` - -### Adding a New Route Group -1. Create folder: `app/(group-name)/` -2. Create `layout.tsx` if custom layout needed -3. Add pages under this group -4. Update `app/APP.md` - -### Adding Product Categories -1. Update `MENU_CATEGORIES` in `lib/constants.ts` -2. Update `Product.category` references -3. Update `MOCK_PRODUCTS` with new category items -4. Document in `lib/LIB.md` - -### Adding Mock Products -1. Add to `MOCK_PRODUCTS` array in `lib/constants.ts` -2. Ensure `Product` interface fields are filled -3. Place images in `public/imgs/products/` -4. Test filtering in main page - -### Using Contexts -```tsx -// In client component with "use client" -import { useAuth } from "@/lib/auth-context"; -import { useCart } from "@/lib/cart-context"; -import { useMenu } from "@/lib/menu-context"; - -export default function MyComponent() { - const { user, login, logout } = useAuth(); - const { items, addToCart, removeFromCart } = useCart(); - const { activeCategory, setActiveCategory } = useMenu(); - // ... component logic -} +``` +ATOM → Basic building block (Button, Text, Icon) +MOLECULE → Atoms group (ProductCard, FormField) +ORGANISM → Complex section (ProductGrid, LoginForm) +TEMPLATE → Page layout (MainLayout, CheckoutLayout) +PAGE → Specific route (app/*/page.tsx) ``` +### Component Decision Tree + +``` +Is it a basic UI element? + ├─ YES → ATOM (Button, Text, Icon, Input, Badge) + └─ NO → Is it a composition of atoms? + ├─ YES → MOLECULE (Card, FormField, SearchBar) + └─ NO → Is it a complex section with logic/context? + ├─ YES → ORGANISM (ProductGrid, LoginForm, Modal) + └─ NO → Is it a page-level layout? + ├─ YES → TEMPLATE (MainLayout, CheckoutLayout) + └─ NO → PAGE (app/page.tsx) +``` + +### Creating a New Component Checklist + +- [ ] Determine component level (Atom/Molecule/Organism/Template) +- [ ] Create directory: `components/[level]/[category]/` +- [ ] Create `ComponentName.tsx` with TypeScript +- [ ] Create `ComponentName.types.ts` with Props interface +- [ ] Add to `index.ts` barrel export in that level +- [ ] Test responsive design (mobile/tablet/desktop) +- [ ] Update markdown documentation +- [ ] Run `npm run format` and `npm run lint` +- [ ] Commit with conventional message + ### Common File Locations -- **Page layouts:** `app/(group-name)/layout.tsx` -- **Page content:** `app/(group-name)/page-name/page.tsx` -- **Shared UI components:** `components/ComponentName.tsx` -- **Layout wrappers:** `layouts/header.tsx`, `layouts/footer.tsx` -- **Business logic:** `lib/auth-context.tsx`, `lib/cart-context.tsx`, etc. -- **Data/constants:** `lib/constants.ts` -- **Type definitions:** `lib/types.ts` -- **Styling:** `app/globals.css` (CSS variables), Tailwind classes in components + +- **Atoms:** `components/atoms/[category]/ComponentName.tsx` +- **Molecules:** `components/molecules/[category]/ComponentName.tsx` +- **Organisms:** `components/organisms/[section-type]/ComponentName.tsx` +- **Templates:** `components/templates/[layout-type]/TemplateName.tsx` +- **Pages:** `app/[route]/page.tsx` +- **Layouts (root):** `layouts/header.tsx`, `layouts/footer.tsx` +- **Contexts:** `lib/auth-context.tsx`, `lib/cart-context.tsx` +- **Types:** `lib/types.ts` +- **Constants:** `lib/constants.ts` + +### Import Patterns + +```tsx +// Atoms +import Button from "@/components/atoms/buttons/Button"; +import { Button } from "@/components/atoms"; // via barrel + +// Molecules +import ProductCard from "@/components/molecules/cards/ProductCard"; +import { ProductCard } from "@/components/molecules"; + +// Organisms +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; +import { ProductGrid } from "@/components/organisms"; + +// Templates +import MainLayout from "@/components/templates/main-layout/MainLayout"; +import { MainLayout } from "@/components/templates"; + +// Contexts +import { useAuth } from "@/lib/auth-context"; +import { useCart } from "@/lib/cart-context"; +``` ### CSS Variables (from `globals.css`) + ```css /* Colors */ ---color-primary: main brand color ---color-primary-dark: darker shade ---color-accent: secondary color ---color-bg-main: main background ---color-bg-card: card background ---color-bg-sidebar: sidebar background ---color-text-primary: main text color ---color-text-secondary: secondary text ---color-text-muted: gray/muted text ---color-border: border color ---color-border-light: light border ---color-shadow-sm: small shadow ---color-shadow-md: medium shadow - -/* Spacing */ ---spacing-header-height: 72px +--color-primary: main brand color --color-primary-dark: darker shade + --color-accent: secondary color --color-bg-main: main background + --color-bg-card: card background --color-bg-sidebar: sidebar background + --color-text-primary: main text color --color-text-secondary: secondary text + --color-text-muted: gray/muted text --color-border: border color + --color-border-light: light border --color-shadow-sm: small shadow + --color-shadow-md: medium shadow /* Spacing */ --spacing-header-height: 72px; ``` ### Useful Commands + ```bash # Development npm run dev # Start dev server @@ -252,30 +574,51 @@ npm run release # Semantic release (auto-version + changelog) ### Common Patterns -**Filtering products by category:** +**Filtering products by category (in Organism):** + ```tsx -const filtered = MOCK_PRODUCTS.filter(p => - activeCategory === "all" || p.category === activeCategory +const filtered = MOCK_PRODUCTS.filter( + (p) => activeCategory === "all" || p.category === activeCategory, ); ``` -**Adding to cart:** +**Using Atoms in Molecules:** + ```tsx -const { addToCart } = useCart(); - +import Button from "@/components/atoms/buttons/Button"; +import Text from "@/components/atoms/typography/Text"; + +export default function Card() { + return ( +
+ Product Name + +
+ ); +} ``` -**Conditional rendering for user roles:** +**Using Organisms in Templates:** + ```tsx -const { user } = useAuth(); -{user?.role === "customer" && } -{user?.role === "manager" && } +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; + +export default function MainLayout({ children }) { + return ( +
+
Header
+ + {children} +
+ ); +} ``` -**Responsive classes:** +**Responsive classes (all levels):** + ```tsx // Mobile-first: base style applies to all, sm:/md:/lg: apply at breakpoints -className="w-full sm:w-1/2 md:w-1/3 p-4 md:p-6 hidden md:block" +className = "w-full sm:w-1/2 md:w-1/3 p-4 md:p-6 hidden md:block"; ``` --- @@ -283,6 +626,7 @@ className="w-full sm:w-1/2 md:w-1/3 p-4 md:p-6 hidden md:block" ## 5) Project Status ### ✅ Completed Features + - User authentication (login, register, logout) - Product grid display with category filtering - Shopping cart with add/remove/update operations @@ -293,12 +637,80 @@ className="w-full sm:w-1/2 md:w-1/3 p-4 md:p-6 hidden md:block" - Sidebar category filter ### 🚀 In Progress + +- Atomic Design refactoring (components reorganization) - Manager dashboard (quản lý sản phẩm) - `app/(manager)/` route group ### 📋 Planned Features + - Order history and tracking - User profile page - Real backend API integration (replace MOCK_PRODUCTS, MOCK_SHOPS) - Dark mode toggle - Search functionality enhancement - Admin order management page + +--- + +## 6) Atomic Design Documentation Structure + +### `components/ATOMIC_DESIGN.md` + +Master guide covering: + +- Overview of 5 levels +- File structure +- Best practices +- Migration guide +- Import patterns +- Performance optimization +- Accessibility guidelines + +### `components/atoms/ATOMS.md` + +Atoms inventory: + +- List of all atoms by category +- Props interfaces +- Variants & states +- Usage examples +- Styling guidelines + +### `components/molecules/MOLECULES.md` + +Molecules inventory: + +- List of all molecules by category +- Atom composition +- Props interfaces +- Behavior & interactions +- Usage examples + +### `components/organisms/ORGANISMS.md` + +Organisms inventory: + +- List of all organisms by section +- Molecule/atom composition +- Contexts used +- Business logic +- Props interfaces +- Features & behavior + +### `components/templates/TEMPLATES.md` + +Templates inventory: + +- List of all templates by layout type +- Responsive structure +- Organism composition +- Props interfaces +- Usage examples + +--- + +Cấu trúc này cung cấp: ✅ **Scalability**: Dễ thêm components mới với vị trí rõ +ràng ✅ **Reusability**: Maximize tái sử dụng atoms → molecules → organisms ✅ +**Maintainability**: Code dễ tìm kiếm, hiểu logic ✅ **Testability**: Mỗi level +có responsibility riêng ✅ **Performance**: Smart code-splitting theo level ✅ +**Documentation**: Chi tiết từng cấp độ, patterns rõ ràng diff --git a/ATOMIC_DESIGN_DOCS_INDEX.md b/ATOMIC_DESIGN_DOCS_INDEX.md new file mode 100644 index 0000000..ff7ccaa --- /dev/null +++ b/ATOMIC_DESIGN_DOCS_INDEX.md @@ -0,0 +1,295 @@ +# Atomic Design Documentation Index + +**Updated:** 2026-04-03 **Status:** Ready for Implementation **Branch:** +atomic_design + +--- + +## 📚 Documentation Files + +### 1. **ATOMIC_REDESIGN_SUMMARY.md** 📋 + +**What:** High-level executive summary **Length:** ~300 lines **Best for:** +Quick overview, time estimates, benefits **Read time:** 10-15 minutes + +✅ Current strengths analysis ✅ Key issues breakdown ✅ Implementation timeline +✅ File structure overview ✅ Next steps + +--- + +### 2. **OPTIMIZATION_PLAN.md** 📘 (MAIN DOCUMENT) + +**What:** Comprehensive implementation guide **Length:** ~400+ lines **Best +for:** Detailed planning, technical specs, migration strategy **Read time:** +30-45 minutes + +✅ Full current state analysis ✅ Atomic design mapping (all 5 levels) ✅ +Phase-by-phase breakdown ✅ Code quality recommendations ✅ Testing strategies +✅ Migration checklist ✅ Success criteria ✅ File structure details + +**👉 START HERE for full understanding** + +--- + +### 3. **QUICK_START_ATOMIC.md** ⚡ + +**What:** Step-by-step implementation guide **Length:** ~200 lines **Best for:** +Getting hands-on immediately **Read time:** 20-30 minutes (implementation 2-3 +hours) + +✅ Step 1: Button Atom (30 min) ✅ Step 2: TextInput Atom (20 min) ✅ Step 3: +Typography Atoms (45 min) ✅ Step 4: Badge Atom (15 min) ✅ Step 5: Divider Atom +(5 min) ✅ Step 6: Atoms Index (10 min) ✅ Step 7: Replace existing code ✅ Step +8: Verify everything works + +**👉 FOLLOW THIS to start building today** + +--- + +### 4. **Atomic.md** (Original) + +**What:** Atomic Design pattern specification **Length:** ~600 lines **Best +for:** Understanding the pattern, design principles **Read time:** 45-60 minutes +(reference material) + +✅ Pattern overview ✅ Detailed examples ✅ Best practices ✅ Import patterns ✅ +Testing guidelines ✅ Accessibility notes + +--- + +## 🗺️ Recommended Reading Order + +### For Decision Makers / Team Leads + +1. Start: **ATOMIC_REDESIGN_SUMMARY.md** (15 min) → Understand scope and + benefits +2. Reference: **Atomic.md** sections 8-10 (15 min) → Understand best practices +3. Planning: **OPTIMIZATION_PLAN.md** sections "Implementation Priority" (10 + min) → Review timeline + +**Total: 40 minutes to make informed decision** + +--- + +### For Developers Implementing Now + +1. Start: **QUICK_START_ATOMIC.md** (20 min reading + 2-3 hours implementing) → + Build foundation atoms +2. Reference: **OPTIMIZATION_PLAN.md** sections 1-5 (20 min) → Understand full + scope +3. Checklist: **OPTIMIZATION_PLAN.md** section "Migration Checklist" (5 min) → + Track progress + +**Total: 1-2 hours reading, ~2-3 hours hands-on, repeat 5x for full +implementation** + +--- + +### For Architects / Code Reviewers + +1. Deep dive: **OPTIMIZATION_PLAN.md** (40 min) → Full technical specification +2. Reference: **Atomic.md** (30 min) → Design patterns and standards +3. Implementation: **QUICK_START_ATOMIC.md** (20 min) → Code examples and + structure + +**Total: 90 minutes for full understanding** + +--- + +## 📊 Document Comparison + +| Document | Length | Audience | Purpose | Depth | +| ------------------------------ | ------ | ---------- | ------------------ | --------- | +| **ATOMIC_REDESIGN_SUMMARY.md** | 300 L | Everyone | Quick overview | Shallow | +| **QUICK_START_ATOMIC.md** | 200 L | Developers | Start implementing | Medium | +| **OPTIMIZATION_PLAN.md** | 400+ L | Architects | Full strategy | Deep | +| **Atomic.md** | 600 L | Designers | Pattern spec | Reference | + +--- + +## 🎯 Quick Links by Question + +### "How long will this take?" + +→ **ATOMIC_REDESIGN_SUMMARY.md** → Section "Time Estimates" → +**OPTIMIZATION_PLAN.md** → Section "Implementation Priority" + +### "What's wrong with our current code?" + +→ **ATOMIC_REDESIGN_SUMMARY.md** → Section "Key Issues to Fix" → +**OPTIMIZATION_PLAN.md** → Section "Current State Analysis" + +### "How do I start?" + +→ **QUICK_START_ATOMIC.md** → Just follow steps 1-8 + +### "What will the file structure look like?" + +→ **ATOMIC_REDESIGN_SUMMARY.md** → Section "File Structure After Implementation" +→ **OPTIMIZATION_PLAN.md** → Section "File Structure After Implementation" + +### "What are the benefits?" + +→ **ATOMIC_REDESIGN_SUMMARY.md** → Section "Benefits You'll Get" → +**OPTIMIZATION_PLAN.md** → Introduction + +### "What design principles should I follow?" + +→ **Atomic.md** → Section "Best Practices" + "Common Patterns" + +### "How do I test this?" + +→ **OPTIMIZATION_PLAN.md** → Section "Testing Strategy per Atomic Level" + +### "Will this break existing code?" + +→ **OPTIMIZATION_PLAN.md** → Section "Migration Guide" → +**QUICK_START_ATOMIC.md** → Step 7 "Replace Existing Code (Optional, Gradual)" + +--- + +## 📋 Current Project State + +**Components to migrate:** + +- ✅ `components/CartProduct.tsx` → `molecules/cards/ProductCard.tsx` +- ✅ `components/CartFab.tsx` → `organisms/cart/CartFab.tsx` +- ✅ `components/Navbar.tsx` → `organisms/navigation/Navbar.tsx` +- ✅ `components/ReviewModal.tsx` → `organisms/modals/ReviewModal.tsx` + +**Logic to extract:** + +- ✅ Search bar → `molecules/search-bar/SearchInput.tsx` +- ✅ Category menu → `organisms/navigation/CategoryMenu.tsx` +- ✅ Product grid → `organisms/product-grid/ProductGrid.tsx` +- ✅ Rating logic → `molecules/ratings/RatingInput.tsx` + +**New atoms needed:** 20+ **New molecules needed:** 10+ **New organisms +needed:** 8+ **Templates needed:** 5 + +--- + +## 🔄 Implementation Phases + +### Phase 1: Atoms (2-3 days) + +Foundation library - everything depends on this. **See:** QUICK_START_ATOMIC.md +for hands-on + +### Phase 2: Molecules (2-3 days) + +Combine atoms into reusable UI components. **See:** OPTIMIZATION_PLAN.md Section +2 + +### Phase 3: Organisms (2-3 days) + +Extract existing logic into organized sections. **See:** OPTIMIZATION_PLAN.md +Section 3 + +### Phase 4: Templates (1-2 days) + +Create reusable page layouts. **See:** OPTIMIZATION_PLAN.md Section 4 + +### Phase 5: Pages (1 day) + +Update pages to use new hierarchy. **See:** OPTIMIZATION_PLAN.md Section 5 + +**Total:** 8-10 days for full implementation **Quick wins:** 2.5 hours to get +foundation + +--- + +## ✅ Success Metrics + +After implementation, verify: + +- [ ] 0 components in `components/` root +- [ ] All atoms properly organized +- [ ] All molecules use atoms +- [ ] All organisms use molecules +- [ ] All pages use templates + organisms +- [ ] No lint errors: `npm run lint` +- [ ] Properly formatted: `npm run format` +- [ ] All interactive components work +- [ ] Responsive on all breakpoints +- [ ] Accessibility requirements met + +--- + +## 🚀 Getting Started Today + +### Minimum (2.5 hours) + +1. Read: **QUICK_START_ATOMIC.md** (20 min) +2. Implement: Steps 1-6 (2+ hours) +3. Verify: Step 8 (10 min) + +**Result:** Solid atom foundation + +### Recommended (4-5 hours) + +1. Read: **ATOMIC_REDESIGN_SUMMARY.md** (15 min) +2. Skim: **OPTIMIZATION_PLAN.md** first sections (15 min) +3. Implement: **QUICK_START_ATOMIC.md** (2+ hours) +4. Plan: Next phases using checklist (30 min) + +**Result:** Foundation + clear roadmap + +### Comprehensive (90 min + implementation) + +1. Read: **ATOMIC_REDESIGN_SUMMARY.md** (15 min) +2. Full read: **OPTIMIZATION_PLAN.md** (40 min) +3. Reference: **Atomic.md** sections 8-10 (15 min) +4. Implement: **QUICK_START_ATOMIC.md** (2+ hours) +5. Plan: All 5 phases (20 min) + +**Result:** Full understanding + ready for team + +--- + +## 💬 FAQ + +**Q: Do I have to do all 5 phases?** A: No, start with Phase 1 (atoms). Then +decide if you want molecules, organisms, etc. + +**Q: Can I do this gradually?** A: Yes! Add atoms/molecules as you create new +components. No deadline. + +**Q: Will this break production?** A: No, you can refactor gradually. Existing +code stays unchanged until updated. + +**Q: Do I need tests?** A: Not required, but highly recommended. See +OPTIMIZATION_PLAN.md section on testing. + +**Q: Should the whole team do this?** A: Yes, once atoms are set up, everyone +should use them. Share the docs! + +--- + +## 📞 Questions? + +All answers are in these documents: + +- **Timeline questions:** ATOMIC_REDESIGN_SUMMARY.md +- **Technical questions:** OPTIMIZATION_PLAN.md +- **How-to questions:** QUICK_START_ATOMIC.md +- **Pattern questions:** Atomic.md + +--- + +## 🎓 Learning Path + +1. **Understand the problem** (15 min) → ATOMIC_REDESIGN_SUMMARY.md + +2. **Learn the pattern** (30 min) → Atomic.md sections 1-7 + +3. **See the full plan** (40 min) → OPTIMIZATION_PLAN.md + +4. **Get hands-on** (2-3 hours) → QUICK_START_ATOMIC.md + +5. **Execute the rest** (5-7 days) → Follow OPTIMIZATION_PLAN.md phases + +--- + +**Status:** ✅ Complete Analysis & Documentation **Last Updated:** 2026-04-03 +**Branch:** atomic_design **Next Action:** Start with QUICK_START_ATOMIC.md diff --git a/ATOMIC_REDESIGN_SUMMARY.md b/ATOMIC_REDESIGN_SUMMARY.md new file mode 100644 index 0000000..4e0c952 --- /dev/null +++ b/ATOMIC_REDESIGN_SUMMARY.md @@ -0,0 +1,406 @@ +# Atomic Design Restructuring - Executive Summary + +## 📋 What I've Done + +I've analyzed your project against the **Atomic Design pattern** defined in +`Atomic.md` and created a comprehensive optimization plan. Here's what you need +to know: + +--- + +## ✅ Current Strengths + +Your project has **excellent foundations:** + +| Area | Grade | Notes | +| ------------------------ | ---------- | ------------------------------------- | +| **Context API Setup** | ⭐⭐⭐⭐⭐ | Well-organized, proper TypeScript | +| **Responsive Design** | ⭐⭐⭐⭐ | Mobile-first, good breakpoints | +| **Documentation** | ⭐⭐⭐⭐ | Detailed COMPONENTS.md, good comments | +| **App Router Structure** | ⭐⭐⭐⭐ | Perfect route group organization | +| **Component Quality** | ⭐⭐⭐ | Good, but missing atomic structure | + +--- + +## 🔴 Key Issues to Fix + +### 1. **No Atomic Hierarchy** (CRITICAL) + +``` +Current: +components/ +├── CartProduct.tsx +├── CartFab.tsx +├── Navbar.tsx +├── ReviewModal.tsx +└── COMPONENTS.md + +Target: +components/ +├── atoms/ ← Reusable UI blocks (Button, Input, Text, etc.) +├── molecules/ ← Small combinations (ProductCard, SearchBar, etc.) +├── organisms/ ← Complex sections (ProductGrid, Navbar, ReviewModal) +├── templates/ ← Page layouts (MainLayout, AuthLayout, etc.) +└── COMPONENTS.md +``` + +**Impact:** Makes reusability impossible, increases maintenance burden + +--- + +### 2. **Inline Component Code** (HIGH) + +Currently, UI logic is scattered throughout pages: + +❌ **app/(main)/page.tsx** (192 lines) + +- Lines 106-127: Search input with clear button → should be `SearchInput` + molecule +- Lines 131-153: Category menu logic → should be `CategoryMenu` organism +- Lines 156-188: Product grid rendering → should be `ProductGrid` organism + +✅ **Should be:** + +```tsx + +``` + +**Impact:** Pages are bloated, hard to test, hard to reuse + +--- + +### 3. **Missing Atom Library** (HIGH) + +You're creating buttons/inputs inline everywhere: + +❌ **Inline button** (CartProduct.tsx:73-79) + +```tsx + +``` + +❌ **Another button** (ReviewModal.tsx:147-154) + +```tsx + +``` + +❌ **Search input** (app/(main)/page.tsx:108-127) + +```tsx +
+ + + {searchQuery && } +
+``` + +✅ **Should be atoms:** + +```tsx + + + +``` + +**Impact:** Inconsistent styling, 100+ lines of duplicate code, hard to update +theme + +--- + +### 4. **No Component Hierarchy** (MEDIUM) + +Components should be composable: + +❌ **Current:** CartProduct is standalone ✅ **Should be:** ProductCard molecule +using atoms (Text, Badge, Button, Image) + +❌ **Current:** ReviewModal contains all form logic ✅ **Should be:** +ReviewModal organism containing ReviewForm molecule with FormField atoms + +--- + +## 📊 Numbers + +| Metric | Current | Target | Benefit | +| ---------------------- | --------- | ---------- | ----------------------- | +| **Components in root** | 5 | 0 | Better organization | +| **Total components** | ~5 | ~40+ | More reusable | +| **Atoms** | 0 | ~20 | Foundation library | +| **Molecules** | 0 | ~10 | Mid-level composability | +| **Organisms** | 0 | ~8 | Complex sections | +| **Templates** | 0 | 5 | Layout reuse | +| **Avg page size** | 192 lines | <100 lines | More maintainable | +| **Button duplication** | 5+ places | 1 atom | DRY principle | + +--- + +## 🎯 Implementation Plan + +### **Phase 1: Atoms** (Foundation - 2-3 days) + +Create reusable UI blocks that everything else depends on: + +- Button, IconButton +- TextInput, SearchInput, Textarea +- Heading, Text, Caption (typography) +- Badge, PriceBadge +- Icon components +- Divider, Spinner, Skeleton + +✅ **First step:** All other components will use these + +--- + +### **Phase 2: Molecules** (Combinations - 2-3 days) + +Combine atoms into small, reusable UI units: + +- **ProductCard** (rename CartProduct) +- **SearchBar** (search input + icon + clear button) +- **FormField** (label + input + error) +- **RatingInput** (5-star interactive rating) +- **PriceTag** (formatted price display) +- Breadcrumb, Tabs, etc. + +✅ **These use atoms from Phase 1** + +--- + +### **Phase 3: Organisms** (Complex Sections - 2-3 days) + +Extract existing logic into organized components: + +- **ProductGrid** (extract from page, use ProductCard) +- **CategoryMenu** (extract from page) +- **Navbar** (move existing) +- **CartFab** (move existing) +- **ReviewModal** (move existing) +- Forms (LoginForm, RegisterForm, etc.) +- ShopGrid, FeaturedSection, etc. + +✅ **These use molecules + atoms** + +--- + +### **Phase 4: Templates** (Layouts - 1-2 days) + +Create page layout structures: + +- MainLayout (header + sidebar + content + footer) +- FeedLayout +- AuthLayout +- CheckoutLayout +- ManagerLayout + +✅ **These wrap pages, use organisms** + +--- + +### **Phase 5: Update Pages** (Integration - 1 day) + +Update pages to use new hierarchy: + +- Replace inline logic with component calls +- Reduce page file sizes +- Update imports + +✅ **Pages become <100 lines of clean composition** + +--- + +## ⏱️ Time Estimates + +| Phase | Scope | Time | Blocker | +| ------------ | ---------------------- | -------------- | ------------ | +| 1️⃣ Atoms | 7 component groups | 2-3 days | None | +| 2️⃣ Molecules | 8 component groups | 2-3 days | Phase 1 done | +| 3️⃣ Organisms | 8 component groups | 2-3 days | Phase 2 done | +| 4️⃣ Templates | 5 component groups | 1-2 days | Phase 3 done | +| 5️⃣ Pages | Page updates + testing | 1 day | Phase 4 done | +| **Total** | **All 40+ components** | **~8-10 days** | - | + +### Quick Win Path (~2.5 hours) + +If you want to start immediately: + +1. Create Button atom (30 min) → unblocks everything +2. Create TextInput atom (20 min) +3. Create Typography atoms (45 min) +4. Move existing components (30 min) +5. Rename CartProduct → ProductCard (15 min) + +This gives you a solid **foundation to build on gradually**. + +--- + +## 📁 File Structure After Implementation + +``` +components/ +├── atoms/ (20 atomic components) +│ ├── buttons/ +│ ├── inputs/ +│ ├── typography/ +│ ├── badges/ +│ ├── icons/ +│ ├── dividers/ +│ ├── loaders/ +│ └── index.ts +├── molecules/ (10 molecular combinations) +│ ├── cards/ +│ ├── form-groups/ +│ ├── ratings/ +│ ├── price-display/ +│ ├── search-bar/ +│ ├── breadcrumb/ +│ ├── tabs/ +│ └── index.ts +├── organisms/ (8 complex sections) +│ ├── navigation/ +│ ├── cart/ +│ ├── product-grid/ +│ ├── forms/ +│ ├── modals/ +│ ├── shop-grid/ +│ ├── hero-section/ +│ ├── featured-section/ +│ └── index.ts +├── templates/ (5 layout templates) +│ ├── main-layout/ +│ ├── feed-layout/ +│ ├── manager-layout/ +│ ├── checkout-layout/ +│ ├── auth-layout/ +│ └── index.ts +└── COMPONENTS.md (updated) +``` + +--- + +## 🎁 Benefits You'll Get + +### Immediate + +- ✅ Consistent button styling across entire app +- ✅ Centralized color/spacing changes +- ✅ Better code organization +- ✅ Clear component boundaries + +### Short-term (1-2 weeks) + +- ✅ 100+ lines of code removed (no duplication) +- ✅ Easier feature additions +- ✅ Pages drop from 192 → <100 lines +- ✅ Team can follow clear patterns + +### Long-term (1-3 months) + +- ✅ 40% faster development +- ✅ 50% easier testing +- ✅ Better for new team members +- ✅ Ready for design system evolution +- ✅ Can add Storybook with confidence + +--- + +## 📖 Documents Created + +### 1. **OPTIMIZATION_PLAN.md** (THIS IS THE MAIN DOCUMENT) + +- Complete analysis of current state +- Detailed breakdown of each phase +- Component mapping (old → new) +- Code quality recommendations +- Testing strategies +- Migration checklist +- Success criteria + +**👉 READ THIS FIRST** - It's 400+ lines but super detailed + +### 2. **This file** (ATOMIC_REDESIGN_SUMMARY.md) + +- High-level overview +- Quick reference guide +- Time estimates +- Benefits summary + +--- + +## 🚀 Next Steps + +### Option A: Start Immediately (Recommended) + +1. Read `OPTIMIZATION_PLAN.md` fully +2. Implement **Quick Wins** section (2.5 hours) +3. Get feedback from team +4. Continue with Phases 1-5 + +### Option B: Plan First + +1. Share `OPTIMIZATION_PLAN.md` with team +2. Discuss timeline and priorities +3. Decide which phases to implement +4. Create sprint backlog + +### Option C: Gradual Refactoring + +1. Start with atoms only +2. Add them as new components needed +3. Gradually move existing components +4. No hard deadline - organic growth + +--- + +## ❓ Questions to Answer + +Before starting, clarify: + +1. **Scope:** Do you want all 5 phases or just atoms/molecules first? +2. **Timeline:** Rush (1 week) or steady (2-3 weeks)? +3. **Testing:** Should we add unit tests for new components? +4. **Breaking changes:** OK to update imports everywhere? +5. **Team:** Will others be working on this too? + +--- + +## 📚 Resources + +- **Main guide:** `OPTIMIZATION_PLAN.md` (comprehensive) +- **Atomic Design reference:** `Atomic.md` (your design spec) +- **Current docs:** `COMPONENTS.md`, `app/APP.md`, `lib/LIB.md` +- **Implementation examples:** Sections 1-5 in OPTIMIZATION_PLAN.md + +--- + +## 💡 Key Insight + +Your code is **good quality** - but it's not following the atomic structure you +defined in `Atomic.md`. Think of it like: + +- ✅ You have **good ingredients** (contexts, hooks, styling) +- ✅ You have a **recipe** (Atomic.md) +- ❌ But you haven't **followed the recipe** + +This document shows you exactly how to follow the recipe step-by-step. + +--- + +## 📞 Support + +When implementing, you'll have detailed guidance in: + +1. **OPTIMIZATION_PLAN.md** - Strategy & structure +2. **Atomic.md** - Design patterns & examples +3. **COMPONENTS.md** - Current component docs (will expand) + +All the pieces are in place. It's just about organizing them correctly. + +--- + +**Status:** ✅ Analysis Complete - Ready for Implementation **Last Updated:** +2026-04-03 **Document:** ATOMIC_REDESIGN_SUMMARY.md diff --git a/Atomic.md b/Atomic.md new file mode 100644 index 0000000..eeaf9b2 --- /dev/null +++ b/Atomic.md @@ -0,0 +1,762 @@ +# ATOMIC DESIGN STRUCTURE GUIDE + +## Overview + +Project sử dụng **Atomic Design Pattern** để tổ chức UI components theo 5 cấp +độ: + +1. **Atoms** - Khối xây dựng cơ bản, không thể chia nhỏ hơn +2. **Molecules** - Nhóm atoms đơn giản hoạt động cùng nhau +3. **Organisms** - Khu vực UI phức tạp, riêng biệt +4. **Templates** - Bố cục cấp trang, cấu trúc nội dung +5. **Pages** - Các phiên bản cụ thể với dữ liệu thật + +--- + +## 1) ATOMS (`components/atoms/`) + +**Mục đích:** Khối xây dựng cơ bản, tái sử dụng cao, không phụ thuộc logic phức +tạp. + +Không có context/hooks logic phức tạp, chỉ nhận props từ parent. + +### Cấu trúc thư mục + +``` +components/atoms/ +├── buttons/ +│ ├── Button.tsx # Nút cơ bản (primary, secondary, danger) +│ ├── IconButton.tsx # Nút chỉ có icon +│ └── Button.types.ts # Props types +├── inputs/ +│ ├── TextInput.tsx # Text input cơ bản +│ ├── NumberInput.tsx # Number input với up/down +│ ├── Checkbox.tsx # Checkbox +│ └── Input.types.ts # Props types +├── badges/ +│ ├── Badge.tsx # Badge cơ bản (color variants) +│ ├── PriceBadge.tsx # Badge hiển thị giá +│ └── Badge.types.ts # Props types +├── icons/ +│ ├── StarIcon.tsx # Rating star icon +│ ├── CartIcon.tsx # Shopping cart icon +│ ├── SearchIcon.tsx # Search icon +│ └── icons.types.ts # Props types +├── typography/ +│ ├── Heading.tsx # h1-h6 headings +│ ├── Text.tsx # Body text variants +│ ├── Caption.tsx # Small caption text +│ └── Typography.types.ts # Props types +├── dividers/ +│ ├── Divider.tsx # Horizontal divider +│ └── Divider.types.ts # Props types +├── loaders/ +│ ├── Spinner.tsx # Loading spinner +│ ├── Skeleton.tsx # Skeleton loader +│ └── Loader.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Atoms + +**Button.tsx:** + +```tsx +import { ButtonHTMLAttributes } from "react"; + +import type { ButtonProps } from "./Button.types"; + +export default function Button({ + variant = "primary", + size = "md", + disabled = false, + children, + className = "", + ...props +}: ButtonProps) { + const baseStyles = + "font-semibold rounded-lg transition-colors disabled:opacity-50"; + const variants = { + primary: + "bg-[color:var(--color-primary)] text-white hover:bg-[color:var(--color-primary-dark)]", + secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300", + danger: "bg-red-500 text-white hover:bg-red-600", + }; + const sizes = { + sm: "px-3 py-1 text-sm", + md: "px-4 py-2 text-base", + lg: "px-6 py-3 text-lg", + }; + + return ( + + ); +} +``` + +**Button.types.ts:** + +```tsx +import { ButtonHTMLAttributes } from "react"; + +export interface ButtonProps extends ButtonHTMLAttributes { + variant?: "primary" | "secondary" | "danger"; + size?: "sm" | "md" | "lg"; + disabled?: boolean; + children: React.ReactNode; + className?: string; +} +``` + +--- + +## 2) MOLECULES (`components/molecules/`) + +**Mục đích:** Nhóm atoms tạo thành những UI unit nhỏ, tái sử dụng, có logic đơn +giản. + +Có thể sử dụng `useState`, nhưng logic chủ yếu nằm ở parent component. + +### Cấu trúc thư mục + +``` +components/molecules/ +├── form-groups/ +│ ├── FormField.tsx # Input + label + error message +│ ├── FormGroup.tsx # Label + input wrapper +│ └── FormGroup.types.ts # Props types +├── cards/ +│ ├── ProductCard.tsx # Card hiển thị sản phẩm (image + name + price + btn) +│ ├── ShopCard.tsx # Card hiển thị quán +│ ├── ReviewCard.tsx # Card hiển thị review +│ └── Card.types.ts # Props types +├── ratings/ +│ ├── RatingStars.tsx # Hiển thị 5 sao rating +│ ├── RatingInput.tsx # Input 5 sao (interactive) +│ └── Rating.types.ts # Props types +├── price-display/ +│ ├── PriceTag.tsx # Hiển thị giá formatted +│ ├── PriceRange.tsx # Hiển thị range giá +│ └── Price.types.ts # Props types +├── search-bar/ +│ ├── SearchInput.tsx # Search input với icon +│ ├── SearchBar.tsx # Search bar wrapper +│ └── Search.types.ts # Props types +├── breadcrumb/ +│ ├── Breadcrumb.tsx # Breadcrumb navigation +│ └── Breadcrumb.types.ts # Props types +├── tabs/ +│ ├── TabGroup.tsx # Tabs wrapper +│ ├── Tab.tsx # Individual tab +│ └── Tabs.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Molecules + +**ProductCard.tsx:** + +```tsx +import Button from "@/components/atoms/buttons/Button"; +import Text from "@/components/atoms/typography/Text"; +import Image from "next/image"; + +import type { ProductCardProps } from "./Card.types"; + +export default function ProductCard({ + product, + onAddToCart, +}: ProductCardProps) { + return ( +
+
+ {product.name} +
+ + {product.name} + + + {product.description} + +
+ + ${product.price.toFixed(2)} + + +
+
+ ); +} +``` + +--- + +## 3) ORGANISMS (`components/organisms/`) + +**Mục đích:** Khu vực UI phức tạp, độc lập, có logic riêng. + +Kết hợp multiple molecules/atoms, có thể sử dụng contexts (useAuth, useCart, +etc.), state phức tạp. + +### Cấu trúc thư mục + +``` +components/organisms/ +├── navigation/ +│ ├── Navbar.tsx # Sidebar category filter (cũ CartProduct) +│ ├── CategoryMenu.tsx # Category menu wrapper +│ └── Navigation.types.ts # Props types +├── cart/ +│ ├── CartFab.tsx # Floating action button giỏ hàng +│ ├── CartSummary.tsx # Cart summary widget +│ ├── CartList.tsx # Danh sách sản phẩm trong giỏ +│ └── Cart.types.ts # Props types +├── product-grid/ +│ ├── ProductGrid.tsx # Grid hiển thị danh sách sản phẩm +│ ├── ProductFilters.tsx # Bộ lọc sản phẩm (category, price, rating) +│ └── ProductGrid.types.ts # Props types +├── forms/ +│ ├── LoginForm.tsx # Form đăng nhập (username + password + submit) +│ ├── RegisterForm.tsx # Form đăng ký +│ ├── CheckoutForm.tsx # Form thanh toán +│ ├── ReviewForm.tsx # Form đánh giá (modal content) +│ └── Forms.types.ts # Props types +├── modals/ +│ ├── ReviewModal.tsx # Modal đánh giá (header + form + footer) +│ ├── ConfirmModal.tsx # Modal xác nhận generic +│ └── Modal.types.ts # Props types +├── shop-grid/ +│ ├── ShopGrid.tsx # Grid hiển thị danh sách quán +│ ├── ShopFilters.tsx # Bộ lọc quán (location, rating) +│ └── ShopGrid.types.ts # Props types +├── hero-section/ +│ ├── HeroSection.tsx # Banner hero cấp trang +│ └── Hero.types.ts # Props types +├── featured-section/ +│ ├── FeaturedProducts.tsx # Section sản phẩm nổi bật +│ ├── FeaturedShops.tsx # Section quán nổi bật +│ └── Featured.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Organisms + +**ProductGrid.tsx:** + +```tsx +"use client"; + +import ProductCard from "@/components/molecules/cards/ProductCard"; +import { useCart } from "@/lib/cart-context"; +import { MOCK_PRODUCTS } from "@/lib/constants"; +import { useMenu } from "@/lib/menu-context"; + +import type { ProductGridProps } from "./ProductGrid.types"; + +export default function ProductGrid({ searchQuery = "" }: ProductGridProps) { + const { activeCategory } = useMenu(); + const { addToCart } = useCart(); + + const filtered = MOCK_PRODUCTS.filter((product) => { + const matchCategory = + activeCategory === "all" || product.category === activeCategory; + const matchSearch = + product.name.toLowerCase().includes(searchQuery.toLowerCase()) || + product.description.toLowerCase().includes(searchQuery.toLowerCase()); + return matchCategory && matchSearch; + }); + + return ( +
+ {filtered.map((product) => ( + + ))} +
+ ); +} +``` + +--- + +## 4) TEMPLATES (`components/templates/`) + +**Mục đích:** Bố cục cấp trang, cấu trúc nội dung, không có data cụ thể. + +Chứa layout và structure của page, nhưng data được truyền từ page component. + +### Cấu trúc thư mục + +``` +components/templates/ +├── main-layout/ +│ ├── MainLayout.tsx # Layout chính (header + sidebar + content + footer) +│ ├── MainLayout.types.ts # Props types +│ └── styles.ts # Responsive grid layout logic +├── feed-layout/ +│ ├── FeedLayout.tsx # Layout feed (khám phá quán) +│ └── FeedLayout.types.ts # Props types +├── manager-layout/ +│ ├── ManagerLayout.tsx # Layout manager dashboard +│ └── ManagerLayout.types.ts # Props types +├── checkout-layout/ +│ ├── CheckoutLayout.tsx # Layout thanh toán (steps, cart, form) +│ └── CheckoutLayout.types.ts # Props types +├── auth-layout/ +│ ├── AuthLayout.tsx # Layout auth (login/register) +│ └── AuthLayout.types.ts # Props types +└── index.ts # Barrel export +``` + +### Ví dụ Templates + +**MainLayout.tsx:** + +```tsx +import Navbar from "@/components/organisms/navigation/Navbar"; +import Footer from "@/layouts/footer"; +import Header from "@/layouts/header"; + +import type { MainLayoutProps } from "./MainLayout.types"; + +export default function MainLayout({ children }: MainLayoutProps) { + return ( +
+
+
+ {/* Sidebar - ẩn trên mobile */} + + {/* Main content */} +
{children}
+
+
+
+ ); +} +``` + +--- + +## 5) PAGES (`app/*/page.tsx`) + +**Mục đích:** Các phiên bản cụ thể với dữ liệu thật, logic cấp trang. + +Server/client components sử dụng templates, organisms, nhận data từ API/context. + +### Ví dụ Pages + +**app/(main)/page.tsx:** + +```tsx +"use client"; + +import FeaturedSection from "@/components/organisms/featured-section/FeaturedSection"; +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; +import MainLayout from "@/components/templates/main-layout/MainLayout"; +import { useState } from "react"; + +export default function MainPage() { + const [searchQuery, setSearchQuery] = useState(""); + + return ( + + +
+ +
+ + ); +} +``` + +--- + +## 6) File Hierarchy Summary + +``` +components/ +├── atoms/ +│ ├── buttons/ +│ ├── inputs/ +│ ├── badges/ +│ ├── icons/ +│ ├── typography/ +│ ├── dividers/ +│ ├── loaders/ +│ └── index.ts +├── molecules/ +│ ├── form-groups/ +│ ├── cards/ +│ ├── ratings/ +│ ├── price-display/ +│ ├── search-bar/ +│ ├── breadcrumb/ +│ ├── tabs/ +│ └── index.ts +├── organisms/ +│ ├── navigation/ +│ ├── cart/ +│ ├── product-grid/ +│ ├── forms/ +│ ├── modals/ +│ ├── shop-grid/ +│ ├── hero-section/ +│ ├── featured-section/ +│ └── index.ts +├── templates/ +│ ├── main-layout/ +│ ├── feed-layout/ +│ ├── manager-layout/ +│ ├── checkout-layout/ +│ ├── auth-layout/ +│ └── index.ts +└── ATOMIC_DESIGN.md (this file) +``` + +--- + +## 7) Migration Guide (Old → New) + +### Old Structure → New Structure Mapping + +| Old File | New Location | Type | +| ----------------- | ---------------------------------- | -------- | +| `CartProduct.tsx` | `molecules/cards/ProductCard.tsx` | Molecule | +| `Navbar.tsx` | `organisms/navigation/Navbar.tsx` | Organism | +| `CartFab.tsx` | `organisms/cart/CartFab.tsx` | Organism | +| `ReviewModal.tsx` | `organisms/modals/ReviewModal.tsx` | Organism | + +### Migration Steps + +1. Create new directory structure under `components/` +2. Move existing components to appropriate levels (atoms → molecules → + organisms) +3. Extract shared styles/logic into atoms +4. Update imports in `app/` pages +5. Test responsiveness at each breakpoint +6. Update `COMPONENTS.md` with new structure + +--- + +## 8) Best Practices + +### Atoms Development + +- ✅ Reusable across entire project +- ✅ No business logic +- ✅ No context/hooks (useAuth, useCart) +- ✅ Pure props-based +- ✅ Full TypeScript typing +- ❌ No "use client" needed (unless interactive, e.g., Button) + +### Molecules Development + +- ✅ Combines multiple atoms +- ✅ Simple state (open/close, hover state) +- ✅ No complex business logic +- ✅ Can use useState for UI state +- ✅ Reusable in multiple contexts +- ❌ No global state (useAuth, useCart) + +### Organisms Development + +- ✅ Complex UI sections +- ✅ Can use contexts (useAuth, useCart, useMenu) +- ✅ Business logic +- ✅ Always "use client" +- ✅ Filter, sort, complex interactions +- ❌ Not reusable across different page types + +### Templates Development + +- ✅ Page layout structure +- ✅ Composition of organisms + layout +- ✅ No data fetching/business logic +- ✅ Children prop pattern +- ✅ Props for customization +- ❌ No hardcoded data + +### Pages Development + +- ✅ Specific page implementations +- ✅ Route-specific logic +- ✅ Data integration +- ✅ Context usage at page level +- ✅ State management orchestration +- ❌ No UI component definitions (use organisms) + +--- + +## 9) Import Patterns + +### Atoms + +```tsx +import Button from "@/components/atoms/buttons/Button"; +import Text from "@/components/atoms/typography/Text"; +``` + +### Molecules + +```tsx +import ProductCard from "@/components/molecules/cards/ProductCard"; +import FormField from "@/components/molecules/form-groups/FormField"; +``` + +### Organisms + +```tsx +import LoginForm from "@/components/organisms/forms/LoginForm"; +import ProductGrid from "@/components/organisms/product-grid/ProductGrid"; +``` + +### Templates + +```tsx +import MainLayout from "@/components/templates/main-layout/MainLayout"; +``` + +### Barrel Exports + +```tsx +// Usage +import { Button, Text } from "@/components/atoms"; + +// components/atoms/index.ts +export { default as Button } from "./buttons/Button"; +export { default as Text } from "./typography/Text"; +export * from "./buttons/Button.types"; +``` + +--- + +## 10) Common Patterns + +### Creating a New Atom + +```tsx +// atoms/buttons/NewButton.tsx +export default function NewButton({ variant, ...props }: Props) { + return +``` + +--- + +## 14) Version Control & Documentation + +### File Format + +``` +components/ +├── atoms/ +│ ├── buttons/ +│ │ ├── Button.tsx +│ │ ├── Button.types.ts +│ │ └── Button.md # Component documentation +│ └── ... +├── molecules/ +│ ├── cards/ +│ │ ├── ProductCard.tsx +│ │ ├── Card.types.ts +│ │ └── ProductCard.md +│ └── ... +└── ... +``` + +### Documentation Template + +```markdown +# ProductCard + +## Purpose + +Display individual product with image, name, price, and action button. + +## Props + +- `product: Product` - Product data +- `onAddToCart: (product: Product) => void` - Add to cart handler + +## Usage + +\`\`\`tsx \`\`\` + +## Variants + +- Image with loading state +- With discount badge +- With rating stars + +## Responsive + +- Mobile: Single column, full width +- Desktop: Grid layout +``` + +--- + +Cấu trúc này cung cấp: ✅ **Scalability**: Dễ thêm components mới ✅ +**Reusability**: Tối đa tái sử dụng ✅ **Maintainability**: Code dễ hiểu, tìm +kiếm ✅ **Testability**: Mỗi level có logic riêng ✅ **Performance**: Smart +code-splitting diff --git a/OPTIMIZATION_PLAN.md b/OPTIMIZATION_PLAN.md new file mode 100644 index 0000000..9b811b9 --- /dev/null +++ b/OPTIMIZATION_PLAN.md @@ -0,0 +1,1184 @@ +# 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 ` +``` + +Should become: + +```tsx + +``` + +**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 +
+ + + {searchQuery && } +
+``` + +Should become: + +```tsx + +``` + +**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 ` + ); +} +``` + +### Create `components/atoms/buttons/index.ts` + +```typescript +export { default as Button } from "./Button"; +export type { ButtonProps } from "./Button.types"; +``` + +### Test it + +```tsx +// Try in any page +import { Button } from "@/components/atoms/buttons"; + + + + +``` + +--- + +## Step 2: Create TextInput Atom (20 minutes) + +### Create directory + +```bash +mkdir -p components/atoms/inputs +``` + +### Create `components/atoms/inputs/Input.types.ts` + +```typescript +import { InputHTMLAttributes } from "react"; + +export interface TextInputProps extends InputHTMLAttributes { + label?: string; + error?: string; + icon?: string; // FontAwesome class + onIconClick?: () => void; + className?: string; +} +``` + +### Create `components/atoms/inputs/TextInput.tsx` + +```typescript +import type { TextInputProps } from "./Input.types"; + +export default function TextInput({ + label, + error, + icon, + onIconClick, + className = "", + ...props +}: TextInputProps) { + return ( +
+ {label && ( + + )} +
+ + {icon && ( + + )} +
+ {error &&

{error}

} +
+ ); +} +``` + +### Create `components/atoms/inputs/SearchInput.tsx` + +```typescript +import { InputHTMLAttributes } from "react"; + +export default function SearchInput({ + value, + onChange, + onClear, + ...props +}: InputHTMLAttributes & { + onClear?: () => void; +}) { + return ( +
+ + + {value && onClear && ( + + )} +
+ ); +} +``` + +### Create `components/atoms/inputs/index.ts` + +```typescript +export { default as TextInput } from "./TextInput"; +export { default as SearchInput } from "./SearchInput"; +export type { TextInputProps } from "./Input.types"; +``` + +--- + +## Step 3: Create Typography Atoms (45 minutes) + +### Create directory + +```bash +mkdir -p components/atoms/typography +``` + +### Create `components/atoms/typography/Typography.types.ts` + +```typescript +import { HTMLAttributes } from "react"; + +export interface HeadingProps extends HTMLAttributes { + level?: 1 | 2 | 3 | 4 | 5 | 6; + children: React.ReactNode; +} + +export interface TextProps extends HTMLAttributes { + variant?: "body1" | "body2" | "caption" | "label"; + children: React.ReactNode; +} + +export interface CaptionProps extends HTMLAttributes { + children: React.ReactNode; +} +``` + +### Create `components/atoms/typography/Heading.tsx` + +```typescript +import type { HeadingProps } from "./Typography.types"; + +export default function Heading({ + level = 2, + children, + className = "", + ...props +}: HeadingProps) { + const sizes = { + 1: "text-3xl font-bold", + 2: "text-2xl font-bold", + 3: "text-xl font-bold", + 4: "text-lg font-semibold", + 5: "text-base font-semibold", + 6: "text-sm font-semibold", + }; + + const Tag = `h${level}` as keyof JSX.IntrinsicElements; + + return ( + + {children} + + ); +} +``` + +### Create `components/atoms/typography/Text.tsx` + +```typescript +import type { TextProps } from "./Typography.types"; + +export default function Text({ + variant = "body1", + children, + className = "", + ...props +}: TextProps) { + const variants = { + body1: "text-base text-(--color-text-primary)", + body2: "text-sm text-(--color-text-secondary)", + caption: "text-xs text-(--color-text-muted)", + label: "text-sm font-medium text-(--color-text-secondary)", + }; + + return ( +

+ {children} +

+ ); +} +``` + +### Create `components/atoms/typography/Caption.tsx` + +```typescript +import type { CaptionProps } from "./Typography.types"; + +export default function Caption({ + children, + className = "", + ...props +}: CaptionProps) { + return ( + + {children} + + ); +} +``` + +### Create `components/atoms/typography/index.ts` + +```typescript +export { default as Heading } from "./Heading"; +export { default as Text } from "./Text"; +export { default as Caption } from "./Caption"; +export type { HeadingProps, TextProps, CaptionProps } from "./Typography.types"; +``` + +--- + +## Step 4: Create Badge Atom (15 minutes) + +### Create directory + +```bash +mkdir -p components/atoms/badges +``` + +### Create `components/atoms/badges/Badge.types.ts` + +```typescript +import { HTMLAttributes } from "react"; + +export interface BadgeProps extends HTMLAttributes { + variant?: "primary" | "secondary" | "success" | "danger" | "warning"; + size?: "sm" | "md"; + children: React.ReactNode; +} +``` + +### Create `components/atoms/badges/Badge.tsx` + +```typescript +import type { BadgeProps } from "./Badge.types"; + +export default function Badge({ + variant = "primary", + size = "md", + children, + className = "", + ...props +}: BadgeProps) { + const variants = { + primary: "bg-(--color-primary) text-white", + secondary: "bg-(--color-border-light) text-(--color-text-secondary)", + success: "bg-green-100 text-green-700", + danger: "bg-red-100 text-red-700", + warning: "bg-yellow-100 text-yellow-700", + }; + + const sizes = { + sm: "px-2 py-1 text-xs", + md: "px-3 py-1.5 text-sm", + }; + + return ( + + {children} + + ); +} +``` + +### Create `components/atoms/badges/index.ts` + +```typescript +export { default as Badge } from "./Badge"; +export type { BadgeProps } from "./Badge.types"; +``` + +--- + +## Step 5: Create Divider Atom (5 minutes) + +### Create directory + +```bash +mkdir -p components/atoms/dividers +``` + +### Create `components/atoms/dividers/Divider.tsx` + +```typescript +import { HTMLAttributes } from "react"; + +export interface DividerProps extends HTMLAttributes { + orientation?: "horizontal" | "vertical"; +} + +export default function Divider({ + orientation = "horizontal", + className = "", + ...props +}: DividerProps) { + return ( +
+ ); +} +``` + +--- + +## Step 6: Create Atoms Index (10 minutes) + +### Create `components/atoms/index.ts` + +```typescript +// Buttons +export { Button } from "./buttons"; +export type { ButtonProps } from "./buttons"; + +// Inputs +export { TextInput, SearchInput } from "./inputs"; +export type { TextInputProps } from "./inputs"; + +// Typography +export { Heading, Text, Caption } from "./typography"; +export type { HeadingProps, TextProps, CaptionProps } from "./typography"; + +// Badges +export { Badge } from "./badges"; +export type { BadgeProps } from "./badges"; + +// Dividers +export { Divider } from "./dividers"; +export type { DividerProps } from "./dividers"; +``` + +--- + +## Step 7: Replace Existing Code (Optional, Gradual) + +Now you have atoms! Start using them: + +### Before (inline) + +```tsx +// components/CartProduct.tsx + +``` + +### After (using atom) + +```tsx +// components/CartProduct.tsx +import { Button } from "@/components/atoms"; + +; +``` + +### Before (inline) + +```tsx +// app/(main)/page.tsx +

+ {activeCategoryLabel} +

+

+ {filteredProducts.length} món +

+``` + +### After (using atoms) + +```tsx +// app/(main)/page.tsx +import { Heading, Text } from "@/components/atoms"; + +{activeCategoryLabel} +{filteredProducts.length} món +``` + +--- + +## Step 8: Verify Everything Works + +```bash +# Check for TypeScript errors +npm run lint + +# Format code +npm run format + +# Run dev server +npm run dev + +# Visit http://localhost:3000 and check styling +``` + +--- + +## Next: Create Molecules + +Once atoms are solid, create molecules that **use** atoms: + +``` +components/molecules/ +├── cards/ +│ └── ProductCard.tsx (uses Button, Text, Badge atoms) +├── form-groups/ +│ └── FormField.tsx (uses TextInput, Text atoms) +├── ratings/ +│ └── RatingInput.tsx (uses Button, Caption atoms) +└── search-bar/ + └── SearchBar.tsx (uses SearchInput, Button atoms) +``` + +**Each molecule = 2-3 atoms combined + simple state** + +--- + +## Checklist + +- [ ] Created `components/atoms/buttons/` +- [ ] Created `components/atoms/inputs/` +- [ ] Created `components/atoms/typography/` +- [ ] Created `components/atoms/badges/` +- [ ] Created `components/atoms/dividers/` +- [ ] Created `components/atoms/index.ts` (barrel export) +- [ ] Updated at least 1 component to use atoms +- [ ] Run `npm run lint` - no errors +- [ ] Run `npm run format` - code formatted +- [ ] Test in browser - styling looks correct + +--- + +## 💡 Tips + +1. **Start small:** Just do atoms. Don't worry about molecules yet. +2. **Use consistently:** Once Button atom exists, never write `