# Design Token Reference

Complete reference of all design tokens used in the DSS Admin UI.

## Color Tokens

### Primary
- **Name**: `--primary` / `--color-primary`
- **Value**: `oklch(0.65 0.18 250)`
- **Usage**: Main brand color for actions, highlights, active states
- **Figma**: Primary component in color library

### Secondary
- **Name**: `--secondary` / `--color-secondary`
- **Value**: `oklch(0.60 0.12 120)`
- **Usage**: Supporting actions, secondary buttons
- **Figma**: Secondary component in color library

### Accent
- **Name**: `--accent` / `--color-accent`
- **Value**: `oklch(0.70 0.20 40)`
- **Usage**: Highlight elements, emphasis
- **Figma**: Accent component in color library

### Semantic Colors

#### Destructive
- **Name**: `--destructive` / `--color-destructive`
- **Value**: `oklch(0.63 0.25 30)`
- **Usage**: Delete, remove, error actions
- **States**:
  - Hover: `oklch(0.53 0.25 30)`
  - Light: `oklch(0.88 0.10 30)`

#### Success
- **Name**: `--success` / `--color-success`
- **Value**: `oklch(0.65 0.18 140)`
- **Usage**: Positive feedback, successful actions
- **States**:
  - Hover: `oklch(0.55 0.18 140)`
  - Light: `oklch(0.86 0.10 140)`

#### Warning
- **Name**: `--warning` / `--color-warning`
- **Value**: `oklch(0.68 0.22 60)`
- **Usage**: Caution, attention-needed states
- **States**:
  - Hover: `oklch(0.58 0.22 60)`
  - Light: `oklch(0.88 0.12 60)`

#### Info
- **Name**: `--info` / `--color-info`
- **Value**: `oklch(0.62 0.18 230)`
- **Usage**: Informational messages, neutral feedback

### Neutral/Grayscale

#### Text Colors
- `--foreground`: `oklch(0.20 0.02 280)` - Primary text
- `--foreground-secondary`: `oklch(0.40 0.02 280)` - Secondary text
- `--muted-foreground`: `oklch(0.55 0.02 280)` - Muted text, disabled states

#### Background & Surface
- `--background`: `oklch(0.98 0.01 280)` - Page background
- `--surface`: `oklch(0.95 0.01 280)` - Section background
- `--surface-secondary`: `oklch(0.92 0.01 280)` - Secondary surface
- `--muted`: `oklch(0.88 0.01 280)` - Muted background (hover states)
- `--card`: `oklch(0.98 0.01 280)` - Card backgrounds

#### UI Elements
- `--border`: `oklch(0.82 0.01 280)` - Border color
- `--ring`: `oklch(0.65 0.18 250)` - Focus ring (uses primary)
- `--input`: `oklch(0.95 0.01 280)` - Input background

### Dark Mode Overrides

When `prefers-color-scheme: dark` or `[data-theme="dark"]`:

- `--foreground`: `oklch(0.92 0.02 280)`
- `--background`: `oklch(0.12 0.02 280)`
- `--surface`: `oklch(0.15 0.02 280)`
- `--border`: `oklch(0.30 0.02 280)`

## Spacing Scale

All values use a 4px base unit for predictable, modular spacing.

| Name | Value | Pixels | Usage |
|------|-------|--------|-------|
| `--space-0` | 0 | 0px | No spacing |
| `--space-1` | 0.25rem | 4px | Minimal gaps |
| `--space-2` | 0.5rem | 8px | Small spacing |
| `--space-3` | 0.75rem | 12px | Component padding |
| `--space-4` | 1rem | 16px | Standard padding |
| `--space-5` | 1.25rem | 20px | Large spacing |
| `--space-6` | 1.5rem | 24px | Section margin |
| `--space-7` | 1.75rem | 28px | Large gap |
| `--space-8` | 2rem | 32px | Extra large spacing |

### Spacing Patterns

- **Component Padding**: `var(--space-3)` to `var(--space-4)`
- **Section Margins**: `var(--space-6)` to `var(--space-8)`
- **Gaps in Flexbox**: `var(--space-2)` to `var(--space-4)`
- **Indentation**: `var(--space-4)` per level

## Typography

### Font Families

- `--font-sans`: System font stack (San Francisco, Segoe UI, Roboto, etc.)
- `--font-mono`: Monospace font (Monaco, Courier New)

