resolutionflow/docs/plans/Frontend/DESIGN_SYSTEM_GUIDE.md

# ResolutionFlow Design System Implementation Guide

## Overview
This guide provides everything needed to implement the new monochrome design with subtle icon accents across the entire ResolutionFlow application.

## Design Philosophy
- **95% Monochrome**: Pure black backgrounds, white text, transparent card overlays
- **5% Color**: Subtle colors ONLY on functional icons
- **Inspiration**: Plasma + Aspect templates (minimalist, modern, enterprise-grade)
- **Key Principle**: Restraint and sophistication over flashy gradients

---

## Color Palette

### Background Colors
```css
/* Main background - pure black with subtle gradient */
background: linear-gradient(to bottom, #000000 0%, #0a0a0a 50%, #000000 100%);

/* Subtle radial overlays (optional, adds depth) */
background: radial-gradient(circle at 50% 0%, rgba(100, 100, 120, 0.03), transparent 50%),
            radial-gradient(circle at 80% 80%, rgba(80, 80, 100, 0.02), transparent 50%);
```

### Text Colors
```css
/* Primary text */
color: white;

/* Secondary text */
color: rgba(255, 255, 255, 0.7);  /* white/70 */

/* Tertiary text */
color: rgba(255, 255, 255, 0.4);  /* white/40 */

/* Subtle text */
color: rgba(255, 255, 255, 0.3);  /* white/30 */
```

### Card/Surface Colors
```css
/* Standard cards */
background: linear-gradient(135deg, rgba(255,255,255,0.04) 0%, rgba(255,255,255,0.01) 100%);
border: 1px solid rgba(255, 255, 255, 0.08);
backdrop-filter: blur(10px);

/* Card hover state */
background: linear-gradient(135deg, rgba(255,255,255,0.06) 0%, rgba(255,255,255,0.02) 100%);
border-color: rgba(255, 255, 255, 0.12);

/* Stat cards */
background: rgba(20, 20, 25, 0.5);
border: 1px solid rgba(255, 255, 255, 0.06);
backdrop-filter: blur(10px);

/* Active/Highlighted card (Bright Glow) */
background: linear-gradient(135deg, rgba(255, 255, 255, 0.08) 0%, rgba(255, 255, 255, 0.04) 100%);
border: 1px solid rgba(255, 255, 255, 0.2);
box-shadow: 0 0 40px rgba(255, 255, 255, 0.1);
```

### Icon Colors (THE ONLY COLORS IN THE APP)
```css
/* AI/Sparkle icons */
color: #22d3ee; /* cyan-400 */

/* Search icons */
color: #60a5fa; /* blue-400 */

/* Active/Play icons */
color: #a78bfa; /* violet-400 */

/* Network category */
color: #60a5fa; /* blue-400 */

/* Printer category */
color: #818cf8; /* indigo-400 */

/* Email category */
color: #22d3ee; /* cyan-400 */

/* Success/Up trends */
color: #34d399; /* emerald-400 */

/* Failure/Down trends */
color: #f87171; /* red-400 */

/* Neutral/Time icons (NO COLOR) */
color: rgba(255, 255, 255, 0.5); /* gray */
```

### Button Colors
```css
/* Primary button (white) */
background: white;
color: black;

/* Primary button hover */
background: rgba(255, 255, 255, 0.9);

/* Secondary button */
background: rgba(255, 255, 255, 0.1);
border: 1px solid rgba(255, 255, 255, 0.2);
color: white;

/* Secondary button hover */
background: rgba(255, 255, 255, 0.2);
```

---

## Typography

### Font Family
```css
font-family: 'Inter', sans-serif;
```

### Font Weights
- Regular: 400
- Medium: 500
- Semibold: 600
- Bold: 700
- Extrabold: 800

