ten31-database/design/DESIGN.md

# Ten31 CRM — Design contract (DESIGN.md)

*The durable brand brief. Any agent (or person) building or changing user-facing UI reads
this file and `design/tokens.tokens.json` first and conforms to them. Extracted **as-built**
from `frontend/index.html` on 2026-06-18 (document-as-is); this is a faithful record of the
look that grew in the code, not an aspirational redesign. The mobile-first redesign in
`design/BRIEF.md` builds **on top of** this contract — it changes layout/navigation/touch,
not the visual language below.*

## 1. Visual theme

A dense, professional, **dark** venture-CRM workspace (a **light** theme is planned as an
optional toggle — see §8 — but dark is the default and the brand's primary identity) — calm,
data-forward, slightly
"terminal/financial." Cool blue-greys throughout, a single saturated blue as the only vivid
accent, and IBM Plex's engineered-but-humane character. Monospace (IBM Plex Mono) carries
all numbers, dates, and codes, reinforcing the data-tool feel. The mood is *trustworthy
instrument*, not consumer-app playful: restraint, legibility, and information density over
decoration. It is used by a ~5-person fund team handling sensitive LP data, so it should
read as serious and discreet.

## 2. Color palette

Canonical values live in `design/tokens.tokens.json`. Summary:

- **Backgrounds (darkest → lightest):** base `#0b1118` → panel `#111a27` → elevated
  `#152233` → hover `#1b2a3a`. Recessed input/table-header surface: `#0d1622`.
- **Borders:** default `#263548` (the workhorse — borders, dividers, every table grid line),
  strong `#35506a` (hover/emphasis).
- **Text:** primary `#e5edf5`, secondary `#c7d3e0`, muted `#8ea2b7` (most common),
  subtle `#70859b`.
- **Accent (the one brand color):** `#3b82c4`. Hover/gradient-end `#2f6ea9`, tint
  `#3b82c422`, on-tint text `#93c5fd`. Used for primary actions, active nav, links, focus.
- **Semantic:** success `#10b981`, warning `#f59e0b`/`#fcd34d`, due-soon `#e0b341`,
  danger `#dc2626`/`#e06c6c`, error-text `#fca5a5`. Badges render semantic color at low
  alpha for the fill with a lighter tint for the text.

White (`#ffffff`) appears only as text on accent fills and in the brand mark.

- **Pipeline-stage chips (redesign)** reuse existing semantic tints — no new hues: lead =
  subtle grey, engaged = accent blue, diligence = due-soon `#e0b341`, commitment = success
  `#10b981`/`#6ee7b7`. **Staleness** (last-contact age) overlays the same ramp: fresh grey →
  due-soon amber `#e0b341` → danger-soft red `#e06c6c`/`#f87171`. Both are tinted-fill + tinted-
  text badges, consistent with the badge rule above.
- **Light theme (planned)** mirrors every slot above in `tokens.tokens.json` `color.light` (e.g.
  base `#eaeef3`, panel `#ffffff`, text-primary `#16202c`); accent `#3b82c4` is unchanged. Dark is
  the default — see §8.

## 3. Typography

- **Families:** `IBM Plex Sans` (UI/body), `IBM Plex Mono` (numbers, dates, badges, logs,
  nav icons). Loaded from Google Fonts; weights 400/500/600/700 sans, 500/600 mono.
- **Scale (as-built):** 11px micro/table-header/badge · 12px help/meta · **13px body / table
  / inputs (desktop base)** · 14px nav · 16px section title · 18px modal title · 20px page
  title · 24px login title & KPI value.
- **Treatments:** global letter-spacing `0.01em`; table headers uppercase with `0.08em`
  tracking; badges uppercase `0.5px`; numbers use `font-variant-numeric: tabular-nums`.
- **Mobile scale (redesign, sourced from the 2026-06-19 comps):** body/inputs/list rows
  **15px** (up from desktop's 13px); card investor name 16/600; mono amounts 15/600; screen
  title 21/600 (vs desktop 20); full-screen detail title 22/600; sheet title 18/600; section
  labels mono-uppercase 11/600 `0.08em`; chips mono-uppercase 10–11/600; meta/last-contact
  mono 12; bottom-tab label mono 10. Inputs are 44–46px tall for touch. The mono-for-numbers
  and uppercase-tracked-badge rules are unchanged — only the base size grows.

## 4. Component styling

- **Buttons:** primary = top-to-bottom gradient `#3b82c4 → #2f6ea9`, white text, radius 6px,
  padding 10×16, lift on hover (`translateY(-1px)` + soft blue shadow). Secondary = flat
  `#1b2837`. Danger = `#dc2626`.
- **Cards / sections:** panel `#111a27`, 1px `#263548` border, radius 8px, padding 16–20px,
  composite drop shadow + inset top highlight. Hover lifts 1px and strengthens the border.
- **Tables:** recessed header `#0d1622`, uppercase muted 11px headers, sticky header +
  sticky first column, 1px grid lines, row hover `#172435`, sticky aggregate footer.
- **Forms:** inputs on `#0d1622`, 1px border, radius 6px, accent focus ring; label 13/500,
  help 12px muted, error 12px `#fca5a5`.
- **Badges:** radius 4px, 11px/600 uppercase, low-alpha semantic fill + tinted text.
- **Overlays:** modal (centered, radius 12, max-width 500, blurred backdrop) and slide-over
  (right drawer, 400px) for detail/edit.
- **Other:** kanban cards (radius 6), toasts (bottom-right), accent spinner, shimmer
  skeletons, left-marker timeline for activity feeds.

**Mobile component states (redesign, from the 2026-06-19 comps — see §8 and `_imports/`):**
- **Bottom tab bar:** exactly four tabs (Grid · Pipeline · Reminders · Contacts), 56px tall,
  border-top, translucent panel bg + `backdrop-filter: blur(8px)`, `padding-bottom` for
  `env(safe-area-inset-bottom)`. Active tab = accent (icon + 10px mono label); inactive =
  subtle. 20px line-icons.
- **Bottom sheet** (replaces the centered modal + right slide-over on mobile): panel bg,
  strong top border, **radius-20 top corners**, 38×4 grey drag handle, slide-up
  (`translateY(100%)→0`, 280ms `cubic-bezier(.2,.8,.2,1)`), scrim `rgba(4,9,16,0.55)` fade-in,
  max-height ~88–90%, scroll-body; tap-scrim or × to dismiss. One field/action per sheet.
- **Mobile card** (the table→card transform): panel, 1px border, **radius-10**, card shadow,
  12–14px padding; name 16/600 + Priority corner badge (top-right); mono amount + stage chip +
  staleness last-contact. Existing-LP = quiet accent **corner earmark** (star is the lighter
  alternative; not a per-card banner).
- **Full-screen detail** (promotes the desktop slide-over): `screenIn` slide (translateX 14px,
  200ms), "‹ Grid" back affordance, grouped read-only sections with per-field edit entry points.
- **Swipe actions** (Reminders): pointer-drag a card to reveal complete (swipe-left) / snooze
  (swipe-right) at a 70px threshold; the action color tints in under the card.
- **Snap-scroll stages** (Pipeline): full-width stage columns, `scroll-snap-type: x mandatory`,
  a segmented stage control + page dots; per-card `‹ / ›` stage move.
- **Account control:** a top-bar avatar opening a small popover (profile + logout) — the only
  non-tab navigation on mobile.
- **Toast:** mobile position is bottom-center **above the tab bar** (not bottom-right).

## 5. Layout

Desktop shell = **fixed 250px left sidebar + flexible main content** with a top header bar
(page title + user). Content max-width 1400px, padding 20px. Primary content patterns:
wide data table (Fundraising Grid), KPI grid + timelines (Dashboard), kanban columns
(Pipeline), list + detail drawer (Contacts/Reminders), two-column (Thesis). Auto-fit grids
are used for KPI cards (`minmax(180px,1fr)`) and kanban columns (`minmax(300px,1fr)`).

## 6. Depth / elevation

Elevation is built from three stacked cues, not just one shadow: (a) a **layered radial-
gradient page background** (two soft blue glows top-left and top-right over `#0b1118`),
(b) panel-color steps (base → panel → elevated), and (c) composite drop shadows with a
1px inset white top-highlight (`inset 0 1px 0 #ffffff07-08`) that gives panels a faint lit
edge. Hover states lift elements 1px and deepen the shadow. Keep this restrained, cool, and
low-contrast — depth should be felt, not seen.

## 7. Do's and don'ts

- **Do** keep `#3b82c4` as the only vivid accent; everything else stays in the blue-grey
  range. **Don't** introduce a second bright hue for emphasis — use weight, tint, or the
  semantic colors.
- **Do** use IBM Plex Mono for every number/date/code. **Don't** set tabular data in the
  sans face.
- **Do** reach for tinted-fill + tinted-text badges for status. **Don't** use solid
  saturated fills for status chips.
- **Do** keep borders at `#263548` and lean on them for structure (this is a grid-lined,
  bordered aesthetic). **Don't** switch to borderless/shadow-only cards.
- **Do** preserve the restrained 1px hover-lift motion. **Don't** add bouncy or long
  animations (and honor `prefers-reduced-motion`, already wired).

## 8. Responsive behavior

**Current (as-built): desktop-first.** Breakpoints are `max-width` (900px, 768px); the
sidebar simply `display:none`s below 768px with no real mobile navigation; wide tables
overflow horizontally; the 400px slide-over overflows a 375px screen. A correct viewport
meta tag is present.

**Target: mobile-first, mobile-preferred.** The design landed via a Claude Design round-trip
(2026-06-19; source + per-surface interaction model in `design/_imports/2026-06-19/`, input
brief in `design/BRIEF.md`). The system:

- **Author base = a 375px column, enhance up** with `min-width` breakpoints for tablet/desktop
  (inverting today's `max-width` rules). **Prerequisite:** responsive layout must live in the
  CSS `<style>` block / utility classes — the ~1,300 inline `style={{}}` objects can't respond
  to media queries, so an **inline-style→CSS migration** gates this work (tracked in `ROADMAP.md`).
- **Mobile is a focused subset, not the whole app:** only **four surfaces** ship on mobile —
  **Fundraising Grid · Pipeline · Reminders · Contacts** — in a **bottom tab bar**; every other
  screen (Dashboard, Thesis, Outreach, Settings, …) is desktop-only and absent, with just a
  minimal top-bar account/logout control.
- **Navigation:** the 250px sidebar → a safe-area-aware **bottom tab bar of four**. No "More"
  menu.
- **Transforms:** wide data table → **investor card list + full-screen detail**; Pipeline kanban
  → **swipe-between-stages** (snap-scroll, segmented control, per-card stage move); centered
  modal + 400px slide-over → **drag-to-dismiss bottom sheets** / full-screen detail; Grid saved
  *views* → a tappable view-name opening a **bottom-sheet view picker**.
- **Editing on mobile** is the on-the-go core only — investor name, contact pills, notes/comm
  log, pipeline stage, reminders, and new-investor create (via the Grid, the canonical write
  path). Commitments/amounts and the full column set stay **read-only / desktop-only**. (Write
  paths use the targeted one-row `log-communication` endpoint + the pipeline link→stage flow,
  **not** whole-grid saves — see `BRIEF.md` §3a "Backend reality.")
- **Touch + safe areas:** 44px minimum primary touch targets; body type bumped 13→15px (§3);
  sticky bottom nav respects `env(safe-area-inset-bottom)` and content gets bottom padding so
  the nav never overlaps it.
- **Light theme — planned (adopted 2026-06-19).** Ship the light palette (`tokens.tokens.json`
  `color.light`) behind a `[data-theme]` switch + a top-bar toggle. **Dark stays the default and
  the brand's primary identity;** light is the optional alternative. It co-lands with the
  inline-style→CSS migration (theming needs CSS custom properties, not per-element inline values).
  Full per-component light tints (stage/staleness/note badges) are in `_imports/2026-06-19/`.

The gap between this section and the current `index.html` is the implementation backlog in
`ROADMAP.md` (incl. the inline-style→CSS migration and the locked pipeline-stages/flags spec).

## 9. Agent prompt guide

When building or changing UI here:
- Pull every color, size, radius, and space value from `design/tokens.tokens.json` — do not
  hand-pick new hexes. The app still inlines many values; prefer the `:root` CSS variables
  (and grow that set) over fresh literals.
- Match the established components above; if you need a new one, compose it from existing
  tokens and the bordered-panel + tinted-badge idiom rather than inventing a new visual style.
- Numbers/dates/codes → IBM Plex Mono + tabular-nums. Status → tinted badge. Primary action →
  the blue gradient button. Destructive → `#dc2626` and a confirm step.
- **Building anything mobile/responsive?** Read `design/BRIEF.md` first — it holds the
  mobile-first layout, navigation, and interaction decisions this section will eventually
  absorb.
- Reminder: inline `style={{}}` objects cannot respond to media queries — put any
  responsive layout in the CSS `<style>` block (or a utility class), not inline.