resolutionflow/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

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 / #1c1f2a) and optionally a very faint cyan glow. This creates perceived depth through contrast.

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

• Primary button hover: 0 2px 10px rgba(34,211,238,0.2) + translateY(-1px) — cyan 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(34,211,238,0.08) — class: tab-active-shadow

Card hover lift (optional): For clickable cards.

• Hover: brighter border + 0 2px 8px rgba(34,211,238,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)

---

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