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:

.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:

.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:

.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:

.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:

.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:

.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:

.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:

@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

/* 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

/* 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

.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

.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

/* 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

/* 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

/* 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
• Component Guidelines: COMPONENT_STYLING.md
• Styling Guidelines: STYLING_GUIDELINES.md

---

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