roa2web-service-auto/docs/DESIGN_TOKENS.md

# Design Tokens Reference

**Version:** 2.0.0
**Last Updated:** 2025-11-19
**Status:** ✅ Complete

---

## Overview

Design tokens are the visual design atoms of the ROA2WEB design system. They are represented as CSS custom properties (`--token-name`) and ensure consistency across the application.

**Location:** `src/assets/css/core/variables.css` and `src/assets/css/core/tokens.css`

---

## Spacing Scale

| Token | Value | Pixels | Use Case |
|-------|-------|--------|----------|
| `--space-xs` | 0.25rem | 4px | Tight spacing, icon gaps, badges |
| `--space-sm` | 0.5rem | 8px | Default gap between related items |
| `--space-md` | 1rem | 16px | Standard component padding |
| `--space-lg` | 1.5rem | 24px | Section padding, card spacing |
| `--space-xl` | 2rem | 32px | Page margins, large separations |
| `--space-2xl` | 3rem | 48px | Major section gaps |
| `--space-3xl` | 4rem | 64px | Hero sections, page-level spacing |

**Usage:**
```css
.card {
  padding: var(--space-md);      /* 16px */
  margin-bottom: var(--space-lg); /* 24px */
}

.button-group {
  gap: var(--space-sm);           /* 8px */
}
```

---

## Typography Scale

### Font Sizes

| Token | Value | Pixels | Use Case |
|-------|-------|--------|----------|
| `--text-xs` | 0.75rem | 12px | Tiny labels, timestamps, badges |
| `--text-sm` | 0.875rem | 14px | Small text, table cells, secondary info |
| `--text-base` | 1rem | 16px | Body text (default) |
| `--text-lg` | 1.125rem | 18px | Emphasized text, large buttons |
| `--text-xl` | 1.25rem | 20px | Small headings, card titles |
| `--text-2xl` | 1.5rem | 24px | Medium headings, metric values |
| `--text-3xl` | 2rem | 32px | Large headings, page titles |
| `--text-4xl` | 2.5rem | 40px | Hero text, dashboard values |

### Font Weights

| Token | Value | Use Case |
|-------|-------|----------|
| `--font-light` | 300 | Rarely used, light emphasis |
| `--font-normal` | 400 | Body text, default |
| `--font-medium` | 500 | Labels, buttons, emphasis |
| `--font-semibold` | 600 | Headings, important text |
| `--font-bold` | 700 | Strong emphasis, titles |

### Line Heights

| Token | Value | Use Case |
|-------|-------|----------|
| `--leading-tight` | 1.2 | Headings, compact text |
| `--leading-normal` | 1.5 | Body text (default) |
| `--leading-loose` | 1.75 | Relaxed reading, large text |

**Usage:**
```css
.heading {
  font-size: var(--text-2xl);
  font-weight: var(--font-semibold);
  line-height: var(--leading-tight);
}

.body-text {
  font-size: var(--text-base);
  font-weight: var(--font-normal);
  line-height: var(--leading-normal);
}
```

---

## Color Palette

### Primary Colors

| Token | Value | Use Case |
|-------|-------|----------|
| `--color-primary` | #2563eb | Primary actions, links, focus states |
| `--color-primary-dark` | #1d4ed8 | Primary hover, active states |
| `--color-primary-light` | #3b82f6 | Backgrounds, light accents |

### Status Colors

| Token | Value | Use Case |
|-------|-------|----------|
| `--color-success` | #059669 | Success messages, positive trends |
| `--color-warning` | #d97706 | Warnings, cautions |
| `--color-error` | #dc2626 | Errors, destructive actions, negative trends |
| `--color-info` | #0891b2 | Info messages, neutral alerts |

### Text Colors

| Token | Value | Contrast | Use Case |
|-------|-------|----------|----------|
| `--color-text` | #111827 | 16.9:1 | Primary text, headings |
| `--color-text-secondary` | #6b7280 | 4.6:1 | Secondary text, labels |
| `--color-text-muted` | #9ca3af | 2.8:1 | Muted text, disabled text |
| `--color-text-inverse` | #ffffff | - | Text on dark backgrounds |

### Background Colors

| Token | Value | Use Case |
|-------|-------|----------|
| `--color-bg` | #ffffff | Primary background, cards |
| `--color-bg-secondary` | #f9fafb | Alternate backgrounds, hover states |
| `--color-bg-muted` | #f3f4f6 | Disabled backgrounds, subtle sections |
| `--color-bg-dark` | #111827 | Dark backgrounds |

### Semantic Surface Tokens (PrimeVue-compatible)

**CRITICAL for dark mode support!** These tokens automatically switch values in dark mode.

| Token | Light Value | Dark Value | Use Case |
|-------|-------------|------------|----------|
| `--surface-card` | #ffffff | #1e293b | Card backgrounds, elevated surfaces |
| `--surface-ground` | #f8fafc | #0f172a | Page background, base layer |
| `--surface-section` | #ffffff | #1e293b | Section backgrounds |
| `--surface-hover` | #f1f5f9 | #334155 | Hover states on surfaces |
| `--surface-border` | #e2e8f0 | #475569 | Borders on surfaces |
| `--surface-overlay` | #ffffff | #1e293b | Modal/overlay backgrounds |

**Usage:**
```css
.card {
  background: var(--surface-card);
  border: 1px solid var(--surface-border);
}

.page {
  background: var(--surface-ground);
}
```

### Border Colors

| Token | Value | Use Case |
|-------|-------|----------|
| `--color-border` | #e5e7eb | Default borders |
| `--color-border-light` | #f3f4f6 | Subtle borders |
| `--color-border-dark` | #d1d5db | Emphasized borders |

**Usage:**
```css
.btn-primary {
  background: var(--color-primary);
  color: var(--color-text-inverse);
  border: 1px solid var(--color-primary);
}

.btn-primary:hover {
  background: var(--color-primary-dark);
}

.card {
  background: var(--color-bg);
  border: 1px solid var(--color-border);
  color: var(--color-text);
}
```

---

## Shadows

| Token | Value | Use Case |
|-------|-------|----------|
| `--shadow-sm` | 0 1px 2px rgba(0,0,0,0.05) | Subtle depth, hover states |
| `--shadow-md` | 0 4px 6px rgba(0,0,0,0.1) | Cards, dropdowns |
| `--shadow-lg` | 0 10px 15px rgba(0,0,0,0.1) | Elevated cards, modals |
| `--shadow-xl` | 0 20px 25px rgba(0,0,0,0.1) | Popovers, large modals |

**Usage:**
```css
.card {
  box-shadow: var(--shadow-sm);
}

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

---

## Border Radius

| Token | Value | Pixels | Use Case |
|-------|-------|--------|----------|
| `--radius-sm` | 0.25rem | 4px | Small elements, badges |
| `--radius-md` | 0.5rem | 8px | Buttons, inputs, cards (default) |
| `--radius-lg` | 0.75rem | 12px | Large cards, images |
| `--radius-xl` | 1rem | 16px | Hero cards, special elements |
| `--radius-full` | 9999px | - | Pills, circles, avatars |

**Usage:**
```css
.btn {
  border-radius: var(--radius-md);
}

.avatar {
  border-radius: var(--radius-full);
}
```

---

## Transitions

| Token | Value | Use Case |
|-------|-------|----------|
| `--transition-fast` | 150ms ease | Hover states, quick interactions |
| `--transition-normal` | 250ms ease | Default transitions |
| `--transition-slow` | 350ms ease | Complex animations, modals |

**Usage:**
```css
.btn {
  transition: all var(--transition-fast);
}

