invest-copilot/docs/04-open-design-integration.md

Invest Copilot — Open Design Integration Guide

What is Open Design?

Open Design is an open-source, local-first design tool that uses AI coding agents to generate:

• UI/UX mockups — HTML/CSS prototypes from natural language
• Brand design systems — Color palettes, typography, spacing, component styles
• Visual directions — Curated design moods (editorial, modern minimal, tech utility, etc.)
• Interactive prototypes — Clickable HTML/CSS that can be directly used as starting points
• Export formats — HTML, PDF, PPTX, MP4

It runs on any coding agent CLI (Claude Code, Codex, Cursor, Qwen, Hermes, etc.) and uses brand-grade design systems (Stripe, Linear, Vercel, Apple, etc.) as visual foundations.

How Open Design Fits Into Our Project

Phase 1: Visual Design Direction (Week 1)

Goal: Define the visual identity of Invest Copilot using Open Design.

Command pattern for Hermes/other CLI agents:
"Using Open Design, generate a visual direction for an AI-native investment copilot app.
Target audience: retail investors, ages 25-45, tech-savvy.
Design constraints:
- Dark mode primary (trading platforms default to dark)
- Data-dense but not cluttered (like Bloomberg but modern)
- Mobile-first responsive layouts
- Financial data visualization (charts, heatmaps, tables)
- Color palette: professional finance (deep navy, electric blue accents, green/red for gains/losses)
- Brand tone: trustworthy, intelligent, cutting-edge
- Reference: Bloomberg Terminal meets Linear.app meets TradingView

Generate 3 visual directions with:
1. Color palette in CSS custom properties (OKLch recommended by Open Design)
2. Font stack recommendation
3. Component style definitions
4. Layout spacing scale
5. Example chart and data table styling"

Phase 2: UI Mockup Generation (Week 1-2)

Goal: Generate HTML/CSS prototypes for each key screen.

Screens to generate:

1. Dashboard — Watchlist overview with portfolio summary
2. Stock Search & Profile — Search bar, stock cards, detailed profile view
3. Stock Detail Page — Charts (OHLCV, volume), SEC filings, insider trades, peer comparison
4. Watchlist Management — Create/edit watchlists, add/remove tickers
5. Strategy Builder — Visual strategy condition builder
6. Screener — Filter-based stock screening (TradingView-style)
7. Alerts Center — Real-time alert feed with severity indicators
8. Sector Rotation Dashboard — Sector heatmaps, momentum rankings, rotation alerts

Command pattern:
"Generate a fully responsive HTML/CSS prototype for the [Screen Name] page.
Use the design system from [direction].
Include:
- Layout structure (mobile-first)
- All interactive elements
- Data visualization placeholders
- Responsive breakpoints
- CSS custom properties for theming

Output: Complete HTML file with embedded CSS and minimal JS for interactivity."

Phase 3: Component Library (Week 2)

Goal: Generate reusable component specs that map to Radix UI + Tailwind.

Command pattern:
"Generate a component library specification for Invest Copilot using TailwindCSS.
Components:
1. StockCard — ticker, price, change %, mini-chart sparkline
2. PriceChart — OHLCV candlestick chart (placeholder for Lightweight Charts)
3. SEC Filing Card — form type, date, summary, sentiment badge
4. Insider Trade Row — name, title, transaction type, shares, value
5. Strategy Condition Builder — visual rule builder (AND/OR logic)
6. Screener Filter — field selector, operator, value input
7. Alert Badge — severity-based color coding (info/warning/critical)
8. Sector Heatmap — color-coded sector performance grid
9. Watchlist Table — sortable, filterable ticker list
10. Navigation — mobile-first bottom nav + desktop sidebar

For each component:
- HTML structure
- TailwindCSS classes
- State variants (hover, active, disabled, error)
- Responsive behavior
- Accessibility attributes (ARIA)"

Phase 4: Brand Design System (Week 2-3)

Goal: Create a complete design token system using Open Design's brand-grade systems.

