[dark-mode] Phase 3.2: WCAG AA accessibility fixes and Playwright a11y test suite

Audit all dark mode color pairs against WCAG 2.1 AA contrast requirements.
Fix 5 failures across both [data-theme=dark] and @media (prefers-color-scheme)
blocks, and add 26 new Playwright accessibility tests (61 total, all passing).

Contrast fixes (dark-mode.pcss):
- --color-line-gray: #3F3F46 -> #71717A (1.70:1 -> 3.67:1, WCAG 1.4.11 UI boundary)
- --color-code-comment: #71717A -> #909099 (3.84:1 -> 5.86:1, WCAG 1.4.3 text)
- --color-checkbox-border: #52525B -> #71717A (2.29:1 -> 3.67:1, WCAG 1.4.11 UI boundary)
- --color-button-primary: #3B82F6 -> #2563EB (3.68:1 -> 5.17:1, white text on bg)
  hover: #2563EB -> #1D4ED8, active: #1D4ED8 -> #1E40AF
- --color-button-warning: #FB923C -> #C2410C (2.26:1 -> 5.18:1, white text on bg)
  hover: #F97316 -> #9A3412, active: #EA580C -> #7C2D12

New test file (e2e/dark-mode/accessibility.spec.ts — 26 tests):
- 12 contrast ratio tests: live CSS variable extraction with luminance calculation
- 4 keyboard navigation tests: Tab reachability, Enter/Space activation
- 2 focus visibility tests (WCAG 2.4.7): toggle and link focus-visible indicators
- 8 ARIA/semantic structure tests: aria-label, semantic elements, SVG a11y, no duplicate IDs

Other changes:
- e2e/fixtures/setup.ts: update --color-line-gray expected value to match fix
- Rename 3.0-development-summary.md -> 3-progress-report.md, add Phase 3.2 details

Author: Hunta

.github/specs/dark-mode/documentation/3-progress-report.md

