KOUM —

01 · Mandate & principles

MANDATE
  Mario: previous design supervision dismissed.
  Elena: directs voice, copy, hierarchy.
  Claude Dev: owns UI, UX, components, motion, perf, a11y.
  Final call: Mario.

PRINCIPLES (the brief, in five lines)
  simple        every screen explains itself in 3 seconds
  addictive     keyboard-first, fast feedback, "one more action"
  intelligent   the platform already knew the answer
  fast          p95 < 400ms, no jank, offline-first
  protected     security visible — operators trust what they can see

02 · Design tokens

/* color */
--bg-0:        #000000   /* page  */
--bg-1:        #0A0A0A   /* surface */
--bg-2:        #0E0E0E   /* card */
--bg-3:        #161616   /* hover */
--line:        #1F1F1F   /* hairline */
--line-2:      #2A2A2A   /* divider */

--fg-0:        #F9F7F4   /* primary text */
--fg-1:        #D4D4D4   /* body */
--fg-2:        #888888   /* muted */
--fg-3:        #555555   /* whisper */

--ember:       #D4874A   /* primary accent — the cursor */
--ember-2:     #B87333   /* hover */
--ember-soft:  #D4874A22 /* tints, badges */

--ok:          #15803D
--warn:        #D4874A
--err:         #EF4444
--info:        #5BB7DB

/* role tints (badge-only, never page chrome) */
--shipper:     #D97706
--carrier:     #15803D
--broker:      #1E40AF
--dispatcher:  #0369A1

/* spacing — 4pt grid */
--s-1: 4px   --s-2: 8px   --s-3: 12px   --s-4: 16px
--s-5: 24px  --s-6: 32px  --s-7: 48px   --s-8: 64px

/* radius — terminals don't round much */
--r-0: 0    /* default for terminal blocks */
--r-1: 4px  /* buttons, inputs */
--r-2: 8px  /* dialog, dropdown */
--r-pill: 999px

/* shadow — almost none. depth = borders, not blur */
--shadow-0: none
--shadow-1: 0 0 0 1px var(--line) inset

/* motion */
--ease:      cubic-bezier(.2,.7,.2,1)
--dur-1:     90ms   /* hover */
--dur-2:     180ms  /* state change */
--dur-3:     320ms  /* page transition */

03 · Type system

STACK
  display:  Fraunces 300       (italic O, headlines, hero numbers)
  ui:       JetBrains Mono     (the room temperature — most of the UI)
  body:     DM Sans            (paragraphs > 3 lines only)

WHY MONO-FIRST
  Terminal operators read fixed-width all day. Numbers align.
  Tables don't dance. The product feels like a tool, not a brochure.

SCALE  (rem on a 16px root)
  display-xl   4.5rem   Fraunces 300   -0.025em   line 1.05
  display      3.0rem   Fraunces 300   -0.020em   line 1.10
  h1           2.0rem   Fraunces 300   -0.015em   line 1.15
  h2           1.5rem   Fraunces 300   -0.010em   line 1.20
  h3           1.125rem JetBrains 600  +0.000em   line 1.30
  body-lg      0.9375rem  DM Sans       0          line 1.6
  body         0.8125rem  JetBrains 400 0          line 1.7   (default)
  body-sm      0.75rem    JetBrains 400 0          line 1.6
  caps         0.6875rem  JetBrains 600 +0.15em    UPPERCASE
  cmd          0.8125rem  JetBrains 500 0          (`$ ` prefix in ember)

RULES
  - body copy never exceeds 72ch
  - caps used as section labels only — never as buttons or paragraphs
  - Fraunces appears only on display, h1, h2 — never below 1.5rem
  - the italic O of KOUM is a brand asset; never restyle it

04 · Component primitives

LIBRARY                              owner            file
  <Wordmark/>                        Claude Dev       components/ui/wordmark.tsx
  <StatusBar/>                       Claude Dev       components/ui/status-bar.tsx
  <Cmd>$ ...</Cmd>                   Claude Dev       components/ui/cmd.tsx
  <Card/> <Card.Header/>             Claude Dev       components/ui/card.tsx
  <KV/> (key/value row)              Claude Dev       components/ui/kv.tsx
  <Pill tone=...>                    Claude Dev       components/ui/pill.tsx
  <Button variant=...>               Claude Dev       components/ui/button.tsx
  <Input/> <Field/>                  Claude Dev       components/ui/input.tsx
  <Select/>                          Claude Dev       components/ui/select.tsx
  <Table/> (mono, dense)             Claude Dev       components/ui/table.tsx
  <Sparkbar/>                        Claude Dev       components/ui/sparkbar.tsx
  <Toast/>                           Claude Dev       components/ui/toast.tsx
  <Dialog/>                          Claude Dev       components/ui/dialog.tsx
  <Tabs/>                            Claude Dev       components/ui/tabs.tsx
  <Empty/>                           Claude Dev       components/ui/empty.tsx
  <Cursor/>  (blinking)              Claude Dev       components/ui/cursor.tsx
  <Kbd>K</Kbd> (keyboard hint)       Claude Dev       components/ui/kbd.tsx
  <CommandPalette/>  ⌘K              Claude Dev       components/cmdk/

