intercept/docs/superpowers/specs/2026-04-13-ui-ux-improvements-design.md

# INTERCEPT UI/UX Improvements — Design Spec

**Date:** 2026-04-13  
**Status:** Approved  
**Scope:** Frontend (CSS, JS, HTML) + backend stubs for new features

---

## Overview

INTERCEPT has grown to 20+ modes faster than its design system has kept pace. The goal of this initiative is to establish a "Mission Control" visual identity — tactical, ops-center, every pixel earning its place — and apply it consistently across the entire application. Work is decomposed into four sequential sub-projects, each building on the last.

## Aesthetic Direction

**Mission Control.** Dense, tactical, ops-center feel. Radar aesthetics, glowing blips, HUD overlays, tight data-rich layouts. Think NORAD or air traffic control.

**Maps:** Premium dark map base (rich land/water separation, minimal labels) with tactical chrome on top — HUD corner panels, range rings, lat/lon grid, custom markers.

**Navigation:** Keep existing sidebar structure, polish execution — density, group headers, active states, collapsible groups.

---

## Sub-Project 1: Design System Uplift + Sidebar Polish

**Goal:** Establish the Mission Control visual language as the new baseline. Every subsequent sub-project inherits from this.

### CSS Token Changes (`static/css/core/variables.css`)

| Token | Current | New | Reason |
|---|---|---|---|
| `--bg-primary` | `#0a0c10` | `#06080d` | Deeper black for richer depth |
| `--bg-secondary` | `#0f1218` | `#090c12` | Consistent depth step |
| New: `--accent-cyan-glow` | — | `rgba(74,158,255,0.15)` | Panel borders and active states |
| `--text-xs` | `10px` | `9px` | Tighter data density |
| `--text-sm` | `12px` | `11px` | Tighter data density |
| New: `--scanline` | — | `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.03) 2px, rgba(0,0,0,0.03) 4px)` | Subtle scanline texture for visual containers |

### Sidebar (`templates/partials/nav.html`, `static/css/core/layout.css`)

- **Group headers:** Uppercase letter-spacing treatment with a fine left-border accent line.
- **Active mode button:** Replace background fill with a 3px left-border glow (`--accent-cyan` with blur) + subtle background tint.
- **Icon sizing:** Standardise all nav button icons to a consistent size (currently varies between modes).
- **Hover state:** Replace flat highlight with `--accent-cyan-glow` background.
- **Group collapse/expand:** Each nav group gets a toggle arrow. State persisted in `localStorage`. Allows users to hide groups they don't use.

### Global Panel Treatment (`static/css/core/components.css`)

- Panel headers: thin gradient top-border (`--accent-cyan` → transparent) for visual hierarchy.
- Panel indicator dots: pulse animation when active (extend existing `.panel-indicator.active` rule).
- Card backgrounds: subtle inner vignette via `box-shadow: inset 0 0 40px rgba(0,0,0,0.3)`.
- Scanline texture applied to all `.visuals-container` elements via `::after` pseudo-element.

---

## Sub-Project 2: Maps Overhaul

**Goal:** Premium map base + tactical chrome. Shared utility applied to all map-using modes.

**Affected pages:** ADS-B dashboard, AIS dashboard, Satellite dashboard, APRS, GPS, Radiosonde map.

### Tile Upgrade

- New default tile provider: **Stadia Maps "Alidade Smooth Dark"** — cleaner land/water separation, minimal label noise, free tier available (requires a free API key from stadiamaps.com; key stored in settings/env var `INTERCEPT_STADIA_KEY`).
- Add **"Tactical"** option in settings tile picker: near-black base, minimal labels, overlays do the visual work.
- Settings modal tile picker updated to include previews of each style.

### Custom Markers

Replace default Leaflet `divIcon` circles with SVG symbols:

- **Aircraft:** Rotated arrow/chevron by heading. Coloured by category: civil (`--accent-cyan`), military (`--accent-orange`), emergency (`--accent-red`). Sized by altitude band (high/mid/low).
- **Vessels:** Ship-silhouette SVG rotated by COG. Coloured by vessel type.
- **Satellites:** Simple diamond marker with pass arc overlay.
- **Selection popup:** Dark glass panel (backdrop-filter blur, `--bg-elevated` background, `--border-color` border), monospace data rows, no default Leaflet chrome.

### Tactical Overlays (shared map utility `static/js/map-utils.js`)

- **Range rings:** Dashed SVG circles at configurable NM/km intervals, label at ring edge.
- **Lat/lon grid:** Subtle graticule overlay, toggleable, 5° or 10° spacing.
- **Observer reticle:** Crosshair SVG replacing the current circle marker.
- **Flight/vessel trails:** Gradient fade — full opacity at current position, transparent at tail. Trail length configurable.
- **HUD corner panels:**
  - Top-left: contact count + mode name
  - Top-right: UTC clock + SDR status dot
  - Bottom-right: scale bar
  - Panels use `backdrop-filter: blur(8px)`, dark glass style.

### Implementation Note

Extract shared map initialisation into `static/js/map-utils.js`. Each dashboard calls `MapUtils.init(container, options)` and `MapUtils.addTacticalOverlays(map, options)`. Reduces duplication across the 6 map-using pages.

---

## Sub-Project 3: Mode Polish Sprint

**Goal:** Apply the new design system to the 12 flagged modes. Consistent structure, no mode feeling like a rough prototype.

**Flagged modes:** Pager, 433MHz Sensors, Sub-GHz, Morse/OOK, GPS, APRS, Radiosonde, WeFax, System Health, Meshtastic, VDL2, ACARS.

