# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Astro + Tailwind CSS v4 project.

Stack: Astro, Tailwind CSS v4.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`

## Project structure

- Routes in `src/pages/`, layouts in `src/layouts/`, components in `src/components/`.
- Markdown/MDX content lives in content collections with a schema in `src/content.config.ts`.

## 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.

## Astro

- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.

## 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.

## Reference docs

- [Astro docs](https://docs.astro.build)
- [Tailwind CSS docs](https://tailwindcss.com/docs)