shoc-frontend-new/docs/DESIGN_SYSTEM.md

SeaHaven Design System

Visual foundation for seaheven.front, aligned with seahaven.desing 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

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

Compose classes with cn()

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.