Design System¶

This document defines the complete visual language for the Open EV Data UI. Every design token, color, typographic scale, and spacing unit documented here maps directly to CSS Custom Properties in src/shared/styles/tokens.css.

Related Documents¶

Table of Contents¶

• Design System
  • Related Documents
• Table of Contents
• Design Philosophy
• Color System
  • Core Palette
  • Gradient Definitions
  • Semantic Colors
  • Surface and Background Colors
  • Border Colors
  • Text Colors
  • State Colors
  • Chart and Data Visualization Colors
• Typography
  • Font Family
  • Type Scale
  • Font Weights
  • Line Heights
  • Letter Spacing
• Spacing
• Border Radius
• Shadows and Elevation
  • Elevation Layers
• Opacity
• Transitions and Animations
  • Transition Durations
  • Easing Functions
  • Precomposed Transitions
  • Animation Keyframes
• Z-Index Scale
• Icons and Iconography
  • Icon Library
  • Icon Sizing
  • Icon Color Rules
• Design Token Implementation
  • File: tokens.css

Design Philosophy¶

The Open EV Data UI follows a dark-first, data-driven visual approach designed to evoke a premium automotive dashboard experience. The design principles are:

1. Dark Elegance: deep, rich dark backgrounds that reduce eye strain and make data visuals pop
2. Cyan Luminance: a signature cyan/teal accent that conveys technology, energy, and electric mobility
3. Glassmorphism Depth: translucent surfaces with subtle blur that create layer hierarchy without heaviness
4. Data Clarity: every visual choice serves readability — high contrast text, structured card layouts, and clear visual grouping
5. Restrained Animation: purposeful micro-interactions that provide feedback without distraction
6. Data-Driven Rendering: the UI adapts to the data each vehicle actually has — sections, fields, charts, and comparison rows are rendered only when the underlying data exists. No empty states, no placeholder labels for missing values. Components use conditional rendering driven by field presence checks against the schema. See UI Components — Data-Driven Rendering for implementation patterns

[!IMPORTANT] All color values must be defined as CSS Custom Properties in tokens.css and never as hard-coded values in component stylesheets. This ensures consistency and enables future theme extensions (e.g., light mode).

Color System¶

Core Palette¶

The foundational brand colors from which all derived colors are generated.

Gradient Definitions¶

Semantic Colors¶

Colors tied to specific UI meanings.

Surface and Background Colors¶

The layered dark background system that creates depth and hierarchy.

Border Colors¶

Text Colors¶

State Colors¶

Chart and Data Visualization Colors¶

Colors specifically for charts, radar diagrams, and data comparisons.

Typography¶

Font Family¶

[!NOTE] Inter is loaded from Google Fonts with weights 400, 500, 600, and 700. It is known for its excellent readability at small sizes and screen rendering, making it ideal for data-heavy interfaces.

Type Scale¶

Based on a 1.200 (Minor Third) scale with 16px base.

Font Weights¶

Line Heights¶

Letter Spacing¶

Spacing¶

An 8px-base spacing scale for consistent rhythm across all layouts.

[!TIP] Use the spacing tokens exclusively. Never use arbitrary pixel values for margins and paddings. The 4px/8px grid ensures visual alignment across all components.

Border Radius¶

Shadows and Elevation¶

The shadow system creates depth through subtle, layered shadows on the dark background. Instead of traditional drop-shadows (which are less visible on dark backgrounds), the system emphasizes glow effects and border luminance.

Elevation Layers¶

block-beta
  columns 1
  block:Layer0
    columns 1
    L0["Layer 0: --bg-base (Page background)"]
    block:Layer1
      columns 1
      L1["Layer 1: --bg-surface-1 (Sidebar, main content)"]
      block:Layer2
        columns 1
        L2["Layer 2: --bg-surface-2 (Cards, panels)"]
        block:Layer3
            columns 1
            L3["Layer 3: --bg-surface-3 (Modals, popovers)"]
        end
      end
    end
  end

  style Layer0 fill:#111827,stroke:#374151,color:#fff
  style Layer1 fill:#1f2937,stroke:#4b5563,color:#fff
  style Layer2 fill:#374151,stroke:#6b7280,color:#fff
  style Layer3 fill:#4b5563,stroke:#9ca3af,color:#fff

  style L0 fill:none,stroke:none,color:#fff
  style L1 fill:none,stroke:none,color:#fff
  style L2 fill:none,stroke:none,color:#fff
  style L3 fill:none,stroke:none,color:#fff

Opacity¶

Transitions and Animations¶

