# ADR 0003 — Adopt the SHOC design system and UI/UX layout

- **Status:** Accepted (2026-07-13)
- **Decision owner:** Adam Moussa
- **Scope:** `web/` theming, layout shell, and all future proposal-system UI work

## Context

Three design-token sets existed across Sea Haven web apps as of 2026-07-13:

1. **Old canon** — Nunito, primary `#0c4f6f`, 220px sidebar, `#f4f6f7` background
   (what SHOC's stale `docs/DESIGN_SYSTEM.md` still describes).
2. **SHOC dev's new system** (shoc-frontend-new PR #17) — Montserrat (display) /
   DM Sans (body) / JetBrains Mono, primary `#1c75bc`, navy `#262262`, page background
   `#f9fafb`, 244px sidebar (76px collapsed), 64px gradient topbar
   (`#1b1f52 → #1c4f8f → #1c75bc`), defined in a single CSS-variable token file
   (`src/styles/theme.css`) consumed by both MUI (`getCssVar` → `createTheme`) and
   Tailwind v4.
3. **proposal-system's "Sea Haven Ops" theme** — Inter, accent `#2563EB`,
   navy-900 AppBar, 216px drawer (`web/src/theme.ts`).

## Decision

**SHOC dev's new design system and UI/UX layout (set 2) is the canonical Sea Haven
standard.** proposal-system adopts it fully:

- **Tokens:** mirror shoc-frontend-new dev's `theme.css` values and structure
  (fonts, palette, radii, spacing, shadows).
- **Mechanism:** single CSS-variable token file is the one source of truth;
  `web/src/theme.ts` becomes a thin `getCssVar` → MUI `createTheme` adapter matching
  SHOC's `mui-theme.ts`. Token changes are values-only edits, never theme rewrites.
- **Layout shell:** SHOC's admin shell dimensions and treatment — 244px/76px-collapse
  sidebar, 64px gradient topbar, avatar initials.
- **Component library:** MUI only. Tailwind (SHOC runs a MUI + Tailwind v4 hybrid off
  the same CSS variables) is **not** adopted here pre-consolidation; the shared
  CSS-variable source keeps that door open.

The reference is shoc-frontend-new's **`dev` branch** at adoption time; subsequent
SHOC token changes should be ported as values-only updates.

## Consequences

- The "Sea Haven Ops" theme (Inter/#2563EB) is retired; alignment plan Phase 2
  implements the port.
- Visual verification for Phase 2 compares proposal-system screens side-by-side with
  SHOC dev screens, not with the old canon.
- The superseded Nunito/`#0c4f6f` tokens must not be reintroduced anywhere.
- At monorepo consolidation, both frontends already share token structure, so a
  single `theme.css` can serve both.