### Type Scale
```css
/* Hero heading */
font-size: 3.5rem; /* 56px */
font-weight: 700;
line-height: 1.1;
letter-spacing: -0.02em;

/* Section heading */
font-size: 2rem; /* 32px */
font-weight: 700;
line-height: 1.2;

/* Card title */
font-size: 1.25rem; /* 20px */
font-weight: 700;
line-height: 1.3;

/* Body large */
font-size: 1.25rem; /* 20px */
font-weight: 400;
line-height: 1.6;

/* Body */
font-size: 1rem; /* 16px */
font-weight: 400;
line-height: 1.5;

/* Small */
font-size: 0.875rem; /* 14px */
font-weight: 500;
line-height: 1.4;

/* Extra small */
font-size: 0.75rem; /* 12px */
font-weight: 500;
line-height: 1.3;
```

---

## Component Patterns

### Header/Navigation
```jsx
<header className="mb-16">
  <div className="flex items-center justify-between">
    <div className="flex items-center gap-3">
      {/* White logo icon */}
      <div className="w-9 h-9 rounded-xl bg-white flex items-center justify-center">
        <svg className="w-5 h-5 text-black" /* icon */></svg>
      </div>
      <span className="text-xl font-semibold text-white tracking-tight">
        ResolutionFlow
      </span>
    </div>
    <div className="flex items-center gap-4">
      <div className="px-4 py-2 rounded-xl bg-white/10 border border-white/20">
        <span className="text-sm text-white font-semibold">Admin</span>
      </div>
    </div>
  </div>
</header>
```

### Hero Section
```jsx
<div className="mb-20 text-center max-w-4xl mx-auto">
  {/* Badge with colored icon */}
  <div className="inline-flex items-center gap-2 px-4 py-2 rounded-full bg-white/5 border border-white/10 mb-8">
    <svg className="w-4 h-4 text-cyan-400" /* sparkle icon */></svg>
    <span className="text-sm text-white/70 font-medium">AI-POWERED TROUBLESHOOTING</span>
  </div>
  
  {/* Main heading */}
  <h1 className="text-5xl md:text-7xl font-bold text-white mb-6 tracking-tight leading-tight">
    All Your Tickets in One<br>
    <span className="text-white/60">Unified Dashboard</span>
  </h1>
  
  {/* Description */}
  <p className="text-xl text-white/40 mb-12 max-w-2xl mx-auto leading-relaxed">
    Search our library of proven decision trees or continue where you left off
  </p>
</div>
```

### Search Bar
```jsx
<div className="relative max-w-2xl mx-auto group">
  <div className="absolute inset-0 bg-white/5 rounded-2xl blur-2xl opacity-0 group-hover:opacity-100 transition-opacity"></div>
  <div className="relative bg-gradient-to-br from-white/[0.04] to-white/[0.01] border border-white/8 backdrop-blur-xl rounded-2xl p-1">
    <div className="flex items-center bg-black/50 rounded-xl">
      {/* Blue search icon */}
      <svg className="ml-5 w-5 h-5 text-blue-400" /* search icon */></svg>
      <input 
        type="text" 
        placeholder="Paste ticket subject or search for a tree..."
        className="flex-1 bg-transparent py-4 px-4 text-white placeholder:text-white/30 focus:outline-none"
      />
      {/* White button */}
      <button className="mr-2 px-5 py-2.5 bg-white text-black font-semibold rounded-lg hover:bg-white/90 transition-all">
        Search
      </button>
    </div>
  </div>
</div>
```

### Stat Card
```jsx
<div className="bg-[rgba(20,20,25,0.5)] border border-white/[0.06] backdrop-blur-xl rounded-2xl p-6 hover:scale-105 transition-transform">
  <div className="text-sm text-white/40 mb-2 font-medium">Active Sessions</div>
  <div className="text-4xl font-bold text-white mb-1">18</div>
  <div className="flex items-center gap-1 text-xs text-emerald-400 font-medium">
    {/* Green up arrow icon */}
    <svg className="w-3 h-3" /* arrow up icon */></svg>
    12% vs last week
  </div>
</div>
```

