WHAT DO YOU NEED?
│
├─► UI Components
│   ├─ Basic (buttons, forms, dialogs) → shadcn/ui
│   ├─ SaaS polish (tickers, marquees) → Magic UI [skill: frontend-magic-ui]
│   └─ Dramatic effects (spotlight, 3D) → Aceternity [skill: frontend-aceternity]
│
├─► Animations
│   ├─ Just plays/loops (loaders, feedback) → Lottie [skill: frontend-lottie]
│   └─ Reacts to input (hover, data) → Rive [skill: frontend-rive]
│
├─► Assets
│   ├─ Icons → Iconify/Lucide [skill: frontend-iconify]
│   ├─ Avatars → DiceBear (FREE) [skill: frontend-image-generation]
│   ├─ Photos → Unsplash (FREE) [skill: frontend-image-generation]
│   └─ Illustrations → unDraw (FREE) [skill: frontend-image-generation]
│
├─► Theming
│   ├─ Colors/palette → Color System [skill: frontend-color-system]
│   └─ Typography → Google Fonts [skill: frontend-google-fonts]
│
└─► Quality
    ├─ Code checks → Debug & Linting [skill: frontend-debug-linting]
    └─ Visual QA → Playwright [skill: frontend-playwright]

# New Next.js project
npx create-next-app@latest my-app --typescript --tailwind --eslint --app

# Essential dependencies
npm install clsx tailwind-merge framer-motion
npm install -D prettier eslint-config-prettier

# UI foundation
npx shadcn@latest init
npx shadcn@latest add button card input dialog

src/
├── app/                    # Next.js App Router
│   ├── layout.tsx          # Root layout + fonts
│   ├── page.tsx            # Home page
│   └── (routes)/           # Route groups
├── components/
│   ├── ui/                 # shadcn components
│   ├── magicui/            # Magic UI components
│   └── [feature]/          # Feature components
├── lib/
│   ├── fonts.ts            # Font configuration
│   ├── utils.ts            # cn() helper
│   └── constants.ts        # App constants
├── styles/
│   └── globals.css         # Tailwind + CSS vars
└── public/
    ├── animations/         # .lottie, .riv files
    ├── icons/              # Downloaded SVGs
    └── images/             # Static images

Need a component?
│
├─► Form element (input, select, checkbox)
│   └─► shadcn/ui — accessible, unstyled base
│
├─► Data display (table, card, list)
│   └─► shadcn/ui — consistent patterns
│
├─► Marketing/Landing page
│   ├─► Stats/numbers → Magic UI: NumberTicker
│   ├─► Logo carousel → Magic UI: Marquee
│   ├─► Feature grid → Magic UI: BentoGrid
│   ├─► Hero spotlight → Aceternity: Spotlight, Aurora
│   ├─► 3D hover cards → Aceternity: 3DCard
│   ├─► Text reveal → Aceternity: TextGenerateEffect
│   └─► Device mockup → Magic UI: Safari, iPhone
│
└─► Interactive element
    ├─► Simple hover/focus → Tailwind transitions
    ├─► Complex entrance → Framer Motion
    └─► State machine → Rive

Animation needed?
│
├─► Does it react to user input?
│   ├─ NO → Lottie (just plays)
│   └─ YES → Does it have multiple states?
│       ├─ Simple hover → CSS/Framer Motion
│       └─ Complex states → Rive
│
├─► What type?
│   ├─ Loading spinner → Lottie
│   ├─ Success/error → Lottie
│   ├─ Empty state illustration → Lottie
│   ├─ Animated toggle/checkbox → Rive
│   ├─ Progress driven by data → Rive
│   └─ Hero background effect → Aceternity

// ✅ Use cn() for conditional classes
import { cn } from "@/lib/utils"

<button className={cn(
  "px-4 py-2 rounded-md font-medium",
  "bg-primary text-primary-foreground",
  "hover:bg-primary/90 transition-colors",
  disabled && "opacity-50 cursor-not-allowed"
)}>

// ✅ Responsive: mobile-first
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

// ✅ Dark mode with CSS variables
<div className="bg-background text-foreground">

// ❌ Avoid arbitrary values when Tailwind has it
<div className="mt-[16px]">  // Bad
<div className="mt-4">       // Good

/* globals.css - shadcn theme structure */
:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --primary: 239 84% 67%;
  --primary-foreground: 0 0% 98%;
  /* ... */
}

.dark {
  --background: 240 10% 3.9%;
  --foreground: 0 0% 98%;
  /* ... */
}

// lib/fonts.ts
import { Inter, Plus_Jakarta_Sans } from 'next/font/google'

export const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
})

export const jakarta = Plus_Jakarta_Sans({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-jakarta',
})

// app/layout.tsx
<html className={`${inter.variable} ${jakarta.variable}`}>

// tailwind.config.ts
fontFamily: {
  sans: ['var(--font-inter)'],
  display: ['var(--font-jakarta)'],
}

// Recommended: @iconify/react with Lucide set
import { Icon } from '@iconify/react'

<Icon icon="lucide:home" className="w-5 h-5" />

