# Team Conventions

Rules that override default assumptions when choosing components and props. Apply these during refinement and implementation.

## Layers (mandatory)

- **Menus:** ALWAYS `useMenuLayer` from `layers/Menus` — never `MenuList` or `Menu` directly
- **Dialogs:** ALWAYS `useDialogLayer` from `layers/Dialogs` — never `Dialog` directly
- **Drawers:** ALWAYS `useDrawerLayer` from `layers/Drawers` — never `Drawer` directly

## Components

- **Page headers:** use `Title` from `design-system/Title` with `title` + `description` props — never two separate `Typography` components
- **Buttons in page headers:** `size="large"`
- **Empty states:** `StateCard` (composed, not design-system) with `slotProps.title.variant="M"` and `slotProps.avatar.color="default"`
- **Forms:** ALWAYS use Form variants (FormInputClassic, FormAutocomplete, etc.) — never manual Controller wrappers

## Styling

- **Colors:** NEVER hardcode hex — use `theme.palette.new.*` tokens via `useTheme()`
- **Imports:** ALWAYS `@material-hu/components/...` — never `@mui/material`

## External services (API integrations)

- **Proxy mandatory:** ALL external API calls go through a Vercel API route in `api/<service-name>/[...path].ts` — the frontend NEVER calls external URLs directly
- **Server-side secrets:** API keys live in `process.env.<SERVICE>_API_KEY` — NEVER use `VITE_` prefix for secrets (Vite exposes those to the client bundle)
- **Scoped endpoints:** Each proxy exposes only the specific operations needed — no open passthrough to the full external API
- **Input validation:** Validate request bodies with Zod in the API route before forwarding to the external service
- **Error sanitization:** Return generic error messages from the proxy — never leak external service error details, stack traces, or internal IDs
- **Timeouts:** All external calls must use `AbortController` with a reasonable timeout (10s default)
- **Environment files:** `.env.example` documents required variables (no real values); `.env.local` holds real values and must be in `.gitignore`

## Data fetching

- **React Query mandatory:** Use `@tanstack/react-query` for all server/async state — `useQuery` for reads, `useMutation` for writes
- **Single-object syntax:** Always `useQuery({ queryKey, queryFn })` — never positional args
- **Query keys factory:** Define in the service file or a dedicated `queries.ts` — see PATTERNS.md
- **Service + hooks split:** Service functions in `src/services/<name>.ts`, hooks in `src/services/<name>.hooks.ts`