Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(dashboard): make every control keyboard operable and name icon-only controls (#3434)

Tejas Chopra15debbef7f17
diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.html
index 8f4c5a494..178e7e8bd 100644
--- a/headroom/dashboard/templates/dashboard.html
+++ b/headroom/dashboard/templates/dashboard.html
@@ -56,6 +56,16 @@
--ttl-card-bg: linear-gradient(180deg, rgba(34,211,238,0.10), rgba(12,16,22,0.88));
}
body { background: var(--bg); }
+ /* Accessibility: visible keyboard focus on every operable element (WCAG 2.4.7 / 2.4.11) */
+ :focus-visible { outline: 2px solid #22d3ee; outline-offset: 2px; border-radius: 4px; }
+ html:not(.dark) :focus-visible { outline-color: #0e7490; }
+ [role="button"]:focus-visible { outline-offset: -2px; }
+ .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
+ @media (prefers-reduced-motion: reduce) {
+ .pulse-live { animation: none; }
+ #feed-container { scroll-behavior: auto; }
+ .transition-colors, .transition-opacity, [x-transition] { transition: none !important; }
+ }
.sparkline { stroke: #22d3ee; stroke-width: 1.5; fill: none; }
.sparkline-area { fill: url(#sparkline-gradient); }
.trend-line { stroke: #22d3ee; stroke-width: 2; fill: none; }
@@ -113,17 +123,17 @@
</div>
<div class="flex flex-col gap-3 md:flex-row md:items-center md:gap-6">
<div class="inline-flex rounded-lg border border-border bg-surface p-1">
- <button class="px-3 py-1.5 text-sm rounded-md transition-colors"
+ <button type="button" :aria-pressed="viewMode === 'session'" class="px-3 py-1.5 text-sm rounded-md transition-colors"
:class="viewMode === 'session' ? 'bg-accent text-black' : 'text-gray-400 hover:text-gray-200'"
@click="setViewMode('session')">
Session
</button>
- <button class="px-3 py-1.5 text-sm rounded-md transition-colors"
+ <button type="button" :aria-pressed="viewMode === 'lifetime'" class="px-3 py-1.5 text-sm rounded-md transition-colors"
:class="viewMode === 'lifetime' ? 'bg-accent text-black' : 'text-gray-400 hover:text-gray-200'"
@click="setViewMode('lifetime')">
Lifetime
</button>
- <button class="px-3 py-1.5 text-sm rounded-md transition-colors"
+ <button type="button" :aria-pressed="viewMode === 'history'" class="px-3 py-1.5 text-sm rounded-md transition-colors"
:class="viewMode === 'history' ? 'bg-accent text-black' : 'text-gray-400 hover:text-gray-200'"
@click="setViewMode('history')">
Historical
@@ -132,7 +142,7 @@
<template x-if="stats.anon_telemetry_shipping">
<div class="inline-flex items-center gap-1.5 rounded-full border border-amber-500/40 bg-amber-500/10 px-2.5 py-1"
title="Anonymous aggregate telemetry is enabled. Disable with HEADROOM_TELEMETRY=off or --no-telemetry.">
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor"
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"
class="w-3 h-3 text-amber-400 shrink-0">
<path fill-rule="evenodd"
d="M6.701 2.25c.577-1 2.02-1 2.598 0l5.196 9a1.5 1.5 0 0 1-1.299 2.25H2.804a1.5 1.5 0 0 1-1.3-2.25l5.197-9ZM8 4a.75.75 0 0 1 .75.75v3a.75.75 0 0 1-1.5 0v-3A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z"
@@ -155,8 +165,8 @@
</template>
<div class="flex items-center gap-2">
<span class="text-xs text-gray-500">Status</span>
- <span class="flex items-center gap-1.5">
- <span class="w-2 h-2 rounded-full pulse-live"
+ <span class="flex items-center gap-1.5" role="status" aria-live="polite">
+ <span class="w-2 h-2 rounded-full pulse-live" aria-hidden="true"
:class="healthy ? 'bg-emerald-400' : 'bg-red-400'"></span>
<span class="text-sm" x-text="healthy ? 'Healthy' : 'Error'"></span>
</span>
@@ -169,18 +179,19 @@
title="Settings">
&#9881; Settings
</a>
- <button onclick="toggleTheme()" id="theme-toggle"
+ <button type="button" onclick="toggleTheme()" id="theme-toggle"
class="px-3 py-1.5 text-sm rounded-md border border-border bg-surface text-gray-400 hover:text-gray-200 transition-colors"
- title="Toggle light/dark mode">
- <svg class="w-4 h-4 dark:hidden" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+ title="Toggle light/dark mode" aria-label="Toggle light or dark mode">
+ <svg class="w-4 h-4 dark:hidden" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"/>
</svg>
- <svg class="w-4 h-4 hidden dark:block" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+ <svg class="w-4 h-4 hidden dark:block" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z"/>
</svg>
</button>
- <button x-show="log_full_messages" id="feed-toggle"
+ <button type="button" x-show="log_full_messages" id="feed-toggle"
class="px-3 py-1.5 text-sm rounded-md border border-border bg-surface text-gray-300 hover:text-white transition-colors"
+ :aria-expanded="feedOpen" aria-controls="feed-drawer"
@click="toggleFeed()"
:class="feedOpen ? 'bg-accent text-black' : ''">
Live Feed
@@ -227,7 +238,8 @@
<span x-text="'Of total wire: ' + (stats.tokens?.savings_percent || 0).toFixed(2) + '%'" title="Savings as fraction of all input tokens including frozen prefix"></span>
</div>
<div class="mt-2 h-8">
- <svg class="w-full h-full" viewBox="0 0 100 32" preserveAspectRatio="none">
+ <svg class="w-full h-full" viewBox="0 0 100 32" preserveAspectRatio="none" role="img"
+ :aria-label="'Savings trend sparkline, ' + (stats.savings_history || []).length + ' recent samples; latest ' + (stats.tokens?.savings_percent || 0).toFixed(1) + ' percent'">
<defs>
<linearGradient id="sparkline-gradient" x1="0%" y1="0%" x2="0%" y2="100%">
<stop offset="0%" style="stop-color:#22d3ee;stop-opacity:0.3"/>
@@ -487,7 +499,8 @@
</div>
<template x-if="(stats.savings_history || []).length >= 2">
<div class="h-32">
- <svg class="w-full h-full" viewBox="0 0 200 64" preserveAspectRatio="none">
+ <svg class="w-full h-full" viewBox="0 0 200 64" preserveAspectRatio="none" role="img"
+ :aria-label="'Savings trend chart, ' + (stats.savings_history || []).length + ' samples; ' + formatNumber(stats.tokens?.saved || 0) + ' tokens saved in total'">
<defs>
<linearGradient id="trend-gradient" x1="0%" y1="0%" x2="0%" y2="100%">
<stop offset="0%" style="stop-color:#22d3ee;stop-opacity:0.2"/>
@@ -1032,11 +1045,16 @@
<div class="divide-y divide-border">
<template x-for="req in (stats.recent_requests || [])" :key="req.request_id">
<div>
- <div class="cursor-pointer" @click="toggleExpanded(req.request_id)">
+ <div class="cursor-pointer" role="button" tabindex="0"
+ :aria-expanded="!!expandedRows[req.request_id]"
+ :aria-label="'Request at ' + formatTime(req.timestamp) + ', ' + truncateModel(req.model) + ', ' + req.savings_percent.toFixed(0) + ' percent saved. Toggle details'"
+ @click="toggleExpanded(req.request_id)"
+ @keydown.enter.prevent="toggleExpanded(req.request_id)"
+ @keydown.space.prevent="toggleExpanded(req.request_id)">
<div class="grid hover:bg-border/30 transition-colors"
style="grid-template-columns: 2rem 12fr 22fr 15fr 12fr 10fr 14fr">
<div class="px-2 py-3 text-gray-500 flex items-center justify-center">
- <span x-text="expandedRows[req.request_id] ? '-' : '+'"></span>
+ <span aria-hidden="true" x-text="expandedRows[req.request_id] ? '-' : '+'"></span>
</div>
<div class="px-4 py-3 font-mono text-gray-400 truncate" x-text="formatTime(req.timestamp)"></div>
<div class="px-4 py-3 min-w-0">
@@ -1738,7 +1756,8 @@
x-text="'Showing ' + formatNumber(historySelectedPointCount) + ' ' + historySelectedSeriesLabel.toLowerCase() + ' points'"></div>
<template x-if="historicalTrend.length >= 2">
<div class="h-48">
- <svg class="w-full h-full" viewBox="0 0 200 64" preserveAspectRatio="none">
+ <svg class="w-full h-full" viewBox="0 0 200 64" preserveAspectRatio="none" role="img"
+ aria-label="Historical savings chart. The per-model table below this chart lists the same values.">
<defs>
<linearGradient id="history-trend-gradient" x1="0%" y1="0%" x2="0%" y2="100%">
<stop offset="0%" style="stop-color:#22d3ee;stop-opacity:0.2"/>
@@ -1774,7 +1793,8 @@
<div class="flex flex-wrap gap-3 mt-3"
x-show="historyChartMode === 'tokens' && historyGranularity !== 'history' && historyModelChartSeries.length > 0">
<template x-for="(series, index) in historyModelChartSeries" :key="series.model">
- <button class="flex items-center gap-1.5 text-xs transition-opacity cursor-pointer"
+ <button type="button" :aria-pressed="historySelectedModel === series.model"
+ class="flex items-center gap-1.5 text-xs transition-opacity cursor-pointer"
:class="historyActiveModel && historyActiveModel !== series.model
? 'text-gray-600 opacity-50'
: 'text-gray-400 hover:text-gray-200'"
@@ -1829,6 +1849,10 @@
<template x-for="row in historyModelBreakdown" :key="row.model">
<tr class="border-t border-border text-gray-300 cursor-pointer transition-colors"
:class="historySelectedModel === row.model ? 'bg-card-alt' : 'hover-bg-surface'"
+ tabindex="0" role="button"
+ :aria-pressed="historySelectedModel === row.model"
+ @keydown.enter.prevent="toggleHistoryModel(row.model)"
+ @keydown.space.prevent="toggleHistoryModel(row.model)"
@click="toggleHistoryModel(row.model)"
:title="historySelectedModel === row.model
? 'Show all models'
@@ -1924,6 +1948,8 @@
x-transition:leave-start="translate-x-0"
x-transition:leave-end="translate-x-full"
@click.away="feedOpen = false"
+ @keydown.escape.window="if (feedOpen) closeFeed()"
+ id="feed-drawer" role="dialog" aria-label="Message Transformations live feed"
class="fixed top-0 right-0 h-full w-[520px] bg-surface border-l border-border z-50 flex flex-col"
style="display: none;">
@@ -1933,19 +1959,20 @@
<span class="text-sm font-medium text-gray-200">Message Transformations</span>
<span class="text-xs text-gray-500 font-mono" x-text="transformations.length + ' msgs'"></span>
</div>
- <button @click="feedOpen = false" class="text-gray-500 hover:text-gray-200 transition-colors p-1">
- <svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" viewBox="0 0 16 16" fill="currentColor">
+ <button type="button" id="feed-close" @click="closeFeed()" aria-label="Close live feed"
+ class="text-gray-500 hover:text-gray-200 transition-colors p-1">
+ <svg xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
<path d="M2.146 2.854a.5.5 0 1 1 .708-.708L8 7.293l5.146-5.147a.5.5 0 0 1 .708.708L8.707 8l5.147 5.146a.5.5 0 0 1-.708.708L8 8.707l-5.146 5.147a.5.5 0 0 1-.708-.708L7.293 8 2.146 2.854z"/>
</svg>
</button>
</div>
<!-- New messages indicator -->
- <div x-show="feedScrolled_ && feedNewCount > 0"
+ <button type="button" x-show="feedScrolled_ && feedNewCount > 0"
@click="scrollToFeedTop()"
class="absolute top-16 right-4 px-3 py-2 bg-accent text-black text-sm rounded-lg shadow-lg cursor-pointer z-50 font-medium">
<span x-text="feedNewCount"></span> new message<span x-show="feedNewCount > 1">s</span>
- </div>
+ </button>
<!-- Drawer Content (virtual scroll container) -->
<div class="flex-1 overflow-y-auto" id="feed-container"
@@ -2042,10 +2069,18 @@
},
async toggleFeed() {
- this.feedOpen = !this.feedOpen;
if (this.feedOpen) {
- await this.fetchTransformations();
+ this.closeFeed();
+ return;
}
+ this.feedOpen = true;
+ this.$nextTick(() => document.getElementById('feed-close')?.focus());
+ await this.fetchTransformations();
+ },
+
+ closeFeed() {
+ this.feedOpen = false;
+ this.$nextTick(() => document.getElementById('feed-toggle')?.focus());
},
formatVersion(value) {
diff --git a/headroom/dashboard/templates/settings.html b/headroom/dashboard/templates/settings.html
index e26aba821..b326c6e8b 100644
--- a/headroom/dashboard/templates/settings.html
+++ b/headroom/dashboard/templates/settings.html
@@ -26,6 +26,10 @@
.field-help { color: var(--muted); }
input, select { background: var(--surface); border: 1px solid var(--border); }
input:disabled, select:disabled { opacity: .55; cursor: not-allowed; }
+ /* Accessibility: visible keyboard focus on every operable element (WCAG 2.4.7 / 2.4.11) */
+ :focus-visible { outline: 2px solid #22d3ee; outline-offset: 2px; border-radius: 4px; }
+ html:not(.dark) :focus-visible { outline-color: #0e7490; }
+ @media (prefers-reduced-motion: reduce) { * { transition: none !important; animation: none !important; } }
</style>
</head>
<body class="text-gray-800 dark:text-gray-100 min-h-screen" x-data="settingsPage()" x-init="init()">
diff --git a/tests/test_dashboard_accessibility.py b/tests/test_dashboard_accessibility.py
new file mode 100644
index 000000000..cfc5be8df
--- /dev/null
+++ b/tests/test_dashboard_accessibility.py
@@ -0,0 +1,204 @@
+"""Keyboard operability and accessible-name invariants for the operator dashboard.
+
+The static tests run everywhere and pin the template contract: every control
+reachable by mouse is reachable by keyboard, every icon-only control has an
+accessible name, charts have text alternatives, and keyboard focus is visible.
+The Playwright tests drive a real browser through the same workflows.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import pytest
+
+from headroom.dashboard import get_dashboard_html
+
+TEMPLATES = Path(__file__).resolve().parents[1] / "headroom" / "dashboard" / "templates"
+DASHBOARD = (TEMPLATES / "dashboard.html").read_text()
+SETTINGS = (TEMPLATES / "settings.html").read_text()
+
+_TAG = re.compile(r"<(\w+)\b([^>]*)>", re.S)
+
+
+def _tags(html: str, name: str) -> list[str]:
+ return [attrs for tag, attrs in _TAG.findall(html) if tag == name]
+
+
[email protected]("html", [DASHBOARD, SETTINGS], ids=["dashboard", "settings"])
+def test_focus_visible_style_is_defined(html: str) -> None:
+ assert ":focus-visible {" in html
+ assert "prefers-reduced-motion" in html
+
+
[email protected]("html", [DASHBOARD, SETTINGS], ids=["dashboard", "settings"])
+def test_every_clickable_non_button_is_keyboard_operable(html: str) -> None:
+ """A div/tr with @click must expose a role, a tabindex and an Enter handler."""
+ offenders = []
+ for tag, attrs in _TAG.findall(html):
+ if tag in ("button", "a", "input", "select", "textarea", "label"):
+ continue
+ if "@click=" not in attrs and "onclick=" not in attrs:
+ continue
+ if "@click.away" in attrs and "@click=" not in attrs:
+ continue
+ ok = 'tabindex="0"' in attrs and 'role="button"' in attrs and "@keydown.enter" in attrs
+ if not ok:
+ offenders.append(f"<{tag} {attrs.strip()[:90]}>")
+ assert not offenders, offenders
+
+
+def test_icon_only_buttons_have_accessible_names() -> None:
+ """Buttons whose visible content is only an SVG need aria-label."""
+ for m in re.finditer(r"<button\b([^>]*)>(.*?)</button>", DASHBOARD, re.S):
+ attrs, inner = m.groups()
+ text = re.sub(r"<svg\b.*?</svg>", "", inner, flags=re.S)
+ text = re.sub(r"<[^>]+>", "", text).strip()
+ if not text and "x-text=" not in attrs and "x-text=" not in inner:
+ assert "aria-label=" in attrs, (
+ f"icon-only button lacks aria-label: {attrs.strip()[:80]}"
+ )
+
+
+def test_svgs_are_named_or_hidden() -> None:
+ for attrs in _tags(DASHBOARD, "svg"):
+ assert 'aria-hidden="true"' in attrs or 'role="img"' in attrs, attrs.strip()[:80]
+ for attrs in _tags(DASHBOARD, "svg"):
+ if 'role="img"' in attrs:
+ assert "aria-label" in attrs, attrs.strip()[:80]
+
+
+def test_feed_drawer_has_dialog_semantics_and_escape() -> None:
+ assert 'id="feed-drawer"' in DASHBOARD
+ assert 'role="dialog"' in DASHBOARD
+ assert "@keydown.escape.window" in DASHBOARD
+ assert 'aria-controls="feed-drawer"' in DASHBOARD
+ assert ':aria-expanded="feedOpen"' in DASHBOARD
+
+
+# --------------------------------------------------------------------------- browser
+playwright = pytest.importorskip("playwright.sync_api")
+expect = playwright.expect
+sync_playwright = playwright.sync_playwright
+
+from tests.test_dashboard_cache_ttl_playwright import ( # noqa: E402
+ _fulfill_static_asset,
+ _sample_history,
+ _sample_stats,
+)
+
+
+def _stats_with_requests() -> dict:
+ stats = copy.deepcopy(_sample_stats())
+ stats["log_full_messages"] = True
+ stats["recent_requests"] = [
+ {
+ "request_id": "req-1",
+ "timestamp": 1_756_000_000.0,
+ "model": "claude-opus-4-6",
+ "input_tokens_optimized": 1200,
+ "output_tokens": 300,
+ "savings_percent": 41.0,
+ "total_latency_ms": 1510.0,
+ "transformations": [],
+ }
+ ]
+ return stats
+
+
+def _open(page, stats: dict) -> None: # type: ignore[no-untyped-def]
+ history = _sample_history()
+ html = get_dashboard_html()
+
+ def handler(route) -> None: # type: ignore[no-untyped-def]
+ path = urlsplit(route.request.url).path
+ if path in ("/dashboard", "/"):
+ route.fulfill(status=200, content_type="text/html", body=html)
+ elif _fulfill_static_asset(route, path):
+ return
+ elif "/stats-history" in path:
+ route.fulfill(status=200, content_type="application/json", body=json.dumps(history))
+ elif path.endswith("/stats"):
+ route.fulfill(status=200, content_type="application/json", body=json.dumps(stats))
+ elif path.endswith("/health"):
+ route.fulfill(
+ status=200,
+ content_type="application/json",
+ body=json.dumps({"status": "healthy", "version": "0.3.0"}),
+ )
+ elif "/transformations/feed" in path:
+ route.fulfill(
+ status=200,
+ content_type="application/json",
+ body=json.dumps({"transformations": []}),
+ )
+ else:
+ route.continue_()
+
+ page.route("**/*", handler)
+ page.goto("http://headroom.local/dashboard")
+ page.wait_for_load_state("networkidle")
+
+
+def test_request_row_expands_with_keyboard() -> None:
+ with sync_playwright() as p:
+ browser = p.chromium.launch()
+ page = browser.new_page(viewport={"width": 1440, "height": 1600})
+ _open(page, _stats_with_requests())
+
+ row = page.get_by_role("button", name=re.compile("claude-opus-4-6.*Toggle details"))
+ expect(row).to_have_attribute("aria-expanded", "false")
+ row.focus()
+ page.keyboard.press("Enter")
+ expect(row).to_have_attribute("aria-expanded", "true")
+ page.keyboard.press("Space")
+ expect(row).to_have_attribute("aria-expanded", "false")
+
+ # Keyboard focus is visibly indicated (outline drawn by :focus-visible).
+ outline = row.evaluate("el => { el.focus(); return getComputedStyle(el).outlineStyle }")
+ assert outline != "none"
+ browser.close()
+
+
+def test_live_feed_drawer_keyboard_flow() -> None:
+ with sync_playwright() as p:
+ browser = p.chromium.launch()
+ page = browser.new_page(viewport={"width": 1440, "height": 1600})
+ _open(page, _stats_with_requests())
+
+ toggle = page.get_by_role("button", name="Live Feed", exact=True)
+ expect(toggle).to_have_attribute("aria-expanded", "false")
+ toggle.focus()
+ page.keyboard.press("Enter")
+ drawer = page.get_by_role("dialog", name="Message Transformations live feed")
+ expect(drawer).to_be_visible()
+ expect(toggle).to_have_attribute("aria-expanded", "true")
+ # Focus moves into the drawer, onto its close control.
+ expect(page.get_by_role("button", name="Close live feed")).to_be_focused()
+ # Escape closes it and returns focus to the control that opened it.
+ page.keyboard.press("Escape")
+ expect(drawer).to_be_hidden()
+ expect(toggle).to_be_focused()
+ browser.close()
+
+
+def test_header_controls_have_names_and_pressed_state() -> None:
+ with sync_playwright() as p:
+ browser = p.chromium.launch()
+ page = browser.new_page(viewport={"width": 1440, "height": 1600})
+ _open(page, _stats_with_requests())
+
+ expect(page.get_by_role("button", name="Toggle light or dark mode")).to_be_visible()
+ session = page.get_by_role("button", name="Session", exact=True)
+ lifetime = page.get_by_role("button", name="Lifetime", exact=True)
+ expect(session).to_have_attribute("aria-pressed", "true")
+ expect(lifetime).to_have_attribute("aria-pressed", "false")
+ lifetime.focus()
+ page.keyboard.press("Enter")
+ expect(lifetime).to_have_attribute("aria-pressed", "true")
+ expect(page.get_by_role("status")).to_contain_text("Healthy")
+ browser.close()