# ResolutionFlow Design System v5

> **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. Also supersedes the v4 cyan accent system.
> **Last Updated:** March 24, 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 (ember orange) appears in ≤5% of the UI. Warm accent on cold charcoal surfaces creates high contrast and distinctive personality — orange conveys urgency and action, fitting for a troubleshooting tool. 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) — Charcoal Palette

```
Page background:     #1a1c23
Sidebar background:  #10121a
Card background:     #22252e
Card hover:          #282b35
Input background:    #282b35
Code background:     #14161e
Elevated surface:    #2e3140

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

Border default:      #2e3240
Border hover:        #3d4252

Accent (ember):      #f97316
Accent hover:        #ea580c
Accent dim (10%):    rgba(249,115,22,0.10)
Accent text:         #fdba74

Success:             #34d399
Success dim:         rgba(52,211,153,0.10)
Warning:             #eab308
Warning dim:         rgba(234,179,8,0.10)
Danger:              #f87171
Danger dim:          rgba(248,113,113,0.10)
```

> **Note:** Warning shifted from amber (#fbbf24) to yellow (#eab308) to maintain clear separation from the orange accent.

### 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:              #ea580c
Accent dim:          rgba(234,88,12,0.07)
Accent text:         #c2410c
```

### 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 cyan accent (`#22d3ee` / `#06b6d4` / `#67e8f9`) — replaced by ember orange in v5
- 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 (#f97316)
Color: #fff
Border: none
Border-radius: 5px
Padding: 9px 16px
Font: 13px, 550 weight
Hover: accent-hover (#ea580c), box-shadow 0 2px 12px rgba(249,115,22,0.25), translateY(-1px)
Active: translateY(0), box-shadow 0 0 4px rgba(249,115,22,0.15)
```

**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, #ea580c, #f97316)`, 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

Shadows communicate **interaction state**, not decoration. On dark backgrounds, traditional black shadows are invisible — use **brighter surfaces + faint accent glow** instead.

**Resting state:** No shadows. Elements are flat with 1px borders.

**Elevation on dark backgrounds (the principle):** Instead of shadow = darker, elevation = lighter. A "raised" element gets a brighter surface color (`bg-elevated` / `#2e3140`) and optionally a very faint orange glow. This creates perceived depth through contrast.

**Hover state (buttons):** Lift effect with accent glow.

- Primary button hover: `0 2px 12px rgba(249,115,22,0.25)` + `translateY(-1px)` — orange glow
- Ghost button hover: brighter border (`border-hover`) + `translateY(-1px)`, no shadow
- Active/click: glow fades, element "presses down" to `translateY(0)`

**Active/selected state (tabs, toggles):** Elevated surface + faint accent glow.

- Active tab: `bg-elevated` + `box-shadow: 0 1px 4px rgba(249,115,22,0.08)` — class: `tab-active-shadow`

**Card hover lift (optional):** For clickable cards.

- Hover: brighter border + `0 2px 8px rgba(249,115,22,0.06)` + `translateY(-2px)` — class: `card-lift`

**Overlays:** Flyouts, dropdowns, modals get stronger shadows (they overlay lighter content).

- Drawer/flyout: `4px 0 12px rgba(0,0,0,0.2)`
- Dropdown: `0 4px 12px rgba(0,0,0,0.3)`
- Modal: `0 8px 24px rgba(0,0,0,0.4)`

**What NOT to do:**

- No `rgba(0,0,0,...)` shadows on resting elements (invisible on dark bg)
- No permanent decorative shadows
- No heavy glow effects — accent glow should be barely perceptible (≤ 0.1 opacity)
- No cyan glow effects — all accent glows use orange rgba(249,115,22,...)

---

## 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`
- Any code using cyan accent values (`#22d3ee`, `#06b6d4`, `#67e8f9`, `rgba(34,211,238,...)`) — migrate to ember orange

---

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-03-24 | Accent color changed from cyan (#22d3ee) to ember orange (#f97316) | Cyan caused contrast issues, felt generic "tech SaaS". Orange provides warmth against cold charcoal, conveys urgency fitting for troubleshooting, and is distinctive in the MSP tool space. |
| 2026-03-24 | Warning color shifted from amber (#fbbf24) to yellow (#eab308) | Orange accent would clash with amber warning. Yellow provides clear semantic separation from the orange accent. |
| 2026-03-24 | Light mode accent set to #ea580c (orange-600) | Darker orange variant ensures proper contrast on white/light surfaces. |
| 2026-03-24 | Synced DESIGN-SYSTEM.md to actual charcoal palette | Doc was behind — still showed pre-charcoal values (#0c0d10 page, #14161d card). Updated to match index.css (#1a1c23 page, #22252e card). |
