# UI / UX Rules

These rules freeze the approved UI behavior for ALLA OS and CRM-facing work.

Future UI should reuse existing dashboard patterns rather than introducing a parallel visual system.

## UX.1 Thai CRM Terminology

- `docs/business/crm-terminology.md` is the source of truth for CRM business labels.
- Use `src/features/crm/shared/terminology.ts` when CRM UI needs shared stage or role labels.
- Keep `CRM` and `Dashboard` in English where the existing product already does so.
- Do not rename schema fields, API routes, or internal codes just to match UI wording.

## Dashboard Layout Standards

- Use `PageContainer` for dashboard page framing and page headers.
- Keep pages inside the existing dashboard shell; do not build a separate CRM shell.
- Prefer small, composable sections instead of one oversized page component.
- Use cards, tables, and filter bars consistent with existing CRM dashboard and report pages.

Reference files:

- `src/components/layout/page-container.tsx`
- `src/features/crm/dashboard/components/crm-dashboard.tsx`
- `src/features/crm/reports/components/pipeline-report-view.tsx`

## Bento Grid Guidelines

- Reuse the existing dashboard-card rhythm: summary cards first, then charts/tables/detail sections.
- Keep KPI modules visually scannable with clear grouping and limited density per row.
- Avoid creating a radically different grid language inside CRM pages.
- Match existing spacing, border radius, and card hierarchy from current dashboard/report pages.

## Form Standards

- Use TanStack Form via `@/components/ui/tanstack-form`.
- Use Zod for submit validation.
- Reuse field components from `@/components/forms/fields`.
- Keep labels and helper text business-readable.
- Use `<Button isLoading={isPending}>` for submit/loading actions.
- Close sheets/dialogs only after successful mutation completion and cache invalidation.

Reference docs and files:

- `docs/forms.md`
- `src/features/crm/customers/components/customer-form-sheet.tsx`
- `src/features/crm/opportunities/components/opportunity-form-sheet.tsx`
- `src/features/crm/quotations/components/quotation-form-sheet.tsx`

## Table Standards

- Use `DataTable`, `DataTableToolbar`, and `useDataTable`.
- Define columns close to the feature component tree.
- Keep filters URL-driven when the list page is shareable/bookmarkable.
- Use `useSuspenseQuery()` for table data that is prefetched on the server.

Reference files:

- `src/components/ui/table/data-table.tsx`
- `src/features/users/components/users-table/index.tsx`
- `src/features/crm/customers/components/customers-table.tsx`
- `src/features/crm/opportunities/components/opportunities-table.tsx`

## Filter Standards

- Reuse shared filter metadata and existing select/date input patterns.
- Prefer `nuqs` query-state filters for reports and list pages.
- Keep "clear filters" behavior explicit.
- Report exports must use the same filter contract as on-screen data.

Reference files:

- `src/features/crm/reports/components/report-filter-bar.tsx`
- `src/features/crm/reports/server/filters/shared.ts`

## Empty State Standards

- Empty states should explain what is missing and what the next action is.
- Prefer existing placeholder/skeleton components before inventing one-off empty-state systems.
- Keep empty states within the same page shell and card layout as loaded content.

## Loading State Standards

- Use skeletons or suspense-friendly loading states for lists, charts, and dashboard panels.
- Preserve layout stability while loading.
- Keep button loading width stable with the existing button loading pattern.

Reference files:

- `src/components/ui/table/data-table-skeleton.tsx`
- `src/features/overview/components/*-skeleton.tsx`
- `src/components/ui/button.tsx`

## Error State Standards

- Use existing route-level `error.tsx` boundaries where available.
- Return actionable copy for recoverable failures.
- Do not expose raw backend or SQL detail in business-facing UI.
- Security denials should remain server-enforced even if the UI also hides the surface.

Reference files:

- `src/app/dashboard/overview/error.tsx`
- `src/app/global-error.tsx`

## Reuse Rules

- Do not create a new CRM design language.
- Do not create a second terminology registry.
- Do not create report-specific filter widgets when shared report filters already fit.
- Do not introduce UI-level permission checks as the only enforcement layer.