PATTERNS
  buttons       solid (ember on black) | ghost (border) | quiet (text)
  inputs        no inner shadow, 1px border, focus = 2px ember outline
  tables        no zebra stripes; use 1px row dividers
  cards         radius 0 by default, 4px when nested in a soft surface
  badges        caps + 1px border + tonal bg (8% opacity of accent)
  loaders       blinking cursor + ascii spinner (not spinner gif)
  empty states  ascii art + one cmd ("$ koum invite")

# example tokens in use — copy/paste-ready
.btn {
  font: 500 13px/1 "JetBrains Mono", monospace;
  letter-spacing: 0.02em;
  padding: 10px 18px;
  border-radius: var(--r-1);
  background: var(--ember);
  color: var(--bg-0);
  transition: background var(--dur-1) var(--ease);
}
.btn:hover { background: var(--ember-2); }
.btn:focus-visible {
  outline: 2px solid var(--ember);
  outline-offset: 2px;
}

05 · Layout — the chrome every page wears

PAGE FRAME
  ┌──────────────────────────────────────────────────────────┐
  │ ●  koum.africa  ·  /loads  ·  session 0x4f2a    08:32EAT │  ← StatusBar (sticky)
  ├──────────────────────────────────────────────────────────┤
  │ $ koum --route /loads                                     │  ← Cmd line (route as command)
  │ // breadcrumb / context                                   │
  │                                                           │
  │  <h1 in Fraunces>                                         │
  │                                                           │
  │  [content — never exceeds 1080px]                         │
  │                                                           │
  ├──────────────────────────────────────────────────────────┤
  │  ⌘K open · ? help · esc back     v3.2.1 · status: green   │  ← FooterBar
  └──────────────────────────────────────────────────────────┘

GRID
  default: single column, max-width 1080px, 24px gutters
  data-heavy: 1440px, 16px gutters, density preset "compact"

NAVIGATION
  no sidebar by default. command palette ⌘K is the nav.
  primary actions exposed as <Cmd> rows on the page.
  user menu: top-right, opens as a terminal block.

06 · Motion & micro-interaction

PRINCIPLE
  motion is feedback, not decoration. nothing animates that
  doesn't confirm an action or carry continuity between states.

THE EIGHT BLESSED ANIMATIONS
  1.  cursor blink         12fr opacity 0↔1, 1.0s, infinite
  2.  cmd-prefix flash     $ tints to ember on submit, 90ms
  3.  status pulse         green dot scales 1↔1.15, 1.6s, infinite
  4.  row hover            bg shifts bg-2→bg-3, 90ms
  5.  press                scale 1→0.985, 60ms in / 120ms out
  6.  toast slide          y 8px→0, opacity 0→1, 180ms ease-out
  7.  page transition      opacity 0→1, 200ms (no slide, no fade-out)
  8.  type-in (hero only)  hero number counts up 600ms, ease-out

DISALLOWED
  - parallax
  - bouncing eases (cubic.in.out)
  - hover scaling above 1.02
  - blurring backdrops on hover
  - any animation > 320ms

07 · Accessibility & performance

A11Y FLOOR (non-negotiable)
  - contrast: body text ≥ 7:1 against bg; hairlines ≥ 3:1
  - every interactive element reachable via Tab in source order
  - focus-visible ring is ember 2px + 2px offset (never removed)
  - mono-first design must keep dyslexia path: body opt-in to DM Sans via
    user setting "Reading mode"
  - prefers-reduced-motion disables all 8 motions except cursor blink
  - keyboard map: ⌘K palette, / focus search, j/k row nav, esc back
  - aria-live for command palette results & toasts

PERF FLOOR
  Lighthouse                Performance ≥ 95   A11y ≥ 95
  TBT                       < 150ms
  LCP                       < 1.6s on 4G
  CLS                       0.00 (mono grid is forgiving)
  Bundle (route /loads)     < 90KB JS gzipped
  Cold edge fn              < 350ms p95
  Streaming                 every page that fetches uses RSC streaming

08 · Security signal in the UI

VISIBLE SIGNAL
  StatusBar shows session id (last 4 of token hash) — copy on click
  every form: lock glyph + "encrypted to ${origin}" in caps
  payments: a "verifying chain" terminal stream replaces spinner
  audit log accessible from any screen via ⌘K → "audit"

INVISIBLE FLOOR
  CSP strict-dynamic, no inline scripts (the page above uses inline
    style only — those will move to CSS modules during migration)
  Trusted Types on for innerHTML sinks
  Cookie: __Host- prefix, SameSite=Lax, Secure, HttpOnly
  Supabase RLS sealed (already done — see vault/decisions/)
  PKCE auth flow stays — no change needed

09 · Page-by-page migration

