# Dark Mode Test Guide - Admin Interface

## Test Scenarios

### 1. Automatic Dark Mode Detection

**Test**: System preference detection
```html
<!-- Browser console test -->
window.matchMedia('(prefers-color-scheme: dark)').matches
// Should return true if system is in dark mode
```

**Expected Behavior**:
- When system is in dark mode and `data-theme="auto"` → Dark mode colors applied
- When system is in light mode and `data-theme="auto"` → Light mode colors applied
- CSS `@media (prefers-color-scheme: dark)` rules activate automatically

**Files to Check**:
- `resources/css/admin/01-settings/_tokens.css` (lines 126-163)
- `src/Application/Admin/templates/layouts/admin.view.php` (data-theme attribute)

### 2. Manual Theme Toggle

**Test**: User override of system preference
```javascript
// Theme toggle cycle: light → dark → auto → light
localStorage.getItem('admin-theme-preference')
```

**Expected Behavior**:
- Click theme toggle button cycles through: light → dark → auto
- Selection persists in localStorage as `admin-theme-preference`
- `data-theme` attribute updates on `<html>` element
- CSS tokens switch immediately without page reload

**Files to Check**:
- `src/Application/Admin/templates/layouts/admin.view.php` (lines 69-92)
- `src/Application/Admin/templates/components/header.component.php` (theme toggle button)

### 3. Component Color Testing

**Components to Test**:

#### Sidebar
- [ ] **Background**: oklch(15% 0.02 280) - Dark blue-gray
- [ ] **Text**: oklch(75% 0.02 280) - Light gray (8.9:1 contrast ✅)
- [ ] **Text Hover**: oklch(95% 0.01 280) - Near white
- [ ] **Active Link**: oklch(35% 0.2 280) - Darker accent blue
- [ ] **Border**: oklch(25% 0.02 280) - Subtle separation

**Test**: Navigate to all sidebar menu items, verify active state visibility

#### Header
- [ ] **Background**: oklch(18% 0.02 280) - Slightly lighter than sidebar
- [ ] **Text**: oklch(90% 0.01 280) - Light gray (13.2:1 contrast ✅)
- [ ] **Border**: oklch(30% 0.02 280) - Subtle bottom border
- [ ] **Search Input**: Background contrast with placeholder text
- [ ] **Dropdown Menus**: Visible borders and hover states

**Test**: Click all header buttons (search, notifications, user menu)

#### Content Area
- [ ] **Background**: oklch(20% 0.02 280) - Dark background
- [ ] **Text**: oklch(90% 0.01 280) - Light text (12.5:1 contrast ✅)
- [ ] **Cards**: Slight background contrast on hover
- [ ] **Links**: oklch(70% 0.2 260) - Blue links (6.2:1 contrast ✅)

**Test**: Scroll through content, hover cards, click links

#### Borders and Dividers
- [ ] **Light Borders**: oklch(42% 0.02 280) - 3.1:1 contrast ✅
- [ ] **Medium Borders**: oklch(48% 0.02 280) - 3.5:1 contrast ✅
- [ ] **Dark Borders**: oklch(55% 0.02 280) - 4.2:1 contrast ✅

**Test**: Check card borders, dividers, input borders are all visible

### 4. Accessibility Features in Dark Mode

#### Focus Indicators
- [ ] **Focus Ring**: oklch(70% 0.2 260) - Bright blue (6.2:1 contrast ✅)
- [ ] **Keyboard Navigation**: Tab through all interactive elements
- [ ] **Skip Link**: Verify visibility on focus

**Test**: Use keyboard only to navigate entire admin interface

#### Color-Blind Safe
- [ ] **Success States**: Green with checkmark icon (not just color)
- [ ] **Error States**: Red with warning icon (not just color)
- [ ] **Warning States**: Yellow with exclamation icon (not just color)
- [ ] **Info States**: Blue with info icon (not just color)

**Test**: View alerts/notifications, verify icons are present

#### Reduced Motion
- [ ] **Animation Disabled**: Check `prefers-reduced-motion: reduce` disables transitions
- [ ] **Smooth Scrolling**: Verify scroll-behavior respects preference

**Test**: Enable reduced motion in OS settings, reload page

### 5. Performance Testing

#### Initial Load
- [ ] **CSS File Size**: Verify admin.css includes dark mode tokens
- [ ] **No FOUC**: Flash of Unstyled Content should not occur
- [ ] **Theme Persistence**: Check localStorage loads before render

**Test**: Hard refresh (Ctrl+Shift+R) and measure time to styled content

#### Theme Switching
- [ ] **Instant Switch**: Theme change should be immediate (<50ms)
- [ ] **No Re-render**: Only CSS variables change, no HTML re-render
- [ ] **Smooth Transition**: Brief transition on theme change (0.2s)

**Test**: Rapidly toggle theme, check for visual glitches

### 6. Cross-Browser Testing

