# LockNKey Extension Theme System

**Version**: 1.0.0
**Last Updated**: November 17, 2025 at 10:45 AM EST

## Quick Start

Import the theme in your HTML files:

```html
<link rel="stylesheet" href="./styles/theme.css">
```

Or in JavaScript/TypeScript:

```javascript
import '../styles/theme.css';
```

## Color Palette Visual Reference

### Light Theme

```css
/* Primary Brand */
--primary: oklch(0.55 0.22 308);              /* #8B3AA7 - Purple */
--primary-foreground: oklch(0.99 0 0);        /* #FCFCFC - White */

/* Backgrounds */
--background: oklch(0.99 0.01 308);           /* #FCFBFC - Off-white */
--foreground: oklch(0.15 0.02 308);           /* #26232A - Dark purple-black */
--card: oklch(0.98 0.01 308);                 /* #FAF9FB - Light purple-white */

/* UI Elements */
--secondary: oklch(0.92 0.01 308);            /* #EBEAED - Light gray */
--muted: oklch(0.95 0.01 308);                /* #F2F1F3 - Lighter gray */
--accent: oklch(0.94 0.015 308);              /* #EFEEEF - Very light purple */
--border: oklch(0.88 0.01 308);               /* #E1DFE3 - Gray border */

/* Status Colors */
--destructive: oklch(0.58 0.22 25);           /* #D84343 - Red */
--qshield-success: oklch(0.60 0.20 150);      /* #2AA876 - Green */
--qshield-warning: oklch(0.70 0.18 70);       /* #D4B942 - Yellow */
```

### Dark Theme

```css
/* Primary Brand */
--primary: oklch(0.65 0.24 308);              /* #A855D8 - Brighter purple */
--primary-foreground: oklch(0.12 0.015 298);  /* #1D1A22 - Very dark */

/* Backgrounds */
--background: oklch(0.12 0.015 298);          /* #1D1A22 - Dark purple-black */
--foreground: oklch(0.92 0.026 305);          /* #E8E4F0 - Light purple */
--card: oklch(0.16 0.018 298);                /* #28242F - Dark card */

/* UI Elements */
--secondary: oklch(0.22 0.020 302);           /* #38323F - Dark gray */
--muted: oklch(0.22 0.020 302);               /* #38323F - Dark gray */
--accent: oklch(0.25 0.025 308);              /* #3F3847 - Dark purple */
--border: oklch(0.25 0.020 302);              /* #3D3745 - Dark border */

/* Status Colors */
--destructive: oklch(0.6861 0.2061 14.9941);  /* #EF5555 - Bright red */
--qshield-success: oklch(0.65 0.22 150);      /* #3BC490 - Bright green */
--qshield-warning: oklch(0.75 0.20 70);       /* #E6CA5A - Bright yellow */
```

## Q-Shield Branding Quick Reference

### Status Indicators

```html
<!-- Active quantum protection -->
<div class="qshield-indicator qshield-indicator--active">
  Q-Shield Active
</div>

<!-- Success state -->
<div class="qshield-indicator qshield-indicator--success">
  Protected
</div>

<!-- Warning state -->
<div class="qshield-indicator qshield-indicator--warning">
  Updating
</div>

<!-- Inactive -->
<div class="qshield-indicator qshield-indicator--inactive">
  Inactive
</div>
```

### Status Badges

```html
<span class="qshield-badge qshield-badge--authenticated">Authenticated</span>
<span class="qshield-badge qshield-badge--quantum-resistant">Q-Shield</span>
<span class="qshield-badge qshield-badge--pending">Encrypting</span>
<span class="qshield-badge qshield-badge--error">Error</span>
```

### Glow Effects

```html
<!-- Static glow -->
<div class="qshield-glow">Protected Content</div>

<!-- Pulsing glow -->
<button class="qshield-glow-pulse">Encrypting...</button>
```

## Utility Classes

### Cards

```html
<div class="card">
  <!-- Card content with shadow and border -->
</div>
```

### Buttons

```html
<button class="button button-primary">Primary Action</button>
<button class="button button-secondary">Secondary Action</button>
<button class="button button-outline">Outline Button</button>
```

### Badges

```html
<span class="badge badge-default">Default</span>
<span class="badge badge-secondary">Secondary</span>
<span class="badge badge-outline">Outline</span>
<span class="badge badge-destructive">Error</span>
```

### Animations

