monthlytracker/openspec/changes/theming-dark-mode/proposal.md at e3ac732b1b0e2c1d9eb7726812964f5bae8627d8

Files

Vijayakanth Manoharan 012385e9e1 Add dark mode with theme toggle and OpenSpec change

- Add @custom-variant dark in globals.css for class-based dark mode
- Add ThemeToggle component with localStorage persistence and system preference fallback
- Inject blocking inline script in layout to prevent flash on load
- Apply dark: variants across all components (layout, site-nav, home-dashboard, expense-workspace, paycheck-workspace, recurring-expense-manager) and page headers
- Create openspec/changes/theming-dark-mode with proposal, design, and tasks artifacts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-23 22:04:20 -04:00

1.6 KiB

Raw Blame History

Why

The app currently ships with a warm light theme only. Adding a system-aware dark mode with a manual toggle removes eye strain in low-light conditions and meets baseline accessibility expectations for a personal finance tool used at any hour.

What Changes

Add a class-based dark mode variant using Tailwind v4 @custom-variant so all dark: utilities are controlled by a dark class on <html>.
Add a ThemeToggle component that persists the user's preference in localStorage and initialises the correct class before first paint to prevent flash.
Update the root layout to inject the inline initialisation script and render the toggle inside the existing header.
Apply dark: variants to all UI components to produce a warm, deep-stone dark palette consistent with the existing amber/stone design language.

Capabilities

New Capabilities

dark-mode: Users can switch between light and dark themes with a toggle that persists across sessions. System preference is respected on first visit.

Modified Capabilities

expense-tracking: Expense workspace and recurring expense manager now render correctly in both themes.
paycheck-tracking: Paycheck workspace now renders correctly in both themes.
monthly-dashboard: Dashboard sections, insight cards, category bars, and stat cards now render correctly in both themes.

Impact

Affected code: globals.css, layout.tsx, all components under src/components/, and page header text in src/app/.
APIs: None.
Dependencies: None — uses Tailwind v4 built-ins and the Web Storage API.
Systems: No server-side changes required; theme state is fully client-side.

1.6 KiB Raw Blame History

Why