# Research Findings

## Overview

This is an Electron + React + TypeScript app called "Claude Flow" that provides a structured AI-assisted coding workflow (Research → Plan → Implement). The styling is managed through a single monolithic CSS file using CSS custom properties. The current window title is "minimal" (a leftover from the starter template). There is no light/dark mode — only dark. The goal is to: rename the title, add a header wordmark, modernize the UI with a cipherpunk aesthetic (full monospace font, sharper borders, electric-blue accent), and add a text-based light/dark mode toggle.

---

## Architecture

### Tech Stack
- **Electron 38** — main process, window chrome, IPC
- **React 19 + Vite** — renderer process
- **TypeScript** throughout
- **CodeMirror 6** — markdown editor in DocumentPane
- **better-sqlite3** — local DB for projects/sessions/messages

### Renderer Structure
```
renderer/
  index.html                   ← <title>minimal</title> — MUST CHANGE to "Claude Flow"
  src/
    main.tsx                   ← React root mount
    App.tsx                    ← Top-level state, layout
    types.ts                   ← Shared TS types
    styles/globals.css         ← ALL styling lives here (CSS custom properties)
    components/
      Header.tsx               ← Top bar: project/session selectors, phase indicator
      DocumentPane.tsx         ← Left pane: CodeMirror editor + ReactMarkdown preview
      ChatPane.tsx             ← Right pane: message list + text input
      ActionBar.tsx            ← Bottom bar: token usage bar, Review/Submit buttons
```

### Main Process Structure
```
src/main/
  index.ts       ← BrowserWindow creation (titleBarStyle: "hiddenInset"), IPC setup
  preload.ts     ← Exposes window.api bridge
  ipc/handlers.ts
  db/            ← SQLite schema/queries
  claude/        ← Claude SDK integration
```

---

## Relevant Files

| File | Relevance to Task |
|------|-------------------|
| `renderer/index.html` | **Line 10**: `<title>minimal</title>` → change to `Claude Flow` |
| `renderer/src/styles/globals.css` | **All CSS** — CSS custom properties `:root {}` define the entire theme. Single file, ~543 lines |
| `renderer/src/components/Header.tsx` | Add app wordmark + text theme toggle button (header-right div) |
| `renderer/src/App.tsx` | Add theme state, persist to localStorage, set `data-theme` on `document.documentElement`, pass props down |
| `renderer/src/components/DocumentPane.tsx` | Make CodeMirror theme dynamic — swap `oneDark` ↔ `syntaxHighlighting(defaultHighlightStyle)` |
| `src/main/index.ts` | `titleBarStyle: "hiddenInset"` — macOS frameless, HTML title used in Dock/app switcher |

---

## Key Insights

### 1. Title Change — Two Locations
The title "minimal" appears in:
- `renderer/index.html` line 10: `<title>minimal</title>` — the browser/OS-level window title
- `package.json` line 1: `"name": "minimal-electron-vite-react-better-sqlite"` — package name (lower-priority)
- `package.json` line 19: `"appId": "com.example.minimalbsqlite"` — build identifier (lower-priority)

**Primary fix**: change `<title>minimal</title>` in `renderer/index.html`.

### 2. Current Color Palette (Dark Only)
```css
:root {
  --bg-primary:    #1a1a1a   /* near-black background */
  --bg-secondary:  #252525   /* panels, header */
  --bg-tertiary:   #333      /* inputs, code blocks */
  --border:        #444      /* dividers */
  --text-primary:  #e0e0e0   /* main text */
  --text-secondary:#888      /* muted text, labels */
  --accent:        #3b82f6   /* blue — buttons, links */
  --accent-hover:  #2563eb
  --success:       #10b981   /* green */
  --warning:       #f59e0b   /* amber */
  --danger:        #ef4444   /* red */
}
```
No light mode variables exist. The mechanism for light/dark is straightforward: add `html[data-theme="light"]` overrides.

### 3. Light/Dark Mode — Implementation Path
**Theme storage**: `localStorage` — persist across sessions
**Toggle mechanism**: Set `data-theme="light"` or `data-theme="dark"` on `document.documentElement`
**CSS**: Override variables under `html[data-theme="light"]` selector
**State**: `useState` + `useEffect` in `App.tsx` — no Context needed, just pass `theme` + `onToggleTheme` as props
**Toggle style**: Text-only, bracket notation: `[dark]` / `[light]` — fits the cipherpunk chrome feel

The `Header` will receive `theme: "dark" | "light"` and `onToggleTheme: () => void` as new props.

**CodeMirror — RESOLVED (no new packages needed)**:
`@codemirror/language` is already installed as a transitive dependency and exports both `defaultHighlightStyle` and `syntaxHighlighting`. The `defaultHighlightStyle` provides a full light-mode syntax highlighting scheme (keywords in purple, strings in red, literals in green, etc.) — identical coverage to `oneDark`, just different colors.

Strategy:
- **Dark** → use `[oneDark]` as today
- **Light** → use `[syntaxHighlighting(defaultHighlightStyle)]` from `@codemirror/language`

`DocumentPane` will receive a `theme` prop. The CodeMirror `useEffect` dependency array will include `theme` (alongside the existing `disabled`) so the editor reinitializes with the correct extension set when the theme changes.

### 4. Accent Color — RESOLVED

