diff --git a/site/CLAUDE.md b/site/CLAUDE.md new file mode 100644 index 0000000000000..aded8db19c419 --- /dev/null +++ b/site/CLAUDE.md @@ -0,0 +1,115 @@ +# Frontend Development Guidelines + +## Bash commands + +- `pnpm dev` - Start Vite development server +- `pnpm storybook --no-open` - Run storybook tests +- `pnpm test` - Run jest unit tests +- `pnpm test -- path/to/specific.test.ts` - Run a single test file +- `pnpm lint` - Run complete linting suite (Biome + TypeScript + circular deps + knip) +- `pnpm lint:fix` - Auto-fix linting issues where possible +- `pnpm playwright:test` - Run playwright e2e tests. When running e2e tests, remind the user that a license is required to run all the tests +- `pnpm format` - Format frontend code. Always run before creating a PR + +## Components + +- MUI components are deprecated - migrate away from these when encountered +- Use shadcn/ui components first - check `site/src/components` for existing implementations. +- Do not use shadcn CLI - manually add components to maintain consistency +- The modules folder should contain components with business logic specific to the codebase. +- Create custom components only when shadcn alternatives don't exist + +## Styling + +- Emotion CSS is deprecated. Use Tailwind CSS instead. +- Use custom Tailwind classes in tailwind.config.js. +- Tailwind CSS reset is currently not used to maintain compatibility with MUI +- Responsive design - use Tailwind's responsive prefixes (sm:, md:, lg:, xl:) +- Do not use `dark:` prefix for dark mode + +## Tailwind Best Practices + +- Group related classes +- Use semantic color names from the theme inside `tailwind.config.js` including `content`, `surface`, `border`, `highlight` semantic tokens +- Prefer Tailwind utilities over custom CSS when possible + +## General Code style + +- Use ES modules (import/export) syntax, not CommonJS (require) +- Destructure imports when possible (eg. import { foo } from 'bar') +- Prefer `for...of` over `forEach` for iteration +- **Biome** handles both linting and formatting (not ESLint/Prettier) + +## Workflow + +- Be sure to typecheck when you’re done making a series of code changes +- Prefer running single tests, and not the whole test suite, for performance +- Some e2e tests require a license from the user to execute +- Use pnpm format before creating a PR + +## Pre-PR Checklist + +1. `pnpm check` - Ensure no TypeScript errors +2. `pnpm lint` - Fix linting issues +3. `pnpm format` - Format code consistently +4. `pnpm test` - Run affected unit tests +5. Visual check in Storybook if component changes + +## Migration (MUI → shadcn) (Emotion → Tailwind) + +### Migration Strategy + +- Identify MUI components in current feature +- Find shadcn equivalent in existing components +- Create wrapper if needed for missing functionality +- Update tests to reflect new component structure +- Remove MUI imports once migration complete + +### Migration Guidelines + +- Use Tailwind classes for all new styling +- Replace Emotion `css` prop with Tailwind classes +- Leverage custom color tokens: `content-primary`, `surface-secondary`, etc. +- Use `className` with `clsx` for conditional styling + +## React Rules + +### 1. Purity & Immutability + +- **Components and custom Hooks must be pure and idempotent**—same inputs → same output; move side-effects to event handlers or Effects. +- **Never mutate props, state, or values returned by Hooks.** Always create new objects or use the setter from useState. + +### 2. Rules of Hooks + +- **Only call Hooks at the top level** of a function component or another custom Hook—never in loops, conditions, nested functions, or try / catch. +- **Only call Hooks from React functions.** Regular JS functions, classes, event handlers, useMemo, etc. are off-limits. + +### 3. React orchestrates execution + +- **Don’t call component functions directly; render them via JSX.** This keeps Hook rules intact and lets React optimize reconciliation. +- **Never pass Hooks around as values or mutate them dynamically.** Keep Hook usage static and local to each component. + +### 4. State Management + +- After calling a setter you’ll still read the **previous** state during the same event; updates are queued and batched. +- Use **functional updates** (setX(prev ⇒ …)) whenever next state depends on previous state. +- Pass a function to useState(initialFn) for **lazy initialization**—it runs only on the first render. +- If the next state is Object.is-equal to the current one, React skips the re-render. + +### 5. Effects + +- An Effect takes a **setup** function and optional **cleanup**; React runs setup after commit, cleanup before the next setup or on unmount. +- The **dependency array must list every reactive value** referenced inside the Effect, and its length must stay constant. +- Effects run **only on the client**, never during server rendering. +- Use Effects solely to **synchronize with external systems**; if you’re not “escaping React,” you probably don’t need one. + +### 6. Lists & Keys + +- Every sibling element in a list **needs a stable, unique key prop**. Never use array indexes or Math.random(); prefer data-driven IDs. +- Keys aren’t passed to children and **must not change between renders**; if you return multiple nodes per item, use `` + +### 7. Refs & DOM Access + +- useRef stores a mutable .current **without causing re-renders**. +- **Don’t call Hooks (including useRef) inside loops, conditions, or map().** Extract a child component instead. +- **Avoid reading or mutating refs during render;** access them in event handlers or Effects after commit. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy