feat(viz): accessibility polish (ARIA, focus, reduced-motion)

Make the generated visualization usable with assistive tech and the
keyboard. The canvas gets role="img" with a descriptive aria-label and
tabindex so screen-reader users land on it and hear what it is; the view
tabs, graph filters, cluster toggle, and dark-mode button expose
aria-pressed state synced to their active class; the search input and
legend get labels and list semantics.

Motion respects the OS preference: the drag reheat of the d3-force
simulation is skipped under prefers-reduced-motion (the node still tracks
the cursor, its neighbors just do not spring), and a reduced-motion media
block neutralizes CSS transitions. Buttons and the canvas get a
focus-visible outline so keyboard focus is visible.

Frontend-only; regenerates the embedded viz.js/viz.css assets.

Author: BartWaardenburg

crates/cli/viz-assets/viz.css

@@ -282,3 +282,28 @@ body {
   margin-top: 4px;
   opacity: 0.7;
 }
+
+/* ── Keyboard focus visibility ─────────────────────────────── */
+
+#fallow-app button:focus-visible,
+.view-tab:focus-visible,
+.filter-btn:focus-visible,
+#fallow-darkmode:focus-visible {
+  outline: 2px solid #3B82F6;
+  outline-offset: 2px;
+}
+
+#fallow-canvas:focus-visible {
+  outline: 2px solid #3B82F6;
+  outline-offset: -2px;
+}
+
+/* ── Respect reduced-motion preference ─────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+  * {
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}

crates/cli/viz-assets/viz.js

@@ -54,6 +54,12 @@ const FONT_GROUP = 'bold 11px -apple-system, BlinkMacSystemFont, "Segoe UI", san
 const NODE_R_MIN = 3;
 const NODE_R_MAX = 12;
 
+// Respect the OS "reduce motion" setting: skip the force-simulation reheat so a
+// drag repositions the node without springing its neighbors around.
+const prefersReducedMotion = (): boolean =>
+  typeof window.matchMedia === "function" &&
+  window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
 // ── Opacity by status and filter ────────────────────────────────
 
 const STATUS_OPACITY: Record<GraphFilter, Record<VizFileStatus, number>> = {
@@ -698,8 +704,10 @@ export const graphDragStart = (state: AppState, nodeIdx: number): void => {
   const node = gvs.fileNodes[nodeIdx];
   node.fx = node.x;
   node.fy = node.y;
-  // Reheat simulation
-  if (gvs.simulation) {
+  // Reheat simulation so neighbors settle around the dragged node, unless the
+  // user asked for reduced motion (then the node still tracks the cursor via
+  // fx/fy + the explicit re-render in interactions.ts, with no spring).
+  if (gvs.simulation && !prefersReducedMotion()) {
     gvs.simulation.alphaTarget(0.3).restart();
   }
 };

viz-frontend/src/graph.ts

@@ -237,6 +237,7 @@ export const setupInteractions = (
     breadcrumbEl.style.backgroundColor = state.theme.breadcrumbBg;
     breadcrumbEl.style.color = state.theme.breadcrumbText;
     darkModeBtn.textContent = state.darkMode ? "☀" : "☾";
+    darkModeBtn.setAttribute("aria-pressed", String(state.darkMode));
     render(state);
   });
 

viz-frontend/src/interactions.ts

@@ -63,17 +63,21 @@ const init = (): void => {
   // View toggle tabs
   const viewTabs = document.createElement("div");
   viewTabs.id = "fallow-view-tabs";
+  viewTabs.setAttribute("role", "group");
+  viewTabs.setAttribute("aria-label", "Visualization view");
 
   const treemapTab = document.createElement("button");
   treemapTab.className = "view-tab active";
   treemapTab.textContent = "Treemap";
   treemapTab.dataset.view = "treemap";
+  treemapTab.setAttribute("aria-pressed", "true");
   viewTabs.appendChild(treemapTab);
 
   const graphTab = document.createElement("button");
   graphTab.className = "view-tab";
   graphTab.textContent = "Graph";
   graphTab.dataset.view = "graph";
+  graphTab.setAttribute("aria-pressed", "false");
   viewTabs.appendChild(graphTab);
 
   controls.appendChild(viewTabs);
@@ -82,6 +86,8 @@ const init = (): void => {
   const filterGroup = document.createElement("div");
   filterGroup.id = "fallow-graph-filters";
   filterGroup.style.display = "none";
+  filterGroup.setAttribute("role", "group");
+  filterGroup.setAttribute("aria-label", "Filter graph nodes");
 
   const filterButtons: Array<{ label: string; value: GraphFilter }> = [
     { label: "All", value: "all" },
@@ -91,12 +97,16 @@ const init = (): void => {
 
   for (const fb of filterButtons) {
     const btn = document.createElement("button");
-    btn.className = `filter-btn${fb.value === "all" ? " active" : ""}`;
+    const isActive = fb.value === "all";
+    btn.className = `filter-btn${isActive ? " active" : ""}`;
     btn.textContent = fb.label;
     btn.dataset.filter = fb.value;
+    btn.setAttribute("aria-pressed", String(isActive));
     btn.addEventListener("click", () => {
       for (const b of filterGroup.querySelectorAll(".filter-btn")) {
-        b.classList.toggle("active", (b as HTMLElement).dataset.filter === fb.value);
+        const on = (b as HTMLElement).dataset.filter === fb.value;
+        b.classList.toggle("active", on);
+        b.setAttribute("aria-pressed", String(on));
       }
       setGraphFilter(state!, fb.value);
     });
@@ -108,6 +118,8 @@ const init = (): void => {
   const clusterGroup = document.createElement("div");
   clusterGroup.id = "fallow-cluster-mode";
   clusterGroup.style.display = "none";
+  clusterGroup.setAttribute("role", "group");
+  clusterGroup.setAttribute("aria-label", "Graph clustering mode");
 
   const clusterLabel = document.createElement("span");
   clusterLabel.className = "cluster-label";
@@ -121,12 +133,16 @@ const init = (): void => {
 
   for (const cb of clusterButtons) {
     const btn = document.createElement("button");
-    btn.className = `filter-btn${cb.value === "directory" ? " active" : ""}`;
+    const isActive = cb.value === "directory";
+    btn.className = `filter-btn${isActive ? " active" : ""}`;
     btn.textContent = cb.label;
     btn.dataset.cluster = cb.value;
+    btn.setAttribute("aria-pressed", String(isActive));
     btn.addEventListener("click", () => {
       for (const b of clusterGroup.querySelectorAll(".filter-btn")) {
-        b.classList.toggle("active", (b as HTMLElement).dataset.cluster === cb.value);
+        const on = (b as HTMLElement).dataset.cluster === cb.value;
+        b.classList.toggle("active", on);
+        b.setAttribute("aria-pressed", String(on));
       }
       setClusterMode(state!, cb.value);
     });
@@ -140,6 +156,14 @@ const init = (): void => {
 
   const canvas = document.createElement("canvas");
   canvas.id = "fallow-canvas";
+  canvas.tabIndex = 0;
+  canvas.setAttribute("role", "img");
+  canvas.setAttribute(
+    "aria-label",
+    `Interactive visualization of ${data.summary.total_files} files. ` +
+      "Use the Treemap and Graph buttons to switch views, the search box to find files, " +
+      "and the number keys 1-3 to set graph focus depth.",
+  );
   app.appendChild(canvas);
 
   const state = createState(data, canvas);
@@ -161,11 +185,15 @@ const init = (): void => {
   darkModeBtn.id = "fallow-darkmode";
   darkModeBtn.textContent = state.darkMode ? "☀" : "☾";
   darkModeBtn.title = "Toggle dark mode";
+  darkModeBtn.setAttribute("aria-label", "Toggle dark mode");
+  darkModeBtn.setAttribute("aria-pressed", String(state.darkMode));
   controls.appendChild(darkModeBtn);
 
   // Legend
   const legend = document.createElement("div");
   legend.id = "fallow-legend";
+  legend.setAttribute("role", "list");
+  legend.setAttribute("aria-label", "Status legend");
   const legendItems: Array<[string, string]> = [
     ["Clean", state.theme.statusColors.clean],
     ["Entry point", state.theme.statusColors.entryPoint],
@@ -175,10 +203,12 @@ const init = (): void => {
   for (const [label, color] of legendItems) {
     const item = document.createElement("span");
     item.className = "legend-item";
+    item.setAttribute("role", "listitem");
 
     const swatch = document.createElement("span");
     swatch.className = "legend-swatch";
     swatch.style.backgroundColor = color;
+    swatch.setAttribute("aria-hidden", "true");
     item.appendChild(swatch);
 
     const text = document.createElement("span");
@@ -196,6 +226,8 @@ const init = (): void => {
     state.activeView = view;
     treemapTab.classList.toggle("active", view === "treemap");
     graphTab.classList.toggle("active", view === "graph");
+    treemapTab.setAttribute("aria-pressed", String(view === "treemap"));
+    graphTab.setAttribute("aria-pressed", String(view === "graph"));
     breadcrumbEl.style.display = view === "treemap" ? "" : "none";
     filterGroup.style.display = view === "graph" ? "" : "none";
     clusterGroup.style.display = view === "graph" ? "" : "none";

viz-frontend/src/main.ts

@@ -30,6 +30,7 @@ export const setupSearch = (state: AppState): HTMLInputElement => {
   input.id = "fallow-search";
   input.placeholder = "Search files… (/)";
   input.setAttribute("autocomplete", "off");
+  input.setAttribute("aria-label", "Search files");
 
   let debounceTimer: ReturnType<typeof setTimeout>;
   input.addEventListener("input", () => {

viz-frontend/src/search.ts

@@ -282,3 +282,28 @@ body {
   margin-top: 4px;
   opacity: 0.7;
 }
+
+/* ── Keyboard focus visibility ─────────────────────────────── */
+
+#fallow-app button:focus-visible,
+.view-tab:focus-visible,
+.filter-btn:focus-visible,
+#fallow-darkmode:focus-visible {
+  outline: 2px solid #3B82F6;
+  outline-offset: 2px;
+}
+
+#fallow-canvas:focus-visible {
+  outline: 2px solid #3B82F6;
+  outline-offset: -2px;
+}
+
+/* ── Respect reduced-motion preference ─────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+  * {
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}