All interactive elements must use consistent transition values for a polished experience.

Transition Durations¶

Easing Functions¶

Precomposed Transitions¶

Animation Keyframes¶

/* Card appear animation for staggered loading */
@keyframes fade-in-up {
  from {
    opacity: 0;
    transform: translateY(12px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* Pulse for loading/skeleton states */
@keyframes pulse {
  0%,
  100% {
    opacity: 1;
  }
  50% {
    opacity: 0.5;
  }
}

/* Slide-in for comparison panel */
@keyframes slide-in-right {
  from {
    transform: translateX(100%);
  }
  to {
    transform: translateX(0);
  }
}

/* Glow pulse for selected/active elements */
@keyframes glow-pulse {
  0%,
  100% {
    box-shadow: 0 0 8px hsla(180, 80%, 50%, 0.2);
  }
  50% {
    box-shadow: 0 0 16px hsla(180, 80%, 50%, 0.4);
  }
}

Z-Index Scale¶

A managed z-index scale to prevent stacking conflicts.

Icons and Iconography¶

Icon Library¶

The project uses Lucide React — a lightweight, tree-shakeable icon library with consistent 24×24 grid.

Icon Sizing¶

Icon Color Rules¶

• Icons inherit currentColor by default
• Action icons use --text-secondary at rest and --text-primary on hover
• Decorative/semantic icons use their respective semantic color tokens
• Icons on CTAs always use --text-on-cta

Design Token Implementation¶

All tokens are defined in src/shared/styles/tokens.css as CSS Custom Properties on the :root selector.

File: tokens.css¶

:root {
  /* === Colors: Core === */
  --color-primary: hsl(180, 80%, 50%);
  --color-primary-light: hsl(180, 80%, 65%);
  --color-primary-dark: hsl(180, 80%, 35%);
  --color-primary-muted: hsla(180, 80%, 50%, 0.15);
  --color-secondary: hsl(150, 70%, 45%);
  --color-secondary-light: hsl(150, 70%, 55%);
  --color-secondary-dark: hsl(150, 70%, 35%);

  /* === Colors: Semantic === */
  --color-success: hsl(145, 65%, 45%);
  --color-warning: hsl(40, 90%, 55%);
  --color-error: hsl(0, 75%, 55%);
  --color-info: hsl(210, 70%, 55%);

  /* === Backgrounds === */
  --bg-base: hsl(210, 35%, 7%);
  --bg-surface-1: hsl(210, 30%, 10%);
  --bg-surface-2: hsl(210, 28%, 13%);
  --bg-surface-3: hsl(210, 25%, 16%);
  --bg-glass: hsla(210, 30%, 12%, 0.7);
  --bg-input: hsl(210, 30%, 9%);
  --bg-card-highlight: hsla(180, 60%, 50%, 0.05);

  /* === Text === */
  --text-primary: hsl(210, 15%, 93%);
  --text-secondary: hsl(210, 15%, 68%);
  --text-tertiary: hsl(210, 15%, 48%);
  --text-accent: hsl(180, 80%, 55%);

  /* === Borders === */
  --border-subtle: hsla(210, 20%, 30%, 0.3);
  --border-default: hsla(210, 20%, 40%, 0.4);
  --border-primary: hsla(180, 80%, 50%, 0.4);

  /* === Gradients === */
  --gradient-cta: linear-gradient(
    135deg,
    hsl(160, 70%, 40%),
    hsl(150, 80%, 50%)
  );
  --gradient-surface: linear-gradient(
    180deg,
    hsla(200, 40%, 12%, 0.8),
    hsla(200, 40%, 8%, 0.6)
  );

  /* === Typography === */
  --font-primary:
    "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", monospace;

  /* === Spacing === */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;
  --space-16: 64px;
  --space-20: 80px;

  /* === Radius === */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;
  --radius-2xl: 24px;
  --radius-full: 9999px;

  /* === Shadows === */
  --shadow-md: 0 4px 12px hsla(0, 0%, 0%, 0.4);
  --shadow-lg: 0 8px 24px hsla(0, 0%, 0%, 0.5);
  --glow-primary: 0 0 12px hsla(180, 80%, 50%, 0.2);

  /* === Transitions === */
  --duration-fast: 120ms;
  --duration-normal: 200ms;
  --duration-slow: 350ms;
  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);

  /* === Z-Index === */
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-overlay: 300;
  --z-modal: 400;
  --z-toast: 600;
}

[!NOTE] This snippet is a condensed reference. The actual tokens.css file should include all tokens listed in the tables above. This condensed version shows the structure and naming convention.