// Or download SVGs for performance
curl -o ./public/icons/home.svg "https://api.iconify.design/lucide/home.svg"

ALWAYS FREE FIRST:
  Avatars:      DiceBear, Boring Avatars, UI Avatars
  Photos:       Unsplash, Picsum
  Illustrations: unDraw, Storyset
  Backgrounds:  Haikei, Hero Patterns

AI GENERATION ONLY WHEN:
  - Custom branded asset needed
  - No suitable free alternative
  - User explicitly requests

// Avatar with fallback
const fallback = `https://api.dicebear.com/7.x/lorelei/svg?seed=${name}`
<img src={src || fallback} onError={e => e.target.src = fallback} />

// Placeholder photo
<img src="https://source.unsplash.com/800x600/?technology" />

// 1. Client components need directive
'use client'

// 2. Browser-only code → useEffect
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return <Skeleton />

// 3. Heavy animations → dynamic import
import dynamic from 'next/dynamic'
const Globe = dynamic(() => import('@/components/globe'), { ssr: false })

// 4. Window/document access → check first
if (typeof window !== 'undefined') {
  // browser code
}

Images:
  ✓ Use next/image with proper sizing
  ✓ Add priority to LCP images
  ✓ Lazy load below-fold images

Fonts:
  ✓ Use next/font (auto self-hosted)
  ✓ Only 'latin' subset unless needed
  ✓ display: 'swap' always

Animations:
  ✓ Reduce particles on mobile
  ✓ Respect prefers-reduced-motion
  ✓ Pause when not in viewport

Components:
  ✓ Dynamic import heavy components
  ✓ Lazy load below-fold sections
  ✓ Memoize expensive renders

// Reduced motion check
const prefersReducedMotion = window.matchMedia(
  '(prefers-reduced-motion: reduce)'
).matches

// Viewport visibility
import { useInView } from 'react-intersection-observer'
const { ref, inView } = useInView({ threshold: 0.1 })
useEffect(() => {
  inView ? animation.play() : animation.pause()
}, [inView])

CODE CHECKS (required):
  npm run lint        → 0 errors
  npm run typecheck   → 0 errors
  npm run format      → clean

VISUAL QA (required):
  1. npm run dev
  2. browser_navigate → page
  3. browser_take_screenshot → looks correct
  4. browser_console_messages { onlyErrors: true } → EMPTY
  5. browser_resize { width: 375 } → mobile works

TypeScript:
  "Type 'X' not assignable to 'Y'" → Fix type or add assertion
  "Object possibly undefined" → Add ?. or ?? fallback

React:
  "Missing useEffect dependencies" → Add deps or useCallback
  "Each child needs unique key" → Add key={item.id}

Hydration:
  "Text content mismatch" → 'use client' + mounted check
  "Hydration failed" → dynamic import with ssr: false

Console:
  "Failed to fetch" → Check API/network
  "Cannot read property of undefined" → Add loading state

<div className="container mx-auto px-4 sm:px-6 lg:px-8 max-w-7xl">
  {children}
</div>

<section className="py-16 md:py-24 lg:py-32">
  <div className="container">
    <h2 className="text-3xl md:text-4xl lg:text-5xl font-bold mb-8">
      Title
    </h2>
  </div>
</section>

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {items.map(item => (
    <Card key={item.id}>
      <CardHeader>
        <CardTitle>{item.title}</CardTitle>
      </CardHeader>
      <CardContent>{item.content}</CardContent>
    </Card>
  ))}
</div>

function Component() {
  const [data, setData] = useState(null)
  const [loading, setLoading] = useState(true)

  if (loading) return <Skeleton className="h-32 w-full" />
  if (!data) return <EmptyState />
  return <Content data={data} />
}

'use client'
import { Spotlight } from '@/components/ui/spotlight'
import { FlipWords } from '@/components/ui/flip-words'

export function Hero() {
  return (
    <section className="relative h-screen bg-black overflow-hidden">
      <Spotlight className="absolute -top-40 left-0" fill="white" />
      <div className="relative z-10 container flex flex-col items-center justify-center h-full text-center">
        <h1 className="text-4xl md:text-6xl font-bold text-white mb-6">
          Build <FlipWords words={["faster", "better", "smarter"]} /> apps
        </h1>
        <p className="text-xl text-gray-400 max-w-2xl mb-8">
          Description text here
        </p>
        <Button size="lg">Get Started</Button>
      </div>
    </section>
  )
}

'use client'
import { NumberTicker } from '@/components/magicui/number-ticker'

const stats = [
  { value: 10000, label: 'Users', suffix: '+' },
  { value: 99.9, label: 'Uptime', suffix: '%' },
  { value: 50, label: 'Countries', suffix: '+' },
]

export function Stats() {
  return (
    <section className="py-16 bg-muted">
      <div className="container grid grid-cols-1 md:grid-cols-3 gap-8 text-center">
        {stats.map(stat => (
          <div key={stat.label}>
            <div className="text-4xl font-bold">
              <NumberTicker value={stat.value} />
              {stat.suffix}
            </div>
            <div className="text-muted-foreground">{stat.label}</div>
          </div>
        ))}
      </div>
    </section>
  )
}