frontend

Frontend — Next.js + Tailwind + shadcn/ui

This command is part of the VibeHarness framework. Verify stack matches PROJECT_RULES.md. Record architecture decisions in docs/ai-dev/.

Frontend stack for building non-developer MVPs fast and clean. Web app projects only.

Tech Stack

• Next.js 14+ (App Router): Page routing, server components
• TypeScript: Type safety
• Tailwind CSS: Utility-first styling
• shadcn/ui: Copy-paste UI components (lightweight dependencies)

Initial Setup

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir
cd my-app
npx shadcn@latest init

Add shadcn/ui components:

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 components (auto-generated)
│   └── {feature}/          # Feature-specific custom components
├── lib/
│   └── utils.ts            # Utilities (cn function, etc.)
└── types/
    └── index.ts            # Shared types

Component Principles

• One component = one role. Split if over 150 lines
• Check shadcn/ui first, build custom only if needed
• Define props with TypeScript interfaces
• State management: useState/useReducer first, Zustand if complex
• HTTP requests: use built-in fetch only. Do NOT install Axios

Tailwind Patterns

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 text-black dark:text-white">

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>

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