# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A React + Vite + Tailwind CSS v4 + Firebase + Vitest project.

Stack: React + Vite, Tailwind CSS v4, Firebase, Vitest.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type-check: `npx tsc --noEmit`
- Lint: `npm run lint`
- Local emulators: `firebase emulators:start`
- Deploy rules only: `firebase deploy --only firestore:rules`
- Unit tests: `npx vitest run`

## Project structure

- Features live in `src/features/<name>/` with their components, hooks and tests together.
- Shared UI in `src/components/`, hooks in `src/hooks/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## React + Vite

- Function components and hooks only. No class components.
- Follow the Rules of Hooks: call hooks at the top level, never inside conditions or loops.
- Derive values during render instead of syncing them into state with `useEffect`.
- Every list item needs a stable `key` from the data, never the array index if the list can change order.
- Type component props with an exported `Props` type or interface. No `any`.
- Env vars must start with `VITE_` to reach the client, which also means they are public. Never put secrets in them.
- Lazy-load heavy routes with `React.lazy` and `Suspense`.

## Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

## Firebase

- Firebase web config is public by design; security comes from Firestore/Storage Security Rules. Never ship `allow read, write: if true`.
- Every collection needs rules that check `request.auth` and validate the written fields.
- Admin SDK credentials are server-only (Cloud Functions or your backend).
- Model Firestore data for your queries: avoid deeply nested data and unbounded arrays; denormalize deliberately.
- Test rules and functions against the Emulator Suite, not production.

## Vitest

- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.

## Avoid

- Do not reach for global state for data that only one component tree uses.

## Reference docs

- [React docs](https://react.dev)
- [Vite docs](https://vite.dev/guide/)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Firebase docs](https://firebase.google.com/docs)
- [Vitest docs](https://vitest.dev)