From 0a3ac6cbf24b4eaa19bba972ff691f7a6ff12275 Mon Sep 17 00:00:00 2001 From: Shantur Rathore Date: Tue, 28 Oct 2025 18:42:54 +0000 Subject: [PATCH] docs: add theme overhaul task series --- tasks/todo/041-tailwind-theme-hooks.md | 35 ++++++++++++++++ tasks/todo/042-style-token-scaffolding.md | 42 +++++++++++++++++++ tasks/todo/043-color-variable-migration.md | 36 ++++++++++++++++ tasks/todo/044-typography-baseline.md | 34 +++++++++++++++ .../045-message-item-tailwind-refactor.md | 35 ++++++++++++++++ 5 files changed, 182 insertions(+) create mode 100644 tasks/todo/041-tailwind-theme-hooks.md create mode 100644 tasks/todo/042-style-token-scaffolding.md create mode 100644 tasks/todo/043-color-variable-migration.md create mode 100644 tasks/todo/044-typography-baseline.md create mode 100644 tasks/todo/045-message-item-tailwind-refactor.md diff --git a/tasks/todo/041-tailwind-theme-hooks.md b/tasks/todo/041-tailwind-theme-hooks.md new file mode 100644 index 00000000..a06ca998 --- /dev/null +++ b/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. diff --git a/tasks/todo/042-style-token-scaffolding.md b/tasks/todo/042-style-token-scaffolding.md new file mode 100644 index 00000000..eed0ed05 --- /dev/null +++ b/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. diff --git a/tasks/todo/043-color-variable-migration.md b/tasks/todo/043-color-variable-migration.md new file mode 100644 index 00000000..4a1bf51d --- /dev/null +++ b/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. diff --git a/tasks/todo/044-typography-baseline.md b/tasks/todo/044-typography-baseline.md new file mode 100644 index 00000000..e3caf01c --- /dev/null +++ b/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.). diff --git a/tasks/todo/045-message-item-tailwind-refactor.md b/tasks/todo/045-message-item-tailwind-refactor.md new file mode 100644 index 00000000..9447db45 --- /dev/null +++ b/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.