**Keep blue, go more electric. No green/cyan.**

The cipherpunk feel will come from sharpness and monospace typography — not a color gimmick.

Proposed accent colors:
```
Dark mode:   #60a5fa  (bright electric blue — more vivid than current #3b82f6)
             hover:   #93c5fd
Light mode:  #2563eb  (deeper blue — maintains contrast on light backgrounds)
             hover:   #1d4ed8
```

### 5. Font — RESOLVED: Full Monospace

Apply a monospace font stack to `body` — the entire UI goes mono. The codebase already uses this stack for code blocks, so extending it to the whole UI creates a unified terminal aesthetic without importing any font files.

```css
body {
  font-family: "SF Mono", "Cascadia Code", "JetBrains Mono", "Fira Code", Monaco, "Courier New", monospace;
}
```

### 6. Header Wordmark — RESOLVED: Yes, Add It

Add a styled `<span className="app-wordmark">CLAUDE FLOW</span>` as the **first element** inside `.header-left`, before the project dropdown. Separated from the controls by a subtle right border.

```css
.app-wordmark {
  font-size: 13px;
  font-weight: 700;
  letter-spacing: 0.15em;
  text-transform: uppercase;
  color: var(--text-primary);
  padding-right: 12px;
  border-right: 1px solid var(--border);
  margin-right: 4px;
  user-select: none;
  white-space: nowrap;
}
```

### 7. Other Cipherpunk Touches — All CSS-Only

- **Sharper borders**: reduce `border-radius` from 4–8px → **2px** on all controls (buttons, inputs, messages, badges). Phase steps → 2px. Chat messages → 4px.
- **Uppercase meta labels**: `text-transform: uppercase; letter-spacing: 0.07em` on `.token-label`, `.phase-step`, `.document-header span`, `.badge`, `.implementing-status`
- **Subtle focus glow**: `box-shadow: 0 0 0 2px rgba(96, 165, 250, 0.3)` on focused inputs and buttons
- **Phase brackets**: Phase step text to be updated in `Header.tsx` JSX: `[Research]` → `[RESEARCH]` etc., with CSS uppercase doing the work so the component just renders the labels naturally

### 8. Light Mode Color Palette (Proposed)

```css
html[data-theme="light"] {
  --bg-primary:    #f4f4f2;   /* warm off-white — not stark, feels terminal-adjacent */
  --bg-secondary:  #e8e8e5;   /* panels, header */
  --bg-tertiary:   #d8d8d4;   /* inputs, code blocks */
  --border:        #b4b4b0;   /* dividers */
  --text-primary:  #1a1a18;   /* near-black */
  --text-secondary:#5a5a56;   /* muted */
  --accent:        #2563eb;   /* deep blue */
  --accent-hover:  #1d4ed8;
  --success:       #059669;
  --warning:       #d97706;
  --danger:        #dc2626;
}
```

Warm stone tones rather than pure white — keeps the app from feeling like a generic SaaS product.

### 9. No Existing Theme Infrastructure
There is currently **no ThemeContext, no localStorage usage, no `data-theme` attribute**. Fully greenfield. Simple prop-passing from `App.tsx` is sufficient.

### 10. Window Styling Note
- **macOS** (`titleBarStyle: "hiddenInset"`): traffic lights appear, no visible title text in window frame. HTML `<title>` shows in Dock tooltip and app switcher.
- **Linux/Windows**: default Electron title bar shows `<title>` in window chrome. Critical to fix.

---

## Resolved Decisions

| Question | Decision |
|----------|----------|
| Accent color | Electric blue: `#60a5fa` (dark) / `#2563eb` (light). No green/cyan. |
| CodeMirror light theme | `syntaxHighlighting(defaultHighlightStyle)` from already-installed `@codemirror/language`. Zero new packages. |
| Font scope | **Full mono** — `body` font-family. Entire UI uses monospace stack. |
| Header wordmark | **Yes** — `CLAUDE FLOW` in `.header-left`, uppercase + letter-spacing + right-border separator |
| Theme toggle style | **Text toggle**: `[dark]` / `[light]` bracket notation |

---

## Proposed Change Scope

| Change | File(s) | Effort |
|--------|---------|--------|
| Fix `<title>` | `renderer/index.html` | Trivial |
| Apply monospace body font | `globals.css` | Trivial |
| Sharpen border-radius across all controls | `globals.css` | Small |
| Uppercase + letter-spacing on meta labels | `globals.css` | Small |
| Brighter dark-mode accent (#60a5fa) | `globals.css` | Trivial |
| Add `html[data-theme="light"]` color block | `globals.css` | Small |
| Add focus glow styles | `globals.css` | Small |
| Add `.app-wordmark` styles | `globals.css` | Trivial |
| Add `[dark]`/`[light]` toggle button styles | `globals.css` | Trivial |
| Add theme state + `localStorage` init | `App.tsx` | Small |
| Pass `theme` + `onToggleTheme` props to Header | `App.tsx` → `Header.tsx` | Small |
| Pass `theme` prop to DocumentPane | `App.tsx` → `DocumentPane.tsx` | Small |
| Add `CLAUDE FLOW` wordmark element | `Header.tsx` | Trivial |
| Add `[dark]`/`[light]` toggle button | `Header.tsx` | Small |
| Make CodeMirror theme dynamic | `DocumentPane.tsx` | Small |