.modal {
  transition: opacity var(--transition-normal);
}
```

---

## Extended Tokens (Dashboard & Metrics)

### Card Tokens

| Token | Value | Use Case |
|-------|-------|----------|
| `--card-padding` | var(--space-lg) | Standard card padding (24px) |
| `--card-padding-sm` | var(--space-md) | Compact card padding (16px) |
| `--card-padding-lg` | var(--space-xl) | Large card padding (32px) |
| `--card-gap` | var(--space-md) | Gap between card elements (16px) |
| `--card-min-height` | 280px | Minimum card height |
| `--card-radius` | var(--radius-md) | Card border radius (8px) |

### Interactive Tokens

| Token | Value | Use Case |
|-------|-------|----------|
| `--hover-lift` | -2px | Vertical lift on hover |
| `--active-lift` | 0px | Reset lift on click |
| `--focus-ring` | 0 0 0 3px rgba(...) | Focus outline |

### Spinner Sizes

| Token | Value | Use Case |
|-------|-------|----------|
| `--spinner-size` | 40px | Default spinner |
| `--spinner-size-sm` | 24px | Small spinner (buttons) |
| `--spinner-size-lg` | 56px | Large spinner (page loading) |
| `--spinner-border` | 4px | Spinner border width |

### Dashboard Metrics

| Token | Value | Use Case |
|-------|-------|----------|
| `--value-size` | 1.5rem | Default metric value (24px) |
| `--value-size-lg` | 2rem | Large metric value (32px) |
| `--label-size` | 0.875rem | Metric label (14px) |
| `--sublabel-size` | 0.8125rem | Sub-label (13px) |
| `--metric-gap` | 1rem | Gap between metrics (16px) |
| `--sparkline-height` | 80px | Sparkline chart height |
| `--sparkline-height-lg` | 150px | Large sparkline height |

---

## Layout Tokens

| Token | Value | Use Case |
|-------|-------|----------|
| `--header-height` | 56px | App header height |
| `--sidebar-width` | 240px | Sidebar width |
| `--container-max-width` | 1400px | Max content width |

---

## Z-Index Scale

| Token | Value | Use Case |
|-------|-------|----------|
| `--z-dropdown` | 1200 | Dropdown menus |
| `--z-sticky` | 1020 | Sticky headers |
| `--z-fixed` | 1030 | Fixed elements |
| `--z-modal-backdrop` | 1040 | Modal backdrop |
| `--z-modal` | 1050 | Modal dialogs |
| `--z-popover` | 1060 | Popovers |
| `--z-tooltip` | 1070 | Tooltips (highest) |

---

## Breakpoints (Reference)

| Token | Value | Use Case |
|-------|-------|----------|
| `--breakpoint-mobile` | 480px | Mobile devices |
| `--breakpoint-tablet` | 768px | Tablets, small laptops |
| `--breakpoint-desktop` | 1024px | Desktops |
| `--breakpoint-wide` | 1400px | Large screens |

**Usage:**
```css
@media (max-width: 768px) {
  .card {
    padding: var(--space-md);
  }
}

@media (min-width: 1024px) {
  .container {
    max-width: var(--container-max-width);
  }
}
```

---

## Utility Patterns

### Color With Opacity

```css
/* Use RGB values for transparency */
background: rgba(var(--color-primary-rgb), 0.1);
/* = rgba(37, 99, 235, 0.1) */

border-color: rgba(var(--color-success-rgb), 0.5);
/* = rgba(5, 150, 105, 0.5) */
```

### Status Background Colors (10% opacity)

| Token | Value | Use Case |
|-------|-------|----------|
| `--color-success-bg` | rgba(5, 150, 105, 0.1) | Success alerts background |
| `--color-warning-bg` | rgba(217, 119, 6, 0.1) | Warning alerts background |
| `--color-error-bg` | rgba(220, 38, 38, 0.1) | Error alerts background |
| `--color-info-bg` | rgba(8, 145, 178, 0.1) | Info alerts background |

### Monospace Font

```css
/* For numbers, code, metrics */
font-family: var(--font-mono);
/* = 'SF Mono', Consolas, 'Liberation Mono', Menlo, Courier, monospace */
```

---

## Compatibility Aliases

For backwards compatibility with existing code:

| Alias | Maps To |
|-------|---------|
| `--primary-color` | `var(--color-primary)` |
| `--primary-color-dark` | `var(--color-primary-dark)` |
| `--text-color` | `var(--color-text)` |
| `--text-color-secondary` | `var(--color-text-secondary)` |

---

## Usage Examples

### Complete Button

```css
.btn-primary {
  /* Typography */
  font-size: var(--text-sm);
  font-weight: var(--font-medium);
  line-height: var(--leading-normal);

  /* Spacing */
  padding: var(--space-sm) var(--space-md);
  gap: var(--space-xs);

  /* Colors */
  background: var(--color-primary);
  color: var(--color-text-inverse);
  border: 1px solid var(--color-primary);

  /* Visual */
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);

  /* Interaction */
  transition: all var(--transition-fast);
}

.btn-primary:hover {
  background: var(--color-primary-dark);
  box-shadow: var(--shadow-md);
  transform: translateY(var(--hover-lift));
}
```

### Complete Card

```css
.card {
  /* Layout */
  padding: var(--card-padding);
  min-height: var(--card-min-height);
  display: flex;
  flex-direction: column;
  gap: var(--card-gap);

  /* Colors */
  background: var(--color-bg);
  border: 1px solid var(--color-border);
  color: var(--color-text);

  /* Visual */
  border-radius: var(--card-radius);
  box-shadow: var(--shadow-sm);

  /* Interaction */
  transition: all var(--transition-fast);
}
```

---

## Best Practices

### ✅ Do

```css
/* Use tokens for all values */
.element {
  color: var(--color-text);
  font-size: var(--text-base);
  padding: var(--space-md);
  border-radius: var(--radius-md);
}

/* Combine tokens */
.card-padding {
  padding: var(--space-lg) var(--space-xl);
}
```

### ❌ Don't

```css
/* Don't hardcode values */
.element {
  color: #111827;           /* Use var(--color-text) */
  font-size: 16px;          /* Use var(--text-base) */
  padding: 16px;            /* Use var(--space-md) */
  border-radius: 8px;       /* Use var(--radius-md) */
}
```

---

## Dark Mode (ACTIVE)

Dark mode is fully supported via `@media (prefers-color-scheme: dark)` in `variables.css`. All tokens automatically switch to dark variants.

### How It Works

```css
/* Light mode (default) */
:root {
  --surface-card: #ffffff;
  --text-color: #111827;
}

/* Dark mode (automatic) */
@media (prefers-color-scheme: dark) {
  :root {
    --surface-card: #1e293b;
    --text-color: #f9fafb;
  }
}
```

### Key Dark Mode Tokens

| Token | Light | Dark | Purpose |
|-------|-------|------|---------|
| `--surface-card` | #ffffff | #1e293b | Card/container backgrounds |
| `--surface-ground` | #f8fafc | #0f172a | Page background |
| `--surface-border` | #e2e8f0 | #475569 | Borders |
| `--text-color` | #111827 | #f9fafb | Primary text |
| `--text-color-secondary` | #6b7280 | #d1d5db | Secondary text |

### Color Scales for Status

Each color has a full scale (50-900) that inverts appropriately in dark mode:

| Color | Light Background | Dark Background | Use Case |
|-------|-----------------|-----------------|----------|
| `--green-50/100` | Light green bg | Dark green bg | Success backgrounds |
| `--green-500/600` | Green text/icons | Same | Success accents |
| `--yellow-50/100` | Light yellow bg | Dark yellow bg | Warning backgrounds |
| `--yellow-500/600` | Yellow text/icons | Same | Warning accents |
| `--red-50/100` | Light red bg | Dark red bg | Error backgrounds |
| `--red-500/600` | Red text/icons | Same | Error accents |

### Testing Dark Mode

1. In browser DevTools: Set `prefers-color-scheme: dark`
2. In Playwright: `await page.emulateMedia({ colorScheme: 'dark' })`
3. System preference: Change OS dark mode setting

---

## Resources

- **Pattern Library:** [CSS_PATTERNS.md](./CSS_PATTERNS.md)
- **Component Guidelines:** [COMPONENT_STYLING.md](./COMPONENT_STYLING.md)
- **Styling Guidelines:** [STYLING_GUIDELINES.md](./STYLING_GUIDELINES.md)

---

**Last Updated:** 2025-11-19
**Version:** 2.0.0
**Maintained By:** Frontend Team