CLAUDE.md for a web app (Next.js / Remix / Astro / SvelteKit / Vue)

# CLAUDE.md — {{project_name}}

## Project overview
{{one_line_what_this_app_does}}. Framework: {{Next.js | Remix | Astro | SvelteKit | Vue}}.
Styling: {{Tailwind | CSS Modules | design-system}}. Package manager: {{pnpm | npm | yarn}}.

## Commands (use these — do not invent scripts; pick the line for THIS framework)
- Dev server: `{{pnpm}} run dev`
- Production build: `{{pnpm}} run build`
- Start the production build:
  - Next.js: `{{pnpm}} run start`   (Next has NO `preview` — `next start` serves the build)
  - Vite / Astro / SvelteKit / Vue: `{{pnpm}} run preview`
- Lint: `{{pnpm}} run lint`   (Next.js: `next lint`)
- Typecheck: `{{pnpm}} run typecheck`   (or `tsc --noEmit`)
- Test: `{{pnpm}} run test`   (e.g. Vitest / Jest / Playwright — use the project's runner)
Verify each script exists in `package.json` before running; never invent a script name.
Always run lint + typecheck + tests before declaring a task done. If no test exists for the
change, add or update one (or state explicitly that none was needed and why).

## Strict guardrails
- SERVER VS CLIENT: Default to Server Components. Add `"use client"` ONLY when the file
  needs state, effects, or browser APIs. Never add it to a component that just renders data.
- DESIGN SYSTEM: Use {{Tailwind utility classes / design-system tokens}} only. NO arbitrary
  values (e.g. no `w-[473px]`, no inline hex). If a token is missing, ask before adding one.
- SEMANTICS: Use native, semantic HTML (`<button>`, `<nav>`, `<header>`, `<main>`) over
  `<div onClick>`. Every interactive element must be keyboard-accessible.
- RESPONSIVE: Mobile-first. Start with the base (mobile) styles and layer breakpoints up.
  Never write desktop-first overrides.
- DATA: Fetch on the server where possible. Do not call internal APIs from the client when
  a server component or loader can do it.
- SEO: Every route/page sets its title and meta description. Do not ship a page without them.

## Conventions
- File/route layout: {{describe your routing convention}}.
- Components live in `{{src/components}}`; one component per file.
- Never commit secrets; read config from `process.env` via {{env validation, e.g. zod}}.

## When unsure
Ask before adding a dependency, changing the build config, or introducing a new pattern.