---
name: conventions
description: Repo-specific coding conventions and gotchas
metadata:
  type: project
---

- **Client boundary:** any component using SDK hooks or `useUi` must start with `"use client"`.
  Route `page.tsx` files stay thin server components that render a client view.
- **Never hard-code colors/radii.** Use semantic Tailwind tokens (`bg-panel`, `text-muted`,
  `border-border`, `bg-accent`, `rounded-card`, `rounded-control`) so light/dark + live theming
  keep working. Tokens are defined in `apps/web/tailwind.config.ts` → CSS vars.
- **Time formatting** is client-only via `apps/web/lib/format.ts` to avoid SSR hydration drift;
  data (messages/tickets) is fetched client-side through the BFF, not server-rendered.
- **BFF params are async in Next 15:** handlers use `{ params }: { params: Promise<…> }` and
  `await params`.
- **Next config** sets `typescript.ignoreBuildErrors` + `eslint.ignoreDuringBuilds` so the demo
  runs even with strict-mode nits; run `pnpm typecheck` for a clean check.
- **No `packageManager` pin** in root `package.json` on purpose — a pin triggered corepack to
  fetch a non-installed pnpm version and fail offline. Use the local pnpm.
- **Mock store is in-memory** and resets on restart; persistence isn't a goal for the demo.
- Adding a data feature touches 4 files in order: `store.ts` → `bff route` → `client.ts` →
  `hooks.ts` → then the component. See [[architecture-decisions]].