resolutionflow/DESIGN-SYSTEM.md

ResolutionFlow Design System v6

Status: ACTIVE — This document is the single source of truth for all frontend design decisions. Supersedes: All previous design system docs including v5 (ember orange accent), DESIGN_SYSTEM_GUIDE.md, UI-DESIGN-SYSTEM.md, REBRAND-IMPLEMENTATION-GUIDE.md, and any COMPONENT_EXAMPLES.md files. Last Updated: March 29, 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 (electric blue) appears in ≤5% of the UI. Cool blue accent on deep charcoal surfaces creates high contrast and technical confidence — blue conveys trust, precision, and reliability, fitting for a troubleshooting tool that MSP engineers depend on during outages. Every design decision prioritizes readability over decoration.

Dual-mode design: Dark mode is the default. Light mode is fully specified — all colors use CSS custom properties so theming is a variable swap, not a rewrite. Semantic colors shift to darker variants (Tailwind 400→600) in light mode to maintain WCAG AA contrast.

---

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) — Deep Charcoal Palette

Page background:     #16181f
Sidebar background:  #0e1016
Card background:     #1e2028
Card hover:          #252830
Input background:    #252830
Code background:     #12141a
Elevated surface:    #2a2d38
Surface raised:      #303442

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

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

Accent (blue):       #60a5fa
Accent hover:        #3b82f6
Accent dim (10%):    rgba(96,165,250,0.10)
Accent text:         #93c5fd
Accent glow (15%):   rgba(96,165,250,0.15)

Success:             #34d399
Success dim:         rgba(52,211,153,0.10)
Warning (amber):     #fbbf24
Warning dim:         rgba(251,191,36,0.10)
Danger:              #f87171
Danger dim:          rgba(248,113,113,0.10)
Info (cyan):         #67e8f9
Info dim:            rgba(103,232,249,0.10)

Light Mode

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

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

Border default:      #dde0e7
Border hover:        #c5c9d3

Accent:              #2563eb
Accent hover:        #1d4ed8
Accent dim:          rgba(37,99,235,0.07)
Accent text:         #1d4ed8
Accent glow:         rgba(37,99,235,0.10)

Success:             #059669
Success dim:         rgba(5,150,105,0.07)
Warning:             #d97706
Warning dim:         rgba(217,119,6,0.07)
Danger:              #dc2626
Danger dim:          rgba(220,38,38,0.07)
Info:                #0891b2
Info dim:            rgba(8,145,178,0.07)

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 ember orange accent (#f97316 / #ea580c / #fdba74) — replaced by blue in v6
• 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, info]
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
Accent	accent-dim	accent-text
Success	success-dim	success
Warning	warning-dim	warning
Danger	danger-dim	danger
Info	info-dim	info

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 (#60a5fa dark / #2563eb light)
Color: #fff
Border: none
Border-radius: 5px
Padding: 9px 16px
Font: 13px, 550 weight
Hover: accent-hover (#3b82f6 dark / #1d4ed8 light), box-shadow 0 2px 12px accent-glow, translateY(-1px)
Active: translateY(0), box-shadow 0 0 4px accent-glow

Ghost:

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

Code Blocks

Background: bg-code (#12141a)
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	#93c5fd (accent-text)
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, #3b82f6, #60a5fa), 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 / #2a2d38 or bg-raised / #303442) and optionally a very faint blue glow. This creates perceived depth through contrast.

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

• Primary button hover: 0 2px 12px rgba(96,165,250,0.25) + translateY(-1px) — blue 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(96,165,250,0.08) — class: tab-active-shadow

Card hover lift (optional): For clickable cards.

• Hover: brighter border + 0 2px 8px rgba(96,165,250,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 orange glow effects — all accent glows use blue rgba(96,165,250,...)

---

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 ember orange accent values (#f97316, #ea580c, #fdba74, rgba(249,115,22,...)) — migrate to blue accent
• Any code using old cyan accent values (#22d3ee, #06b6d4) for accent purposes — cyan is now the info color only

---

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.
2026-03-24	Warning color shifted from amber (#fbbf24) to yellow (#eab308)	Orange accent would clash with amber warning.
2026-03-24	Synced DESIGN-SYSTEM.md to actual charcoal palette	Doc was behind — updated to match index.css.
2026-03-29	Accent changed from ember orange (#f97316) to electric blue (#60a5fa/#2563eb)	Orange did not test well with users — read as "budget/cautionary." Blue conveys trust and technical confidence. Electric blue is brighter than the corporate blues used by NinjaOne/ConnectWise/Datto, maintaining differentiation. Works on both dark and light backgrounds.
2026-03-29	Info color set to cyan (#67e8f9/#0891b2)	Blue accent freed the info slot. Cyan is visually distinct from accent blue (cooler/lighter) and intuitive for informational contexts.
2026-03-29	Warning reclaimed as amber (#fbbf24/#d97706)	Yellow (#eab308) was only needed to avoid clashing with orange accent. With blue accent, amber is the natural warning color again.
2026-03-29	Surfaces deepened for better layer separation	Page: #1a1c23→#16181f, Card: #22252e→#1e2028, Sidebar: #10121a→#0e1016. Wider range gives 4+ clear visual depth layers instead of 2. Added surface-raised (#303442) for hover/active states.
2026-03-29	Full light mode semantic colors specified	All semantic colors get light-mode variants at Tailwind 600 level (dark uses 400). Ensures WCAG AA contrast on white/light surfaces.