shoc-frontend-new/docs/DESIGN_SYSTEM.md

# SeaHaven Design System

Visual foundation for **seaheven.front**, aligned with [seahaven.desing](https://github.com) tokens and IrisLoan.Admin integration patterns (centralized CSS, `@theme inline`, `cn()`).

## Stack

- **MUI-only** — no Radix/shadcn; MUI is the sole component library
- **Tailwind v4** — semantic utility classes from CSS tokens
- **Fonts** — Montserrat (headings), DM Sans (body), JetBrains Mono (code) via `@fontsource`

## Token source of truth

| File                        | Purpose                                                      |
| --------------------------- | ------------------------------------------------------------ |
| `src/styles/theme.css`      | All `:root` CSS variables + `@theme inline` Tailwind aliases |
| `src/styles/fonts.css`      | `@fontsource` imports                                        |
| `src/styles/typography.css` | Base `html`, `body`, `h1–h6`, `.text-caption`, `.text-label` |
| `src/styles/motion.css`     | `--duration-fast`, `--duration-normal`, `--ease-default`     |
| `src/styles/globals.css`    | Entry: imports all above + `@custom-variant dark`            |

## Key tokens

### Brand & surfaces

| Token                | Value     | Usage                      |
| -------------------- | --------- | -------------------------- |
| `--primary`          | `#1c75bc` | Buttons, links, focus ring |
| `--primary-hover`    | `#155a92` | Hover states               |
| `--foreground`       | `#262262` | Primary text               |
| `--background`       | `#ffffff` | Cards, inputs              |
| `--color-bg-page`    | `#f9fafb` | Page background            |
| `--border`           | `#dfe3ea` | Dividers, outlines         |
| `--muted-foreground` | `#58595b` | Secondary text             |

### Layout

| Token                         | Value   |
| ----------------------------- | ------- |
| `--spacing-sidebar`           | `220px` |
| `--spacing-sidebar-collapsed` | `56px`  |
| `--spacing-topbar`            | `64px`  |

### Typography scale

| Token            | Size |
| ---------------- | ---- |
| `--text-xs`      | 11px |
| `--text-sm`      | 12px |
| `--text-base-sm` | 13px |
| `--text-base`    | 14px |
| `--text-md`      | 16px |
| `--text-lg`      | 18px |
| `--text-xl`      | 22px |
| `--text-2xl`     | 28px |

### Elevation

| Token         | Usage               |
| ------------- | ------------------- |
| `--shadow-sm` | Cards, subtle depth |
| `--shadow-md` | Dropdowns, panels   |
| `--shadow-lg` | Dialogs, modals     |

### Work order badges (immutable)

Type, status, and completion-doc tokens (`--type-*`, `--status-*`, `--doc-*`) must not be changed — see `src/components/domain/`.

## Typography hierarchy

| Element         | Font       | Weight | Size           |
| --------------- | ---------- | ------ | -------------- |
| `h1`            | Montserrat | 800    | 28px           |
| `h2`            | Montserrat | 700    | 22px           |
| `h3`            | Montserrat | 600    | 18px           |
| `h4–h6`         | Montserrat | 600    | 16–13px        |
| Body            | DM Sans    | 400    | 14px           |
| `.text-caption` | DM Sans    | 400    | 12px           |
| `.text-label`   | DM Sans    | 600    | 11px uppercase |

MUI typography variants in `src/lib/theme/mui-theme.ts` mirror this hierarchy.

## MUI + Tailwind usage

### Prefer themed MUI in forms and data tables

MUI components inherit Seahaven styling via `mui-theme.ts` overrides (`Button`, `TextField`, `Table`, `Chip`, `Paper`, `Dialog`, `Alert`).

### Prefer semantic Tailwind in layout shells

```tsx
<div className="bg-background text-foreground border-border" />
<div className="text-muted-foreground" />
<div className="bg-primary text-primary-foreground" />
```

### Compose classes with `cn()`

```tsx
import { cn } from "@/lib/utils";

<div className={cn("flex gap-2", isActive && "bg-sidebar-accent")} />;
```

### Shared UI wrappers

| Component    | Path                            | Pattern                      |
| ------------ | ------------------------------- | ---------------------------- |
| `Button`     | `components/ui/button.tsx`      | MUI Button + variant presets |
| `Badge`      | `components/ui/badge.tsx`       | MUI Chip                     |
| `PageHeader` | `components/ui/page-header.tsx` | PATTERN_001                  |
| `EmptyState` | `components/ui/empty-state.tsx` | PATTERN_003                  |
| `FormField`  | `components/ui/form-field.tsx`  | PATTERN_004                  |

### Domain badges

| Component                              | Path                                 |
| -------------------------------------- | ------------------------------------ |
| `TypeBadge`                            | `components/domain/type-badge.tsx`   |
| `StatusBadge` / `WorkOrderStatusBadge` | `components/domain/status-badge.tsx` |
| `DocBadge`                             | `components/domain/doc-badge.tsx`    |

## Legacy → Seahaven mapping

| Legacy                    | Seahaven                       | Consumption                      |
| ------------------------- | ------------------------------ | -------------------------------- |
| `#0c4f6f` / `--blue-main` | `--primary` (`#1c75bc`)        | MUI `primary.main`, `bg-primary` |
| `#083a52` / `--blue-dark` | `--primary-hover`              | Button hover                     |
| `#f4f6f7` / `--bg`        | `--color-bg-page`              | Body, page shell                 |
| `#d9dde0` / `--border`    | `--border`                     | Dividers, inputs                 |
| `#fbfbfb` sidebar         | `--color-sidebar-bg`           | App sidebar                      |
| Segoe UI 13px             | DM Sans 14px                   | Body typography                  |
| Bootstrap calendar colors | `--primary`, `--success`, etc. | `calendar-utils.ts`              |
| `#1a3a5c` login header    | `--color-header-bg-start`      | Login branding strip             |

## Dark mode

`@custom-variant dark (&:is(.dark *))` is configured in `globals.css`. Full dark token set is a future enhancement; light mode is the current default.