# 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:

```yaml
# 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.