resolutionflow/Design/DESIGN-SYSTEM.md

# ResolutionFlow Design System v4

> **Status:** ACTIVE — This document is the single source of truth for all frontend design decisions.
> **Supersedes:** All previous design system docs including `DESIGN_SYSTEM_GUIDE.md`, `UI-DESIGN-SYSTEM.md`, `REBRAND-IMPLEMENTATION-GUIDE.md`, and any `COMPONENT_EXAMPLES.md` files.
> **Last Updated:** March 21, 2026

---

## Design Philosophy

ResolutionFlow uses a **flat, high-contrast dark theme** inspired by Sentry and PostHog. The aesthetic is premium, clean, and minimal — no glass morphism, no backdrop blur, no ambient orbs, no gradient backgrounds on surfaces. The accent color appears in ≤5% of the UI. Every design decision prioritizes **readability over decoration**.

**Light mode** is a planned addition (dark/light toggle). Design all components with CSS variables so theming is a variable swap, not a rewrite.

---

## Color System

All colors are defined as CSS custom properties in `index.css` inside the `@theme` block (Tailwind v4) or `:root` / `.dark` blocks (Tailwind v3).

### Dark Mode (Default)

```
Page background:     #0c0d10
Sidebar background:  #0f1118
Card background:     #14161d
Card hover:          #191c25
Input background:    #191c25
Code background:     #0e1017
Elevated surface:    #1c1f2a

Text primary:        #e2e5eb
Text heading:        #f0f2f5
Text secondary:      #848b9b
Text muted:          #4f5666
Text rail label:     #6b7280

Border default:      #1e2130
Border hover:        #2a2f3d

Accent (cyan):       #22d3ee
Accent hover:        #06b6d4
Accent dim (8-10%):  rgba(34,211,238,0.10)
Accent text:         #67e8f9

Success:             #34d399
Success dim:         rgba(52,211,153,0.10)
Warning:             #fbbf24
Warning dim:         rgba(251,191,36,0.10)
Danger:              #f87171
Danger dim:          rgba(248,113,113,0.10)
```

### Light Mode (Planned)

```
Page background:     #f3f4f7
Sidebar background:  #ffffff
Card background:     #ffffff
Card hover:          #f8f9fb
Input background:    #eef0f4
Code background:     #f5f6f9
Elevated surface:    #e8eaef

Text primary:        #1a1d24
Text heading:        #0d0f13
Text secondary:      #5a6274
Text muted:          #8b92a1

Border default:      #dde0e7
Border hover:        #c5c9d3

Accent:              #0891b2
Accent dim:          rgba(8,145,178,0.07)
Accent text:         #0e7490
```

### What NOT To Use

- No glass morphism (`backdrop-filter: blur`)
- No gradient backgrounds on cards or surfaces
- No ambient orbs or floating glow elements
- No `bg-white/[0.04]` opacity-based backgrounds
- No purple gradient accent (`#818cf8 → #a78bfa`) — this is deprecated
- No `text-gradient-brand` utility — replaced by solid `accent-text` color
- No `glass-card`, `glass-stat`, `glass-card-glow` CSS utilities

---

## Typography

### Font Stack

| Role | Font | Weights | CSS Variable |
|------|------|---------|-------------|
| Body text | IBM Plex Sans | 400, 500, 600, 700 | `--font-sans` / `font-sans` |
| Headings | Bricolage Grotesque | 600, 700, 800 | `--font-heading` / `font-heading` |
| Code / Monospace | JetBrains Mono | 400, 500 | `--font-mono` / `font-mono` |

### Typography Scale

| Element | Size | Weight | Color | Letter Spacing |
|---------|------|--------|-------|---------------|
| Page title (h1) | 22px | 700 (Bricolage) | text-heading | -0.03em |
| Section title | 15px | 600 (Bricolage) | text-heading | normal |
| Card title | 14px | 600 (IBM Plex) | text-heading | normal |
| Body text | 14px | 400 (IBM Plex) | text-primary | normal |
| Secondary text | 13px | 400 (IBM Plex) | text-secondary | normal |
| Label / hint | 12px | 500 (IBM Plex) | text-muted | normal |
| Nav section header | 10px | 600 (IBM Plex) | text-muted | 1.2px, uppercase |
| Rail icon label | 10px | 500 (IBM Plex) | text-rail-label | normal |
| Code | 12px | 400 (JetBrains) | text-primary | normal |
| Stat number | 28px | 700 (Bricolage) | text-heading | -0.03em |
| Badge | 11px | 550 (IBM Plex) | varies | normal |

