docs: add theme overhaul task series

tasks/todo/041-tailwind-theme-hooks.md

@@ -0,0 +1,35 @@
+# Task 041 - Tailwind Theme Hooks
+
+## Goal
+Establish the base Tailwind configuration needed for theming work without changing current visuals.
+
+## Prerequisites
+- Installed project dependencies (`npm install`).
+- Ability to run the renderer locally (`npm run dev`).
+
+## Acceptance Criteria
+- [ ] `tailwind.config.js` uses `darkMode: ["class", '[data-theme="dark"]']`.
+- [ ] `theme.extend` contains empty objects for upcoming tokens: `colors`, `spacing`, `fontSize`, `borderRadius`, and `boxShadow`.
+- [ ] No other configuration changes are introduced.
+- [ ] App builds and renders exactly as before (no visual diffs expected).
+
+## Steps
+1. Update `tailwind.config.js` with the new `darkMode` array value.
+2. Add empty extension objects for `colors`, `spacing`, `fontSize`, `borderRadius`, and `boxShadow` under `theme.extend`.
+3. Double-check that all other keys remain untouched.
+4. Save the file.
+
+## Testing Checklist
+- [ ] Run `npm run dev` and ensure the renderer starts successfully.
+- [ ] Smoke test the UI in light and dark mode to confirm no visual regressions.
+
+## Dependencies
+- None.
+
+## Estimated Time
+0.25 hours
+
+## Notes
+- Create a branch (e.g., `feature/task-041-tailwind-theme-hooks`).
+- Commit message suggestion: `chore: prep tailwind for theming`.
+- Include before/after screenshots only if an unexpected visual change occurs.

tasks/todo/042-style-token-scaffolding.md

@@ -0,0 +1,42 @@
+# Task 042 - Style Token Scaffolding
+
+## Goal
+Create the shared token stylesheet placeholder and wire it into the app without defining actual variables yet.
+
+## Prerequisites
+- Task 041 complete (Tailwind theme hooks ready).
+- Local dev server can be run (`npm run dev`).
+
+## Acceptance Criteria
+- [ ] New file `src/styles/tokens.css` exists with section headings for light and dark palettes plus TODO comments for future tokens.
+- [ ] `src/index.css` imports `src/styles/tokens.css` near the top of the file.
+- [ ] No CSS variables are defined yet (only structure and comments).
+- [ ] App compiles and renders as before.
+
+## Steps
+1. Create `src/styles/` if missing and add `tokens.css` with placeholders:
+   ```css
+   :root {
+     /* TODO: surface, text, accent, status tokens */
+   }
+
+   [data-theme="dark"] {
+     /* TODO: dark-mode overrides */
+   }
+   ```
+2. Import `./styles/tokens.css` from `src/index.css` after the Tailwind directives.
+3. Ensure no existing CSS variables are removed yet.
+
+## Testing Checklist
+- [ ] Run `npm run dev` and confirm the renderer starts without warnings.
+- [ ] Visually spot-check a session view in light and dark mode for unchanged styling.
+
+## Dependencies
+- Blocks Task 043 (color variable migration).
+
+## Estimated Time
+0.25 hours
+
+## Notes
+- Branch name suggestion: `feature/task-042-style-token-scaffolding`.
+- Keep the file ASCII-only and avoid trailing spaces.

tasks/todo/043-color-variable-migration.md

@@ -0,0 +1,36 @@
+# Task 043 - Color Variable Migration
+
+## Goal
+Move all hard-coded color variables from `src/index.css` into `src/styles/tokens.css`, aligning with the documented light and dark palettes.
+
+## Prerequisites
+- Task 042 complete (token scaffolding in place).
+- Access to color definitions from `docs/user-interface.md`.
+
+## Acceptance Criteria
+- [ ] Light mode color tokens (`--surface-*`, `--border-*`, `--text-*`, `--accent`, `--status-success|error|warning`) defined under `:root` in `src/styles/tokens.css`.
+- [ ] Dark mode overrides defined under `[data-theme="dark"]` in the same file.
+- [ ] `src/index.css` no longer declares color variables directly; it references the new tokens instead.
+- [ ] Theme toggle continues to switch palettes correctly.
+
+## Steps
+1. Transfer existing color custom properties from `src/index.css` into `src/styles/tokens.css`, renaming them to semantic names that match the design doc.
+2. Add any missing variables required by the design spec (e.g., `--surface-muted`, `--text-inverted`).
+3. Update `src/index.css` to reference the new semantic variable names where necessary (e.g., `background-color: var(--surface-base)`).
+4. Remove redundant color declarations from `src/index.css` after confirming replacements.
+
+## Testing Checklist
+- [ ] Run `npm run dev` and switch between light and dark themes.
+- [ ] Verify primary screens (instance tabs, session view, prompt input) in both themes for correct colors.
+- [ ] Confirm no CSS warnings/errors in the console.
+
+## Dependencies
+- Depends on Task 042.
+- Blocks Task 044 (typography tokens) and Task 045 (component migration batch 1).
+
+## Estimated Time
+0.5 hours
+
+## Notes
+- Align hex values with `docs/user-interface.md`; note any intentional deviations in the PR description.
+- Provide side-by-side screenshots (light/dark) in the PR for quicker review.

