UI Components¶

This document defines the visual specifications, anatomy, variants, and interaction states for all UI components. Each component maps to a file in src/shared/ui/ or src/entities/*/ui/. Visual tokens (colors, spacing, typography) are defined in DESIGN_SYSTEM.md and not duplicated here. Responsive behavior is defined in RESPONSIVE_STRATEGY.md.

Related Documents¶

Table of Contents¶

• UI Components
  • Related Documents
• Table of Contents
• Design Principles
• Data-Driven Rendering Principle
  • Schema Field Classification
  • Always Available (Required by Schema)
  • Conditionally Rendered (Optional by Schema)
  • Rendering Rules
  • Implementation Pattern
• Shared UI Components
  • Button
  • Variants
  • Sizes
  • States
  • Input
  • Anatomy
  • Specs
  • SearchBar
  • Anatomy
  • Specs
  • Card
  • Variants
  • Specs
  • Badge
  • Variants
  • Specs
  • Slider
  • Anatomy
  • Specs
  • Checkbox
  • States
  • Specs
  • Select
  • Specs
  • Spinner
  • Specs
  • Modal
  • Specs
  • Pagination
  • Specs
  • Tabs
  • Anatomy
  • Specs
  • ErrorFallback
  • Specs
• Entity Components
  • VehicleCard
  • Desktop Anatomy (Grid)
  • Mobile Anatomy (List)
  • Specs
  • Vehicle Image Styling
  • VehicleSpecsTable
  • Anatomy
  • Specs
• Feature Components
  • SearchBar (Feature)
  • Behavior
  • FilterPanel
  • Desktop Anatomy
  • Specs
  • CompareTable
  • Desktop Anatomy (Overlay Panel)
  • Specs
• Interaction States
• Accessibility Requirements

Design Principles¶

1. Dark-surface native: components are designed for dark backgrounds; avoid light-bg assumptions
2. Token-only styling: all visual values reference CSS Custom Properties from tokens.css (see Design System)
3. State-complete: every interactive component defines :hover, :focus-visible, :active, and :disabled states
4. Compose, don't configure: prefer small, composable components over monolithic ones with many boolean props (SRP / SOLID)
5. Data-driven rendering: components only render fields that exist in the vehicle data — see Data-Driven Rendering Principle below

Data-Driven Rendering Principle¶

The vehicle schema (reference_20260216.json) defines required and optional fields. Components must adapt intelligently to what data each vehicle actually has, following SOLID's Single Responsibility (each component renders one concern) and DRY (one utility for null-checking, reused everywhere).

Schema Field Classification¶

Always Available (Required by Schema)¶

These fields are guaranteed to exist on every vehicle and can be rendered unconditionally.

Conditionally Rendered (Optional by Schema)¶

These fields may or may not exist. Components must check for presence before rendering.

Rendering Rules¶

1. Never show empty labels: if performance.acceleration_0_100_kmh_s is undefined/null, the entire "0-100 km/h" stat pill must not render — not even with a dash or "N/A"
2. Section collapse: if an entire optional section has no data (e.g., all dimensions fields are missing), the section header and container must not render
3. Comparison row skip: in the CompareTable, if none of the compared vehicles have a given field, the entire row is omitted. If some have it and others don't, show "—" for vehicles without the data
4. Filter adaptability: filter options (e.g., Vehicle Type checkboxes) should only show values that actually exist in the loaded dataset, not all possible enum values
5. Tab visibility: detail page tabs (Charging Curve, Range Scenarios) only appear if the vehicle has dc_charge_curve or real_world range data respectively

Implementation Pattern¶

A single reusable utility in shared/lib/ handles field presence checking, keeping the codebase DRY:

// shared/lib/data-presence.ts

/** Returns true if value is not null, undefined, or empty array/object */
export function hasData<T>(value: T | null | undefined): value is T {
  if (value === null || value === undefined) return false;
  if (Array.isArray(value)) return value.length > 0;
  if (typeof value === "object") return Object.keys(value).length > 0;
  return true;
}

/** Renders children only if value has data. Passes validated value to render. */
export function DataField<T>({
  value,
  render,
}: {
  value: T | null | undefined;
  render: (data: T) => React.ReactNode;
}) {
  return hasData(value) ? <>{render(value)}</> : null;
}

Usage in components:

// Only render the 0-100 stat if performance data exists
<DataField
  value={vehicle.performance?.acceleration_0_100_kmh_s}
  render={(val) => <SpecPill label="0-100 km/h" value={`${val}s`} />}
/>;

// Only render Charging Curve tab if data exists
{
  hasData(vehicle.charging?.dc_charge_curve) && (
    <Tab label="Charging Curve">
      <ChargingCurveChart data={vehicle.charging.dc_charge_curve} />
    </Tab>
  );
}

[!IMPORTANT] The hasData utility is the single source of truth for field presence checks. All components must use it instead of inline !== undefined checks. This ensures consistent behavior and a single place to update if null-checking logic evolves.

Shared UI Components¶

Button¶

Reusable button with multiple variants and sizes.

Variants¶

Sizes¶

States¶

stateDiagram-v2
    [*] --> s_Default
    s_Default: Default
    s_Hover: Hover
    s_Active: Active
    s_FocusVisible: FocusVisible
    s_Disabled: Disabled

    s_Default --> s_Hover: hover
    s_Hover --> s_Active: mousedown
    s_Active --> s_Default: mouseup

    s_Default --> s_FocusVisible: tab focus
    s_FocusVisible --> s_Active: enter/space

    s_Default --> s_Disabled: prop disabled=true
    s_Hover --> s_Disabled: prop disabled=true

• Hover: filter: brightness(1.1), add --glow-cta shadow
• Active: transform: scale(0.98)
• Focus-visible: outline: 2px solid var(--state-focus-ring), outline-offset: 2px
• Disabled: opacity: var(--state-disabled-opacity), pointer-events: none

Input¶

Text input field with support for adornments (icons, buttons).

Anatomy¶

block-beta
  columns 3
  IconL["[icon]"]:1
  Input["placeholder / value"]:1
  IconR["[icon]"]:1

  style IconL fill:none,stroke:none
  style Input fill:#111827,stroke:#374151
  style IconR fill:none,stroke:none

Specs¶

SearchBar¶

The global search component in the header.

Anatomy¶

block-beta
  columns 3
  IconL["🔍"]:1
  Input["Search EV Models, Specs, or Features..."]:1
  IconR["🎤"]:1

  style IconL fill:none,stroke:none
  style Input fill:#111827,stroke:#374151
  style IconR fill:none,stroke:none

Specs¶

Card¶

Generic container component with glassmorphism surface.

Variants¶

Specs¶

Badge¶

Small informational tag for categories and labels.

Variants¶

Specs¶

Slider¶

Range selector for filter values (Range, Battery, Charging Power, 0-100 km/h).

Anatomy¶

block-beta
  columns 1
  block:Group
    columns 2
    Label["Label"]
    Value["Value"]
  end
  block:Slider
    columns 5
    Filled["━━━━━━"]:3
    Thumb["(thumb)"]:1
    Empty["─────"]:1
  end

  style Label fill:none,stroke:none
  style Value fill:none,stroke:none
  style Filled fill:none,stroke:none,color:#10b981
  style Thumb fill:#10b981,stroke:#fff,stroke-width:2px,color:#fff
  style Empty fill:none,stroke:none,color:#4b5563

Specs¶

Checkbox¶

Filter checkboxes with consistent dark-theme styling.

States¶

Specs¶

Select¶

Dropdown selector for filter categories.

Specs¶

Spinner¶

Loading indicator for data fetching states.

Specs¶

Modal¶

Overlay container used for the Comparison panel on desktop.

Specs¶

Pagination¶

Page navigation for the vehicle card grid.

Specs¶

Tabs¶

Horizontal tab switcher for vehicle detail sub-sections.

Anatomy¶

block-beta
  columns 4
  Tab1["Overview"]:1
  Tab2["Charging Curve"]:1
  Tab3["Range Scenarios"]:1
  Tab4["Full Specs"]:1

  ActiveLine["━━━━━━━━"]:1
  Inactive1["   "]:1
  Inactive2["   "]:1
  Inactive3["   "]:1

  style Tab1 fill:none,stroke:none,color:#fff
  style Tab2 fill:none,stroke:none,color:#9ca3af
  style Tab3 fill:none,stroke:none,color:#9ca3af
  style Tab4 fill:none,stroke:none,color:#9ca3af
  style ActiveLine fill:none,stroke:none,color:#10b981
  style Inactive1 fill:none,stroke:none
  style Inactive2 fill:none,stroke:none
  style Inactive3 fill:none,stroke:none

