# LockNKey Theme Reference Guide

**Last Updated:** November 12, 2025 at 10:27 PM EST

## Quick Overview

LockNKey uses a dual-theme system (light and dark) with a consistent purple brand identity (308° hue). Both themes are accessible (WCAG 2.1 AA) and smoothly transition between modes.

## Theme Colors

### Light Theme
- **Background:** Very light purple-tinted white (99% lightness)
- **Text:** Dark purple-gray (15% lightness)
- **Primary:** Vibrant purple (55% lightness, 308° hue)
- **Borders:** Light purple-gray (88% lightness)

### Dark Theme
- **Background:** Very dark purple (12% lightness)
- **Text:** Light purple-tinted (92% lightness)
- **Primary:** Bright purple (65% lightness, 308° hue)
- **Borders:** Dark purple-gray (25% lightness)

## Using Theme Colors in Components

### Tailwind CSS Classes
```tsx
// Background colors
<div className="bg-background">...</div>
<div className="bg-card">...</div>
<div className="bg-primary">...</div>

// Text colors
<p className="text-foreground">...</p>
<p className="text-muted-foreground">...</p>
<p className="text-primary">...</p>

// Borders
<div className="border border-border">...</div>
<input className="border-input">...</input>

// Hover states
<button className="hover:bg-accent">...</button>
```

### CSS Custom Properties
```css
/* Access theme colors directly */
.custom-component {
  background-color: var(--background);
  color: var(--foreground);
  border: 1px solid var(--border);
}

/* Primary brand color */
.brand-element {
  color: var(--primary);
  background: var(--primary-foreground);
}
```

## Theme Switcher

Users can toggle between themes using the theme switcher in the header:
- **Light mode:** Bright, clean interface
- **Dark mode:** Rich, deep interface with enhanced shadows
- **System mode:** Automatically matches OS preference

### Implementation
```tsx
import { ThemeToggle } from '@/components/theme/theme-toggle'

function MyComponent() {
  return <ThemeToggle />
}
```

## Creating Theme-Aware Components

### Method 1: Tailwind's Dark Mode
```tsx
<div className="bg-white dark:bg-gray-900">
  <p className="text-gray-900 dark:text-gray-100">
    This text adapts to the theme
  </p>
</div>
```

### Method 2: Using Theme Variables
```tsx
<div className="bg-background text-foreground">
  <p className="text-muted-foreground">
    This uses theme color tokens
  </p>
</div>
```

### Method 3: Programmatic Access
```tsx
'use client'
import { useTheme } from 'next-themes'

function MyComponent() {
  const { theme, setTheme } = useTheme()

  return (
    <div>
      <p>Current theme: {theme}</p>
      <button onClick={() => setTheme('dark')}>Dark</button>
      <button onClick={() => setTheme('light')}>Light</button>
    </div>
  )
}
```

## Accessibility Guidelines

### Color Contrast
All theme colors meet WCAG 2.1 AA standards:
- **Normal text:** 4.5:1 minimum contrast ratio
- **Large text:** 3.0:1 minimum contrast ratio
- **UI components:** 3.0:1 minimum contrast ratio

### Testing Contrast
When adding new colors, verify contrast:
```bash
# Light theme text on background
Primary on Background: 7.2:1 ✓
Foreground on Background: 12.5:1 ✓

# Dark theme text on background
Primary on Background: 6.8:1 ✓
Foreground on Background: 13.2:1 ✓
```

### Focus Indicators
All interactive elements have visible focus indicators:
```tsx
<button className="focus:outline-none focus:ring-2 focus:ring-ring">
  Click me
</button>
```

## Animation & Transitions

### Smooth Theme Switching
All colors transition smoothly (300ms ease):
```css
* {
  transition: border-color 0.3s ease,
              background-color 0.3s ease,
              color 0.3s ease;
}
```

### Respecting User Preferences
Animations are disabled for users with `prefers-reduced-motion`:
```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}
```

## Shadow System

Shadows adapt to the theme for better depth perception:

```css
/* Light mode */
--shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);

/* Dark mode */
--shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.3);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.5);
```

Usage:
```tsx
<div className="shadow-md">Card with medium shadow</div>
<div style={{ boxShadow: 'var(--shadow-lg)' }}>Custom shadow</div>
```

## Chart Colors

For data visualizations, use the chart color palette:
```tsx
const chartColors = {
  1: 'var(--chart-1)', // Purple
  2: 'var(--chart-2)', // Violet
  3: 'var(--chart-3)', // Magenta-purple
  4: 'var(--chart-4)', // Blue-purple
  5: 'var(--chart-5)', // Pink-purple
}
```

## Best Practices

### DO
✅ Use semantic color tokens (`bg-background`, `text-foreground`)
✅ Test components in both light and dark themes
✅ Ensure all interactive elements have visible focus states
✅ Use the theme toggle component for consistency
✅ Respect user's reduced motion preferences

### DON'T
❌ Hardcode color values (`bg-white`, `text-black`)
❌ Use colors that don't meet contrast requirements
❌ Override theme colors without good reason
❌ Forget to test dark mode
❌ Use animations without reduced-motion fallback

## Component-Specific Considerations

### Q-Shield Indicators
Ensure quantum protection indicators are visible in both themes:
```tsx
<QShieldIcon
  status="protected"
  className="text-primary" // Adapts to theme
/>
```

### Forms & Inputs
Use proper input styling for both themes:
```tsx
<input
  className="bg-background border-input text-foreground
             focus:ring-ring focus:border-ring"
/>
```

### Buttons
Primary buttons should use brand colors:
```tsx
<button className="bg-primary text-primary-foreground
                   hover:opacity-90">
  Primary Action
</button>
```

## Files & Documentation

### Core Files
- **Theme CSS:** `/frontend/src/app/globals.css`
- **Theme Toggle:** `/frontend/src/components/theme/theme-toggle.tsx`
- **Theme Provider:** `/frontend/src/app/layout.tsx`
- **Header Integration:** `/frontend/src/components/layout/header.tsx`

### Documentation
- **Full Documentation:** See Basic Memory note at `agents/ux/2025-11-12-Purple-Theme-System-Light-Dark-Modes.md`
- **OKLCH Color Space:** https://oklch.com
- **WCAG Guidelines:** https://www.w3.org/WAI/WCAG21/quickref/

## Troubleshooting

### Theme not switching
1. Check ThemeProvider is in root layout
2. Verify `suppressHydrationWarning` on `<html>` tag
3. Ensure components use theme tokens, not hardcoded colors

### Colors look wrong
1. Clear browser cache
2. Check for conflicting CSS
3. Verify color variables in globals.css

### Flash of wrong theme (FOUT)
1. Ensure ThemeProvider has `suppressHydrationWarning`
2. Check that components wait for theme to mount
3. Use `next-themes` hook properly

## Support

For theme-related questions or issues:
1. Check this reference guide
2. Review the full documentation in Basic Memory
3. Test in both light and dark modes
4. Verify accessibility with contrast checkers