### Active Session Card (Bright Glow)
```jsx
<div className="bg-gradient-to-br from-white/[0.08] to-white/[0.04] border border-white/20 backdrop-blur-xl rounded-2xl p-8 shadow-[0_0_40px_rgba(255,255,255,0.1)]">
  <div className="flex items-start justify-between mb-6">
    <div>
      <div className="flex items-center gap-3 mb-3">
        {/* Icon with violet color */}
        <div className="w-12 h-12 rounded-xl bg-white/15 border border-white/30 flex items-center justify-center">
          <svg className="w-6 h-6 text-violet-400" /* play icon */></svg>
        </div>
        <div>
          <div className="text-xs text-white/70 font-semibold uppercase tracking-wider mb-1">
            Active Session
          </div>
          <h3 className="text-2xl font-bold text-white">Email Delivery Issues</h3>
        </div>
      </div>
      <p className="text-sm text-white/50">Ticket #5847 • Started 2h ago • 11 of 15 steps</p>
    </div>
    <button className="px-4 py-2 bg-white text-black rounded-xl font-semibold hover:bg-white/90 transition-all">
      Continue →
    </button>
  </div>
  
  {/* Progress bar */}
  <div>
    <div className="flex items-center justify-between text-sm text-white/70 mb-3 font-medium">
      <span>Progress</span>
      <span>72%</span>
    </div>
    <div className="h-2 bg-white/10 rounded-full overflow-hidden">
      <div className="h-full bg-white rounded-full" style={{width: '72%'}}></div>
    </div>
  </div>
</div>
```

### Tree Card
```jsx
<div className="bg-gradient-to-br from-white/[0.04] to-white/[0.01] border border-white/8 backdrop-blur-xl rounded-2xl p-6 hover:scale-105 hover:from-white/[0.06] hover:to-white/[0.02] hover:border-white/12 transition-all cursor-pointer">
  <div className="flex items-start justify-between mb-4">
    {/* Icon with category-specific color */}
    <div className="w-12 h-12 rounded-xl bg-white/5 border border-white/10 flex items-center justify-center">
      <svg className="w-6 h-6 text-blue-400" /* network icon */></svg>
    </div>
    <div className="px-2 py-1 rounded-lg bg-white/10 border border-white/20">
      <span className="text-xs text-white/80 font-semibold">Available</span>
    </div>
  </div>
  <h4 className="text-lg font-bold text-white mb-2">Network Connectivity</h4>
  <p className="text-sm text-white/40 mb-4">Diagnose and resolve network issues</p>
  <div className="flex items-center gap-1.5 text-xs text-white/30">
    {/* Gray clock icon (NO COLOR) */}
    <svg className="w-3.5 h-3.5 text-slate-500" /* clock icon */></svg>
    Last used 5h ago
  </div>
</div>
```

### Primary Button (White)
```jsx
<button className="px-8 py-4 bg-white text-black font-bold rounded-xl hover:bg-white/90 transition-all hover:scale-105">
  Get Started Free
</button>
```

### Secondary Button (Transparent)
```jsx
<button className="px-8 py-4 bg-white/10 border border-white/20 text-white font-semibold rounded-xl hover:bg-white/20 transition-all">
  Book a Demo
</button>
```

---

## Icon Color Mapping

### Where to use each color:

**Cyan (#22d3ee / cyan-400):**
- AI/Sparkle icons
- Email-related icons
- Magic/automation indicators

**Blue (#60a5fa / blue-400):**
- Search icons
- Network-related icons
- General tech icons

**Violet (#a78bfa / violet-400):**
- Active/playing state icons
- Current session indicators
- Progress-related icons

**Indigo (#818cf8 / indigo-400):**
- Printer-related icons
- Hardware icons

**Emerald (#34d399 / emerald-400):**
- Success indicators
- Up arrows/trends
- Positive metrics

**Red (#f87171 / red-400):**
- Error indicators
- Down arrows/trends
- Negative metrics

**Gray (rgba(255,255,255,0.5) / white/50):**
- Time/clock icons
- Neutral informational icons
- Non-critical icons

---

## Tailwind Classes Reference

### Background Patterns
```
bg-black
bg-white
bg-white/5   (5% opacity)
bg-white/10  (10% opacity)
bg-white/15  (15% opacity)
```

### Text Opacity
```
text-white
text-white/70
text-white/60
text-white/50
text-white/40
text-white/30
```

### Border Opacity
```
border-white/8
border-white/10
border-white/12
border-white/20
border-white/30
```

### Icon Colors
```
text-cyan-400
text-blue-400
text-violet-400
text-indigo-400
text-emerald-400
text-red-400
text-slate-500
```

### Rounded Corners
```
rounded-xl    (12px - cards, buttons)
rounded-2xl   (16px - large cards)
rounded-3xl   (24px - hero sections)
rounded-full  (perfect circle - badges, dots)
rounded-lg    (8px - small elements)
```

### Spacing
```
gap-1, gap-2, gap-3, gap-4, gap-6, gap-8
p-4, p-6, p-8, p-12
mb-2, mb-3, mb-4, mb-6, mb-8, mb-12, mb-16, mb-20
```

---

## Animation & Transitions

### Standard Transition
```css
transition: all 0.2s ease;
```

### Hover Scale
```css
hover:scale-105
transition-transform
```

### Hover Opacity
```css
hover:opacity-100
transition-opacity
```

### Card Hover Glow
```css
hover:shadow-[0_0_40px_rgba(255,255,255,0.15)]
```

---

## Implementation Checklist

### Phase 1: Global Styles
- [ ] Update background color to pure black gradient
- [ ] Set font-family to Inter
- [ ] Add subtle radial gradient overlays

### Phase 2: Component Updates
- [ ] Header/Navigation
- [ ] Hero sections
- [ ] Search bars
- [ ] Stat cards
- [ ] Active session cards (Bright Glow)
- [ ] Tree/item cards
- [ ] Buttons (primary & secondary)
- [ ] Forms/inputs
- [ ] Modals
- [ ] Empty states

### Phase 3: Icon Colors
- [ ] Map all icons to appropriate colors
- [ ] Keep time/clock icons gray
- [ ] Add category colors to tree icons

### Phase 4: Polish
- [ ] Add hover states to all interactive elements
- [ ] Test backdrop-filter blur support
- [ ] Verify contrast ratios for accessibility
- [ ] Test on dark displays

---

## Notes for Claude Code

1. **Preserve existing functionality** - Only change visual styling, not logic
2. **Use Tailwind classes** - Avoid custom CSS where possible
3. **Keep shadcn/ui components** - Just reskin them with new colors
4. **Test incrementally** - Update one component type at a time
5. **Icon mapping is critical** - Different tree types get different icon colors

## Questions to Resolve

1. Should all buttons use the same white style, or do you want variations?
2. Do you want the subtle radial gradient overlays, or pure black background?
3. Should stat cards always show trend indicators (up/down arrows)?
4. Any specific components that should NOT follow this design?

---

## Example Files to Update

**Priority 1 (Core UI):**
- `AppLayout.tsx` - Main layout wrapper
- `QuickStartPage.tsx` - Homepage/dashboard
- `Header.tsx` / `Navbar.tsx` - Navigation

**Priority 2 (Features):**
- Tree list components
- Session components
- Search components
- Stats/metrics components

**Priority 3 (Supporting):**
- Modals
- Forms
- Settings pages
- Admin panels

---

## Testing Checklist

After implementation:
- [ ] Dark mode looks correct
- [ ] All text is readable (contrast check)
- [ ] Icons have correct colors
- [ ] Hover states work
- [ ] Cards have proper depth/hierarchy
- [ ] Buttons are prominent
- [ ] Layout is consistent across pages