### Font Sizes

All sizes scale responsively based on viewport.

| Name | Value | Pixels | Usage |
|------|-------|--------|-------|
| `--text-xs` | 0.75rem | 12px | Labels, captions, help text |
| `--text-sm` | 0.875rem | 14px | Secondary text, small UI |
| `--text-base` | 1rem | 16px | Body text, default |
| `--text-lg` | 1.125rem | 18px | Subheadings |
| `--text-xl` | 1.25rem | 20px | Section headers |
| `--text-2xl` | 1.5rem | 24px | Page titles |

### Font Weights

- `--font-400`: 400 (Normal) - Body text
- `--font-500`: 500 (Medium) - Buttons, labels
- `--font-600`: 600 (Semibold) - Section headers
- `--font-700`: 700 (Bold) - Page titles

### Line Heights

- `--line-height-tight`: 1.2 - Headings
- `--line-height-normal`: 1.5 - Body text
- `--line-height-relaxed`: 1.75 - Long-form content
- `--line-height-loose`: 2 - Very relaxed spacing

## Border Radius

| Name | Value | Usage |
|------|-------|-------|
| `--radius-none` | 0 | Sharp corners |
| `--radius-sm` | 0.25rem (4px) | Small elements, badges |
| `--radius` | 0.375rem (6px) | Buttons, inputs, default |
| `--radius-md` | 0.5rem (8px) | Cards, panels |
| `--radius-lg` | 0.75rem (12px) | Large containers |
| `--radius-full` | 9999px | Completely round |

## Shadows

Used for elevation and depth perception.

| Name | Value | Usage |
|------|-------|-------|
| `--shadow-sm` | `0 1px 2px rgba(0, 0, 0, 0.05)` | Subtle elevation |
| `--shadow` | `0 1px 3px rgba(0, 0, 0, 0.1), ...` | Default shadow |
| `--shadow-md` | `0 4px 6px -1px rgba(0, 0, 0, 0.1), ...` | Medium elevation |
| `--shadow-lg` | `0 10px 15px -3px rgba(0, 0, 0, 0.1), ...` | Large elevation |

## Animation

### Durations

- `--duration-fast`: 150ms - Quick interactions (hover, micro-interactions)
- `--duration-normal`: 200ms - Standard transitions
- `--duration-slow`: 300ms - Slow, deliberate animations

### Easing Functions

- `--ease-default`: `cubic-bezier(0.4, 0, 0.2, 1)` - Standard easing
- `--ease-in`: `cubic-bezier(0.4, 0, 1, 1)` - Ease in (start slow)
- `--ease-out`: `cubic-bezier(0, 0, 0.2, 1)` - Ease out (end slow)
- `--ease-in-out`: `cubic-bezier(0.4, 0, 0.2, 1)` - Ease both directions

### Animation Examples

```css
/* Quick hover state */
button {
  transition: background var(--duration-fast) var(--ease-default);
}

/* Smooth panel open */
.panel {
  transition: max-height var(--duration-normal) var(--ease-default);
}

/* Slower meaningful animation */
.modal {
  animation: slideUp var(--duration-slow) var(--ease-out);
}
```

## Color Space Notes

All colors are defined in **OKLCH color space**:
- Better perceptual uniformity than HSL
- Easier to adjust lightness independently
- Better for accessible color contrast
- Format: `oklch(lightness saturation hue)`
  - Lightness: 0-1 (0 = black, 1 = white)
  - Saturation: 0-0.4 (higher = more vibrant)
  - Hue: 0-360 (angle on color wheel)

## Accessibility Considerations

### Color Contrast
- Text on `--background`: ✓ WCAG AAA
- Text on `--surface`: ✓ WCAG AAA
- Primary action on muted: ✓ WCAG AA

### Focus Indicators
- `--ring`: 2px solid, 2px offset
- Visible on all interactive elements
- Never removed without replacement

### Motion
- `--duration-fast`: Imperceptible to most
- Consider `prefers-reduced-motion` for slower animations

## Contributing

When adding new tokens:

1. Add to `design-tokens.json`
2. Update appropriate CSS layer file
3. Document in this file
4. Update `DESIGN-SYSTEM.md` if behavior changes
5. Test contrast ratios (colors)
6. Test responsiveness (sizing)