## Portal UI Design System (Frontend)

This project uses **Tailwind CSS v4** with a **token-based theme** so pages look cohesive and remain easy to maintain.

### Principles

- **Use semantic tokens** instead of raw colors (`bg-card`, `text-foreground`, `border-border`, `text-muted-foreground`, `ring-ring`).
- **Use shared shells and templates**:
  - Public pages: `PublicShell` via `apps/portal/src/app/(public)/layout.tsx`
  - Authenticated pages: `AppShell` via `apps/portal/src/app/(authenticated)/layout.tsx`
  - Authenticated page content: `PageLayout` for titles/breadcrumbs/loading/error
- **Prefer shared primitives** (`Button`, `AlertBanner`, `ErrorState`, `Loading*`, `SubCard`) over ad-hoc markup.
- **Keep motion subtle** (shadow/color transitions; avoid big gradients/translate/scale).

### Quick reference: what to use

- **Page wrapper**: `PageLayout`
  - Use `loading`, `error`, `onRetry`, and `breadcrumbs` for consistent states.
- **Surfaces**
  - Use `bg-card border-border shadow-[var(--cp-shadow-1)]` for panels.
  - Use `.cp-card` for simple card surfaces when you don’t need a component.
- **Typography**
  - Titles: `text-foreground`
  - Secondary text: `text-muted-foreground`
- **Inputs**
  - Use `Input` / `FormField` to get correct borders/focus/invalid states.
- **Buttons**
  - Use `Button` variants (`default`, `outline`, `secondary`, `ghost`, `link`).
- **Status/feedback**
  - Use `AlertBanner` (`success|info|warning|error`) and `StatusPill`.

### Token sources

- Global semantic colors: `apps/portal/src/app/globals.css`
- Portal-specific tokens/spacing/shadows: `apps/portal/src/styles/tokens.css`
- Semantic utility classes: `apps/portal/src/styles/utilities.css`