tasks/todo/044-typography-baseline.md

@@ -0,0 +1,34 @@
+# Task 044 - Typography Baseline
+
+## Goal
+Define the shared typography tokens and map them into Tailwind so text sizing stays consistent with the UI spec.
+
+## Prerequisites
+- Task 043 complete (color variables migrated).
+
+## Acceptance Criteria
+- [ ] `src/styles/tokens.css` includes typography variables (font families, weights, line heights, size scale).
+- [ ] `tailwind.config.js` `theme.extend.fontFamily` and `theme.extend.fontSize` reference the new variables.
+- [ ] `src/index.css` applies body font and default text color using the new variables.
+- [ ] No existing components lose readability or spacing.
+
+## Steps
+1. Add typography variables to `src/styles/tokens.css`, e.g., `--font-family-sans`, `--font-size-body`, `--line-height-body`.
+2. Extend Tailwind font families and sizes to match the variable names (`font-body`, `font-heading`, `text-body`, `text-label`).
+3. Update `src/index.css` body rules to use `var(--font-family-sans)` and the appropriate default sizes.
+4. Spot-check components for any stray font-size declarations that should use utilities instead.
+
+## Testing Checklist
+- [ ] Run `npm run dev` and verify the app renders without layout shifts.
+- [ ] Inspect headings, labels, and body text to make sure sizes align with the design doc.
+
+## Dependencies
+- Depends on Task 043.
+- Blocks Task 045 (component migration batch 1).
+
+## Estimated Time
+0.5 hours
+
+## Notes
+- Keep variable names semantic; record any design clarifications in the Notes section of the PR.
+- Use browser dev tools to confirm computed font values match expectations (14px body, 16px headers, etc.).

tasks/todo/045-message-item-tailwind-refactor.md

@@ -0,0 +1,35 @@
+# Task 045 - Message Item Tailwind Refactor
+
+## Goal
+Refactor `MessageItem` to rely on Tailwind utilities and the new token variables instead of bespoke global CSS.
+
+## Prerequisites
+- Task 043 complete (color tokens available).
+- Task 044 complete (typography baseline available).
+
+## Acceptance Criteria
+- [ ] `src/components/message-item.tsx` uses Tailwind utility classes (with CSS variable references where needed) for layout, colors, and typography.
+- [ ] Legacy `.message-item*` styles are removed from `src/index.css`.
+- [ ] Visual parity in light and dark modes is maintained for queued, sending, error, and generating states.
+
+## Steps
+1. Replace `class="message-item ..."` and nested class usage with Tailwind class lists that reference tokens (e.g., `bg-[var(--surface-elevated)]`, `text-[var(--text-secondary)]`).
+2. Create any small reusable utility classes (e.g., `.chip`, `.card`) in a new `src/styles/components.css` if repeated patterns arise; keep them token-based.
+3. Delete the now-unused `.message-item` block from `src/index.css`.
+4. Verify conditional states (queued badge, sending indicator, error block) still render with correct colors/typography.
+
+## Testing Checklist
+- [ ] Run `npm run dev` and load a session with mixed message states.
+- [ ] Toggle between light/dark themes to confirm token usage.
+- [ ] Use dev tools to ensure no stale `.message-item` selectors remain in the DOM.
+
+## Dependencies
+- Depends on Tasks 043 and 044.
+- Blocks future component refactor tasks (046+).
+
+## Estimated Time
+0.75 hours
+
+## Notes
+- Capture before/after screenshots (light + dark, streamed message) for review.
+- Mention any new utility classes in the PR description so reviewers know where to look.