# DESIGN.md — MotorSignal Hybrid v1 Canonical Tokens & Components

## 1. Visual Language & Principles
- **Theme Name**: MotorSignal Precision Telemetry & Community (Hybrid v1)
- **Visual Direction**: Conventional cockpit layout clarity, high-contrast anti-glare data hierarchy, restrained cyan branding accents, and strict zero-clutter riding ergonomics.
- **Static Recording Discipline**: Active recording indicators (`REC • LIVE`) must remain 100% static (no pulsating, flashing, or shifting animations) to eliminate rider distraction during high-speed operation.
- **Physical Touch Enforcement**: Strict minimum `48×48 CSS px` (48×48dp) touch boundaries across all buttons, segmented toggles, navigation tabs, and modal triggers. Primary riding controls enforce `56dp` minimum height.
- **Platform Inset Rules**: Dynamic runtime safe-area clearance (`SafeArea` / `MediaQuery.of(context).padding` in Flutter; `env(safe-area-inset-*)` in Web/PWA).
- **Accessibility & Runtime Verification**: Accessibility scaling (200% text scale) and runtime performance claims are treated as unverified targets until proven via emulator/device test execution.

---

## 2. Canonical Token Set (Synchronized Day & Night Modes)

> [!NOTE]
> Canonical Canvas Token Reconciliation: `#0B1326` is the canonical night canvas background. Hex variants like `#081326` or `#0B111E` appearing in intermediate drafts are reconciled to canonical `#0B1326`.

```json
{
  "theme": "MotorSignal Hybrid v1",
  "modes": {
    "night": {
      "surface_canvas": "#0B1326",
      "surface_card_primary": "#111C38",
      "surface_card_secondary": "#17223B",
      "surface_card_lowest": "#060E20",
      "surface_border": "#1E293B",
      "surface_border_subtle": "#24324D",
      "text_primary": "#DAE2FD",
      "text_muted": "#869397",
      "brand_cyan": "#06B6D4",
      "brand_cyan_bright": "#22D3EE",
      "brand_cyan_container": "#00424F",
      "rec_static_green": "#10B981",
      "rec_static_green_bg": "#064E3B",
      "caution_amber": "#F59E0B",
      "danger_red": "#EF4444"
    },
    "day": {
      "surface_canvas": "#F8FAFC",
      "surface_card_primary": "#FFFFFF",
      "surface_card_secondary": "#F1F5F9",
      "surface_card_lowest": "#E2E8F0",
      "surface_border": "#CBD5E1",
      "surface_border_subtle": "#E2E8F0",
      "text_primary": "#0F172A",
      "text_muted": "#64748B",
      "brand_cyan": "#0284C7",
      "brand_cyan_bright": "#0EA5E9",
      "brand_cyan_container": "#E0F2FE",
      "rec_static_green": "#10B981",
      "rec_static_green_bg": "#D1FAE5",
      "caution_amber": "#D97706",
      "danger_red": "#DC2626"
    }
  },
  "typography": {
    "font_primary": "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
    "font_telemetry": "JetBrains Mono, monospace",
    "scale": {
      "display_speed": "58px–72px (font-black / tabular)",
      "telemetry_primary": "24px–28px (font-bold / tabular)",
      "telemetry_unit": "10px–12px (uppercase, tracking-wider)",
      "headline_lg": "24px–28px (font-bold)",
      "headline_md": "18px–20px (font-semibold)",
      "body_regular": "14px (line-height: 20px)",
      "label_nav": "10px–11px (font-medium / bold)"
    }
  },
  "touch_targets": {
    "standard_minimum": "48px × 48px",
    "primary_riding_cta": "56px height",
    "nav_bar_height": "72px"
  }
}
```

---

## 3. Reusable Component Guidelines

1. **Persistent 6-Destination Bottom Nav**:
   - Items: `Dash` (1), `Map` (2), `Activity` (3), `Garage` (4), `Social` (5), `Settings` (6).
   - Target bounding box: `≥48×48dp` per tab icon & label.

2. **Riding Dashboard Telemetry Cards**:
   - Speed Hero: High-contrast large numeral with instant unit label (`mph` or `km/h`).
   - Secondary Telemetry: Distance, Elapsed Time, Lean Dynamics (neutral max lean styling, live lean in cyan), Elevation Gain, and Braking G.
   - Pinned Action Bar: `Pause Ride` (Amber, min 56dp) and `Finish Ride` (Dark/Slate with Cyan/Green accent, min 56dp), pinned to screen base with scrollable telemetry above in accessibility text scales.
   - Non-pulsing `REC • LIVE` status badge.

3. **Group Ride Cards & Hub**:
   - Decoupled Logistics: Date, time, and staging location placed on a dedicated full-width row with clock icon to avoid button/text truncation.
   - Hitboxes: Segmented switcher (Feed vs Hub) and ride card buttons (`Manage Ride`, `Open Hub`, `Ride Details`, `Leave Pack`) sized to minimum `48dp` height.
   - Visibility & Join Policies: Strict preservation of existing permissions, host/organizer badges, and join policies.

4. **Replay HUD**:
   - Dedicated map controls locked to Top-Right quadrant, isolated from scrub timeline and lower telemetry gauges.
   - Telemetry loading/status reflects real storage retrieval (e.g. SQLite database cache or cloud bundle retrieval), replacing speculative "100% buffered in-memory" labels.
   - Scoped deletion options (*Local Device Cache Only* vs *Cloud & Local Records*). Never preselected.

5. **Account & System Status**:
   - Reflects actual device sensors (Internal Phone IMU at authoritative 20Hz pipeline). Discards unsupported 100Hz claims and invalid Pro restrictions on basic telemetry acquisition.