feat(codex.docs): complete dark mode implementation with theme persistence and accessibility compliance - #1
Conversation
…nt dropdown indent
…ality - Add theme toggle button to header.twig with sun/moon SVG icons - Implement accessible button with aria-label and title attributes - Create ThemeToggle module for click handling and icon updates - Add theme-toggle button styles to header.pcss with CSS variables - Implement hover, focus, and active states for accessibility - Update app.js to initialize ThemeToggle module - Button position: right-aligned in header menu via margin-left: auto - Icon display toggles based on current theme automatically - Click handler toggles between light/dark themes and persists to localStorage - All styling uses CSS variables (--color-text-main, --color-link-hover) - Project builds without errors: npm run build-frontend and build-backend SUCCESS - Update Tasks.md to mark Tasks 2.1, 2.2, 2.3 as complete Build Status: VERIFIED - Frontend: 8 assets, 230 modules, 1 pre-existing warning - Backend: TypeScript compilation successful
…on and Header Toggle Button comprehensive guides
…phase 2.1-2.3 documentation
…ed colors with CSS variables and reorganize documentation
…theme setup and FOUC prevention
….md with build verification and completion dates
… for phases 1.1-1.3 and 2.1-2.4
…led, project ready for Phase 2.5
…4 as complete with checkpoint summary
…coded colors with CSS variables and add dark mode support
… mode support with comprehensive documentation
…ion and verification Complete CSS variable migration with 100% component coverage - Audit all 11 component files for hardcoded colors - Found and fixed 2 hardcoded colors in sidebar.pcss - Replace gradient colors with CSS variables - Replace focus state color with CSS variable - Add 4 new CSS variables with light and dark mode values - Add system preference fallback in @media (prefers-color-scheme: dark) - Verify frontend and backend builds (0 errors, 230 modules) - Create comprehensive task documentation (1340+ lines) - Update Tasks.md with complete task 2.8 acceptance criteria Result: 100% CSS variable coverage - all 11 components now fully theme-aware
The ThemeToggle module was instantiated but never initialized, causing the theme toggle button to be non-functional in the UI. The module's init() method is now called during document ready, ensuring the button properly listens for clicks and updates the theme. This was the final blocker preventing dark mode toggle from working in the deployed application.
…s, and NeDB migration Dark Mode Color Palette (neutral zinc grays): - Redesigned dark-mode.pcss with Tailwind zinc-based neutral palette (bg: #18181B, surface: #27272A, borders: #3F3F46, text: #E4E4E7) - Vibrant accent colors for syntax highlighting (indigo keywords, cyan variables, pink params, emerald classes) - System preference fallback (@media prefers-color-scheme) mirrors the data-theme='dark' values exactly - Added diff color CSS variables to vars.pcss (light) and dark-mode.pcss Structural CSS Fixes: - main.pcss: Added background: var(--color-bg-main) to body element - header.pcss: Replaced hardcoded 'background: white' with CSS variable - copy-button.pcss: Replaced hardcoded 'background: white' with CSS variable - diff.pcss: Converted 4 hardcoded colors to CSS custom properties Bug Fixes: - themeToggle.js: Fixed event listener using wrong event name (was 'themeToggle' via onThemeToggle, now listens to 'themeChange' which is what ThemeManager.setTheme() actually dispatches) - index.twig: Added main.bundle.js script tag so ThemeManager initializes on the greeting/landing page (dark mode was lost after login) - pages.ts: Added missing 'await' on alias.save() in both insert() and update() methods, fixing race condition where page redirect arrived before alias was persisted to database NeDB Migration (Node 24 compatibility): - Replaced unmaintained 'nedb' 1.8.0 with '@seald-io/nedb' (maintained fork) - Fixes util.isDate, util.isRegExp, util.isArray removal in Node 24 - Updated imports in local.ts and test/database.ts using createRequire() for clean CJS/ESM interop with Node16 module resolution - Added explicit callback parameter types for @seald-io/nedb type defs Playwright E2E Test Suite (35 tests): - playwright.config.ts: Chromium-only config with webServer auto-start - e2e/fixtures/setup.ts: Shared selectors, color constants, helpers - theme-toggle.spec.ts: Button visibility, ARIA, click/keyboard toggle - theme-persistence.spec.ts: localStorage save/restore across reloads - system-preference.spec.ts: prefers-color-scheme emulation fallback - components.spec.ts: CSS variable verification, rendered element colors - no-fouc.spec.ts: Flash-of-unstyled-content prevention checks - Added test scripts and @playwright/test dependency to package.json - Updated .gitignore for Playwright artifacts
…y 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
…t, FOUC, CSS architecture Add 12 Playwright performance tests verifying NFR-3.1.1 through NFR-3.1.3. All 73 tests passing (61 existing + 12 new). New test file (e2e/dark-mode/performance.spec.ts): Theme Switch Timing (NFR-3.1.1 — < 100ms): - Light-to-dark and dark-to-light toggle timing via performance.now() - 10 rapid successive toggles each validated under 100ms - Raw setAttribute performance baseline No Layout Shift (NFR-3.1.2): - PerformanceObserver CLS measurement during toggle (threshold: < 0.05) - Header/sidebar dimensions stable across theme switch - Scroll position preserved after toggle No FOUC on Page Load: - MutationObserver verifies first data-theme write is 'dark' (no light flash) - Theme application completes within DOMContentLoaded CSS Variables Architecture (NFR-3.1.3): - Confirms data-theme attribute mechanism (not class swapping) - CSS variables update synchronously with attribute change - No inline color styles on layout elements
Add 9 new persistence tests to theme-persistence.spec.ts covering edge cases
from FR-2.2.1 through FR-2.2.4. All 82 tests passing.
New tests:
- Cross-page navigation: theme survives navigating away and back
- localStorage.clear(): resets to default light mode
- removeItem(key): resets to default light mode
- Invalid value ('invalid-theme'): no crash, toggle still functional
- Rapid toggles (7x): final state persisted correctly, survives reload
- Storage format: value is plain string, not JSON object
- No key leakage: only codex-docs-theme key in storage
- CSS variables: --color-bg-main and --color-text-main correct after reload
- Toggle icon: sun/moon visibility correct after reload
…ager invalid-value bugfix Add 19 browser-compat tests run across Chromium, Firefox, and WebKit (57 total cross-browser runs). Fix ThemeManager bug where invalid localStorage values caused applyTheme(null). All 139 tests passing. ThemeManager bugfix (themeManager.js): - init() now handles invalid localStorage values: hasSavedPreference() returning true while getSavedPreference() returns null correctly falls back to system preference or light default Playwright config (playwright.config.ts): - Add chromium-compat, firefox-compat, webkit-compat projects - browser-compat.spec.ts runs on all 3 browsers - Existing chromium project excludes compat tests to avoid duplication New test file (e2e/dark-mode/browser-compat.spec.ts — 19 tests x 3 browsers): - CSS custom properties: light/dark resolution, [data-theme] selector override - Theme toggle: click both directions, icon swap, keyboard Enter/Space - localStorage: save, restore after reload, API availability check - System preference: matchMedia API, prefers-color-scheme dark/light emulation - Rendered colors: body bg dark/light, text color, header bg - API support: CustomEvent dispatch, MutationObserver attribute detection Updated tests (theme-persistence.spec.ts): - Invalid value test updated: now asserts fallback to light mode
Remove dead code from ThemeManager and fix CSS specificity bug. All 139 tests passing after changes. ThemeManager cleanup (themeManager.js — 227 → 173 lines): - Remove unused onThemeToggle(callback): no code references this method - Remove unused static toggleTheme(): ThemeToggle calls setTheme() directly CSS specificity bugfix (dark-mode.pcss): - @media (prefers-color-scheme: dark) selector changed from :root to :root:not([data-theme='light']) to prevent system dark preference from overriding an explicit user choice of light mode when JS has set the attribute. JS-disabled users still get dark mode correctly. Documentation: - Rename 3-progress-report.md → progress-report.md - Add Phase 4.1 completion details
Relocate Playwright e2e test suite from top-level e2e/ into src/test/e2e/ to align with existing test directory structure. Update testDir in playwright.config.ts accordingly.
Add 30 Mocha unit tests for ThemeManager covering all public methods and edge cases using JSDOM for browser environment simulation. New file (src/test/modules/themeManager.ts — 30 tests): - init(): saved preference, system preference, default fallback, idempotent - getCurrentTheme(): returns current theme, reads from DOM if not set - setTheme(): applies theme and persists, emits themeChange event, rejects invalid values, handles localStorage quota errors - applyTheme(): sets data-theme attribute, updates internal state - getSystemPreference(): detects dark/light, caches result, handles errors - hasSavedPreference(): checks localStorage key existence, handles errors - getSavedPreference(): reads valid values, rejects invalid, handles errors - emitThemeChange(): dispatches CustomEvent with theme detail - Invalid value fallback: init() with invalid stored value falls back correctly Dependencies: - jsdom (devDependency) for browser environment simulation Run with: npx ts-mocha src/test/modules/themeManager.ts --timeout 5000
Remove 12 documentation files that became inaccurate after Phase 3-4 changes (removed ThemeManager methods, color palette redesign, WCAG fixes, test moves). Deleted (outdated — referenced removed API methods, old color palette): - CHECKPOINT_REPORT.md, COMPLETION_SUMMARY.md, SESSION_COMPLETION.md - 1.1-theme-manager-foundation/ (3 files) — referenced onThemeToggle(), toggleTheme() - 1.2-css-variables-infrastructure/ (3 files) — old VS Code palette colors - 2.1-2.3-header-toggle-button/ (3 files) — referenced onThemeToggle() Kept (verified accurate): - 1.3-app-initialization/, 2.4-2.8 component docs — still correct - progress-report.md — authoritative doc (paths fixed: e2e/ → src/test/e2e/) - Requirements.md, Design.md, Tasks.md, README.md — spec docs
- ImplementationSummary.md: complete test suite overview, bugs found/fixed, WCAG fixes, palette redesign, database migration - QuickReference.md: test commands, file map, fixture helpers, color reference, WCAG thresholds, troubleshooting - TechnicalDeepDive.md: architecture, multi-browser config, WCAG calculation methodology, JSDOM setup, CSS specificity analysis, performance measurement, root cause analyses
…ENT.md) - README.md: Add dark mode to Features list - DEVELOPMENT.md: Add Prerequisites section with Node.js >= 18 requirement - DEVELOPMENT.md: Document nedb -> @seald-io/nedb migration (Node 24 compat) - DEVELOPMENT.md: Add Dark Mode section and Testing section - progress-report.md: Mark Phase 4.4 as done
…roving efficiency and readability. Update sidebar filter to handle navigation more robustly by ensuring the correct element is clicked.
…ine data structure. Update Twig template to handle depth-based indentation for improved clarity in dropdowns.
- Update Dockerfile.prod to use Node 20 with --ignore-engines for yarn installs - Update docker-compose.yml to build from local source with proper port mapping - Add docs-config.local.yaml with required port and configuration - Update PULL_REQUEST.md with Getting Started guide for yarn dev and Docker deployment - Document Node.js version requirements and --ignore-engines usage - Include database migration notes for nedb to @seald-io/nedb"
PR title: Fix deep page nesting in sidebar, prev/next order, and parent dropdown indent
Fix nested breadcrumbs
…omponent extraction
Hunta
added
documentation
Implementation SummaryThis PR implements the dark mode feature from the What was implemented
Additional changes included in this branch
Testing
Files changed (55)
Review checklist
|
Review of PR #1 - Dark Mode Implementation=== TASK INFO === === 1. ARCHITECTURE & DESIGN === PASS - CSS custom properties approach for theming is clean and maintainable. Using NOTE - The dark-mode.pcss file has duplicated color definitions in both === 2. ACCESSIBILITY (WCAG 2.1 AA) === PASS - Theme toggle uses semantic PASS - Keyboard accessibility verified: Enter and Space keys activate the toggle, Tab navigation tested, focus visibility checks included. PASS - SVG icons in the toggle button are handled correctly - the parent button's aria-label provides the accessible name for screen readers. NOTE - The SVG icons in theme-toggle.twig do not have === 3. CODE QUALITY === PASS - themeToggle.js: Properly integrates with ModuleDispatcher lifecycle. Listens for custom themeChange events. Handles missing DOM elements gracefully with console.warn. PASS - breadcrumbs.ts: Well-structured utility with clear TypeScript types. The collapseToFirstEllipsisCurrent function correctly limits breadcrumbs to 3 segments. PASS - Unit test suite (30 tests) uses JSDOM to isolate ThemeManager from Node.js globals. Each test gets a fresh environment. sinon stubs properly cleaned up in afterEach. PASS - E2E test suite (139 tests) covers all major scenarios: FOUC, persistence, system preference, accessibility, cross-browser, performance. === 4. SECURITY === PASS - The @seald-io/nedb migration maintains the same security posture as the original nedb package. No new attack surface introduced. NOTE - The === 5. TESTING === PASS - Tests cover edge cases: localStorage unavailability, invalid saved values, rapid toggles, cross-browser compatibility, performance metrics. PASS - FOUC tests verify that NOTE - The unit test suite inlines a copy of the ThemeManager class (lines 38-108 in themeManager.ts test file) rather than importing the actual module. This is necessary due to ESM import issues with the singleton export, but it creates a test-to-production code drift risk. Consider exporting a factory function instead of a singleton to make testing more straightforward. === 6. DOCKER & DEPLOYMENT === PASS - Production image only copies necessary artifacts (prod_node_modules, dist, public). === 7. BUGS & CONCERNS === BUG-1 (low severity): BUG-2 (low severity): BUG-3 (UX concern): The breadcrumb collapse logic ( === VERDICT: APPROVED === This is a well-executed, comprehensive dark mode implementation. The accessibility compliance is thorough, the testing is extensive, and the code quality is high. The nedb migration is clean and the FOUC prevention approach is correct. Recommendations for follow-up:
|
|
[TEST] Governance verification test - please ignore |
2 participants
Overview
Complete dark mode implementation with theme persistence, system preference detection, and full accessibility compliance (WCAG 2.1 AA).
Branch:
feature/dark-modeStatus: Ready for review
Files changed: 55 files, 6300 insertions, 1602 deletions
Commits: 49 (includes merge of main, nested breadcrumbs fix, deep page nesting refactor)
Architecture
ThemeManager Module
codex-docs-themepersists user preferenceprefers-color-schememedia query for system preferencethemeChangeevent for reactive module updatesCSS Variables System
:rootselector invars.pcss(default)[data-theme="dark"]selector indark-mode.pcss@media (prefers-color-scheme: dark)fallbackTheme Toggle UI
theme-toggle.twig)Files Created
src/frontend/js/modules/themeManager.js— Theme management singletonsrc/frontend/js/modules/themeToggle.js— Toggle interaction handlersrc/frontend/styles/dark-mode.pcss— Dark theme CSS variables (Tailwind zinc palette)src/backend/views/components/theme-toggle.twig— Twig template componentsrc/backend/utils/breadcrumbs.ts— Page breadcrumb utility (new)playwright.config.ts— Multi-browser test configurationsrc/test/e2e/dark-mode/*.spec.ts— E2E test suite (7 files, 139 tests)src/test/modules/themeManager.ts— Unit tests (30 tests)codex.docs.code-workspace— VS Code workspace config.github/specs/dark-mode/DarkMode.md— Implementation specFiles Modified
src/frontend/js/app.js— Import and initialize ThemeManager firstsrc/frontend/styles/vars.pcss— Light theme color definitionssrc/frontend/styles/components/header.pcss— Header dark mode + toggle stylessrc/frontend/styles/components/sidebar.pcss— Sidebar dark modesrc/frontend/styles/components/page.pcss— Page dark mode + breadcrumb navsrc/frontend/styles/components/writing.pcss— Writing header dark modesrc/frontend/styles/components/diff.pcss— Diff colors via CSS variablessrc/frontend/styles/components/copy-button.pcss— Copy button dark modesrc/frontend/styles/components/navigator.pcss— Navigator dark modesrc/backend/database/local.ts— Migrated to@seald-io/nedbfor Node 24 compatibilitysrc/backend/models/page.ts— AddedgetAncestorChain()methodsrc/backend/models/pagesFlatArray.ts— Updated nesting limit docssrc/backend/routes/aliases.ts— Added breadcrumb importsrc/backend/routes/index.ts— Fixed middleware orderingsrc/backend/routes/pages.ts— Added breadcrumb integrationsrc/backend/views/components/header.twig— Added theme toggle, breadcrumbssrc/backend/views/components/sidebar-section.twig— New sidebar section componentsrc/backend/views/components/sidebar.twig— Refactored sidebar structuresrc/backend/views/pages/page.twig— Added breadcrumb navigationsrc/backend/views/pages/form.twig— Updated parent select optionspackage.json— Version bump 2.2.4 -> 2.3.1, new scripts, new depsdocker-compose.yml— Build from Dockerfile.proddocker/Dockerfile.prod— Updated to Node 20DEVELOPMENT.md— Updated prerequisites and NeDB migration noteREADME.md— Added dark mode feature badgeyarn.lock— Updated dependenciesBug Fixes
themeChangeeventwhitebackgroundsvar(--color-bg-main)main.bundle.jsto login templatealias.save()not awaitedawaitkeywordutil.isDateremoved from Node 24@seald-io/nedbforkWCAG AA Compliance
All color contrast ratios meet WCAG AA standards:
Testing Coverage
Color Palette
Final zinc-based palette (WCAG AA compliant):
#18181B#27272A#71717A#E4E4E7Browser Support
prefers-color-schemesupportAdditional Changes in This Branch
This branch also includes: