# UI Micro-Interaction Theme & Contrast Guidance (MI10)

This document defines theme tokens and contrast requirements for micro-interactions across light, dark, and high-contrast modes.

## Color Contrast Requirements

| Element Type | Minimum Contrast Ratio | WCAG Level |
| --- | --- | --- |
| Normal text (< 18px) | 4.5:1 | AA |
| Large text (>= 18px bold or >= 24px) | 3:1 | AA |
| UI components (borders, icons) | 3:1 | AA |
| Focus indicators | 3:1 | AA |
| Status colors on background | 3:1 | AA |

## Theme Token Reference

### Light Theme (Default)

```scss
:root {
  /* Backgrounds */
  --theme-bg-primary: #ffffff;
  --theme-bg-secondary: #f8fafc;
  --theme-bg-elevated: #ffffff;
  --theme-bg-overlay: rgba(15, 23, 42, 0.5);

  /* Text */
  --theme-text-primary: #0f172a;     /* 15.42:1 on white */
  --theme-text-secondary: #475569;   /* 7.05:1 on white */
  --theme-text-muted: #94a3b8;       /* 3.21:1 on white - decorative only */
  --theme-text-inverse: #ffffff;

  /* Borders */
  --theme-border-default: #e2e8f0;
  --theme-border-focus: #3b82f6;     /* 4.5:1 on white */
  --theme-border-error: #ef4444;

  /* Status Colors */
  --theme-status-success: #16a34a;   /* 4.52:1 on white */
  --theme-status-warning: #d97706;   /* 4.51:1 on white */
  --theme-status-error: #dc2626;     /* 5.92:1 on white */
  --theme-status-info: #2563eb;      /* 5.28:1 on white */

  /* Focus Ring */
  --theme-focus-ring-color: #3b82f6;
  --theme-focus-ring-width: 2px;
  --theme-focus-ring-offset: 2px;
}
```

### Dark Theme

```scss
[data-theme='dark'] {
  /* Backgrounds */
  --theme-bg-primary: #0f172a;
  --theme-bg-secondary: #1e293b;
  --theme-bg-elevated: #334155;
  --theme-bg-overlay: rgba(0, 0, 0, 0.7);

  /* Text */
  --theme-text-primary: #f8fafc;     /* 15.42:1 on dark bg */
  --theme-text-secondary: #cbd5e1;   /* 8.12:1 on dark bg */
  --theme-text-muted: #64748b;
  --theme-text-inverse: #0f172a;

  /* Borders */
  --theme-border-default: #334155;
  --theme-border-focus: #60a5fa;
  --theme-border-error: #f87171;

  /* Status Colors */
  --theme-status-success: #4ade80;
  --theme-status-warning: #fbbf24;
  --theme-status-error: #f87171;
  --theme-status-info: #60a5fa;

  /* Focus Ring */
  --theme-focus-ring-color: #60a5fa;
}
```

### High Contrast Theme

```scss
[data-theme='high-contrast'] {
  /* Backgrounds */
  --theme-bg-primary: #000000;
  --theme-bg-secondary: #000000;
  --theme-bg-elevated: #1a1a1a;
  --theme-bg-overlay: rgba(0, 0, 0, 0.9);

  /* Text */
  --theme-text-primary: #ffffff;     /* 21:1 on black */
  --theme-text-secondary: #ffffff;
  --theme-text-muted: #e5e5e5;
  --theme-text-inverse: #000000;

  /* Borders - thicker and higher contrast */
  --theme-border-default: #ffffff;
  --theme-border-focus: #ffff00;     /* Yellow for maximum visibility */
  --theme-border-error: #ff0000;

  /* Status Colors - bold, saturated */
  --theme-status-success: #00ff00;
  --theme-status-warning: #ffff00;
  --theme-status-error: #ff0000;
  --theme-status-info: #00ffff;

  /* Focus Ring - extra visible */
  --theme-focus-ring-color: #ffff00;
  --theme-focus-ring-width: 3px;
  --theme-focus-ring-offset: 3px;
}
```

## Focus Indicator Requirements

1. Focus ring must be visible in all themes (never `outline: none` without replacement)
2. Minimum 2px width, 3:1 contrast with adjacent colors
3. In high-contrast mode: 3px width, yellow (#ffff00) color
4. Focus must be visible when using keyboard navigation only

## Validation Checklist

- [ ] All text passes 4.5:1 contrast ratio (use axe DevTools)
- [ ] All UI elements pass 3:1 contrast ratio
- [ ] Focus indicators visible in all themes
- [ ] No reliance on color alone for state indication
- [ ] Theme toggle persists user preference
- [ ] Reduced motion settings respected across themes

## Testing

Run axe accessibility tests in Storybook:
```bash
npm run test:a11y
```

Run contrast checks in Playwright:
```bash
npx playwright test --project=a11y
```

## Evidence

- Storybook: Theme toggle available in toolbar
- Playwright: `tests/e2e/theme-contrast.spec.ts`
- axe reports: `tests/a11y/reports/`