diff --git a/site/CLAUDE.md b/site/CLAUDE.md index 43538c012e6e8..155674e829cd5 100644 --- a/site/CLAUDE.md +++ b/site/CLAUDE.md @@ -1,5 +1,17 @@ # Frontend Development Guidelines +## Critical Pattern Migrations (MUST FOLLOW) + +The following patterns are actively being migrated and have **STRICT policies**: + +1. **Emotion → Tailwind**: "No new emotion styles, full stop" - Always use Tailwind CSS +2. **MUI Components → Custom/Radix Components**: Replace MUI components (Tooltips, Tables, Buttons) with custom/shadcn equivalents +3. **MUI Icons → lucide-react**: All icons must use lucide-react, never MUI icons +4. **spyOn → queries parameter**: Use `queries` in story parameters for GET endpoint mocks +5. **localStorage → user_configs**: Store user preferences in backend, not browser storage + +When touching existing code, **"leave the campsite better than you found it"** - refactor old patterns to new ones even if not directly related to your changes. + ## TypeScript LSP Navigation (USE FIRST) When investigating or editing TypeScript/React code, always use the TypeScript language server tools for accurate navigation: @@ -26,25 +38,84 @@ When investigating or editing TypeScript/React code, always use the TypeScript l ## Components -- MUI components are deprecated - migrate away from these when encountered -- Use shadcn/ui components first - check `site/src/components` for existing implementations. +- **MUI components are deprecated** - migrate away from these when encountered + - Replace `@mui/material/Tooltip` with custom `Tooltip` component (Radix-based) + - Default 100ms delay via global tooltip provider + - Use `delayDuration={0}` when immediate tooltip needed + - Replace MUI Tables with custom table components + - Replace MUI Buttons with shadcn Button components + - Systematically replace MUI components with custom/shadcn equivalents +- 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. +- The modules folder should contain components with business logic specific to the codebase - Create custom components only when shadcn alternatives don't exist +### Icon Migration: MUI Icons → lucide-react + +Never import from `@mui/icons-material`. Use `lucide-react` instead. + +```tsx +import { Building2Icon, UsersIcon, GlobeIcon, UserIcon } from "lucide-react"; +``` + +**Common replacements:** `BusinessIcon` → `Building2Icon`, `GroupIcon` → `UsersIcon`, `PublicIcon` → `GlobeIcon`, `PersonIcon` → `UserIcon` + +### MUI → Radix Component Prop Naming + +When migrating from MUI to Radix components, use Radix naming conventions: + +```tsx + + Hover me + Tooltip text + +``` + +**Prop changes from MUI:** Use `side` instead of `placement`, remove `PopperProps`, and use `TooltipContent` children instead of `title` prop. + ## Styling -- Emotion CSS is deprecated. Use Tailwind CSS instead. -- Use custom Tailwind classes in tailwind.config.js. +- **Emotion CSS is STRICTLY DEPRECATED: "no new emotion styles, full stop"** + - Never use `@emotion/react`, `css` prop, `useTheme()`, or emotion styled components + - Always use Tailwind CSS utility classes 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 +### Common Emotion → Tailwind Migrations + +Use Tailwind CSS utility classes: + +```tsx +
+
+ + Content here + +
+
+``` + +**Common replacements:** + +- Replace `css={visuallyHidden}` with `className="sr-only"` +- Replace `Stack` component with Tailwind flex (`flex`, `flex-col`, `gap-*`) +- Replace emotion `css` prop and theme colors with Tailwind utilities (`text-content-primary`, `bg-surface-secondary`, `border-border-default`) +- Use lucide-react icons with `size-icon-sm`, `size-icon-xs` classes + ## 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 +- For conditional classes, use the `cn()` utility (from `utils/cn`) which combines `clsx` and `tailwind-merge` + + ```tsx + import { cn } from "utils/cn"; + +
+ ``` ## General Code style @@ -53,6 +124,54 @@ When investigating or editing TypeScript/React code, always use the TypeScript l - Prefer `for...of` over `forEach` for iteration - **Biome** handles both linting and formatting (not ESLint/Prettier) +## Testing Patterns + +### Storybook: queries parameter for GET endpoint mocks + +**PREFERRED PATTERN**: For GET endpoint mocks in Storybook stories, use `queries` parameter instead of `spyOn`. + +```tsx +// Use queries parameter pattern +parameters: { + queries: [ + { + key: usersKey({ q: "" }), + data: { + users: MockUsers, + count: MockUsers.length, + }, + }, + { + key: getTemplatesQueryKey({ q: "has-ai-task:true" }), + data: [MockTemplate], + }, + ], +} +``` + +**Important notes:** + +- This applies specifically to GET endpoint mocks in Storybook stories +- `spyOn` is still appropriate for other mock types (POST, PUT, DELETE, non-GET endpoints) +- Must import the correct query key functions (e.g., `usersKey`, `getTemplatesQueryKey`) + +### Chromatic/Storybook Testing Best Practices + +- Prefer visual validation through Chromatic snapshots over programmatic assertions +- Remove redundant assertions that duplicate snapshot validation +- Stories are snapshot tests - rely on screenshots to verify correctness + +## State Storage + +### localStorage vs user_configs table + +**IMPORTANT**: Use `user_configs` table for user preferences, NOT `localStorage`. + +- localStorage is browser-specific; user preferences should persist across devices +- Follow `theme_preference` as reference implementation +- Use localStorage only for truly transient UI state +- **Key principle**: User preferences should be tied to their account, not their browser + ## Workflow - Be sure to typecheck when you're done making a series of code changes @@ -69,23 +188,6 @@ When investigating or editing TypeScript/React code, always use the TypeScript l 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