docs: swap to Design System v4 — flat dark theme, no glass morphism

- Add DESIGN-SYSTEM.md as single source of truth for all design decisions - Update CLAUDE.md branding and design system sections to reference new system - Archive UI-DESIGN-SYSTEM.md to docs/archive/design-docs/ - Update tech stack styling line and quick reference table The new design system moves from glassmorphism/gradients to a flat, high-contrast dark theme inspired by Sentry/PostHog. Light mode planned. CSS implementation to follow in a separate branch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-21 22:36:03 -04:00
parent bcf4c80f14
commit 6ff793bf45
3 changed files with 411 additions and 33 deletions
--- a/docs/archive/design-docs/UI-DESIGN-SYSTEM.md
+++ b/docs/archive/design-docs/UI-DESIGN-SYSTEM.md
@@ -0,0 +1,806 @@
+# ResolutionFlow UI Design System & Layout Architecture
+
+> **Purpose:** This document defines the app-shell layout, design tokens, component patterns, and navigation architecture for ResolutionFlow. It is the single source of truth for all frontend UI work going forward.
+> **Last Updated:** February 15, 2026
+> **Status:** Approved for implementation (v2 — workspace system removed, replaced with flat nav + type sub-items)
+> **Reference Mockup:** `docs/mockups/resolutionflow-workspaces-mockup.html` (interactive — note: mockup shows old workspace switcher design which has been superseded by this document)
+
+---
+
+## IMPORTANT: Changes from Previous Version
+
+This is version 2 of the design system. The following changes were made based on UX research and product decisions:
+
+1. **Workspace system REMOVED.** The workspace switcher, workspace table, workspace API, `workspaceStore`, and all workspace-related components should be removed. Workspaces added unnecessary cognitive overhead and context-switching cost for the current scale of the product.
+2. **"Procedures" renamed to "Projects"** in all user-facing labels. The `tree_type` database column retains the value `'procedural'` — only UI labels change.
+3. **"Trees" renamed to "Flows"** in all user-facing labels. "Tree" is an internal/technical term. Users see "Flows" everywhere.
+4. **Flow type filtering** is handled via nav sub-items (All Flows → Troubleshooting / Projects), not workspaces.
+5. **Pinned Flows** section added to sidebar for quick access to favorites.
+6. **Folder sidebar panel REMOVED** from the flow library page. Folders remain in the database and API but are not displayed as a persistent second panel. Folder organization is deferred to a future release.
+7. **Search bar centered** in the top bar (flex spacers on both sides).
+8. **Keyboard shortcut badge** is platform-aware: `⌘K` on Mac, `Ctrl+K` on Windows/Linux.
+
+### Files to Remove or Deprecate
+
+These files were created for the workspace system and should be **deleted**:
+
+```
+frontend/src/store/workspaceStore.ts          → DELETE (replace with flowFilterStore.ts)
+frontend/src/api/workspaces.ts                → DELETE
+frontend/src/types/workspace.ts               → DELETE (remove Workspace type)
+frontend/src/components/workspace/            → DELETE entire directory
+frontend/src/constants/workspaceLabels.ts      → DELETE (replace with flowLabels.ts)
+backend/app/models/workspace.py               → DELETE
+backend/app/api/endpoints/workspaces.py        → DELETE
+backend/app/schemas/workspace.py               → DELETE (if exists)
+```
+
+### Database Migration
+
+Create a new migration that:
+1. Drops the `workspace_id` column from `trees` table (if added)
+2. Drops the `workspace_id` column from `tree_categories` table (if added)
+3. Drops the `workspaces` table
+4. **Does NOT touch** the existing `tree_type` column — it stays as-is
+
+Remove the workspace router from `backend/app/api/router.py`.
+
+---
+
+## Table of Contents
+
+1. [Layout Architecture](#1-layout-architecture)
+2. [Design Tokens](#2-design-tokens)
+3. [Naming & Terminology](#3-naming--terminology)
+4. [Sidebar Components](#4-sidebar-components)
+5. [Top Bar](#5-top-bar)
+6. [Main Content Area](#6-main-content-area)
+7. [Component Patterns](#7-component-patterns)
+8. [Icon System](#8-icon-system)
+9. [Animation & Transitions](#9-animation--transitions)
+10. [Migration Strategy](#10-migration-strategy)
+11. [Implementation Phases](#11-implementation-phases)
+
+---
+
+## 1. Layout Architecture
+
+### Overview
+
+ResolutionFlow uses a **persistent sidebar + top bar + main content** layout. This mirrors the UX patterns MSP engineers already use in ConnectWise Automate, Datto RMM, and HaloPSA.
+
+### Shell Structure
+
+```
+┌──────────────────────────────────────────────────────┐
+│  TOP BAR (56px) — Logo, ── Search (centered) ──, User│
+├──────────────┬───────────────────────────────────────┤
+│  SIDEBAR     │  MAIN CONTENT AREA                    │
+│  (260px)     │                                       │
+│              │  Page Header + Actions                │
+│  Pinned      │  Quick Stats Row                      │
+│  Flows       │  Filters Bar                          │
+│              │  Content Sections                     │
+│  Navigation  │  (flow list, sessions, etc.)          │
+│  + sub-items │                                       │
+│              │                                       │
+│  Categories  │                                       │
+│  Tags        │                                       │
+│              │                                       │
+│  ─────────── │                                       │
+│  Team        │                                       │
+│  Settings    │                                       │
+└──────────────┴───────────────────────────────────────┘
+```
+
+### CSS Grid Implementation
+
+```tsx
+// AppLayout.tsx
+<div className="app-shell">
+  <header className="topbar">...</header>
+  <nav className="sidebar">...</nav>
+  <main className="main-content">
+    <Outlet />
+  </main>
+</div>
+```
+
+```css
+.app-shell {
+  display: grid;
+  grid-template-columns: 260px 1fr;
+  grid-template-rows: 56px 1fr;
+  height: 100vh;
+  overflow: hidden;
+}
+
+.topbar {
+  grid-column: 1 / -1; /* spans full width */
+}
+
+.sidebar {
+  overflow-y: auto;
+}
+
+.main-content {
+  overflow-y: auto;
+}
+```
+
+### CSS Variable for Sidebar Width
+
+```css
+:root {
+  --sidebar-w: 260px;
+}
+```
+
+---
+
+## 2. Design Tokens
+
+### Existing Tokens (Already in tailwind.config.js and index.css)
+
+These are already implemented and MUST be used. Do NOT introduce new color values that duplicate or conflict with these.
+
+#### Brand Colors (from tailwind.config.js)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `brand.gradient.from` | `#818cf8` | Gradient start, primary accent |
+| `brand.gradient.to` | `#a78bfa` | Gradient end |
+| `brand.dark.DEFAULT` | `#09090b` | App background (dark mode) |
+| `brand.dark.card` | `#18181b` | Card backgrounds |
+| `brand.dark.surface` | `#12121c` | Elevated surface |
+| `brand.text.primary` | `#ffffff` | Primary text |
+| `brand.text.secondary` | `#a1a1aa` | Secondary text |
+| `brand.text.muted` | `#52525b` | Muted/dim text |
+| `brand.border` | `#27272a` | Standard borders |
+
+#### Tailwind Utilities (from index.css)
+
+| Utility | Description |
+|---------|-------------|
+| `bg-gradient-brand` | `linear-gradient(90deg, #818cf8, #a78bfa)` |
+| `bg-gradient-brand-hover` | `linear-gradient(90deg, #6366f1, #9333ea)` |
+| `text-gradient-brand` | Gradient text effect (uses bg-clip-text) |
+| `font-heading` | Plus Jakarta Sans |
+| `font-sans` | Inter |
+| `font-label` | Outfit |
+
+#### shadcn/ui CSS Variables (from index.css)
+
+All shadcn component tokens are defined via HSL CSS variables (`--background`, `--foreground`, `--card`, `--primary`, etc.) in `:root`. The app is dark-only — all tokens live in `:root`, not `.dark`.
+
+### App Shell Tokens (in index.css `:root`)
+
+```css
+:root {
+  /* App Shell tokens */
+  --sidebar-bg: 240 10% 4.5%;
+  --sidebar-hover: 240 6% 12%;
+  --sidebar-active: 243 75% 59% / 0.08;
+  --border-subtle: 240 6% 12%;
+  --text-dimmed: 240 4% 24%;
+}
+```
+
+### Semantic Status Colors
+
+| Status | Color | Tailwind Class | Usage |
+|--------|-------|---------------|-------|
+| Success / Resolved | `#22c55e` | `text-green-500` / `bg-green-500` | Completed sessions, resolved |
+| Warning / In Progress | `#f59e0b` | `text-amber-500` / `bg-amber-500` | Open/active sessions |
+| Error / Critical | `#ef4444` | `text-red-500` / `bg-red-500` | Failed, critical priority |
+| Info | `#3b82f6` | `text-blue-500` / `bg-blue-500` | Informational, default |
+
+### Category Colors
+
+```typescript
+// constants/categoryColors.ts
+export const CATEGORY_COLORS = [
+  '#3b82f6', // blue
+  '#22c55e', // green
+  '#f59e0b', // amber
+  '#ef4444', // red
+  '#8b5cf6', // violet
+  '#06b6d4', // cyan
+  '#ec4899', // pink
+  '#f97316', // orange
+  '#14b8a6', // teal
+  '#6366f1', // indigo
+] as const;
+```
+
+> **Migration needed:** Add `color` column to `tree_categories`:
+> ```sql
+> ALTER TABLE tree_categories ADD COLUMN color VARCHAR(7) DEFAULT '#3b82f6';
+> ```
+
+---
+
+## 3. Naming & Terminology
+
+### User-Facing Labels
+
+| Internal / Database | User-Facing Label | Context |
+|--------------------|--------------------|---------|
+| `tree` | **Flow** | Universal term for all flow types |
+| `tree_type = 'troubleshooting'` | **Troubleshooting** | Branching decision-tree flows |
+| `tree_type = 'procedural'` | **Project** | Linear step-by-step flows (onboarding, migrations, etc.) |
+| `tree_structure` | Flow structure | Internal — never shown to users |
+| `tree_editor` | **Flow Editor** | The editor page |
+| `session` | **Session** (troubleshooting) / **Run** (projects) | Active use of a flow |
+
+### Label Constants
+
+Replace `workspaceLabels.ts` with a simpler type-based label system:
+
+```typescript
+// constants/flowLabels.ts
+export interface FlowTypeLabels {
+  navLabel: string;
+  newButton: string;
+  editorLabel: string;
+  searchPlaceholder: string;
+}
+
+export const FLOW_TYPE_LABELS: Record<string, FlowTypeLabels> = {
+  all: {
+    navLabel: 'All Flows',
+    newButton: '+ Create Flow',
+    editorLabel: 'Flow Editor',
+    searchPlaceholder: 'Search flows, sessions, tags…',
+  },
+  troubleshooting: {
+    navLabel: 'Troubleshooting',
+    newButton: '+ New Troubleshooting Flow',
+    editorLabel: 'Flow Editor',
+    searchPlaceholder: 'Search troubleshooting flows…',
+  },
+  procedural: {
+    navLabel: 'Projects',
+    newButton: '+ New Project',
+    editorLabel: 'Flow Editor',
+    searchPlaceholder: 'Search projects, runbooks…',
+  },
+};
+
+export function getFlowLabels(typeFilter: string): FlowTypeLabels {
+  return FLOW_TYPE_LABELS[typeFilter] || FLOW_TYPE_LABELS.all;
+}
+```
+
+### Where Labels Appear
+
+- Sidebar nav: "All Flows" (parent), "Troubleshooting" (sub), "Projects" (sub)
+- Page title on flow library: "Flow Library" (always — does not change with filter)
+- "+ Create Flow" button in page header (adapts based on active type filter)
+- Search bar placeholder in top bar (adapts based on active type filter)
+- Flow Editor nav item: Always "Flow Editor"
+
+---
+
+## 4. Sidebar Components
+
+### Structure (top to bottom)
+
+```
+1. ─── PINNED FLOWS ─── (section, collapsible)
+   - Pinned flow items (star icon, click to start session)
+   - "Pin a flow…" hint if empty
+2. ─── divider ───
+3. Primary Navigation
+   - Dashboard (LayoutGrid icon)
+   - All Flows (Box icon) [badge: total count]
+     ├─ Troubleshooting (sub-item, indented)
+     └─ Projects (sub-item, indented)
+   - Flow Editor (PenLine icon)
+   - Sessions (Clock icon) [badge: active count]
+   - Exports (FileText icon)
+   - Step Library (Bookmark icon) [dot: new items]
+4. ─── divider ───
+5. Categories Section
+   - Section label: "CATEGORIES"
+   - Category items with color dots and counts
+6. ─── divider ───
+7. Tags Section
+   - Section label: "POPULAR TAGS"
+   - Tag chips in a flex-wrap cloud
+8. ─── spacer (flex-grow) ───
+9. Footer (pinned to bottom)
+   - Team (Users icon)
+   - Settings (Settings icon)
+```
+
+### Pinned Flows Section
+
+```tsx
+interface PinnedFlow {
+  id: string;
+  name: string;
+  treeType: 'troubleshooting' | 'procedural';
+  categoryEmoji?: string;
+}
+
+interface PinnedFlowsSectionProps {
+  pinnedFlows: PinnedFlow[];
+  onFlowClick: (id: string) => void;
+  onUnpin: (id: string) => void;
+}
+```
+
+**Visual design:**
+- Section label: `PINNED` in `font-label text-[0.6875rem] uppercase tracking-wide text-muted-foreground`
+- Each pinned flow: single line with emoji/icon + flow name (truncated) + quick-start button on hover
+- Max 10 pinned flows visible; if more, show "View all pinned" link
+- Empty state: subtle hint text "Star a flow to pin it here" with `text-muted-foreground text-xs`
+- Collapsible via section header chevron
+
+**Data model:**
+- New junction table: `user_pinned_trees` (user_id UUID, tree_id UUID, pinned_at TIMESTAMPTZ, display_order INTEGER)
+- API: `POST /api/v1/trees/{id}/pin`, `DELETE /api/v1/trees/{id}/pin`, `GET /api/v1/trees/pinned`
+- Store: add `pinnedFlows` array to existing auth or a new lightweight `pinnedStore`
+
+**Pin/unpin interaction:**
+- Pin via: star icon on flow cards in library, three-dot menu → "Pin to sidebar", right-click context menu
+- Unpin via: right-click pinned item → "Unpin", or three-dot menu on flow card
+- Toast on pin: "📌 Pinned **Flow Name** to sidebar"
+- Toast on unpin: "Unpinned **Flow Name**"
+
+### Nav Item Component
+
+```tsx
+interface NavItemProps {
+  href: string;
+  icon: LucideIcon;
+  label: string;
+  badge?: number | 'dot';
+  isActive?: boolean;
+  children?: NavSubItem[];  // for expandable sub-items
+}
+
+interface NavSubItem {
+  href: string;
+  label: string;
+  count?: number;
+  isActive?: boolean;
+}
+```
+
+**Active state styling:**
+- Background: `var(--sidebar-active)` (brand purple at 8% opacity)
+- Left border accent: 3px gradient bar (brand gradient, rounded right corners)
+- Text: `text-foreground` (white)
+- Icon: full opacity
+
+**Inactive state styling:**
+- Background: transparent
+- Text: `text-muted-foreground`
+- Icon: 70% opacity
+- Hover: `var(--sidebar-hover)` background
+
+### Nav Sub-Items (Flow Type Filter)
+
+Sub-items appear indented under "All Flows":
+
+```
+📦 All Flows           47
+   🔧 Troubleshooting  29
+   📋 Projects          18
+```
+
+**Sub-item styling:**
+- Indented: `pl-9` (aligns text with parent label, past the icon)
+- No icon of their own (the emoji/text suffices, or use a small dot)
+- Font: `text-[0.8125rem] text-muted-foreground`
+- Active: same purple highlight as parent but without the left accent bar
+- Count: right-aligned in `font-label text-xs text-muted-foreground`
+
+**Behavior:**
+- Clicking "All Flows" navigates to `/flows` (or `/trees` — use existing route) with no type filter
+- Clicking "Troubleshooting" navigates to `/flows?type=troubleshooting`
+- Clicking "Projects" navigates to `/flows?type=procedural`
+- The active state highlights whichever is currently selected
+- When a sub-item is active, the parent "All Flows" stays visually highlighted (dimmer) to show context
+- Sub-items are always visible (not collapsible) — there are only 2
+
+**Flow library page behavior:**
+- Reads `type` from URL search params (already implemented in `TreeLibraryPage.tsx`)
+- Filters the flow list accordingly
+- Updates the page subtitle and "Create" button label via `getFlowLabels(typeFilter)`
+- Categories, tags, stats, and sessions in the sidebar do NOT change — they show data across all types
+
+### Category Item Component
+
+```tsx
+interface CategoryItemProps {
+  name: string;
+  color: string;  // hex color for the dot
+  count: number;
+  onClick: () => void;
+}
+```
+
+Renders as: `[●] Category Name .............. 12`
+
+- 8px color dot (rounded full)
+- Name in `text-sm text-muted-foreground`
+- Count right-aligned in `font-label text-xs`
+- Hover: `var(--sidebar-hover)` background, text brightens
+
+### Tag Cloud Component
+
+```tsx
+interface TagCloudProps {
+  tags: string[];
+  onTagClick: (tag: string) => void;
+  activeTags?: string[];
+}
+```
+
+- Background: `bg-card`, Border: `border-border`
+- Text: `font-label text-xs` (Outfit)
+- Active: purple-tinted background and border
+- Gap: 4px
+
+---
+
+## 5. Top Bar
+
+### Structure (left to right)
+
+```
+[Logo + Wordmark] | ──flex grow── | [Search Input (Ctrl+K / ⌘K)] | ──flex grow── | [Quick Launch] [Notifications] [Avatar]
+```
+
+The search bar is **centered** between the logo and action buttons using flex spacers on both sides.
+
+### Logo Area
+
+- Width: fits content (not fixed to sidebar width)
+- Contains: ResolutionFlow logo SVG (32x32) + branded wordmark
+- Wordmark: "Resolution" in white + "Flow" in gradient text
+
+### Search Bar
+
+- Width: 100%, max-width 480px
+- **Centered** in the top bar via `flex-1` spacers on both sides
+- Placeholder: "Search flows, sessions, tags…" (static — does NOT change with type filter)
+- Left icon: magnifying glass (Lucide `Search`)
+- Right badge: platform-aware keyboard shortcut hint
+  ```tsx
+  {navigator.platform?.toLowerCase().includes('mac') ? '⌘K' : 'Ctrl+K'}
+  ```
+- Border: `border-border`, focus: `border-primary/30`
+
+### Action Buttons
+
+| Button | Icon | Behavior |
+|--------|------|----------|
+| Quick Launch | `Zap` (Lucide) | Opens quick-launch modal to start a session fast |
+| Notifications | `Bell` (Lucide) | Opens notification panel. Red dot badge when unread |
+| User Avatar | Initials circle | Opens user menu dropdown (profile, settings, logout) |
+
+Avatar: 32px circle with brand gradient background, white initials in `font-heading text-xs font-bold`.
+
+---
+
+## 6. Main Content Area
+
+### Page Structure
+
+```
+1. Page Header (title + action buttons)
+2. Quick Stats Row (4 cards)
+3. Filters Bar (chips)
+4. Content Sections (flow list, sessions panel)
+```
+
+Not every page uses all sections. Dashboard/Flow Library uses all four. Flow Editor uses only the header.
+
+### Quick Stats Row
+
+4 stat cards in a CSS grid (`grid-template-columns: repeat(4, 1fr)`).
+
+Each card:
+- Background: `bg-card`
+- Border: `border` (subtle, brightens on hover)
+- Border radius: `rounded-xl`
+- Padding: 16px 18px
+- Label: `font-label text-[0.6875rem] uppercase tracking-wide text-muted-foreground`
+- Value: `font-heading text-2xl font-bold`
+- Meta: `text-[0.6875rem] text-[var(--text-dimmed)]`
+
+Stat cards for the Flow Library page:
+
+| Stat | Label | Value Source |
+|------|-------|-------------|
+| 1 | Active Flows | Total published flows (use `text-gradient-brand`) |
+| 2 | Sessions Today | Sessions started today (number) |
+| 3 | Open Sessions | In-progress sessions (use `text-amber-500` if > 0) |
+| 4 | Docs Generated | Export count this month |
+
+### Filters Bar
+
+```
+[All] [Recently Used] [My Flows] [Team Flows] [Defaults] | [⊗ More Filters]
+```
+
+Active chip: purple-tinted background/border.
+
+> **Note:** The "Troubleshooting" / "Projects" type filter is handled by the **sidebar sub-items**, NOT by filter chips in this bar. The filters bar is for orthogonal filters (ownership, recency, status).
+
+### Flow List Items
+
+Grid layout per item:
+
+```
+grid-template-columns: 40px 1fr 130px 80px 100px 40px
+                       icon  info category uses updated actions
+```
+
+Each item:
+- Background: `bg-card`, transparent border
+- Hover: `border-border`, `bg-[var(--sidebar-hover)]`
+- Border radius: `rounded-lg`
+- Padding: 12px 16px
+
+**Pin star:** Show a subtle star icon (Lucide `Star`) on hover, filled if pinned. Click to toggle pin.
+
+**Actions three-dot menu includes:**
+- Start Session
+- Edit
+- Duplicate
+- Pin to Sidebar / Unpin from Sidebar
+- Share
+- Delete
+
+### Sessions Panel
+
+Contained card with header and rows:
+
+```
+┌ Recent Sessions ──────── [View All] ┐
+│ ● DNS Resolution Failure  → step 4/12  TKT-4821  12 min ago │
+│ ● Account Lockout         → step 6/18  TKT-4819  45 min ago │
+│ ✓ Mail Flow               ✓ Resolved   TKT-4815  Yesterday  │
+└──────────────────────────────────────┘
+```
+
+Status dot colors: `bg-amber-500` (in-progress), `bg-green-500` (completed).
+
+---
+
+## 7. Component Patterns
+
+### Buttons
+
+| Variant | Background | Text | Shadow | Hover |
+|---------|-----------|------|--------|-------|
+| Primary | `bg-gradient-brand` | white | `shadow-lg shadow-primary/20` | Lift + stronger shadow |
+| Secondary | `bg-card` | `text-muted-foreground` | border only | Border brightens |
+
+Both: `rounded-lg px-4 py-2 text-sm font-semibold`, with icon support (16px Lucide icon + 6px gap).
+
+### Badges
+
+- **Count badge:** `bg-card border border-border rounded-full px-2 text-[0.6875rem] font-label`
+- **Active count badge:** purple-tinted background/border
+- **Dot badge:** 6px circle, `bg-brand-gradient-from`
+- **Notification badge:** 8px red circle with sidebar-bg border
+
+### Toast Notifications
+
+Fixed-position, **top-right** (current Sonner config — keep as-is):
+- Background: `bg-card`
+- Border: brand gradient border
+- Border radius: `rounded-xl`
+- Auto-dismiss: 2000ms
+
+---
+
+## 8. Icon System
+
+### Primary Source: Lucide React
+
+| Context | Size |
+|---------|------|
+| Nav items | 18px |
+| Buttons | 16px |
+| Top bar actions | 18px |
+| Section headers | 14px |
+| Filter chips | 14px |
+
+### Navigation Icon Mapping
+
+| Nav Item | Lucide Icon |
+|----------|-------------|
+| Dashboard | `LayoutGrid` |
+| All Flows | `Box` |
+| Flow Editor | `PenLine` |
+| Sessions | `Clock` |
+| Exports | `FileText` |
+| Step Library | `Bookmark` |
+| Team | `Users` |
+| Settings | `Settings` |
+| Search | `Search` |
+| Quick Launch | `Zap` |
+| Notifications | `Bell` |
+| Create Flow | `Plus` |
+| Pin/Favorite | `Star` |
+| More Actions | `MoreHorizontal` |
+
+### Category Emoji Icons
+
+Default emoji per common categories:
+- Networking: 🌐, Active Directory: 🔒, Email/Exchange: 📧, Server Issues: 🖥️
+- VPN/Remote: 🔌, Printers: 🖨️, Backup/DR: 🔄, Onboarding: 👤, Security: 🔐
+
+---
+
+## 9. Animation & Transitions
+
+### Page/Section Load
+
+Staggered fade-in with incrementing `animation-delay`:
+- Stats row: 50ms
+- Filters: 100ms
+- Section 1: 150ms
+- Section 2: 200ms
+
+### Interactive Elements
+
+| Element | Property | Duration | Easing |
+|---------|----------|----------|--------|
+| Nav item hover | background-color | 120ms | ease |
+| Button hover | transform, box-shadow | 150ms | ease |
+| Flow item hover | background, border-color | 120ms | ease |
+| Dropdown open | opacity, transform | 150ms | ease |
+| Action buttons (three-dot) | opacity | 120ms | ease |
+| Toast appear/disappear | opacity, transform | 300ms | ease |
+| Pin star toggle | scale + color | 200ms | ease |
+
+---
+
+## 10. Migration Strategy
+
+### What to Remove
+
+1. **WorkspaceSwitcher component** and all workspace UI
+2. **workspaceStore.ts** — replace with `flowFilterStore.ts` (or just use URL params, which `TreeLibraryPage.tsx` already does)
+3. **workspaceLabels.ts** — replace with `flowLabels.ts`
+4. **Workspace API** (`backend/app/api/endpoints/workspaces.py`) and model
+5. **Folder sidebar panel** from `TreeLibraryPage` — remove `FolderSidebar` import and the column it occupies. The `UserFolder` model, API, and database table remain untouched for future use.
+6. All `workspace_id` references in queries
+
+### What to Add
+
+1. **Pinned flows** — `user_pinned_trees` table, API endpoints, sidebar section
+2. **Nav sub-items** — update `Sidebar.tsx` to render "Troubleshooting" and "Projects" as indented children of "All Flows"
+3. **flowLabels.ts** — simple type-based label lookup
+4. **Pin star** on flow cards in the library grid/list views
+
+### What to Keep (Already Built)
+
+1. **AppLayout.tsx** CSS Grid shell — keep as-is
+2. **TopBar.tsx** — keep, but verify search is centered and keyboard shortcut is platform-aware (already fixed)
+3. **Sidebar.tsx** — keep structure, remove workspace switcher, add pinned flows section and nav sub-items
+4. **NavItem.tsx** — keep, extend to support `children` sub-items
+5. **CategoryList, TagCloud** — keep as-is
+6. **All existing pages** — keep rendering inside the shell
+
+### Label Replacements (Global Find & Replace)
+
+In all frontend files:
+
+| Find | Replace With |
+|------|-------------|
+| `All Trees` | `All Flows` |
+| `Tree Editor` | `Flow Editor` |
+| `New Tree` | `Create Flow` |
+| `All Procedures` | `Projects` |
+| `New Procedure` | `New Project` |
+| `Flow Library` (page title) | `Flow Library` (keep) |
+
+In `Sidebar.tsx` nav items:
+- Remove workspace switcher
+- Add pinned flows section at top
+- "All Flows" with sub-items "Troubleshooting" and "Projects"
+
+---
+
+## 11. Implementation Phases
+
+### Phase A: Cleanup & Labels
+
+1. Remove workspace-related files (see list above)
+2. Create down-migration to drop workspace tables/columns
+3. Remove workspace router from `backend/app/api/router.py`
+4. Create `constants/flowLabels.ts`
+5. Update all UI labels: Trees → Flows, Procedures → Projects
+6. Remove `FolderSidebar` from `TreeLibraryPage` (keep folder model/API)
+7. Verify search bar is centered and shortcut is platform-aware in `TopBar.tsx`
+
+### Phase B: Nav Sub-Items
+
+1. Extend `NavItem` component to support `children` sub-items
+2. Update `Sidebar.tsx` to render "All Flows" with "Troubleshooting" and "Projects" children
+3. Sub-items link to `/trees?type=troubleshooting` and `/trees?type=procedural`
+4. Verify `TreeLibraryPage.tsx` correctly reads `type` from URL params (already does)
+5. Add flow counts to sub-item badges
+
+### Phase C: Pinned Flows
+
+1. Create `user_pinned_trees` table and Alembic migration
+2. Create pin/unpin API endpoints (`POST /api/v1/trees/{id}/pin`, `DELETE /api/v1/trees/{id}/pin`, `GET /api/v1/trees/pinned`)
+3. Create Pydantic schemas for pinned flows
+4. Build `PinnedFlowsSection` sidebar component
+5. Add pin star to flow cards in library (visible on hover, filled if pinned)
+6. Add "Pin to Sidebar" / "Unpin" to flow card three-dot menu
+7. Toast notifications for pin/unpin actions
+
+### Phase D: Polish
+
+1. Add category color column migration + backfill
+2. Verify all animations and transitions
+3. Responsive breakpoints (collapse sidebar on mobile)
+4. E2E testing of navigation flow
+5. Performance testing
+
+---
+
+## Appendix A: File Structure for New/Modified Components
+
+```
+frontend/src/
+├── components/
+│   ├── layout/
+│   │   ├── AppLayout.tsx          (keep — CSS Grid shell)
+│   │   ├── TopBar.tsx             (keep — search centered, shortcut fixed)
+│   │   ├── Sidebar.tsx            (MODIFY — remove workspace switcher, add pinned + sub-items)
+│   │   ├── NavItem.tsx            (MODIFY — add children sub-item support)
+│   │   └── ProtectedRoute.tsx     (keep)
+│   ├── sidebar/
+│   │   ├── PinnedFlowsSection.tsx ← NEW
+│   │   ├── CategoryList.tsx       (keep or move from workspace/)
+│   │   └── TagCloud.tsx           (keep or move from workspace/)
+│   ├── workspace/                 ← DELETE entire directory
+│   ├── dashboard/
+│   │   ├── QuickStats.tsx         (keep)
+│   │   ├── FiltersBar.tsx         (keep)
+│   │   └── ...
+│   └── common/
+│       └── ...
+├── store/
+│   ├── workspaceStore.ts          ← DELETE
+│   └── ...
+├── api/
+│   ├── workspaces.ts              ← DELETE
+│   ├── pinnedFlows.ts             ← NEW
+│   └── ...
+├── constants/
+│   ├── workspaceLabels.ts         ← DELETE
+│   ├── flowLabels.ts              ← NEW
+│   └── categoryColors.ts          (keep)
+└── types/
+    └── ...                        (remove Workspace type if exists)
+```
+
+## Appendix B: Typography Quick Reference
+
+| Element | Font | Weight | Size | Tracking |
+|---------|------|--------|------|----------|
+| Page titles | Plus Jakarta Sans (`font-heading`) | 700 | 1.375rem (22px) | -0.01em |
+| Section titles | Plus Jakarta Sans | 700 | 0.8125rem (13px) | 0.04em, uppercase |
+| Nav items | Inter (`font-sans`) | 500 | 0.8125rem (13px) | normal |
+| Nav sub-items | Inter (`font-sans`) | 400 | 0.8125rem (13px) | normal |
+| Flow names | Plus Jakarta Sans | 600 | 0.875rem (14px) | -0.005em |
+| Stat values | Plus Jakarta Sans | 700 | 1.5rem (24px) | -0.02em |
+| Stat labels | Outfit (`font-label`) | 600 | 0.6875rem (11px) | 0.05em, uppercase |
+| Badges/counts | Outfit | 400 | 0.6875rem (11px) | normal |
+| Timestamps | Inter | 400 | 0.6875rem (11px) | normal |
+| Tags/chips | Outfit | 400 | 0.625rem (10px) | normal |
+| Pinned flow names | Inter | 500 | 0.8125rem (13px) | normal |
+| Search input | Inter | 400 | 0.8125rem (13px) | normal |