Specs¶

ErrorFallback¶

Displayed when an Error Boundary catches an error.

Specs¶

Entity Components¶

VehicleCard¶

The primary vehicle display card used in the grid/list views.

Desktop Anatomy (Grid)¶

block-beta
  columns 1
  block:Header
    columns 2
    Space:1
    Fav["♡"]:1
  end
  Image["[Vehicle Image]"]
  Title["Make Model"]
  block:Stats
    columns 3
    S1["450 \n WLTP km"]
    S2["28.6 \n kWh"]
    S3["7.5 \n 0-100"]
  end
  Btn["Compare"]

  style Image fill:#1f2937,stroke:none
  style Title fill:none,stroke:none
  style Btn fill:#10b981,stroke:none,color:#fff

Mobile Anatomy (List)¶

block-beta
  columns 2
  Image["[Image]"]:1
  block:Content
    columns 1
    block:Header
      columns 2
      Title["Make Model"]
      Fav["♡"]
    end
    block:Stats
        columns 3
        S1["450 km"]
        S2["28.6 kWh"]
        S3["7.5s"]
    end
    Btn["Compare"]
  end

  style Image fill:#1f2937,stroke:none
  style Btn fill:#10b981,stroke:none,color:#fff

Specs¶

Vehicle Image Styling¶

Vehicle images are treated with a subtle blue/cyan tint to match the dark UI aesthetic:

.vehicleImage {
  filter: brightness(0.9) contrast(1.1) saturate(0.8);
  opacity: var(--opacity-image);
  transition: var(--transition-transform);
}

.vehicleImage:hover {
  transform: scale(1.05);
}

VehicleSpecsTable¶

Key specs display in both the card and the detail page.

Anatomy¶

block-beta
  columns 4
  P1["$14.6k \n Price"]:1
  P2["450 km \n WLTP"]:1
  P3["23.5 kWh \n Battery"]:1
  P4["3.8s \n 0-100"]:1

  style P1 fill:#1f2937,stroke:#374151
  style P2 fill:#1f2937,stroke:#374151
  style P3 fill:#1f2937,stroke:#374151
  style P4 fill:#1f2937,stroke:#374151

Specs¶

Feature Components¶

SearchBar (Feature)¶

The global search component combining Input + autocomplete dropdown.

Behavior¶

1. User types → debounced search (300ms)
2. Results appear in dropdown overlay
3. Each result shows: vehicle image (mini), make + model, year
4. Click navigates to /vehicle/:code
5. Escape clears and closes dropdown

FilterPanel¶

Sidebar filter panel visible on desktop, collapsible accordion on mobile.

Desktop Anatomy¶

block-beta
  columns 1
  Title["Filtering"]:1

  RangeLabel["Range (WLTP km) 500"]:1
  RangeSlider["●━━━━━━━○──"]:1

  BatteryLabel["Battery (kWh) 230"]:1
  BatterySlider["●━━━━━○────"]:1

  Check1["[ ] Market"]:1
  Check2["[x] Compared"]:1

  TypeLabel["Vehicle Type"]:1
  Check3["[ ] SUV"]:1
  Check4["[ ] Sedan"]:1

  style Title fill:none,stroke:none
  style RangeSlider fill:none,stroke:none,color:#10b981
  style BatterySlider fill:none,stroke:none,color:#10b981

Specs¶

CompareTable¶

Side-by-side vehicle comparison with data rows and visualizations.

Desktop Anatomy (Overlay Panel)¶

block-beta
  columns 1
  block:Row1
    columns 1
    Header["Comparison (X)"]
    block:Cols
        columns 3
        V1["Vehicle 1 \n [Img] \n Tesla M3"]
        V2["Vehicle 2 \n [Img] \n BYD Seal"]
        V3["Vehicle 3 \n [Img] \n Porsche T"]

        R1["150 km"]
        R2["7.7 km"]
        R3["2.3 km"]

        C1["[Radar]"]
        C2["[Radar]"]
        C3["[Radar]"]
    end
  end

  style V1 fill:#1f2937,stroke:#374151
  style V2 fill:#1f2937,stroke:#374151
  style V3 fill:#1f2937,stroke:#374151

Specs¶

Interaction States¶

Every interactive element follows this consistent state model:

Accessibility Requirements¶

All components must meet WCAG 2.1 AA standards:

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}