fix: replace all remaining old brand tokens (text-brand-dark, border-brand-border, bg-white opacity)

30 references to removed CSS variables: border-brand-border → border-[#1e2130], text-brand-text-muted → text-[#4f5666], text-brand-dark → text-white, bg-white/[0.04] → bg-[#191c25], hover:border-white/[0.12] → hover:border-[#2a2f3d]. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-22 04:27:46 -04:00
parent 4c5649d620
commit 123fc50af9
32 changed files with 578 additions and 72 deletions
--- a/Design/DESIGN-SYSTEM-SETUP-GUIDE.md
+++ b/Design/DESIGN-SYSTEM-SETUP-GUIDE.md
@@ -0,0 +1,128 @@
+# How To Make Claude Code Follow The New Design System
+
+## The Problem
+
+Your project currently has MULTIPLE contradicting design documents:
+- CLAUDE.md references purple gradients, glass-morphism, AND cyan accents
+- Old docs like DESIGN_SYSTEM_GUIDE.md describe monochrome glass-card patterns
+- UI-DESIGN-SYSTEM.md describes a purple gradient workspace system
+- REBRAND-IMPLEMENTATION-GUIDE.md has the old Patherly → ResolutionFlow rebrand
+- Your actual CSS has Tailwind v4 with OKLCH cyan tokens
+
+Claude Code sees ALL of these and gets confused about which to follow.
+
+## The Fix — 4 Steps
+
+### Step 1: Place the new DESIGN-SYSTEM.md in your project root
+
+Copy `DESIGN-SYSTEM.md` (the file I created alongside this one) to:
+```
+C:\Dev\Projects\patherly\DESIGN-SYSTEM.md
+```
+
+This is the SINGLE SOURCE OF TRUTH for all design decisions going forward.
+
+---
+
+### Step 2: Update CLAUDE.md — Branding Section
+
+Find the `### Branding` section and REPLACE EVERYTHING between `**Brand details:**`
+and the next `---` separator with this:
+
+```markdown
+**Brand details:**
+
+- **Design system:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — THE source of truth for all design decisions
+- **Design aesthetic:** Flat, high-contrast dark theme (Sentry/PostHog-inspired). No glass morphism, no gradients on surfaces, no ambient effects.
+- **Accent color:** Cyan (#22d3ee / #06b6d4). Used sparingly — ≤5% of the UI.
+- **Fonts:** IBM Plex Sans (body), Bricolage Grotesque (headings), JetBrains Mono (code) — loaded via Google Fonts
+- **Logo:** 30px gradient square (cyan) + "ResolutionFlow" in Bricolage Grotesque 700
+- **Layout:** Icon rail sidebar (72px, default) with hover flyout panels. Pinnable to full 260px sidebar.
+- **Brand assets:** `brand-assets/` (source SVGs), `frontend/src/assets/brand/` (app assets), `frontend/public/icons/` (favicon)
+- **Landing page:** Shares color system and typography. Full-width marketing layout at `/` route.
+- **Reference mockups:** `docs/mockups/` (HTML files, open in browser)
+
+**Component rules:**
+- Primary buttons: solid `accent` background (#22d3ee), white text
+- Cards: `bg-card` with 1px `border-default`, 8px radius. NO shadows, NO blur, NO gradients.
+- Badges: pill-shaped (20px radius), semantic dim background + matching text color
+- Active nav: `accent-dim` background + `accent-text` color + 3px left accent bar
+- Stat cards: 3px colored left border (accent/success/warning by position)
+- Code blocks: `bg-code` with JetBrains Mono, material-inspired syntax highlighting
+- Status colors: green (success), amber (warning), red (danger) — ONLY for semantic meaning
+
+When adding new pages/components: reference DESIGN-SYSTEM.md. Use flat dark surfaces, 1px borders, no decorative effects. All colors via CSS variables.
+```
+
+---
+
+### Step 3: Update CLAUDE.md — Tech Stack Line
+
+Find the styling line under Tech Stack → Frontend and change it to:
+
+```markdown
+- **Styling:** Tailwind CSS v4 — flat dark theme with cyan accent (see DESIGN-SYSTEM.md)
+```
+
+Remove any references to "monochrome glass-morphism" or "dark-only" limitations.
+
+---
+
+### Step 4: Archive Old Design Docs
+
+Move these files into an `archive/` folder (don't delete — you might want to reference them later):
+
+```
+mkdir archive
+mkdir archive\design-docs
+
+move DESIGN_SYSTEM_GUIDE.md archive\design-docs\
+move UI-DESIGN-SYSTEM.md archive\design-docs\
+move REBRAND-IMPLEMENTATION-GUIDE.md archive\design-docs\
+move COMPONENT_EXAMPLES.md archive\design-docs\   (if it exists in root)
+move docs\plans\Frontend\DESIGN_SYSTEM_GUIDE.md archive\design-docs\  (if it exists here)
+```
+
+If any of these files are referenced elsewhere in CLAUDE.md, remove those references.
+
+---
+
+## Why This Works
+
+Claude Code prioritizes files in this order:
+1. **CLAUDE.md** — reads this first, every time
+2. **Files referenced in CLAUDE.md** — follows links to read referenced docs
+3. **Files in the project root** — scans these for context
+4. **Files deeper in the tree** — only reads if specifically asked
+
+By putting DESIGN-SYSTEM.md in the root AND linking it from CLAUDE.md's branding section,
+Claude Code will find it immediately and treat it as authoritative. By archiving the old
+docs, Claude Code won't stumble on contradicting information.
+
+---
+
+## Verification
+
+After making these changes, test by asking Claude Code:
+1. "What color system does this project use?" — Should say cyan/teal flat dark theme, NOT purple gradients or monochrome
+2. "Create a new card component" — Should use bg-card with 1px border, NOT glass-card with backdrop-blur
+3. "What fonts does this project use?" — Should say IBM Plex Sans + Bricolage Grotesque, NOT Inter + Plus Jakarta Sans
+4. "Add a sidebar nav item" — Should follow the icon rail pattern, NOT a traditional full sidebar
+
+If any of these come back wrong, check that the old docs are actually archived and not still being found.
+
+---
+
+## Place These Mockup Files in docs/mockups/
+
+Also copy the HTML mockups we created into your project so Claude Code has visual references:
+
+```
+mkdir docs\mockups
+
+copy resolutionflow-redesign.html docs\mockups\
+copy resolutionflow-sidebar-final.html docs\mockups\
+copy resolutionflow-landing.html docs\mockups\
+```
+
+Then Claude Code can open these in a browser to see exactly what the target looks like.
--- a/Design/DESIGN-SYSTEM.md
+++ b/Design/DESIGN-SYSTEM.md
@@ -0,0 +1,378 @@
+# 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`