MARKETING  app/(marketing)/
  /                  → Sample 03 hero verbatim. Hero number = live "loads.active".
  /pricing           → Three terminal blocks side-by-side, $ koum --tier comparisons.
  /for-carriers      → "// for the driver" — keyboard-styled FAQ rows.
  /fleet-partner     → KV table (their pain → our cmd that solves it).
  /join              → single email field + cursor; submit = type-in confirmation.
  /about             → Manifesto block, Isaiah 46:4 in italic Fraunces.
  /legal             → mono prose, no decoration; page is the protection.
  /flyers            → printable terminal sheet. Same chrome, white-on-black optional.
  /kenya             → corridor-specific landing — replace with template + locale prop.

AUTH  app/(auth)/
  /login             → 2-field block. Cursor in the active field. "$ koum --auth ..."
  /login/callback    → terminal stream of auth steps; "● verifying" dots.

APP  app/(app)/
  /dashboard         → 6-tile metric grid (matches Sample 03). Role-aware.
  /loads             → mono table, j/k row nav, ? for shortcuts overlay.
  /dispatch          → split pane (loads | candidates). ⌘↵ to assign.
  /tracking          → ascii route + live KV (ETA, distance, fuel).
  /bids              → row table; bid = $ keystroke + amount field.
  /bookings          → grouped by status; status = pill tone.
  /clients           → contact cards as terminal blocks.
  /fleet             → vehicle table; row expand reveals nested KV.
  /corridors         → 4 sparkbars, one per active corridor.
  /backhaul          → load matcher; cmd palette returns matches.
  /commissions       → ledger view — append-only mono table.
  /credit            → score in Fraunces 4.5rem; reasons as KV rows.
  /earnings          → same ledger pattern; export as .csv via $ koum export.
  /insurance         → policy blocks; claim = inline form.
  /invite            → single field; success = ascii confetti (allowed).
  /onboarding        → 5 steps as numbered Cmd rows; progress as │█│ bar.
  /documents         → file list, mono, with hash digest.
  /analytics         → density preset "compact"; data-dense pattern.
  /academy           → lesson list as $ ls; lesson = mono prose.
  /settings          → grouped Cmd rows. Toggles = [x]/[ ].
  /developer         → API keys, webhooks; matches the platform's own voice.

OTHER  app/
  /apex              → already a chess board. Re-skin: pieces become typographic
                       glyphs (♜♞♝♛♚) on terminal grid.
  /dev               → already terminal-leaning; promote it as the canonical pattern.
  /diagnostics       → keep current (already mono-led); harmonize tokens.
  /design-samples    → preserve as gallery. Move to /design/samples.
  /design-plan       → this page. Move to /design under final IA.
  /api/*             → no UI; no change.

10 · Migration sequence

P0  TOKENIZE & WIRE              [ 1 day  ]
    └─ rewrite app/globals.css with new vars
    └─ extend tailwind.config.ts theme.colors / fontFamily / spacing
    └─ delete legacy Tailwind hex usages (codemod: hex → var)
    └─ ship behind feature flag NEXT_PUBLIC_DESIGN=tk

P1  PRIMITIVES                   [ 2 days ]
    └─ build the 17 components in components/ui/
    └─ Storybook-style harness at /design/components
    └─ unit-snapshot every component

P2  CHROME                       [ 1 day  ]
    └─ <StatusBar/>, <FooterBar/>, layout shell
    └─ command palette ⌘K + keyboard map
    └─ apply to root app/layout.tsx behind flag

P3  AUTH                         [ 1 day  ]
    └─ /login, /signup, /callback refit
    └─ visible security signal + cursor

P4  DASHBOARD + 4 ROLES          [ 2 days ]
    └─ /dashboard role-aware
    └─ /loads, /dispatch, /tracking, /bookings (the daily five)

P5  LONG TAIL                    [ 3 days ]
    └─ remaining 22 (app) routes in dependency order
    └─ marketing pages
    └─ apex, settings, developer

P6  POLISH                       [ 1 day  ]
    └─ a11y audit (axe + manual)
    └─ Lighthouse pass on /, /login, /dashboard, /loads
    └─ remove flag, delete old design

TOTAL                            ≈ 11 working days
PARALLELIZABLE                   P1 (components) || P5 (page refits) safely

11 · Risks & rollback

R-01  mono-first hurts paragraph readability         mitigation: opt-in DM Sans body
R-02  4 role color systems clash with terminal      mitigation: role tones become badges only
R-03  motion-reduced users see 100% static UI       mitigation: keep cursor blink (essential signal)
R-04  bundle size regression from cmdk lib          mitigation: lazy import; budget enforced in CI
R-05  Lusion-style stakeholders push back           mitigation: not relevant — supervision dismissed
R-06  Supabase auth callback FOUC                   mitigation: streaming SSR + skeleton block
R-07  partial refit in prod looks inconsistent      mitigation: feature flag is per-route, not partial
R-08  developer route already different             mitigation: it becomes the reference, not the outlier

ROLLBACK
  feature flag NEXT_PUBLIC_DESIGN=legacy on Vercel env → instant revert.
  no schema changes. no API changes. zero data risk.

12 · Acceptance gates