### What NOT To Use

- No Inter, Plus Jakarta Sans, or Outfit — these are deprecated
- No `font-label` utility — use `font-mono` for monospace or `font-sans` at small size
- No font sizes below 10px

---

## Layout Architecture

### App Shell

The app uses a CSS Grid layout with two states:

**Icon Rail (Default):**
```
[icon-rail: 72px] [main-content: 1fr]
```

**Pinned Sidebar:**
```
[full-sidebar: 260px] [main-content: 1fr]
```

### Icon Rail Sidebar

The default navigation is a narrow icon rail (72px) with:
- Logo mark at top (30px square, gradient background, lightning bolt icon)
- Nav items as vertical column: icon (20px) + label text (10px) underneath
- Dividers between nav sections
- User avatar at bottom
- Pin/expand button below avatar

**Hover behavior:** Hovering a rail item opens a flyout panel (220px) to the right of the rail with sub-navigation items for that section. The flyout stays open while the cursor is on either the rail item or the flyout panel.

**Pinned state:** Clicking the pin button expands to a traditional 260px sidebar with full text labels, section headers, badges, and the active left-bar accent. An unpin button in the header returns to the icon rail.

### Active Nav Indicator

- **Icon rail:** `accent-dim` background on the item, `accent-text` color on icon and label
- **Pinned sidebar:** Same as above, plus a 3px left border (`border-radius: 0 3px 3px 0`) in `accent` color

### Main Content Area

- Padding: 28px top/bottom, 36px left/right
- Max content width: not constrained (fills available space)
- Page title: Bricolage Grotesque, 22px, weight 700

---

## Component Patterns

### Stat Cards

```
Background: bg-card
Border: 1px solid border-default
Border-left: 3px solid [varies by position - accent, success, warning, accent]
Border-radius: 8px
Padding: 18px 16px
```

- Label: 11px, uppercase, 600 weight, text-muted
- Value: 28px, Bricolage Grotesque 700, text-heading
- Delta: 12px, 500 weight, success/danger color with ↑/↓ prefix

### Cards

```
Background: bg-card
Border: 1px solid border-default
Border-radius: 8px
Padding: 20px
Hover: border-color transitions to border-hover
```

No shadows. No gradients. No glow effects.

### Flow List Items

```
Layout: flex row, 12px gap
Padding: 10px 8px
Border-bottom: 1px solid border-default (divider style, not bordered cards)
Hover: bg-card-hover
```

- Icon: 34px square, border-radius 5px, semantic dim background + colored stroke
- Name: 13px, 500 weight, text-heading
- Meta: 11.5px, text-muted
- Badge: right-aligned status badge

### Badges

```
Font: 11px, 550 weight
Padding: 3px 9px
Border-radius: 20px (pill)
```

| Type | Background | Text Color |
|------|-----------|------------|
| Info/Accent | accent-dim | accent-text |
| Success | success-dim | success |
| Warning | warning-dim | warning |
| Danger | danger-dim | danger |

### Form Inputs

```
Background: bg-input
Border: 1px solid border-default
Border-radius: 5px
Padding: 9px 12px
Font: 13px, IBM Plex Sans
Focus: border-color accent, box-shadow 0 0 0 2px accent-dim
Placeholder: text-muted
```

### Buttons

**Primary:**
```
Background: accent (#22d3ee)
Color: #fff
Border: none
Border-radius: 5px
Padding: 9px 16px
Font: 13px, 550 weight
Hover: brightness(1.1)
```

**Ghost:**
```
Background: transparent
Color: text-secondary
Border: 1px solid border-default
Hover: bg-elevated, text-primary, border-hover
```

