feat(theme): FE-37 Chessboard Theme Studio with Real-time Palette Customizer

[kaizercodes]

Overview

Implements the Chessboard Theme Studio in AppearanceSettings.tsx, featuring 6 curated theme presets, a 4-color custom palette picker, real-time WCAG contrast ratio calculations with accessibility warnings, a live interactive preview board, persistent storage, and backend profile synchronization.

Related Issue

Closes #1035

Changes

Frontend Theme System & Settings

• [MODIFY] frontend/context/ThemeContext.tsx
  • Added 6 curated preset themes (emerald, wood, obsidian, neon, classic_blue, bordeaux) and mapped legacy themes for full backwards compatibility.
  • Added custom 4-color palette state (light, dark, selected, lastMove).
  • Added WCAG relative luminance and contrast ratio utilities (calculateContrastRatio, getContrastEvaluation).
  • Implemented dynamic CSS variables synchronization on document.documentElement (--board-light, --board-dark, --board-selected, --board-last-move).
  • Implemented localStorage persistence and automatic backend profile synchronization.
• [MODIFY] frontend/components/AppearanceSettings.tsx
  • Transformed into a full Theme Studio featuring preset selection chips with swatch previews.
  • Added Custom Palette builder with color pickers, hex inputs, and live contrast evaluation meter.
  • Added live interactive preview chessboard allowing real-time square selection and last-move testing.
  • Added reset to defaults action and cloud synchronization status indicator.
• [MODIFY] frontend/components/chess/ChessboardComponent.tsx
  • Integrated dynamic colors.selected and colors.lastMove highlighting.
  • Added support for optional lastMove coordinates without layout reflows.
• [MODIFY] frontend/app/globals.css
  • Declared CSS custom properties --board-light, --board-dark, --board-selected, and --board-last-move on :root and .dark.
• [MODIFY] frontend/lib/api.ts
  • Added profile endpoints for user preference and appearance theme synchronization.
• [NEW] frontend/services/themeService.ts
  • Implemented resilient backend synchronization service with offline and guest fallback.
• [NEW] frontend/__tests__/appearance.test.ts / frontend/__tests__/appearance.test.tsx
  • Added 15 comprehensive unit and component tests covering presets, custom palette, contrast calculations, storage persistence, and UI interactions.

Verification Results

✓ __tests__/appearance.test.tsx (15 tests)
✓ components/__tests__/accessibility.test.tsx (34 tests)
✓ __tests__/useSpectatorSocket.test.ts (6 tests)
✓ __tests__/useEloStats.test.ts (4 tests)
✓ __tests__/spectatorUtils.test.ts (9 tests)
✓ __tests__/eloStatsUtils.test.ts (19 tests)
✓ __tests__/eloService.test.ts (5 tests)
✓ __tests__/cheatDetection.test.ts (18 tests)

Test Files  11 passed (11)
Tests       144 passed (144)

Acceptance Criteria	Status
Switching presets updates board instantly across the entire application	✅ Verified via ThemeContext & CSS variables
Custom hex colors apply correctly with sufficient contrast warnings	✅ Verified with WCAG AA/AAA meter and warning banner
Theme persists across browser reloads	✅ Verified with localStorage persistence tests
Component tests test theme selection and storage persistence	✅ Verified with 15 dedicated appearance unit & component tests
Minimum contrast enforced / identical colors prohibited	✅ Verified with contrast ratio validator preventing identical colors
Zero layout reflows during theme switching	✅ Verified with CSS transitions and custom properties

[drips-wave]

@Kaizer4show Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits