# LockNKey Design Tokens

Design system foundation for LockNKey quantum-resistant password manager.

**Last Updated**: November 12, 2025 at 9:44 PM EST

---

## Typography

### Font Families

LockNKey uses a three-font system optimized for accessibility and readability:

#### 1. Geist Sans (Primary)
- **Usage**: UI text, body content, buttons, labels
- **Variable**: `--font-geist-sans`
- **Tailwind Class**: `font-sans`
- **Characteristics**: Clean, modern, highly legible at all sizes

```tsx
// Example usage
<h1 className="font-sans text-4xl">Welcome to LockNKey</h1>
<p className="font-sans text-base">Your quantum-secure password manager</p>
```

#### 2. Geist Mono (Code & Technical)
- **Usage**: Password displays, code snippets, technical data, monospace content
- **Variable**: `--font-geist-mono`
- **Tailwind Class**: `font-mono`
- **Characteristics**: Fixed-width, excellent for code and data alignment

```tsx
// Example usage
<code className="font-mono text-sm">X7k$mP9#qL2@</code>
<pre className="font-mono">{JSON.stringify(data, null, 2)}</pre>
```

#### 3. Source Serif 4 (Editorial)
- **Usage**: Headings, hero text, marketing content, emphasis
- **Variable**: `--font-serif`
- **Tailwind Class**: `font-serif`
- **Weights**: 400 (Regular), 600 (SemiBold), 700 (Bold)
- **Characteristics**: Elegant, professional, adds visual hierarchy

```tsx
// Example usage
<h1 className="font-serif font-bold text-5xl">Quantum-Resistant Security</h1>
<blockquote className="font-serif text-xl italic">Future-proof your passwords</blockquote>
```

### Typography Scale

Use Tailwind's responsive text utilities:

| Size | Class | Use Case |
|------|-------|----------|
| 12px | `text-xs` | Fine print, metadata |
| 14px | `text-sm` | Secondary text, captions |
| 16px | `text-base` | Body text (default) |
| 18px | `text-lg` | Emphasis, large body text |
| 20px | `text-xl` | Section headings |
| 24px | `text-2xl` | Page headings |
| 30px | `text-3xl` | Hero headings |
| 36px | `text-4xl` | Primary hero text |
| 48px | `text-5xl` | Marketing headlines |

### Font Weight

| Weight | Class | Usage |
|--------|-------|-------|
| 400 | `font-normal` | Body text |
| 500 | `font-medium` | Subtle emphasis |
| 600 | `font-semibold` | Headings, strong emphasis |
| 700 | `font-bold` | Hero text, primary CTAs |

---

## Color System

LockNKey uses OKLCH color space for perceptually uniform colors and better accessibility.

### Color Format: OKLCH
```
oklch(L C H)
- L: Lightness (0-1)
- C: Chroma/saturation (0-0.4)
- H: Hue (0-360)
```

### Primary Colors

**Light Mode**:
- Primary: `oklch(0.55 0.22 264)` - Purple/Lavender
- Background: `oklch(0.99 0 0)` - Near white
- Foreground: `oklch(0.09 0 0)` - Near black

**Dark Mode**:
- Primary: `oklch(0.65 0.24 264)` - Brighter purple
- Background: `oklch(0.12 0.015 264)` - Dark purple-tinted
- Foreground: `oklch(0.95 0.01 264)` - Near white

### Using Colors in Components

```tsx
// Background colors
<div className="bg-background text-foreground">Default container</div>
<div className="bg-card text-card-foreground">Card container</div>
<div className="bg-popover text-popover-foreground">Popover container</div>

// Accent colors
<button className="bg-primary text-primary-foreground">Primary Button</button>
<button className="bg-secondary text-secondary-foreground">Secondary Button</button>
<span className="text-muted-foreground">Muted text</span>

// Semantic colors
<div className="border-destructive">Error state</div>
<input className="border-input focus:ring-ring" />
```

### Color Semantic Tokens

| Token | Light Mode | Dark Mode | Usage |
|-------|------------|-----------|-------|
| `background` | oklch(0.99 0 0) | oklch(0.12 0.015 264) | Page background |
| `foreground` | oklch(0.09 0 0) | oklch(0.95 0.01 264) | Primary text |
| `primary` | oklch(0.55 0.22 264) | oklch(0.65 0.24 264) | Brand actions |
| `secondary` | oklch(0.96 0.005 264) | oklch(0.22 0.020 264) | Secondary actions |
| `muted` | oklch(0.96 0.005 264) | oklch(0.22 0.020 264) | Disabled states |
| `destructive` | oklch(0.58 0.22 25) | oklch(0.65 0.24 25) | Errors, delete |
| `border` | oklch(0.92 0.005 264) | oklch(0.25 0.020 264) | Borders |
| `input` | oklch(0.92 0.005 264) | oklch(0.25 0.020 264) | Input borders |
| `ring` | oklch(0.55 0.22 264) | oklch(0.65 0.24 264) | Focus rings |