**Browsers to Test**:
- [ ] **Chrome/Edge**: Full OKLCH support (native)
- [ ] **Firefox**: OKLCH support (recent versions)
- [ ] **Safari**: OKLCH support (Safari 15.4+)

**OKLCH Fallbacks**:
If browser doesn't support OKLCH, colors should gracefully degrade.

**Test**: Load in each browser, verify colors render correctly

### 7. Contrast Edge Cases

**High Contrast Mode**:
- [ ] **Windows High Contrast**: Test forced colors mode
- [ ] **Border Visibility**: All UI elements should have visible borders
- [ ] **Icon Visibility**: Icons should be visible in high contrast

**Test**: Enable Windows High Contrast mode, verify UI is usable

### 8. Real-World Usage Testing

**Long-Form Content**:
- [ ] **Reading Comfort**: Extended text reading in dark mode
- [ ] **Eye Strain**: Test for 30+ minutes of use
- [ ] **Color Fatigue**: Check if accent colors are too bright

**Test**: Use admin interface for real tasks, note any discomfort

**Data Visualization**:
- [ ] **Tables**: Row striping visible
- [ ] **Charts**: Colors distinguishable
- [ ] **Status Badges**: Clear color differentiation

**Test**: View tables, charts, status indicators in dark mode

## Known Issues and Limitations

### OKLCH Browser Support
**Issue**: Older browsers may not support OKLCH colors
**Mitigation**: Modern browsers (2023+) have full support. Consider RGB fallbacks for legacy support.
**Status**: ⚠️ Monitor browser compatibility

### Color Consistency Across Displays
**Issue**: OKLCH colors may appear different on various monitor calibrations
**Mitigation**: Test on multiple displays with different color profiles
**Status**: ⚠️ User testing required

### System Theme Detection
**Issue**: Some Linux desktop environments may not report dark mode preference correctly
**Mitigation**: Manual theme toggle always available
**Status**: ⚠️ Provide manual override (already implemented ✅)

## Testing Checklist

### Before Release
- [ ] All contrast ratios verified with automated tools (Lighthouse, axe DevTools)
- [ ] Manual keyboard navigation test completed
- [ ] Cross-browser testing completed (Chrome, Firefox, Safari)
- [ ] Dark mode tested on actual devices (desktop, tablet, mobile)
- [ ] User testing with visually impaired users
- [ ] Performance benchmarks met (theme switch <50ms)
- [ ] No console errors when toggling theme
- [ ] localStorage persistence working correctly

### Post-Release Monitoring
- [ ] Track user theme preferences (analytics)
- [ ] Monitor browser console for OKLCH errors
- [ ] Collect user feedback on dark mode usability
- [ ] A/B test different accent color brightness levels

## Automated Testing Script

```javascript
// Dark Mode Automated Test Suite
describe('Dark Mode Functionality', () => {
    it('should apply dark mode colors when data-theme="dark"', () => {
        document.documentElement.setAttribute('data-theme', 'dark');

        const computedStyle = getComputedStyle(document.documentElement);
        const bgPrimary = computedStyle.getPropertyValue('--admin-bg-primary');

        expect(bgPrimary).toContain('oklch(20%'); // Dark background
    });

    it('should persist theme preference to localStorage', () => {
        const themeToggle = document.querySelector('[data-theme-toggle]');
        themeToggle.click();

        const storedTheme = localStorage.getItem('admin-theme-preference');
        expect(storedTheme).toBeTruthy();
    });

    it('should have sufficient contrast ratios', () => {
        // Use contrast calculation algorithm
        const textColor = 'oklch(90% 0.01 280)'; // Light text
        const bgColor = 'oklch(20% 0.02 280)'; // Dark background

        const ratio = calculateContrastRatio(textColor, bgColor);
        expect(ratio).toBeGreaterThan(4.5); // WCAG AA for normal text
    });
});
```

## Manual Test Results Log

**Test Date**: _____________________
**Tester**: _____________________
**Browser/OS**: _____________________

| Test Scenario | Pass/Fail | Notes |
|---------------|-----------|-------|
| System preference detection | ☐ Pass ☐ Fail | |
| Manual theme toggle | ☐ Pass ☐ Fail | |
| Sidebar colors | ☐ Pass ☐ Fail | |
| Header colors | ☐ Pass ☐ Fail | |
| Content area colors | ☐ Pass ☐ Fail | |
| Border visibility | ☐ Pass ☐ Fail | |
| Focus indicators | ☐ Pass ☐ Fail | |
| Keyboard navigation | ☐ Pass ☐ Fail | |
| Color-blind safe | ☐ Pass ☐ Fail | |
| Reduced motion | ☐ Pass ☐ Fail | |
| Performance | ☐ Pass ☐ Fail | |
| Cross-browser | ☐ Pass ☐ Fail | |

**Overall Assessment**: ☐ Ready for Release ☐ Needs Fixes

**Critical Issues Found**:
1. _____________________
2. _____________________
3. _____________________

**Recommendations**:
_____________________
_____________________
_____________________
