mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-09-30 23:13:12 +00:00
042b9db2ac
* fix: correct Sea Haven branding in page title and wordmark * chore: use correct company name in docs and comments * docs: rewrite README * docs: add README badge block per github-standards * fix: update command syntax in deployment instructions * fix: replace template PWA icons and manifest branding * test: assert PWA manifest branding
137 lines
6 KiB
Markdown
137 lines
6 KiB
Markdown
# Sea Haven 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 Sea Haven 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 → Sea Haven mapping
|
||
|
||
| Legacy | Sea Haven | 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.
|