mercadodevida/work/artifacts/F-036/DESIGN.md

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)

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

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

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