document the ui

docs/design-system.md

@@ -0,0 +1,90 @@
+# Design System
+
+Everything needed to reproduce the visual look of the SAR Link Portal. The UI is built on **shadcn/ui** (style: `new-york`, base color: `neutral`, icon set: `lucide`) over **Tailwind CSS v4** (CSS-first config — there is no `tailwind.config.ts`; theming lives in `app/globals.css` via `@theme`).
+
+## Brand color
+
+| Token | Value | Use |
+|---|---|---|
+| `--color-sarLinkOrange` / `text-sarLinkOrange` | `#f49b5b` | Primary brand accent — page headings, logo text, highlights, top loader |
+| Pattern orange (dark) | `#e06f10` | Diagonal SVG background pattern (opacity 0.35) |
+| Pattern orange (light) | `#f49b5b` | `.title-bg` SVG background pattern (opacity 0.1) |
+
+The brand orange is used mainly as an **accent on top of a neutral (grayscale) shadcn palette** — it is not the shadcn `--primary`. Primary/secondary/muted etc. remain the default neutral shadcn tokens.
+
+## Theme tokens
+
+Colors use the **oklch** color space, neutral base. Defined as CSS variables in `app/globals.css` under `:root` (light) and `.dark` (dark). Standard shadcn token set:
+
+`--background --foreground --card --card-foreground --popover --popover-foreground --primary --primary-foreground --secondary --secondary-foreground --muted --muted-foreground --accent --accent-foreground --destructive --border --input --ring` plus a sidebar group `--sidebar --sidebar-foreground --sidebar-primary --sidebar-accent --sidebar-border --sidebar-ring`.
+
+Key values:
+- **Light:** `--background: oklch(1 0 0)` (white), `--foreground: oklch(0.145 0 0)` (near-black), `--primary: oklch(0.205 0 0)`.
+- **Dark:** `--background: oklch(0.145 0 0)`, `--foreground: oklch(0.985 0 0)`, `--primary: oklch(0.922 0 0)`.
+- **Radius:** `--radius: 0.625rem`, with `sm/md/lg/xl` derived (`calc(var(--radius) ± n)`).
+- App background (body): `bg-gray-100` light / `bg-black` dark (set in root layout).
+
+Dark mode is class-based (`@custom-variant dark (&:is(.dark *))`) via `next-themes` (`attribute="class"`, default `system`).
+
+## Custom utility classes (in `app/globals.css`)
+
+- **`.title-bg`** — subtle diagonal SVG pattern in brand orange at 0.1 opacity. Used behind page-heading blocks and auth/login cards to give the faint textured background.
+- A second diagonal-line SVG pattern using `#e06f10` at 0.35 opacity.
+
+## Typography
+
+Two Google fonts loaded in `app/layout.tsx` as CSS variables:
+
+| Font | Variable | Weights | Use |
+|---|---|---|---|
+| **Barlow** | `--font-barlow` (also the `font-sans` body font) | 100,300,400,500,600,700,800,900 | Body text, UI, everything by default |
+| **Bokor** | `--font-bokor` | 400 | Display / decorative headings (brand) |
+| mono | `--font-mono` | — | Monospace bits (e.g. "Profile Status" label) |
+
+Body element applies `${barlow.variable} ${bokor.variable} antialiased font-sans`.
+
+## Tailwind plugins in use
+
+`tailwindcss-animate`, `@pyncz/tailwind-mask-image`, `tailwindcss-motion`. Animations also via `motion` (Framer Motion) — used by the welcome banner and some transitions. `TextShimmer` component for shimmer loading states.
+
+## Status color conventions
+
+These recur across badges and table rows (payments, topups, devices, users). Reproduce consistently:
+
+| State | Color | Typical classes |
+|---|---|---|
+| Paid / Verified / Credit / success | green / lime | `bg-green-500 text-white`, `bg-lime-*`, green row tint |
+| Pending / awaiting | yellow | `bg-yellow-500 text-white`, yellow row tint |
+| Failed / Cancelled / Rejected / Debit | red | `bg-red-500 text-white`, `destructive` buttons |
+| Expired | gray | gray row tint / muted |
+| Unknown | yellow | `bg-yellow-500` |
+| Active device (until date) | green accent | brand/green text |
+| Inactive / blocked | red / muted | red text, block dialog |
+
+## Recurring layout patterns
+
+- **Page heading block** — a flex row with a dashed border, `title-bg` background, rounded, `text-sarLinkOrange text-2xl` heading on the left, optional status/action on the right. (See `profile`, most list pages.)
+- **Dual list layout** — every list screen renders an HTML **`<table>` on desktop** and a stack of **cards on mobile** (`MobilePaymentDetails`, `MobileTopupDetails`, `MobileTransactionDetails`, `device-card`), showing the same data. Footer shows `Total N item(s).` and pagination.
+- **Read-only field grid** — labeled read-only values in a responsive grid (`grid-cols-1 sm:grid-cols-2 md:grid-cols-3`), used by profile & user details.
+- **Drawers** (shadcn `drawer`/`vaul`) — device cart, wallet top-up, and filter panels open as bottom/side drawers.
+- **Filter drawer + active-filter chips** — filters applied to URL query params (via `nuqs`), shown as dismissible badges.
+- **Skeletons** — `DevicesTableSkeleton` and per-route `loading.tsx` files provide loading UI; `FullPageLoader` for full-screen spins.
+- **Countdown** — `ExpiryTimeCountdown` shows `Time left: …` with a progress bar for unpaid payments/topups, ticking every second.
+
+## App shell (authenticated)
+
+Rendered by `components/auth/application-layout.tsx`:
+- **Sidebar** (`AppSidebar`) on the left inside `SidebarProvider` — see [navigation.md](./navigation.md).
+- **Sticky header** (`h-16`, `border-b`, `sticky top-0`, `z-10`): left = sidebar trigger + separator; right = **Wallet balance** button, **theme toggle**, **account popover**.
+- **WelcomeBanner** — animated "Welcome, {first} {last}" that auto-hides after 4s.
+- **DeviceCartDrawer** — floating cart (hidden on payment pages).
+- **Main content** — `p-4`, rounded, `bg-background`, wrapped in `NuqsAdapter` for URL state.
+
+## Auth-page shell
+
+`app/(auth)/auth/layout.tsx`: centered full-screen container (`bg-gray-100` light / `bg-black` dark) holding a single card. Login card uses `title-bg` and a `border-2 border-sarLinkOrange/50 rounded-lg shadow`.
+
+## Global chrome
+
+- **NextTopLoader** — top progress bar, color `#f49d1b` (orange), no spinner.
+- **Toaster** (`sonner`, `richColors`) — all success/error toasts.