---

## Shadow System

Enhanced shadow tokens for depth and elevation. Shadows automatically adjust for dark mode.

### Shadow Levels

| Token | CSS Variable | Usage |
|-------|--------------|-------|
| Extra Small | `var(--shadow-xs)` | Subtle hover effects |
| Small | `var(--shadow-sm)` | Cards, buttons |
| Medium | `var(--shadow-md)` | Dropdowns, popovers |
| Large | `var(--shadow-lg)` | Modals, dialogs |
| Extra Large | `var(--shadow-xl)` | Navigation drawers |
| 2X Large | `var(--shadow-2xl)` | Full-screen overlays |

### Shadow CSS Values

**Light Mode**:
```css
--shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
--shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
--shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25);
```

**Dark Mode**:
```css
--shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.2);
--shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.3), 0 1px 2px -1px rgb(0 0 0 / 0.2);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4), 0 2px 4px -2px rgb(0 0 0 / 0.3);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.5), 0 4px 6px -4px rgb(0 0 0 / 0.4);
--shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.6), 0 8px 10px -6px rgb(0 0 0 / 0.5);
--shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.7);
```

### Using Shadows

```tsx
// Direct CSS variable
<div style={{ boxShadow: 'var(--shadow-md)' }}>Card with medium shadow</div>

// In custom CSS
.card-elevated {
  box-shadow: var(--shadow-lg);
  transition: box-shadow var(--transition-base);
}

.card-elevated:hover {
  box-shadow: var(--shadow-xl);
}
```

### Shadow Guidelines

1. **Cards**: Use `--shadow-sm` for default state, `--shadow-md` on hover
2. **Dropdowns/Popovers**: Use `--shadow-md` or `--shadow-lg`
3. **Modals**: Use `--shadow-xl` or `--shadow-2xl`
4. **Buttons**: Use `--shadow-xs` or no shadow (rely on color)
5. **Floating Elements**: Increase shadow on hover for depth feedback

---

## Animation Tokens

Smooth, consistent transitions throughout the UI.

### Transition Speeds

| Token | Value | Usage |
|-------|-------|-------|
| `--transition-fast` | 150ms | Hover states, simple interactions |
| `--transition-base` | 200ms | Default transitions (buttons, inputs) |
| `--transition-slow` | 300ms | Layout changes, theme transitions |
| `--transition-slower` | 500ms | Complex animations, page transitions |

### Easing Curve

All transitions use `cubic-bezier(0.4, 0, 0.2, 1)` (ease-in-out) for natural motion.

### Using Transitions

```tsx
// In components
<button
  className="transition-all duration-200 hover:scale-105"
  style={{ transition: 'all var(--transition-base)' }}
>
  Hover Me
</button>

// In custom CSS
.interactive-element {
  transition: transform var(--transition-base),
              box-shadow var(--transition-base),
              background-color var(--transition-slow);
}

.interactive-element:hover {
  transform: translateY(-2px);
  box-shadow: var(--shadow-lg);
}
```

### Animation Guidelines

1. **Keep it subtle**: Avoid distracting animations
2. **Use consistent timing**: Stick to defined transition tokens
3. **Respect user preferences**: Honor `prefers-reduced-motion`
4. **Performance**: Use `transform` and `opacity` for smooth 60fps animations

---

## Border Radius

Consistent rounding throughout the UI.

### Radius Scale

| Token | Value | Tailwind Class | Usage |
|-------|-------|----------------|-------|
| `--radius-sm` | calc(var(--radius) - 4px) | `rounded-sm` | Small elements, tags |
| `--radius-md` | calc(var(--radius) - 2px) | `rounded-md` | Inputs, small buttons |
| `--radius-lg` | var(--radius) | `rounded-lg` | Cards, default radius |
| `--radius-xl` | calc(var(--radius) + 4px) | `rounded-xl` | Modals, large panels |

**Base Radius**: `--radius: 0.75rem` (12px)

### Using Border Radius

```tsx
// Tailwind utilities
<div className="rounded-lg">Default card rounding</div>
<button className="rounded-md">Button</button>
<span className="rounded-sm">Tag</span>

// Custom CSS
.custom-card {
  border-radius: var(--radius-lg);
}
```

