---
name: frontend-nextjs
description: >-
  Next.js App Router + TypeScript + Tailwind + shadcn/ui setup, folder layout,
  and patterns (component size, mobile-first, Zustand when needed). Use for
  web app/service projects using Next.js — not for Python-only stacks.
  Trigger: .tsx/.ts, next.config, new web UI.
---

# Frontend — Next.js + Tailwind + shadcn/ui

> **Web app/service only.** Do not apply to Python-only projects.
> Verify stack matches `PROJECT_RULES.md`. Record architecture decisions in `docs/ai-dev/`.

## Initial Setup

```bash
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir
cd my-app
npx shadcn@latest init
npx shadcn@latest add button card input dialog toast
```

## Directory Structure

```
src/
├── app/
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Home page
│   ├── globals.css         # Tailwind + custom styles
│   └── {feature}/
│       └── page.tsx        # Feature pages
├── components/
│   ├── ui/                 # shadcn/ui (auto-generated)
│   └── {feature}/          # Feature-specific components
├── lib/
│   └── utils.ts            # Utilities (cn function, etc.)
└── types/
    └── index.ts            # Shared types
```

## Key Patterns

- One component = max 150 lines. Split if exceeded
- Check shadcn/ui first, build custom only if needed
- Props: define with TypeScript interfaces
- State: useState first, Zustand if complex
- **HTTP requests: use built-in `fetch` only. Do NOT install Axios**

## Tailwind Patterns

```tsx
// Responsive
<div className="px-4 md:px-8 lg:px-16">
  <h1 className="text-2xl md:text-4xl font-bold">Title</h1>
</div>

// Dark mode
<div className="bg-white dark:bg-gray-900">

// Card grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {items.map(item => <Card key={item.id}>...</Card>)}
</div>
```

## ESLint

Next.js includes ESLint by default. After each feature:

```bash
npx eslint .
```

Fix all errors before committing. Never use `// eslint-disable` without a documented reason.

## Building Pages

1. Create `src/app/{path}/page.tsx`
2. Install needed shadcn/ui components
3. Build in order: layout -> components -> data connection
4. Mobile first, expand with `md:` `lg:` prefixes
5. ESLint pass (`npx eslint .` — zero errors)