---
description: Project-wide coding conventions for NoWhatever
alwaysApply: true
---

# NoWhatever Project Conventions

## Philosophy

- This is a **new project** — never worry about backward compatibility or legacy code migration
- Prioritize **code elegance and reuse** over quick hacks
- Extract shared logic into reusable utilities (`src/lib/`) and components (`src/components/`)
- DRY: if the same pattern appears twice, extract it

## Tech Stack

- **Framework**: Next.js App Router (all pages are `"use client"`)
- **Database**: Prisma + SQLite
- **Styling**: Tailwind CSS v4 (use `bg-linear-to-*` NOT `bg-gradient-to-*`)
- **Animation**: framer-motion
- **Icons**: lucide-react
- **Effects**: canvas-confetti

## Tailwind v4 Syntax

- Gradients: `bg-linear-to-br` (not `bg-gradient-to-br`)
- Arbitrary values: prefer Tailwind built-in classes over `[]` when possible (e.g. `max-w-20` not `max-w-[5rem]`)

## Component Patterns

- Page components export `default function PageName()`
- Use `useCallback` for event handlers passed as props
- Use `motion.*` from framer-motion for animated elements
- Mobile-first, `min-h-dvh` for full-height pages
- `overflow-y-auto scrollbar-none` for scrollable pages
- Extract reusable UI patterns into shared components (modals, cards, empty states)

## Theme-Safe Colors

- **Never use `text-white` for content text on page backgrounds** — it becomes invisible in light mode
- Use semantic colors: `text-heading`, `text-foreground`, `text-secondary`, `text-muted` for content text
- `text-white` is only correct on **colored backgrounds** (buttons, badges, gradient cards, overlays)
- Same applies to `bg-black` — prefer `bg-background`, `bg-surface`, `bg-elevated`

## Loading States

- **Page-level and list-level loading**: always use skeleton screens (`src/components/Skeleton.tsx`), never bare spinners
- Skeleton shape should mimic the actual content layout (cards, list items, avatars, text lines)
- Compose page skeletons from reusable skeleton primitives: `Skeleton`, `SkeletonCircle`, `RecordItemSkeleton`, `RoomCardSkeleton`, etc.
- **Button-level loading** (submit, save, join): keep using inline `Loader2` spinner — skeleton screens don't apply to buttons
- When adding a new page or async data section, always include a skeleton loading state

## API Routes

- Located in `src/app/api/`
- Return `NextResponse.json()` with appropriate status codes
- Always handle errors with try/catch
- Extract common validation (userId, membership) into utility functions in `src/lib/`
- Use consistent error response shape: `{ error: string }`