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 → Custom/Radix Components**: Replace MUI components with custom equivalents (especially Tooltips)

3.**spyOn → queries parameter**: Use`queries` in story parameters for GET endpoint mocks

4.**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.

When investigating or editing TypeScript/React code, always use the TypeScript language server tools for accurate navigation:

- 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

- 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

- 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

- When touching code with emotion styles, refactor to Tailwind ("leave the campsite better than you found it")

- 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

import {typeInterpolation,typeTheme,useTheme }from"@emotion/react";

<divcss={styles.container}>

<Stackdirection="row"spacing={3}>

<spancss={{ fontWeight:500, color:theme.experimental.l1.text }}>

// NEW - Tailwind

<divclassName="flex flex-col gap-2">

<divclassName="flex items-center gap-6">

<spanclassName="font-medium text-content-primary">

```

**Common replacements:**

- `css={visuallyHidden}` → `className="sr-only"`

- `Stack` component → flex with Tailwind classes (`flex`, `flex-col`, `flex-row`, `gap-*`)

- Theme colors → Tailwind semantic tokens (`text-content-primary`, `bg-surface-secondary`, `border-border-default`)

- Icons: use lucide-react with `size-icon-sm`, `size-icon-xs` classes

## Tailwind Best Practices

- Group related classes

- Prefer `for...of` over `forEach` for iteration

- **Biome** handles both linting and formatting (not ESLint/Prettier)

## Testing Patterns

### Storybook: spyOn → queries parameter (for GET endpoint mocks)

**PREFERRED PATTERN**: Use `queries` parameter in story parameters instead of `spyOn` for GET endpoint mocks.

```tsx

// OLD - spyOn pattern (AVOID for GET mocks)

beforeEach: () =>{

spyOn(API,"getUsers").mockResolvedValue({

users:MockUsers,

count:MockUsers.length,

});

spyOn(API,"getTemplates").mockResolvedValue([MockTemplate]);

// NEW - queries parameter pattern (PREFERRED)

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 used 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 snapshots** over programmatic assertions

- Chromatic snapshots catch visual changes during review

- Avoid programmatic assertions in stories that duplicate what snapshots show

- Programmatic assertions can introduce flakiness - remove when redundant

- Stories are snapshot tests - rely on the screenshot to verify correctness

## State Storage

### localStorage vs user_configs table

**IMPORTANT**: For user preferences that should persist across devices and browsers, use the `user_configs` table in the backend, NOT `localStorage`.

- **localStorage is browser-specific**, not user-specific

- **User preferences should persist** across devices/browsers

- Follow the plumbing for `theme_preference` as a reference example

- localStorage may be acceptable only for truly transient UI state that doesn't need to follow the user

**Key principle**: If a user dismisses something or sets a preference, it should be tied to their account, not their browser.

## Workflow

- Be sure to typecheck when you're done making a series of code changes