feat: add dark mode support (001-dark-mode)

.specify/templates/constitution-template.md

@@ -70,4 +70,4 @@
 
 **Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
 
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+<!-- Example: Version: 2.1.1 | Ratified: 2026-02-14 | Last Amended: 2026-02-15 -->

.windsurf/rules/specify-rules.md

@@ -4,6 +4,9 @@ Auto-generated from all feature plans. Last updated: 2026-02-14
 
 ## Active Technologies
 
+- TypeScript 5 (React 19) + React 19, Tailwind CSS 4 (001-dark-mode)
+- localStorage for theme persistence (001-dark-mode)
+
 - TypeScript 5 (React 19) + React 19, Vite 7, Vitest 4, Tailwind CSS 4 (001-multiple-words)
 - localStorage for user preferences (001-multiple-words)
 
@@ -30,11 +33,11 @@ TypeScript 5 (strict) with React 19: Follow standard conventions
 
 ## Recent Changes
 
+- 001-dark-mode: Added TypeScript 5 (React 19) + React 19, Tailwind CSS 4
+
 - 001-multiple-words: Added TypeScript 5 (React 19) + React 19, Vite 7, Vitest 4, Tailwind CSS 4
 
 - 001-component-refactor: Added TypeScript 5 (strict mode) with React 19 + React 19, Vite 7, Vitest 4, Tailwind CSS 4
 
-- 001-speed-reading-app: Added TypeScript 5 (strict) with React 19 + React 19, React DOM 19, Vite 7, Tailwind CSS 4
-
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

AGENTS.md

@@ -19,7 +19,7 @@ You're an expert engineer for this React app.
   - Vite 7 (build tool)
   - Vitest 4 (testing framework)
   - Node.js 24
-  - Tailwind CSS 4
+  - Tailwind CSS 4 (with dark mode support)
   - ESLint 9 with TypeScript support
   - Prettier with Tailwind plugin
   - React Compiler (babel-plugin-react-compiler)
@@ -108,6 +108,7 @@ import type { User } from './types';
 
 ### Testing Standards
 
+- **TDD** - tests MUST be written first and validated before implementation (red, green, refactor)
 - **100% coverage required** - all statements, branches, functions, and lines (except for barrel exports)
 - **Do not test barrel exports** - index.ts files are barrel exports and should not have dedicated tests
 - **Testing Library** - use @testing-library/react for component testing

index.html

@@ -10,6 +10,30 @@
     <meta name="description" content="Speed reading app." />
     <title>Speed Reader</title>
 
+    <!-- Apply theme before React loads to prevent flash -->
+    <script>
+      (function () {
+        switch (localStorage.getItem('speedreader.theme')) {
+          case 'light':
+            break;
+          case 'dark':
+            document.documentElement.classList.add('dark');
+            break;
+          case 'system':
+          default:
+            if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+              document.documentElement.classList.add('dark');
+            }
+        }
+      })();
+    </script>
+    <style>
+      .dark body {
+        background-color: #111827; /* bg-slate-900 */
+        color: #f9fafb; /* text-slate-50 */
+      }
+    </style>
+
     <!--
       GitHub Corners. See https://github.com/remarkablemark/github-corners
     -->

specs/001-dark-mode/checklists/accessibility.md

@@ -0,0 +1,52 @@
+# Accessibility & Responsive Test Checklist: Dark Mode
+
+**Purpose**: Validate accessibility and responsive design for dark mode feature
+**Created**: 2026-02-15
+**Feature**: Dark Mode
+
+## Keyboard Navigation
+
+- [x] ThemeToggle is focusable via Tab key
+- [x] ThemeToggle activates with Enter key
+- [x] ThemeToggle activates with Space key
+- [x] Focus indicator is visible (2px outline)
+- [x] Focus order is logical and predictable
+
+## Semantics & ARIA
+
+- [x] ThemeToggle has proper ARIA label describing current state
+- [x] ThemeToggle role is "button"
+- [x] Theme changes are announced to screen readers
+- [x] No ARIA violations detected
+
+## Responsive Design
+
+- [x] ThemeToggle is visible and functional on mobile (320px+)
+- [x] ThemeToggle is visible and functional on tablet (768px+)
+- [x] ThemeToggle is visible and functional on desktop (1024px+)
+- [x] Touch target meets minimum 48px × 48px requirement
+- [x] No layout shifts occur during theme transitions
+
+## Color Contrast
+
+- [x] Light mode text meets WCAG AA contrast ratio (4.5:1)
+- [x] Dark mode text meets WCAG AA contrast ratio (4.5:1)
+- [x] Focus indicators meet contrast requirements
+- [x] Interactive elements meet contrast requirements
+
+## High Contrast Mode
+
+- [x] High contrast mode is detected correctly
+- [x] High contrast mode overrides dark mode when active
+- [x] Theme remains functional in high contrast mode
+
+## Reduced Motion
+
+- [x] Theme transitions respect prefers-reduced-motion
+- [x] No animations when reduced motion is preferred
+- [x] Functionality remains intact without animations
+
+## Notes
+
+- All items must be checked before feature is considered complete
+- Use browser DevTools and accessibility testing tools for validation