### Shared Treatment (all 12 modes)

- **Scan indicator:** Animated dot + status text in list header. Pattern from WiFi/Bluetooth applied universally.
- **Sort + filter controls row:** Where a list exists, add sort controls (signal/name/time) in the list header.
- **Empty states:** All modes use `components/empty_state.html` consistently with mode-specific copy.
- **Control panels:** Unified layout — label left, input right, consistent `--space-3` gaps.
- **Data rows:** 2-line row treatment — primary info on line 1, secondary metadata on line 2 (signal level, timestamp, etc.).

### Mode-Specific Highlights

**Pager, ACARS, VDL2:**
- Message rows: signal strength bar on the left edge, collapsible raw data section, relative timestamp with absolute on hover.
- Message type badge (coloured by category/priority).

**433MHz Sensors:**
- Sensor cards grouped by device type with a category header.
- Last-seen freshness indicator (green → amber → red based on age).
- Per-sensor RSSI sparkline (reuse Chart.js pattern from WiFi signal history).

**Sub-GHz, Morse/OOK, WeFax:**
- Signal visualisation panels get scanline texture + dark glass aesthetic.
- WeFax image gallery upgraded: lightbox overlay, larger thumbnails, metadata strip below each image.

**Meshtastic:**
- Chat-style message layout (sent right, received left, timestamp inline).
- Node list with signal quality bars (RSSI + SNR visualised as bar segments).

**System Health:**
- Metric cards in Grafana style: large value, small label, sparkline, status colour border.
- Process list: coloured status pill (running/stopped/error), uptime, PID.

**GPS, APRS, Radiosonde:**
- Map-centric layout using the Sub-Project 2 shared map utility (requires Sub-Project 2 complete first).
- Sub-Project 2 handles the map surface itself (tiles, markers, overlays). Sub-Project 3 handles the surrounding UI: control panel layout, telemetry sidebar panel, empty states, and scan indicator.
- These two modes should be done last in the Sub-Project 3 sprint, after Sub-Project 2 is merged.

---

## Sub-Project 4: New Features

### 4a — Spectrum Overview Dashboard (`/spectrum`)

A new full-screen dashboard showing a wideband frequency sweep (rtl_power) as a waterfall/bar chart. Colour-coded markers overlay the sweep at frequencies used by active modes. Clicking a marker navigates to that mode.

- Backend: new `/spectrum` route + SSE stream from rtl_power.
- Frontend: Chart.js frequency bar chart, mode markers as overlaid labels.
- Entry point: new nav item in Signals group, plus a link from the System Health mode.

### 4b — Alerts & Trigger Engine

Rule-based alert system evaluated server-side against SSE event streams.

- **Rule schema:** `{ event_type, condition_field, condition_op, condition_value, action_type, action_payload }`
- **Storage:** New `alerts` SQLite table in `instance/`.
- **UI:** Rule builder modal accessible from a new "Alerts" nav item. Rule list with enable/disable toggle, test button.
- **Initial event types:**
  - Aircraft: callsign match, squawk code, altitude threshold, military flag
  - Bluetooth: new tracker detected, specific MAC seen
  - Pager: message keyword match
  - AIS: vessel type, MMSI match
- **Actions:** Desktop notification, audio alert (reuse existing alert sounds), log to file.

### 4c — Signal Recording & Playback

Per-mode session recording of decoded output (not I/Q — storage/complexity deferred).

- **Record:** "Record" toggle button in each mode's control panel. Saves decoded events as timestamped JSON to `data/recordings/<mode>/<timestamp>.json`.
- **Playback:** Recording browser in a modal. Select a recording, choose playback speed (1×, 2×, 5×). Playback re-streams events through the existing SSE infrastructure via a `/playback/stream` endpoint.
- **I/Q recording:** Out of scope for this phase.

### 4d — Signal Identification

"What is this?" capability in the Listening Post (waterfall) mode.

- User selects a frequency range on the waterfall.
- Backend calls `inspectrum` (if installed) or a lightweight Python classifier against the captured I/Q segment.
- Returns: estimated modulation type, bandwidth, symbol rate, and a match against a curated known-signals database (JSON file).
- UI: result panel slides up from the bottom of the waterfall with signal details and suggested decoder.
- Graceful degradation: button is hidden if `inspectrum` is not installed.

### 4e — Mobile PWA

Installable, responsive INTERCEPT for field use.

- `static/manifest.json`: name, icons, display standalone, theme colour.
- Service worker (`static/sw.js`): cache shell assets for offline load. SSE streams remain live-only.
- **Responsive breakpoints** (`static/css/responsive.css`): sidebar collapses to bottom tab bar on `max-width: 768px`. Priority mobile views: BT Locate, WiFi Locate, GPS (field-use modes). Map-heavy modes scale gracefully. Control panels stack vertically on narrow screens.
- Home screen icons: generate from existing `favicon.svg` at 192×192 and 512×512.

---

## Implementation Order

1. Sub-Project 1 — Design System + Sidebar (foundation, ~1 week)
2. Sub-Project 2 — Maps Overhaul (high impact, ~1 week)
3. Sub-Project 3 — Mode Polish Sprint (breadth, ~2 weeks)
4. Sub-Project 4 — New Features (sequentially: Spectrum → Alerts → Recording → Signal ID → PWA)

## Out of Scope

- I/Q signal recording (deferred to a later phase)
- Backend infrastructure changes beyond what new features require
- New SDR hardware support
- Existing WiFi and Bluetooth modes (recently redesigned, not flagged)