# DESIGN.md — F-036 Homepage

## Modules Touched

| Module | Change |
|---|---|
| `frontend/` (new) | Full Next.js frontend scaffold + homepage |

## Modules NOT Touched

- Backend (no changes)
- Existing modules

---

## 1. Project Structure

```
frontend/
├── src/
│   ├── app/
│   │   ├── layout.tsx          # Root layout: Header + Footer
│   │   ├── page.tsx            # Homepage (Server Component)
│   │   └── globals.css         # Tailwind + custom vars
│   ├── components/
│   │   ├── layout/
│   │   │   ├── Header.tsx
│   │   │   └── Footer.tsx
│   │   ├── home/
│   │   │   ├── Hero.tsx
│   │   │   ├── FeaturedProducts.tsx
│   │   │   ├── CategoriesGrid.tsx
│   │   │   └── BrandsSection.tsx
│   │   └── ui/
│   │       ├── Button.tsx
│   │       └── Card.tsx
│   ├── lib/
│   │   ├── api.ts              # API client (typed fetch)
│   │   └── types.ts            # Shared types
│   └── types/                  # API response types
├── public/
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── next.config.ts
```

---

## 2. Component Design

### `page.tsx` (Server Component)
```typescript
// Fetches data server-side, passes to sections
export default async function HomePage() {
  const [products, categories, brands] = await Promise.all([
    fetchProducts(),
    fetchCategories(),
    fetchBrands(),
  ]);
  return (
    <main>
      <Hero />
      <FeaturedProducts products={products} />
      <CategoriesGrid categories={categories} />
      <BrandsSection brands={brands} />
    </main>
  );
}
```

### `Hero.tsx`
- Static (no props)
- Tailwind gradient bg, large headline, subheadline, CTA link to /products

### `FeaturedProducts.tsx`
- Props: `products: Product[]`
- Client-side: none — pure display
- 4-column responsive grid, product cards

### `CategoriesGrid.tsx`
- Props: `categories: Category[]`
- 4-column responsive grid

### `BrandsSection.tsx`
- Props: `brands: Brand[]`
- Horizontal scroll on mobile, grid on desktop

---

## 3. API Client

```typescript
// src/lib/api.ts
const BASE = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000';

export async function fetchCategories() {
  const res = await fetch(`${BASE}/categories`);
  return res.json();
}
export async function fetchProducts() {
  const res = await fetch(`${BASE}/products`);
  return res.json();
}
export async function fetchBrands() {
  const res = await fetch(`${BASE}/brands`);
  return res.json();
}
```

---

## 4. Type Definitions

```typescript
// src/types/api.ts
export interface Product {
  id: string;
  name: string;
  slug: string;
  priceCents: number;
  imageUrl?: string;
  brand?: { name: string };
}

export interface Category {
  id: string;
  name: string;
  slug: string;
  imageUrl?: string;
}

export interface Brand {
  id: string;
  name: string;
  slug: string;
  logoUrl?: string;
}
```

---

## 5. Styling

- Tailwind CSS
- Custom color palette via `tailwind.config.ts`:
  - Primary: green (#2D6A4F) — natural, organic
  - Secondary: cream (#F5F0E8)
  - Accent: orange (#E76F51)
- Google Fonts: `Inter` + `Playfair Display` for headings

---

## 6. Responsiveness

| Breakpoint | Layout |
|---|---|
| mobile (< 640px) | 1 col product grid |
| tablet (640-1024px) | 2 col product grid |
| desktop (> 1024px) | 4 col product grid |

---

## 7. Environment

```
NEXT_PUBLIC_API_URL=http://localhost:3000
```

---

## 8. Migration Strategy

- Create `frontend/` directory
- `npm create next-app@latest frontend --typescript --tailwind`
- Build homepage step by step
- No breaking changes to backend