diff --git a/CLAUDE.md b/CLAUDE.md index c75453bb..1d65028a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,29 +19,29 @@ | Repository / directory / database / Docker | `patherly` / `patherly_postgres` | | Backend, frontend UI, production URLs | **ResolutionFlow** | -- **Design:** Dark glassmorphism with ice-cyan accent gradient (`#06b6d4` → `#22d3ee`). Charcoal backgrounds, frosted-glass cards with `backdrop-filter: blur()`, orchestrated page-load animations, bold display typography. Design doc: [docs/plans/2026-03-03-aesthetic-redesign-design.md](docs/plans/2026-03-03-aesthetic-redesign-design.md) -- **Fonts:** Bricolage Grotesque (`font-heading`, headings/titles), IBM Plex Sans (`font-sans`, body text), JetBrains Mono (`font-label`, labels/badges/timestamps) — loaded via Google Fonts -- **Logo:** Inline SVG in `BrandLogo.tsx` (decision-tree icon with cyan gradient). Wordmark: "Resolution" in `text-foreground` + "Flow" in `text-gradient-brand` -- **Brand assets:** `brand-assets/` (source SVGs + brand-guide.html), `frontend/src/assets/brand/` (app assets), `frontend/public/icons/` (favicon) -- **CSS utilities:** `text-gradient-brand`, `bg-gradient-brand`, `bg-gradient-brand-hover` (defined in `index.css` via `@theme`). Glass utilities: `.glass-card` (interactive, `scale(1.02)` hover), `.glass-card-static` (no hover transform), `.active-glow` (breathing cyan shadow) -- **Layout:** App shell with persistent sidebar + top bar + main content (CSS Grid). Two fixed atmosphere orbs (cyan top-right, purple bottom-left) behind the shell for ambient glow. See [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md) -- **Navigation:** Sidebar nav with type sub-items (All Flows → Troubleshooting / Projects / Maintenance). Pinned flows section for quick access. NO workspace switcher. See [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md) +- **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. Light mode planned. +- **Accent color:** Cyan (#22d3ee / #06b6d4). Used sparingly — ≤5% of the UI. +- **Fonts:** IBM Plex Sans (`font-sans`, body), Bricolage Grotesque (`font-heading`, headings), JetBrains Mono (`font-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. See [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) +- **Brand assets:** `brand-assets/` (source SVGs), `frontend/src/assets/brand/` (app assets), `frontend/public/icons/` (favicon) - **Terminology:** User-facing label is "Flows" (not "Trees"). Procedural flows are called "Projects" in the UI. Maintenance flows are called "Maintenance" in the UI. `tree_type` column values unchanged in DB. -- **Rebrand guide:** [REBRAND-IMPLEMENTATION-GUIDE.md](docs/archive/REBRAND-IMPLEMENTATION-GUIDE.md) +- **Reference mockups:** `docs/mockups/` (HTML files, open in browser) **Component styling rules:** -- Primary buttons: `bg-gradient-brand` (cyan `135deg`) with `shadow-lg shadow-primary/20`, hover `opacity-0.9`, active `scale(0.97)` -- Secondary buttons: `bg-[rgba(255,255,255,0.04)]` with `border-[rgba(255,255,255,0.06)]`, hover brightens border -- Active nav items: `bg-primary/10` background + 3px left cyan gradient accent bar -- Stat values: use `text-gradient-brand` for highlighted metrics -- Status colors: emerald-400 (success), amber-400 (in-progress), rose-500 (error/critical) -- Category dots: 8px colored circles using the category color palette -- Tags/badges: `font-label` (JetBrains Mono), small rounded chips with `bg-card border-border` -- Cards: `.glass-card` (interactive) or `.glass-card-static` (non-interactive) — semi-transparent bg with `backdrop-filter: blur(16px)`, `border-radius: 16px` -- Section labels: `font-label text-[0.625rem] uppercase tracking-[0.1em] text-muted-foreground` +- Primary buttons: solid `accent` background (#22d3ee), white text, 5px radius +- Ghost buttons: transparent with 1px `border-default`, hover `bg-elevated` +- 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/`#34d399` (success), amber/`#fbbf24` (warning), red/`#f87171` (danger) — ONLY for semantic meaning +- Section labels: 10px, 600 weight, uppercase, `text-muted`, 1.2px letter-spacing -When adding new pages/components: use "ResolutionFlow" branding, ice-cyan gradient accent theme, `.glass-card` / `.glass-card-static` containers, `text-foreground`/`text-muted-foreground` hierarchy. Primary actions use `bg-gradient-brand`. Pages render inside the app shell (CSS Grid: topbar + sidebar + main). Use "Flows" not "Trees" in all user-facing text; use "Projects" not "Procedures" for procedural flows. Reference [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md) for layout patterns, navigation, and component specs. +When adding new pages/components: reference [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md). Use flat dark surfaces, 1px borders, no decorative effects. All colors via CSS variables. Use "Flows" not "Trees" in all user-facing text; use "Projects" not "Procedures" for procedural flows. ## Implementation Principles @@ -97,7 +97,7 @@ When adding new pages/components: use "ResolutionFlow" branding, ice-cyan gradie ### Frontend - **Framework:** React 19 + Vite + TypeScript -- **Styling:** Tailwind CSS v4 (`@tailwindcss/vite` plugin, CSS-only config in `index.css`) — dark-first with ice-cyan gradient accents (see Branding section) +- **Styling:** Tailwind CSS v4 (`@tailwindcss/vite` plugin, CSS-only config in `index.css`) — flat dark theme with cyan accent (see [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md)) - **State:** Zustand (with immer + zundo for undo/redo) - **Routing:** React Router v7 - **API Client:** Axios with token refresh interceptor @@ -379,20 +379,20 @@ gh run view --json jobs --jq '.jobs[] | {name: .name, conclusion: .conclusi --- -## Design System (Slate & Ice Modern) +## Design System -- **Theme:** Dark glassmorphism with ice-cyan accent (`#06b6d4` → `#22d3ee`). Uses `.glass-card` / `.glass-card-static` for card surfaces -- **Backgrounds:** `bg-background` (`#101114` page), glass surfaces use `rgba(24, 26, 31, 0.55)` with `backdrop-filter: blur()` -- **Cards:** `.glass-card` (interactive, hover `scale(1.02)` + border/shadow upgrade) or `.glass-card-static` (no hover). Both have `border-radius: 16px`, semi-transparent bg, backdrop blur -- **Buttons:** Primary: `bg-gradient-brand text-[#101114] font-semibold rounded-[10px] hover:opacity-90 active:scale-[0.97]`. Secondary: `bg-[rgba(255,255,255,0.04)] border-[rgba(255,255,255,0.06)] text-foreground rounded-[10px]` -- **Inputs:** `border-border bg-card text-foreground placeholder:text-muted-foreground` + focus: `focus:border-[rgba(6,182,212,0.3)]` -- **Text:** `text-foreground` (`#f8fafc`) → `text-muted-foreground` (`#8891a0`) → `text-[#5a6170]` (dim, for section labels/timestamps) -- **Borders:** `var(--glass-border)` (`rgba(255,255,255,0.06)`) default, `rgba(255,255,255,0.12)` on hover -- **Hover states:** Border brightens to `rgba(255,255,255,0.12)`, shadow upgrades to `--shadow-float-hover` -- **Active/selected:** `bg-primary/10 text-foreground` or cyan gradient accent bar -- **Functional colors:** emerald-400 (success), rose-500 (error), amber-400 (warning), blue-400 (info). Always pair with icons, not color alone. -- **CSS variables:** Glass system vars (`--glass-bg`, `--glass-border`, `--glass-blur`), shadow system (`--shadow-float`, `--shadow-float-hover`, `--shadow-cyan-glow`), easing (`--ease-out-smooth`) — all in `index.css` `:root` -- **Animations:** Orchestrated page-load sequence (slideDown, slideInLeft, fadeInUp cascade, fadeInRight). `breatheGlow` on first stat card. `bellWobble` on notification hover. See design doc for full spec. +**Source of truth:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — always read this before making visual or UI decisions. + +- **Theme:** Flat, high-contrast dark theme (Sentry/PostHog-inspired). No glass morphism, no backdrop blur, no ambient orbs, no gradient backgrounds on surfaces. Light mode planned. +- **Backgrounds:** `bg-page` (`#0c0d10`), `bg-sidebar` (`#0f1118`), `bg-card` (`#14161d`), `bg-elevated` (`#1c1f2a`) +- **Cards:** `bg-card` with 1px `border-default` (`#1e2130`), 8px radius. No shadows, no blur, no gradients. Hover: `border-hover` (`#2a2f3d`) +- **Buttons:** Primary: solid `accent` (#22d3ee), white text, 5px radius. Ghost: transparent + 1px border, hover `bg-elevated` +- **Inputs:** `bg-input` (`#191c25`) with 1px `border-default`, 5px radius. Focus: `border-color: accent` + `box-shadow: 0 0 0 2px accent-dim` +- **Text:** `text-heading` (`#f0f2f5`) → `text-primary` (`#e2e5eb`) → `text-secondary` (`#848b9b`) → `text-muted` (`#4f5666`) +- **Borders:** `border-default` (`#1e2130`), `border-hover` (`#2a2f3d`) +- **Functional colors:** `#34d399` (success), `#fbbf24` (warning), `#f87171` (danger) — each with `-dim` variant at 10% opacity +- **Accent:** Cyan `#22d3ee` — used sparingly (≤5% of UI). `accent-dim` = `rgba(34,211,238,0.10)`, `accent-text` = `#67e8f9` +- **Deprecated:** Do NOT use `glass-card`, `glass-stat`, `bg-gradient-brand`, `text-gradient-brand`, `backdrop-filter: blur()`, ambient orbs, or purple gradients --- @@ -518,5 +518,5 @@ Use `/browse` from gstack for **all web browsing** — never use `mcp__claude-in | GitHub Issues | `gh issue list --state open` | | Bugs & Fixes | CLAUDE.md → Critical Lessons Learned section | | Feature Specs | [04-FEATURE-SPECIFICATIONS.md](04-FEATURE-SPECIFICATIONS.md) | -| Design System | [docs/plans/Frontend/DESIGN_SYSTEM_GUIDE.md](docs/plans/Frontend/DESIGN_SYSTEM_GUIDE.md) | +| Design System | [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) | | Dev Environment | [DEV-ENV.md](DEV-ENV.md) — devserver01 setup, Docker, CORS, networking | diff --git a/DESIGN-SYSTEM.md b/DESIGN-SYSTEM.md new file mode 100644 index 00000000..aafd2911 --- /dev/null +++ b/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` diff --git a/UI-DESIGN-SYSTEM.md b/docs/archive/design-docs/UI-DESIGN-SYSTEM.md similarity index 100% rename from UI-DESIGN-SYSTEM.md rename to docs/archive/design-docs/UI-DESIGN-SYSTEM.md