Design tokens structure:
{
  "color": {
    "background": {
      "primary": "OKLch(0.08 0 0)",       // near-black
      "secondary": "OKLch(0.12 0 0)",     // dark gray
      "tertiary": "OKLch(0.18 0 0)"      // lighter gray
    },
    "surface": {
      "card": "OKLch(0.15 0 0)",
      "hover": "OKLch(0.20 0 0)",
      "active": "OKLch(0.25 0 0)"
    },
    "text": {
      "primary": "OKLch(0.95 0 0)",
      "secondary": "OKLch(0.70 0 0)",
      "tertiary": "OKLch(0.50 0 0)"
    },
    "semantic": {
      "positive": "OKLch(0.65 0.18 140)",   // green
      "negative": "OKLch(0.55 0.20 20)",     // red
      "accent": "OKLch(0.65 0.18 250)",      // blue
      "warning": "OKLch(0.70 0.18 80)",      // amber
      "critical": "OKLch(0.50 0.22 20)"      // deep red
    }
  },
  "typography": {
    "fontFamily": {
      "display": "Inter, system-ui, sans-serif",
      "mono": "JetBrains Mono, monospace",
      "body": "Inter, system-ui, sans-serif"
    },
    "size": {
      "xs": "0.75rem",
      "sm": "0.875rem",
      "base": "1rem",
      "lg": "1.125rem",
      "xl": "1.25rem",
      "2xl": "1.5rem",
      "3xl": "1.875rem"
    },
    "weight": {
      "normal": "400",
      "medium": "500",
      "semibold": "600",
      "bold": "700"
    }
  },
  "spacing": {
    "1": "0.25rem",
    "2": "0.5rem",
    "3": "0.75rem",
    "4": "1rem",
    "6": "1.5rem",
    "8": "2rem",
    "12": "3rem",
    "16": "4rem"
  },
  "radius": {
    "sm": "0.375rem",
    "md": "0.5rem",
    "lg": "0.75rem",
    "xl": "1rem",
    "full": "9999px"
  },
  "breakpoints": {
    "mobile": "375px",
    "tablet": "768px",
    "desktop": "1024px",
    "wide": "1280px"
  }
}

Phase 5: Interactive Prototype to Code Bridge (Week 3)

Goal: Convert Open Design HTML/CSS prototypes into Next.js components.

Process:

1. Open Design generates HTML/CSS prototype
2. Developer maps HTML structure to React/Next.js components
3. Tailwind classes transfer directly (same syntax)
4. Replace static data with API-driven data
5. Add interactivity (Zustand state, API calls)
6. Ensure accessibility (ARIA, keyboard navigation)

Mapping guide:
┌────────────────────┬─────────────────────────────────────────┐
│  Open Design Output │  Next.js Implementation                  │
├────────────────────┼─────────────────────────────────────────┤
│  HTML <div>        │  React <div> (same)                          │
│  HTML <a>          │  Next.js <Link>                             │
│  CSS classes       │  TailwindCSS classes (same syntax)           │
│  CSS custom props  │  tailwind.config.js theme extension          │
│  Static data       │  API call → Zustand store → component        │
│  Hover effects     │  Tailwind hover: classes                     │
│  Responsive        │  Tailwind responsive prefixes (sm:, md:)     │
│  Interactivity     │  React useState, useEffect, API calls        │
└────────────────────┴───────────────────────────────────────────────┘

Open Design Skill Integration

For Hermes Agent

Use Open Design as a design-phase skill for the invest-copilot project:

# In your agent session context for invest-copilot:
skills:
  - name: open-design  # if installed as a skill
  - name: architecture-diagram  # for system architecture SVGs
  - name: sketch  # for quick UI mockup comparisons

For Other CLI Agents

Open Design works with all 16 supported coding agents. When working with:

• Claude Code: Use natural language design prompts with Open Design conventions
• Cursor: Use Open Design's brand systems as autocomplete context
• Qwen (your model): Generate design specs that map to the TailwindCSS + Radix UI stack

Design System Selection

For Invest Copilot's visual direction, Open Design provides these brand systems:

Brand System	Why It Works	Application
Stripe	Clean, data-dense, professional	Dashboard, data tables, cards
Linear	Modern, minimal, dark mode	Navigation, sidebar, controls
Bloomberg	Financial data visualization	Charts, heatmaps, trading UI
Vercel	Developer-friendly, clean	Settings, configuration screens
Apple	Premium, accessible, intuitive	Onboarding, empty states

Recommended Blend

Primary: Stripe (layout + spacing principles)
Dark mode: Linear (dark mode design system)
Financial charts: Bloomberg (data density)
Navigation: Vercel (clean, minimal)
Typography: Apple (readability at small sizes)

Design Validation Checklist

Before moving from design to implementation, validate:

• All screens are responsive at 375px, 768px, 1024px, 1280px
• Dark mode contrast ratios meet WCAG AA (4.5:1 for text)
• Touch targets are ≥ 44px on mobile
• Charts are readable at 375px width
• Color-coding for profit/loss works for colorblind users (add icons + labels)
• All interactive elements have hover and focus states
• Loading states defined for all data-fetching screens
• Empty states designed for watchlists, strategies, alerts
• Error states defined for API failures
• Keyboard navigation works on all screens (not just mouse/touch)
• Semantic HTML structure (header, main, nav, aside, footer)

Anti-Patterns to Avoid

1. Bloomberg clutter — Don't make it look like Bloomberg Terminal. It's a modern PWA, not a desktop trading terminal.
2. Over-charting — Every stock page should have at most 3-4 charts max. More than that overwhelms.
3. Desktop-first thinking — Design for 375px width first, then expand. Not the other way around.
4. Ignoring loading states — Financial data takes time to fetch. Skeleton screens are mandatory.
5. Color-only signaling — Never use color alone to indicate profit/loss. Use arrows, icons, and labels too.
6. Ignoring accessibility — Financial tools serve all users. Screen reader support is non-negotiable.