@@ -0,0 +1,136 @@
+# Dark Mode Feature - Development Summary
+
+**Branch:** `feature/dark-mode` (based off `main`)  
+**Latest Commit:** `7844eb0` — [dark-mode] Dark theme implementation, Playwright e2e tests, bug fixes, and NeDB migration  
+**Working Tree:** Clean (all changes committed)  
+**Last Updated:** March 31, 2026
+
+---
+
+## Completed Work (Phases 1 & 2) - All verified with passing builds
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| **1.1** | ThemeManager module (`themeManager.js` — 227 lines, singleton pattern, localStorage, system preference detection) | ✅ Done |
+| **1.2** | CSS variables infrastructure (`vars.pcss`, `dark-mode.pcss`) | ✅ Done |
+| **1.3** | App initialization (ThemeManager.init() called first in `app.js` to prevent FOUC) | ✅ Done |
+| **2.1-2.3** | Header toggle button (sun/moon icons in `header.twig`, `themeToggle.js`, header.pcss styles) | ✅ Done |
+| **2.4** | Page component styles (`page.pcss` — all hardcoded colors replaced with CSS variables) | ✅ Done |
+| **2.5** | Sidebar component styles (`sidebar.pcss`, `navigator.pcss` — 4 new CSS variables) | ✅ Done |
+| **2.6** | Button component styles (already using CSS variables, verified + documented) | ✅ Done |
+| **2.7** | Input/Form component styles (`writing.pcss` — 2 hardcoded colors replaced) | ✅ Done |
+| **2.8** | Remaining component styles (sidebar gradient/focus — final 2 hardcoded colors replaced) | ✅ Done |
+
+---
+
+## Remaining Work (Phases 3-5)
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| **3.1** | Visual testing, Playwright E2E suite (35 tests), structural CSS fixes, color palette redesign, bug fixes, NeDB migration | ✅ Done |
+| **3.2** | Accessibility testing (WCAG AA contrast, keyboard nav, focus visibility, ARIA) | ✅ Done |
+| **3.3** | Performance testing (< 100ms theme switch, no layout shifts) | Not Started |
+| **3.4** | localStorage persistence testing | Not Started |
+| **3.5** | Browser compatibility testing | Not Started |
+| **4.1** | Code review & cleanup | Not Started |
+| **4.2** | Unit tests for ThemeManager | Not Started |
+| **4.3** | Developer documentation | Not Started |
+| **4.4** | Update project documentation (README, DEVELOPMENT.md) | Not Started |
+| **5.1** | Prepare for merge (rebase, PR) | Not Started |
+| **5.2** | Deploy & monitor | Not Started |
+
+---
+
+## Phase 3.1 Completion Details
+
+### Playwright E2E Test Suite (35 tests — all passing)
+
+| Spec File | Tests | Coverage |
+|-----------|-------|----------|
+| `theme-toggle.spec.ts` | 6 | Button visibility, ARIA labels, click toggle, keyboard (Enter/Space) |
+| `theme-persistence.spec.ts` | 5 | localStorage save/restore, survives reload, clear resets default |
+| `system-preference.spec.ts` | 4 | `prefers-color-scheme` emulation, saved preference overrides system |
+| `components.spec.ts` | 16 | CSS variable values per theme, body/header/text rendered colors |
+| `no-fouc.spec.ts` | 4 | data-theme attribute on load, DOM consistent with localStorage |
+
+**Infrastructure:** `playwright.config.ts`, `e2e/fixtures/setup.ts`, `.gitignore` for artifacts, `package.json` test scripts
+
+### Bugs Discovered & Fixed
+
+| Bug | Symptom | Root Cause | Fix |
+|-----|---------|------------|-----|
+| **themeToggle event** | Icons never updated after click | `onThemeToggle()` listens for `themeToggle` but `setTheme()` emits `themeChange` | Listen to `themeChange` directly |
+| **Missing body bg** | Page still white in dark mode | `body`, `header`, `copy-button` had hardcoded `white` | Replaced with `var(--color-bg-main)` |
+| **Greeting page** | Dark mode lost after login | `index.twig` missing `main.bundle.js` script | Added script tag |
+| **Alias race condition** | Page redirect → 500 error | `alias.save()` missing `await` in pages.ts | Added `await` to insert/update |
+| **NeDB Node 24 crash** | `util.isDate is not a function` | Node 24 removed `util.is*` functions | Migrated to `@seald-io/nedb` |
+
+### Color Palette Redesign (3 iterations)
+
+1. **Original (Phase 2):** VS Code flat grays `#1E1E1E` — "too boring"
+2. **Slate attempt:** Tailwind slate `#0F172A` — "dark blue mode, not dark mode"
+3. **Final (zinc):** Tailwind zinc neutrals `#18181B` bg, `#27272A` surface, `#3F3F46` borders, `#E4E4E7` text
+
+---
+
+## Phase 3.2 Completion Details — Accessibility (WCAG 2.1 AA)
+
+### WCAG Contrast Audit — 5 Failures Found & Fixed
+
+| Variable | Before | Ratio | After | Ratio | Standard |
+|----------|--------|-------|-------|-------|----------|
+| `--color-line-gray` | `#3F3F46` | 1.70:1 ✗ | `#71717A` | 3.67:1 ✓ | 3:1 (UI boundary) |
+| `--color-code-comment` | `#71717A` | 3.84:1 ✗ | `#909099` | 5.86:1 ✓ | 4.5:1 (text) |
+| `--color-checkbox-border` | `#52525B` | 2.29:1 ✗ | `#71717A` | 3.67:1 ✓ | 3:1 (UI boundary) |
+| `--color-button-primary` | `#3B82F6` | 3.68:1 ✗ | `#2563EB` | 5.17:1 ✓ | 4.5:1 (text on bg) |
+| `--color-button-warning` | `#FB923C` | 2.26:1 ✗ | `#C2410C` | 5.18:1 ✓ | 4.5:1 (text on bg) |
+
+Button hover/active states also adjusted: primary-hover → `#1D4ED8`, primary-active → `#1E40AF`, warning-hover → `#9A3412`, warning-active → `#7C2D12`.
+
+Fixes applied to both `[data-theme="dark"]` and `@media (prefers-color-scheme: dark)` blocks.
+
+### Playwright Accessibility Test Suite (26 new tests)
+
+| Test Group | Tests | Coverage |
+|------------|-------|----------|
+| WCAG AA Contrast Ratios | 12 | text/bg pairs, link on bg, code comment on code bg, line-gray boundary, checkbox boundary, button text on bg, success on bg |
+| Keyboard Navigation | 4 | Tab reaches toggle, Enter activates, Space activates, sidebar search focusable |
+| Focus Visibility (2.4.7) | 2 | Toggle button has visible focus ring, links get focus-visible outline via Tab |
+| ARIA & Semantic Structure | 8 | aria-label, title, semantic button/header/aside, SVG screen reader handling, no duplicate IDs |
+
+**Total test suite:** 61 tests (35 existing + 26 new) — all passing.
+
+---
+
+## Architecture Summary
+
+- **Approach:** CSS custom properties + `[data-theme="dark"]` attribute on `<html>`
+- **Persistence:** `localStorage` key `codex-docs-theme`, with `prefers-color-scheme` fallback
+- **Color palette:** Neutral zinc grays (`#18181B` background, `#E4E4E7` text) with vibrant accents
+- **No FOUC:** ThemeManager initializes synchronously before other modules
+- **Database:** `@seald-io/nedb` (maintained fork of NeDB, Node 24 compatible)
+- **E2E Tests:** 35 Playwright tests (Chromium), run with `npx playwright test`
+- **Server:** Port 7777, start with `npx cross-env NODE_ENV=development node --loader ts-node/esm src/backend/app.ts -c docs-config.yaml`
+
+---
+
+## Commit History
+
+```
+7844eb0 [dark-mode] Dark theme implementation, Playwright e2e tests, bug fixes, and NeDB migration
+bd10c2c [dark-mode] Fix: Initialize ThemeToggle module in docReady
+6dd83c6 [dark-mode] Phase 2.8: Update remaining component styles - Documentation and verification
+055c05c [dark-mode] Phase 2.7: Update input/form component styles with CSS variables
+6b2863c [dark-mode] Phase 2.6: Update button component styles - Complete dark mode support with comprehensive documentation
+fc8d58b [dark-mode] Phase 2.5: Update sidebar component styles - Replace hardcoded colors with CSS variables and add dark mode support
+473780a [dark-mode] Final Tasks.md update: Mark all phases 1.1-1.3 and 2.1-2.4 as complete with checkpoint summary
+8334810 [dark-mode] Add session completion report - All 7 requirements fulfilled, project ready for Phase 2.5
+ab61470 [dark-mode] Add checkpoint verification report - All requirements met for phases 1.1-1.3 and 2.1-2.4
+6f6429c [dark-mode] Add comprehensive completion summary for phases 1.1-1.3 and 2.1-2.4
+ec7516f [dark-mode] Phase 1.1-1.3 and Phase 2.1-2.4 completion: Updated Tasks.md with build verification and completion dates
+4c8a957 [dark-mode] Phase 1.3 app initialization documentation - Synchronous theme setup and FOUC prevention
+9dbe946 [dark-mode] Phase 1.2-1.3 task documentation - CSS variables and app initialization
+5f1076e [dark-mode] Phase 2.4: Update page component styles - Replace hardcoded colors with CSS variables and reorganize documentation
+7a2b4de [dark-mode] Refactor documentation folder structure
+996288f [dark-mode] Update Tasks.md - Add Task 2.3-DOC completion status for phase 2.1-2.3 documentation
+```