### Code Blocks

```
Background: bg-code (#0e1017)
Border: 1px solid border-default
Border-radius: 8px
Padding: 18px 20px
Font: JetBrains Mono, 12px, line-height 1.7
```

**Syntax colors (dark mode):**

| Token | Color |
|-------|-------|
| Comment | #4a5568 |
| Keyword | #c792ea |
| Function/Cmdlet | #82aaff |
| String | #c3e88d |
| Variable | #89ddff |
| Parameter | #8c93a4 |
| Number | #f78c6c |

### Chips / Tags

```
Font: 11.5px, 500 weight
Padding: 4px 11px
Border-radius: 20px
Background: accent-dim
Color: accent-text
```

---

## Logo

- **Mark:** 30-32px square, border-radius 8px, `linear-gradient(135deg, #06b6d4, #22d3ee)`, white lightning bolt SVG
- **Wordmark:** "ResolutionFlow" in Bricolage Grotesque, 16-17px, weight 700, text-heading color
- **Combined:** Mark + wordmark horizontally, 10px gap

---

## Spacing System

- Component internal gaps: 6px, 8px, 12px, 14px, 16px
- Card padding: 20px
- Section gaps: 24px between major sections
- Page padding: 28px vertical, 36px horizontal
- Stat grid gap: 12px
- Two-column gap: 16px
- Nav item padding: 8px 10px (pinned), 8px 4px (rail)

---

## Border Radius

| Token | Value | Use |
|-------|-------|-----|
| radius-sm | 5px | Inputs, buttons, small elements |
| radius | 8px | Cards, stat cards, code blocks |
| radius-lg | 12px | Large cards, modals |
| radius-xl | 16px | Hero elements, CTA boxes |
| radius-pill | 100px | Badges, chips, toggle tracks |

---

## Shadows

Minimal to none. No decorative shadows.

- Cards: none (border only)
- Dropdowns/flyouts: `0 4px 12px rgba(0,0,0,0.3)` if needed
- Logo mark: `0 2px 8px rgba(14,165,233,0.25)` (subtle brand glow on logo only)

---

## Icons

All icons use Lucide React (`lucide-react` package).
- Default size: 16-18px
- Stroke width: 1.6-1.8
- Color: `currentColor` (inherits from parent text color)
- Nav icons: 20px at stroke-width 1.6
- Rail icon opacity: 0.6 default, 0.85 on hover, 1.0 when active

---

## Landing Page

The marketing landing page at `/` shares the same color system and typography but has its own layout (no sidebar, full-width sections). Key differences:

- Navigation: fixed top bar with logo, links, and CTAs
- Hero: centered layout with glow effect (radial gradient, accent at 15% opacity)
- Sections: 100px vertical padding, max-width 1120px container
- Section labels: JetBrains Mono, 12px, uppercase, accent-text color
- Section titles: Bricolage Grotesque, clamp(28px, 4vw, 42px), weight 800
- Pricing cards: same card pattern but with featured state (accent border + subtle glow)
- Product mockup: embedded in hero, shows the actual app UI with browser chrome

---

## Files That Define The Design System

These are the source-of-truth files in the codebase:

| File | What It Controls |
|------|-----------------|
| `frontend/src/index.css` | CSS variables, `@theme` block, base styles |
| `frontend/tailwind.config.js` (v3) or inline in index.css (v4) | Color tokens, font families, spacing extensions |
| `frontend/index.html` | Google Font imports |
| `DESIGN-SYSTEM.md` (this file) | Design decisions, component specs, rules |

---

## Deprecated Files — DO NOT Reference

These files contain outdated design information and should be ignored:

- `DESIGN_SYSTEM_GUIDE.md` — Old monochrome glass-morphism system
- `UI-DESIGN-SYSTEM.md` — Old workspace/purple gradient system
- `REBRAND-IMPLEMENTATION-GUIDE.md` — Old purple rebrand from Patherly
- `COMPONENT_EXAMPLES.md` — Old monochrome component patterns
- Any file referencing `glass-card`, `glass-stat`, `bg-gradient-brand`, or `text-gradient-brand`