specs/001-dark-mode/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Dark Mode
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-02-15
+**Feature**: [Dark Mode](spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All checklist items completed - specification is ready for `/speckit.plan`

specs/001-dark-mode/contracts/component-contracts.md

@@ -0,0 +1,198 @@
+# Component Contracts: Dark Mode
+
+**Feature**: Dark Mode  
+**Date**: 2026-02-15  
+**Phase**: 1 - Design
+
+## ThemeToggle Component Contract
+
+### Interface Definition
+
+```typescript
+interface ThemeToggleProps {
+  /** Current theme state */
+  currentTheme: 'light' | 'dark' | 'system';
+  /** Callback when theme is toggled */
+  onThemeToggle: () => void;
+  /** Optional CSS class name */
+  className?: string;
+  /** Whether the toggle should be disabled */
+  disabled?: boolean;
+}
+```
+
+### Behavioral Contract
+
+#### User Interactions
+
+1. **Click Action**
+   - **Trigger**: User clicks the toggle button
+   - **Action**: Calls `onThemeToggle()` callback
+   - **Visual Feedback**: Shows sun/moon icon change
+
+2. **Keyboard Navigation**
+   - **Tab Order**: Toggle must be focusable and included in tab sequence
+   - **Enter/Space**: Activates toggle when focused
+   - **Focus Indicator**: Visible focus state with 2px outline
+
+3. **Screen Reader Support**
+   - **ARIA Label**: "Toggle dark mode, currently {light/dark} mode"
+   - **ARIA Role**: `button`
+   - **State Announcement**: Theme change announced to screen readers
+
+#### Visual Requirements
+
+1. **Position**: Fixed position, bottom-right corner
+2. **Size**: 48px × 48px minimum touch target
+3. **Icons**: Sun icon for light mode, moon icon for dark mode
+4. **Hover State**: Slight scale increase and background color change
+
+### Accessibility Contract
+
+```typescript
+interface AccessibilityRequirements {
+  /** Minimum touch target size in pixels */
+  minTouchTarget: 48;
+  /** Minimum color contrast ratio for normal text */
+  minContrastRatio: 4.5;
+  /** Keyboard support required */
+  keyboardSupport: true;
+  /** Screen reader support required */
+  screenReaderSupport: true;
+}
+```
+
+## useTheme Hook Contract
+
+### Interface Definition
+
+```typescript
+interface UseThemeReturn {
+  /** Currently applied theme */
+  theme: 'light' | 'dark';
+  /** User's preference setting */
+  preference: 'light' | 'dark' | 'system';
+  /** Whether system preference is being followed */
+  followingSystem: boolean;
+  /** Toggle between light and dark themes */
+  toggleTheme: () => void;
+  /** Set specific theme preference */
+  setTheme: (theme: 'light' | 'dark' | 'system') => void;
+  /** Whether high contrast mode is active */
+  highContrastMode: boolean;
+}
+```
+
+### Behavioral Contract
+
+#### Theme Management
+
+1. **Initialization**
+   - Load preference from localStorage if available
+   - Detect system theme as fallback
+   - Apply theme before rendering to prevent flash
+
+2. **Persistence**
+   - Save user preference to localStorage on change
+   - Include timestamp for debugging
+   - Handle storage errors gracefully
+
+3. **System Detection**
+   - Listen for system theme changes
+   - Update theme automatically when following system
+   - Clean up listeners on unmount
+
+#### Error Handling
+
+```typescript
+interface ErrorHandling {
+  /** Fallback behavior when localStorage fails */
+  localStorageFallback: 'system-preference';
+  /** Behavior when string validation fails */
+  parseErrorFallback: 'use-system-preference';
+  /** Behavior when media queries not supported */
+  mediaQueryFallback: 'assume-no-preference';
+}
+```
+
+**Approach**: Simple try-catch blocks following existing `storage.ts` pattern with silent failure and system preference fallback.
+
+## Theme Utility Contract
+
+### Interface Definition
+
+```typescript
+interface ThemeUtils {
+  /** Get system theme preference */
+  getSystemTheme: () => 'light' | 'dark' | 'no-preference';
+  /** Check if high contrast mode is active */
+  getHighContrastMode: () => boolean;
+  /** Save theme preference to localStorage */
+  saveThemePreference: (theme: 'light' | 'dark' | 'system') => boolean;
+  /** Load theme preference from localStorage */
+  loadThemePreference: () => 'light' | 'dark' | 'system' | null;
+  /** Validate theme preference string */
+  validateThemePreference: (
+    data: unknown,
+  ) => data is 'light' | 'dark' | 'system';
+}
+```
+
+### Storage Contract
+
+#### localStorage Schema
+
+```typescript
+interface StorageContract {
+  /** Storage key for theme preference */
+  key: 'speedreader.theme';
+  /** Data format stored */
+  format: 'light' | 'dark' | 'system';
+}
+```
+
+#### Error Handling
+
+Follow existing codebase pattern with simple try-catch blocks:
+
+```typescript
+interface ErrorHandling {
+  /** Fallback behavior when localStorage fails */
+  localStorageFallback: 'system-preference';
+  /** Error handling approach */
+  errorStrategy: 'silent-failure-with-default';
+}
+```
+
+**Storage Operations**:
+
+- All localStorage operations wrapped in try-catch blocks
+- On any error, fall back to system preference
+- No explicit error logging or data corruption detection
+- Follows same pattern as existing `storage.ts` utility
+
+## Integration Contract
+
+### App Component Integration
+
+```typescript
+interface AppThemeIntegration {
+  /** Theme must be applied to entire app */
+  providerLocation: 'root';
+  /** Theme must be applied before first render */
+  initializationTiming: 'before-render';
+  /** Theme changes must not cause layout shifts */
+  layoutStability: 'no-shift';
+}
+```
+
+### CSS Integration
+
+```typescript
+interface CSSIntegration {
+  /** Tailwind class strategy */
+  tailwindStrategy: 'class';
+  /** Custom properties for theme colors */
+  cssVariables: boolean;
+}
+```