# THEME SWITCHER IMPLEMENTATION NOTES — KEVRON SUITES AND APARTMENTS This document details the pre-development audit, architecture design, and final quality assurance checklist for the implementation of the **Global Multi-Coloured Theme System & Switcher** across the entire Kevron Suites and Apartments website. --- ## 1. PRE-DEVELOPMENT AUDIT & FINDINGS ### 1.1 Current Theme Issues & Hardcoded Colours * **Static Dark Mode**: The existing script in `layouts/app.blade.php` only parses `color-theme` from `localStorage` or matches the user's OS preference (`prefers-color-scheme`). There is no multi-coloured accent theme selector or database persistence mechanism. * **Hardcoded Tailwind Colors**: * Many Blade files contain hardcoded CSS class properties, such as `bg-[#080D2B]` (Midnight Navy), `text-[#D6A84F]` (Champagne Gold), and `bg-[#F4F8FF]` (Soft Ice Blue). * These components do not dynamically update when changing the brand accent color set. * **Logo Visibility**: The logo image is loaded statically as `pictures/kevron-logo.png`. Under pure dark mode (Midnight Navy or black), a custom light/dark SVG outline or tailored styling is required to keep it extremely readable. * **Components Ignoring Themes**: * *Virtual Tour*: Custom hotspots are styled with fixed `#D6A84F` (Champagne Gold) highlight rings and border frames. * *Booking Widgets & Date Pickers*: Livewire form inputs and selection states are locked to the default `#2B3192` (Kevron Royal Blue). * *Scrollbars*: The browser's native scrollbar is either default or styled statically with `#2B3192` in `app.css`. ### 1.2 Contrast & Accessibility Risks * **Contrast Hazards**: Certain theme/accent combinations (e.g. Amber text on light blue backgrounds or Cyan highlight on Cloud White) may violate WCAG 2.2 AA standards (requiring >= 4.5:1 ratio for normal text). Accent styles must adapt background/text layers dynamically. * **Keyboard Operability**: Swatches inside dropdown lists are often non-interactive divs or lack ARIA attributes, making them inaccessible to screen readers and keyboard-only users. * **Reduced-Motion Override**: Theme transitions (e.g., color morphing or dropdown sliding) do not currently respect `prefers-reduced-motion` settings. ### 1.3 Mobile & Interface Issues * **Touch Targets**: Small swatch buttons in the header utility bar are below the minimum 44px touch target requirement. * **Layout Shift**: Fast theme switching or late script execution triggers a visible page flash (FOIT/FLUT), degrading the luxury first impression. --- ## 2. PROPOSED THEME ARCHITECTURE ### 2.1 CSS Custom Properties (Tokens) We will leverage CSS variables on the `` element bound to semantic utility tokens: ```css :root[data-theme-mode="light"] { --ka-bg: #FFFFFF; --ka-bg-soft: #F4F8FF; --ka-surface: #FFFFFF; --ka-surface-hover: #EEF5FF; --ka-text: #172033; --ka-text-muted: #64748B; --ka-border: #DDE6F3; } :root[data-theme-mode="dark"] { --ka-bg: #080D2B; --ka-bg-soft: #0E1643; --ka-surface: #0E1643; --ka-surface-hover: #172060; --ka-text: #F4F8FF; --ka-text-muted: #94A3B8; --ka-border: #1E293B; } /* Accent Color Variations */ :root[data-ka-accent="royal"] { --ka-primary: #2B3192; --ka-primary-hover: #242A7C; --ka-secondary: #1FADEA; --ka-luxury: #D6A84F; --ka-scrollbar: #2B3192; --ka-gradient-start: #2B3192; --ka-gradient-end: #1FADEA; } :root[data-ka-accent="cyan"] { --ka-primary: #1FADEA; --ka-primary-hover: #158FCA; --ka-secondary: #2B3192; --ka-luxury: #D6A84F; --ka-scrollbar: #1FADEA; --ka-gradient-start: #1FADEA; --ka-gradient-end: #2B3192; } :root[data-ka-accent="gold"] { --ka-primary: #D6A84F; --ka-primary-hover: #C09540; --ka-secondary: #2B3192; --ka-luxury: #1FADEA; --ka-scrollbar: #D6A84F; --ka-gradient-start: #D6A84F; --ka-gradient-end: #2B3192; } :root[data-ka-accent="navy"] { --ka-primary: #080D2B; --ka-primary-hover: #040718; --ka-secondary: #1FADEA; --ka-luxury: #D6A84F; --ka-scrollbar: #080D2B; --ka-gradient-start: #080D2B; --ka-gradient-end: #1FADEA; } :root[data-ka-accent="emerald"] { --ka-primary: #16A34A; --ka-primary-hover: #15803d; --ka-secondary: #2B3192; --ka-luxury: #D6A84F; --ka-scrollbar: #16A34A; --ka-gradient-start: #16A34A; --ka-gradient-end: #2B3192; } :root[data-ka-accent="amber"] { --ka-primary: #F59E0B; --ka-primary-hover: #d97706; --ka-secondary: #2B3192; --ka-luxury: #D6A84F; --ka-scrollbar: #F59E0B; --ka-gradient-start: #F59E0B; --ka-gradient-end: #2B3192; } ``` ### 2.2 Dynamic Tailwind Integration We will configure semantic utilities inside `resources/css/app.css` using modern Tailwind source bindings or direct custom property utility class hooks: * `bg-theme` mapped to `var(--ka-bg)` * `bg-theme-soft` mapped to `var(--ka-bg-soft)` * `bg-surface` mapped to `var(--ka-surface)` * `text-theme` mapped to `var(--ka-text)` * `text-muted` mapped to `var(--ka-text-muted)` * `border-theme` mapped to `var(--ka-border)` * `bg-primary` mapped to `var(--ka-primary)` * `text-primary` mapped to `var(--ka-primary)` --- ## 3. FINAL QA & VERIFICATION CHECKLIST ### 3.1 Appearance & Accent Mode Core Matrix - [ ] **Light Mode**: cloud white backgrounds, strong charcoal text, slate-grey borders, legible contrasting elements. - [ ] **Dark Mode**: layered midnight navy tones, light readable gray/white text, visible contrast, and clear logo treatment. - [ ] **System Mode**: automatically resolves to OS appearance and updates on real-time OS theme toggle. - [ ] **Royal Blue Accent**: uses royal blue primary hooks with cyan and gold highlights. - [ ] **Sky Cyan Accent**: uses cyan primary hooks. - [ ] **Champagne Gold Accent**: uses gold primary hooks. - [ ] **Midnight Navy Accent**: uses midnight navy primary hooks. - [ ] **Emerald Stay Accent**: uses emerald green primary hooks. - [ ] **Warm Amber Accent**: uses warm amber primary hooks. ### 3.2 Switcher UI & Integrations - [ ] **Desktop Header**: interactive dropdown/popover panel showing swatches and icons with clear focus states. - [ ] **Mobile Drawer**: full-width accordion control panel blocks. - [ ] **Footer bottom bar**: settings triggers or compact switcher overlay. - [ ] **Guest Dashboard**: layout and service components adapt fully to selected preferences. - [ ] **Anti-Flash Pre-render**: Zero visual layout shifting or background blinking during initial page rendering. - [ ] **Reduced-motion compatibility**: Theme transitions respect user system settings. - [ ] **Filament Administrative Control**: Settings managers and swatch lists configure default preferences seamlessly. --- ## 4. DATABASE & MODEL DETAILS * `theme_settings`: Regulates public switcher visibility, user preferences toggles, default mode and default accent. * `accent_themes`: Holds active hex settings, names, and custom overrides for the six brand themes. * `user_theme_preferences`: Persists preferences linked to authenticated profiles. * `theme_audit_logs`: Logs any changes executed in administrative panels.