---

## Spacing System

Use Tailwind's default spacing scale for consistency:

| Value | Class | Usage |
|-------|-------|-------|
| 4px | `p-1`, `m-1` | Tight spacing |
| 8px | `p-2`, `m-2` | Compact spacing |
| 12px | `p-3`, `m-3` | Small spacing |
| 16px | `p-4`, `m-4` | Base spacing |
| 24px | `p-6`, `m-6` | Medium spacing |
| 32px | `p-8`, `m-8` | Large spacing |
| 48px | `p-12`, `m-12` | Extra large spacing |

---

## Component Examples

### Button with Design Tokens

```tsx
<button
  className="
    font-sans font-medium text-base
    bg-primary text-primary-foreground
    px-4 py-2 rounded-md
    transition-all duration-200
    hover:scale-105
  "
  style={{
    boxShadow: 'var(--shadow-sm)',
    transition: 'all var(--transition-base)',
  }}
>
  Save Password
</button>
```

### Card with Design Tokens

```tsx
<div
  className="
    font-sans
    bg-card text-card-foreground
    p-6 rounded-lg border border-border
  "
  style={{
    boxShadow: 'var(--shadow-md)',
    transition: 'box-shadow var(--transition-base)',
  }}
>
  <h2 className="font-serif font-bold text-2xl mb-2">Quantum Protection</h2>
  <p className="text-muted-foreground">
    Your passwords are secured with NIST-approved post-quantum cryptography.
  </p>
</div>
```

### Input with Design Tokens

```tsx
<input
  type="text"
  className="
    font-sans text-base
    bg-background text-foreground
    border border-input rounded-md
    px-3 py-2
    focus:outline-none focus:ring-2 focus:ring-ring
  "
  style={{
    transition: 'border-color var(--transition-fast), box-shadow var(--transition-fast)',
  }}
  placeholder="Enter master password"
/>
```

---

## Accessibility Considerations

### Color Contrast

All color pairings meet WCAG 2.1 AA standards:
- Normal text: 4.5:1 contrast ratio
- Large text (18px+): 3:1 contrast ratio
- UI components: 3:1 contrast ratio

### Focus Indicators

Always visible focus rings using `--ring` color:
```tsx
<button className="focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
  Accessible Button
</button>
```

### Typography Accessibility

- Minimum font size: 14px for body text
- Line height: 1.5 for body text, 1.2 for headings
- Max line length: 65-75 characters for optimal readability

### Motion Preferences

Respect user motion preferences:
```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## Usage for Other Agents

### For Component Designers

1. **Start with semantic tokens**: Use `bg-card`, `text-foreground`, not raw OKLCH values
2. **Use defined shadows**: Reference `var(--shadow-*)` for consistency
3. **Apply transitions**: All interactive elements should use transition tokens
4. **Test in both themes**: Verify light and dark mode appearance

### For Frontend Developers

1. **Import fonts**: Already configured in `layout.tsx`
2. **Use Tailwind classes**: `font-sans`, `font-mono`, `font-serif`
3. **Reference CSS variables**: `var(--shadow-md)`, `var(--transition-base)`
4. **Follow component examples**: Use patterns from this document

### For QA Engineers

Test checklist:
- [ ] Typography renders correctly in all three fonts
- [ ] Shadows display properly in light and dark mode
- [ ] Transitions are smooth and consistent (200ms default)
- [ ] Color contrast meets WCAG AA standards
- [ ] Focus indicators are visible on all interactive elements
- [ ] Reduced motion preference is respected

---

## Quick Reference

### CSS Variables Available

```css
/* Typography */
--font-geist-sans
--font-geist-mono
--font-serif

/* Shadows */
--shadow-xs, --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl, --shadow-2xl

/* Transitions */
--transition-fast (150ms)
--transition-base (200ms)
--transition-slow (300ms)
--transition-slower (500ms)

/* Radius */
--radius (0.75rem)
--radius-sm, --radius-md, --radius-lg, --radius-xl
```

### Tailwind Classes to Use

```
Font: font-sans, font-mono, font-serif
Size: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl, text-4xl, text-5xl
Weight: font-normal, font-medium, font-semibold, font-bold
Radius: rounded-sm, rounded-md, rounded-lg, rounded-xl
```

---

**Questions?** Refer to:
- `/frontend/src/app/layout.tsx` - Font configuration
- `/frontend/src/app/globals.css` - Token definitions
- `/frontend/tailwind.config.ts` - Tailwind theme extension