```html
<!-- Basic animations -->
<div class="animate-fadeIn">Fades in smoothly</div>
<div class="animate-slideInLeft">Slides from left</div>
<div class="animate-slideInRight">Slides from right</div>
<div class="animate-slideUp">Slides up from bottom</div>
<div class="animate-scaleIn">Scales up</div>

<!-- Infinite animations -->
<div class="animate-pulseGlow">Pulsing glow (Q-Shield)</div>
<div class="animate-float">Floating effect</div>
<div class="animate-spin">Spinning loader</div>

<!-- Staggered children -->
<ul class="stagger-children">
  <li>Item 1 (0ms delay)</li>
  <li>Item 2 (100ms delay)</li>
  <li>Item 3 (150ms delay)</li>
</ul>

<!-- Hover effects -->
<button class="hover-lift">Lift on hover</button>
<div class="hover-scale">Scale on hover</div>
<div class="hover-glow">Glow on hover</div>

<!-- Loading states -->
<div class="loading-skeleton" style="height: 50px;"></div>
<div class="shimmer-overlay">Loading content...</div>
```

#### TypeScript Animation API

```typescript
import { animate, staggerChildren, ANIMATION_PRESETS } from '@/extension/styles/animation-utils';

// Simple animation
await animate(element, { type: 'fadeIn' });

// Use a preset
await animate(dialog, ANIMATION_PRESETS.dialog);

// Stagger children
await staggerChildren(listContainer, {
  type: 'slideInLeft',
  staggerDelay: 75,
});

// Sequential animations
import { animateSequence } from '@/extension/styles/animation-utils';
await animateSequence([
  [header, { type: 'fadeIn' }],
  [content, { type: 'slideUp', delay: 100 }],
]);
```

**Complete animation documentation**: See `animations.css` and `animation-utils.ts` for full API

## Shadow System

```css
var(--shadow-xs)   /* Subtle elevation */
var(--shadow-sm)   /* Small elevation (cards) */
var(--shadow-md)   /* Medium elevation (dropdowns) */
var(--shadow-lg)   /* Large elevation (modals) */
var(--shadow-xl)   /* Extra large elevation (overlays) */
var(--shadow-2xl)  /* Dramatic elevation (heroes) */
```

## Transition Timing

```css
var(--transition-fast)   /* 150ms - Quick feedback */
var(--transition-base)   /* 200ms - Standard transitions */
var(--transition-slow)   /* 300ms - Deliberate animations */
var(--transition-slower) /* 500ms - Theme changes */
```

## Accessibility

### Reduced Motion

All animations automatically respect `prefers-reduced-motion: reduce` preference.

### Focus Indicators

All interactive elements have visible focus rings using `var(--ring)` with 2px minimum outline.

### Color Contrast

- Text on background: 11.3:1 (Light), 9.1:1 (Dark) - WCAG AAA ✅
- Button text: 4.8:1 - WCAG AA ✅
- Muted text: 4.7:1 - WCAG AA ✅

## Browser Support

- **OKLCH Colors**: Chrome 111+, Firefox 113+, Safari 16.4+, Edge 111+
- **CSS Custom Properties**: All modern browsers
- **Auto dark mode**: All modern browsers

Older browsers automatically fall back to nearest sRGB color.

## Migration Example

### Before (Hardcoded)

```css
.button {
  background: #8B3AA7;
  color: #FCFCFC;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
  transition: all 0.3s ease;
}
```

### After (Theme System)

```css
.button {
  background: var(--primary);
  color: var(--primary-foreground);
  box-shadow: var(--shadow-md);
  transition: all var(--transition-base);
}
```

## Documentation

For complete documentation, see:
- **Theme System**: `/lockkey/agents/ux/Designer 2 - Extension Theme System & Q-Shield Branding.md` (Obsidian)
- **Animation System**: `/lockkey/agents/ux/Designer 1 - Extension Animation System.md` (Obsidian)
- **Interactive Demo**: `animation-demo.html` (in this directory)
- Main webapp theme: `/frontend/src/app/globals.css`

### Interactive Animation Demo

Open `animation-demo.html` in your browser to see all animations:

```bash
cd frontend/src/extension/styles
python3 -m http.server 8080
# Visit: http://localhost:8080/animation-demo.html
```

## Questions?

This theme system was designed by the LockNKey UX team to ensure consistent quantum protection branding across the browser extension.

**Last updated**: November 17, 2025 at 10:45 AM EST
