From da7e8673be71f5230b6101bd85c5eaa218f644d0 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Mon, 19 Oct 2026 16:49:18 +0530
Subject: [PATCH 1/7] docs(stories): label the textarea and select controls

---
 stories/primitives/select.stories.tsx   | 122 +++++++++++++-----------
 stories/primitives/textarea.stories.tsx |  84 ++++++++++------
 2 files changed, 119 insertions(+), 87 deletions(-)

diff --git a/stories/primitives/select.stories.tsx b/stories/primitives/select.stories.tsx
index 155cbd59..b021deb6 100644
--- a/stories/primitives/select.stories.tsx
+++ b/stories/primitives/select.stories.tsx
@@ -1,3 +1,4 @@
+import type * as React from "react";
 import { useState } from "react";
 
 import { Select } from "../../src/ui/select.js";
@@ -10,58 +11,67 @@ const options = [
   { value: "haiku", label: "Haiku" },
 ];
 
+const optionElements = options.map((option) => (
+  <option key={option.value} value={option.value}>
+    {option.label}
+  </option>
+));
+
+function Field({ children }: { readonly children: React.ReactNode }) {
+  return (
+    <label className="grid gap-1.5 text-sm">
+      <span className="font-medium">Model</span>
+      {children}
+    </label>
+  );
+}
+
 export const Default = () => {
   const [value, setValue] = useState("sonnet");
   return (
-    <Select value={value} onChange={(event) => setValue(event.target.value)}>
-      {options.map((option) => (
-        <option key={option.value} value={option.value}>
-          {option.label}
-        </option>
-      ))}
-    </Select>
+    <Field>
+      <Select value={value} onChange={(event) => setValue(event.target.value)}>
+        {optionElements}
+      </Select>
+    </Field>
   );
 };
 
 export const Focus = () => (
-  <Select autoFocus defaultValue="sonnet">
-    {options.map((option) => (
-      <option key={option.value} value={option.value}>
-        {option.label}
-      </option>
-    ))}
-  </Select>
+  <Field>
+    <Select autoFocus defaultValue="sonnet">
+      {optionElements}
+    </Select>
+  </Field>
 );
 
 export const Disabled = () => (
-  <Select disabled defaultValue="sonnet">
-    {options.map((option) => (
-      <option key={option.value} value={option.value}>
-        {option.label}
-      </option>
-    ))}
-  </Select>
+  <Field>
+    <Select disabled defaultValue="sonnet">
+      {optionElements}
+    </Select>
+  </Field>
 );
 
 export const Invalid = () => (
-  <Select aria-invalid defaultValue="sonnet">
-    {options.map((option) => (
-      <option key={option.value} value={option.value}>
-        {option.label}
-      </option>
-    ))}
-  </Select>
+  <Field>
+    <Select aria-invalid defaultValue="sonnet">
+      {optionElements}
+    </Select>
+  </Field>
 );
 
 export const DisabledWithDescription = () => (
   <div className="flex flex-col gap-1.5">
-    <Select disabled aria-describedby="model-select-hint" defaultValue="sonnet">
-      {options.map((option) => (
-        <option key={option.value} value={option.value}>
-          {option.label}
-        </option>
-      ))}
-    </Select>
+    <Field>
+      <Select
+        disabled
+        aria-describedby="model-select-hint"
+        defaultValue="sonnet"
+      >
+        {optionElements}
+      </Select>
+    </Field>
     <p id="model-select-hint" className="text-xs text-muted-foreground">
       Model selection is locked for this workspace.
     </p>
@@ -70,17 +80,15 @@ export const DisabledWithDescription = () => (
 
 export const InvalidWithDescription = () => (
   <div className="flex flex-col gap-1.5">
-    <Select
-      aria-invalid
-      aria-describedby="model-select-error"
-      defaultValue="sonnet"
-    >
-      {options.map((option) => (
-        <option key={option.value} value={option.value}>
-          {option.label}
-        </option>
-      ))}
-    </Select>
+    <Field>
+      <Select
+        aria-invalid
+        aria-describedby="model-select-error"
+        defaultValue="sonnet"
+      >
+        {optionElements}
+      </Select>
+    </Field>
     <p id="model-select-error" className="text-xs text-destructive">
       Choose a model available on your plan.
     </p>
@@ -89,18 +97,16 @@ export const InvalidWithDescription = () => (
 
 export const DisabledInvalid = () => (
   <div className="flex flex-col gap-1.5">
-    <Select
-      disabled
-      aria-invalid
-      aria-describedby="model-select-disabled-error"
-      defaultValue="sonnet"
-    >
-      {options.map((option) => (
-        <option key={option.value} value={option.value}>
-          {option.label}
-        </option>
-      ))}
-    </Select>
+    <Field>
+      <Select
+        disabled
+        aria-invalid
+        aria-describedby="model-select-disabled-error"
+        defaultValue="sonnet"
+      >
+        {optionElements}
+      </Select>
+    </Field>
     <p id="model-select-disabled-error" className="text-xs text-destructive">
       Choose a model available on your plan.
     </p>
diff --git a/stories/primitives/textarea.stories.tsx b/stories/primitives/textarea.stories.tsx
index 1577f0ba..44828153 100644
--- a/stories/primitives/textarea.stories.tsx
+++ b/stories/primitives/textarea.stories.tsx
@@ -1,39 +1,59 @@
+import type * as React from "react";
 import { useState } from "react";
 
 import { Textarea } from "../../src/ui/textarea.js";
 
 export default { title: "Primitives / Textarea" };
 
+function Field({ children }: { readonly children: React.ReactNode }) {
+  return (
+    <label className="grid gap-1.5 text-sm">
+      <span className="font-medium">Task</span>
+      {children}
+    </label>
+  );
+}
+
 export const Default = () => {
   const [value, setValue] = useState("");
   return (
-    <Textarea
-      placeholder="Describe what you want the agent to do."
-      value={value}
-      onChange={(event) => setValue(event.target.value)}
-    />
+    <Field>
+      <Textarea
+        placeholder="Describe what you want the agent to do."
+        value={value}
+        onChange={(event) => setValue(event.target.value)}
+      />
+    </Field>
   );
 };
 
 export const Focus = () => (
-  <Textarea autoFocus placeholder="Describe what you want the agent to do." />
+  <Field>
+    <Textarea autoFocus placeholder="Describe what you want the agent to do." />
+  </Field>
 );
 
 export const Disabled = () => (
-  <Textarea disabled defaultValue="This field is locked." />
+  <Field>
+    <Textarea disabled defaultValue="This field is locked." />
+  </Field>
 );
 
 export const Invalid = () => (
-  <Textarea aria-invalid defaultValue="This value did not pass validation." />
+  <Field>
+    <Textarea aria-invalid defaultValue="This value did not pass validation." />
+  </Field>
 );
 
 export const DisabledWithDescription = () => (
   <div className="flex flex-col gap-1.5">
-    <Textarea
-      disabled
-      aria-describedby="task-hint"
-      defaultValue="This field is locked."
-    />
+    <Field>
+      <Textarea
+        disabled
+        aria-describedby="task-hint"
+        defaultValue="This field is locked."
+      />
+    </Field>
     <p id="task-hint" className="text-xs text-muted-foreground">
       Editing is disabled while the agent is running.
     </p>
@@ -42,11 +62,13 @@ export const DisabledWithDescription = () => (
 
 export const InvalidWithDescription = () => (
   <div className="flex flex-col gap-1.5">
-    <Textarea
-      aria-invalid
-      aria-describedby="task-error"
-      defaultValue="This value did not pass validation."
-    />
+    <Field>
+      <Textarea
+        aria-invalid
+        aria-describedby="task-error"
+        defaultValue="This value did not pass validation."
+      />
+    </Field>
     <p id="task-error" className="text-xs text-destructive">
       Describe the task in 500 characters or fewer.
     </p>
@@ -55,12 +77,14 @@ export const InvalidWithDescription = () => (
 
 export const DisabledInvalid = () => (
   <div className="flex flex-col gap-1.5">
-    <Textarea
-      disabled
-      aria-invalid
-      aria-describedby="task-disabled-error"
-      defaultValue="This value did not pass validation."
-    />
+    <Field>
+      <Textarea
+        disabled
+        aria-invalid
+        aria-describedby="task-disabled-error"
+        defaultValue="This value did not pass validation."
+      />
+    </Field>
     <p id="task-disabled-error" className="text-xs text-destructive">
       Describe the task in 500 characters or fewer.
     </p>
@@ -70,10 +94,12 @@ export const DisabledInvalid = () => (
 export const AutoResize = () => {
   const [value, setValue] = useState("Short at first.");
   return (
-    <Textarea
-      autoResize
-      value={value}
-      onChange={(event) => setValue(event.target.value)}
-    />
+    <Field>
+      <Textarea
+        autoResize
+        value={value}
+        onChange={(event) => setValue(event.target.value)}
+      />
+    </Field>
   );
 };

From 138cd8fd40540aecf0fa66ceebf35bd4ad87233e Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Mon, 19 Oct 2026 16:49:18 +0530
Subject: [PATCH 2/7] fix(status-dot): hide the dot when its label is empty

Badge, step-list and progress-checklist pass label="" because nearby text
already names the state, which rendered an unnamed role="img". An empty
label now drops the dot from the accessibility tree, as <img alt=""> does.
---
 src/ui/status-dot.test.tsx | 37 +++++++++++++++++++++++++++++++++++++
 src/ui/status-dot.tsx      | 14 ++++++++++----
 2 files changed, 47 insertions(+), 4 deletions(-)
 create mode 100644 src/ui/status-dot.test.tsx

diff --git a/src/ui/status-dot.test.tsx b/src/ui/status-dot.test.tsx
new file mode 100644
index 00000000..531c6342
--- /dev/null
+++ b/src/ui/status-dot.test.tsx
@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { act, createElement } from "react";
+import type { ComponentProps } from "react";
+import { createRoot } from "react-dom/client";
+
+import { StatusDot } from "./status-dot.js";
+
+function mount(props: ComponentProps<typeof StatusDot>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => {
+    root.render(createElement(StatusDot, props));
+  });
+  return {
+    dot: () => container.firstElementChild as HTMLElement,
+    unmount: () => root.unmount(),
+  };
+}
+
+describe("StatusDot", () => {
+  test("a label makes the dot a named image", () => {
+    const { dot, unmount } = mount({ label: "Running" });
+    expect(dot().getAttribute("role")).toBe("img");
+    expect(dot().getAttribute("aria-label")).toBe("Running");
+    expect(dot().hasAttribute("aria-hidden")).toBe(false);
+    unmount();
+  });
+
+  test("an empty label hides the dot instead of announcing an unnamed image", () => {
+    const { dot, unmount } = mount({ label: "" });
+    expect(dot().hasAttribute("role")).toBe(false);
+    expect(dot().hasAttribute("aria-label")).toBe(false);
+    expect(dot().getAttribute("aria-hidden")).toBe("true");
+    unmount();
+  });
+});
diff --git a/src/ui/status-dot.tsx b/src/ui/status-dot.tsx
index 85234379..23ad72c8 100644
--- a/src/ui/status-dot.tsx
+++ b/src/ui/status-dot.tsx
@@ -8,7 +8,11 @@ export type StatusDotTone =
   | "danger";
 
 export type StatusDotProps = {
-  /** Names the state for assistive tech. Required — a bare colour says nothing. */
+  /**
+   * Names the state for assistive tech. Required — a bare colour says nothing.
+   * Pass `""` when adjacent text already names the state (a status `Badge`, a
+   * step title): the dot is then decorative and hidden, as `<img alt="">` is.
+   */
   readonly label: string;
   /** Adds a ring that pulses outward: this state is live and still changing. */
   readonly live?: boolean;
@@ -45,7 +49,8 @@ const TONE_CLASS: Record<StatusDotTone, string> = {
 /**
  * A state marker carrying its own accessible name — a coloured dot with no
  * label is invisible to a screen reader, so the label is required rather than
- * optional.
+ * optional. An empty label opts out explicitly: the dot leaves the
+ * accessibility tree instead of announcing an unnamed image.
  *
  * The `live` ring is a separate `aria-hidden` element: motion says "still
  * changing" to people who can see it, and the label already says so to those
@@ -65,8 +70,9 @@ export function StatusDot({
 }: StatusDotProps) {
   return (
     <span
-      role="img"
-      aria-label={label}
+      {...(label
+        ? { role: "img", "aria-label": label }
+        : { "aria-hidden": true })}
       className={cn(
         "relative inline-flex shrink-0",
         SIZE_CLASS[size],

From 7b58f86d03130fd66252af0e2215ad666389bd56 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Mon, 19 Oct 2026 16:49:18 +0530
Subject: [PATCH 3/7] feat(sidebar-panel): add SidebarPanelSection to hold item
 rows

SidebarItemRow renders an <li>, but the panel family had no list to put it
in, so rows sat directly in a <div>. SidebarPanelSection is that <ul>, with
an optional label that adds a heading and names the list.
---
 src/ui/sidebar-item-row.tsx                   |  3 +
 src/ui/sidebar-panel.test.tsx                 | 27 ++++++
 src/ui/sidebar-panel.tsx                      | 37 +++++++-
 .../sidebar-rail-and-panel.stories.tsx        | 93 ++++++++++---------
 4 files changed, 116 insertions(+), 44 deletions(-)
 create mode 100644 src/ui/sidebar-panel.test.tsx

diff --git a/src/ui/sidebar-item-row.tsx b/src/ui/sidebar-item-row.tsx
index 80f87af0..a69eb972 100644
--- a/src/ui/sidebar-item-row.tsx
+++ b/src/ui/sidebar-item-row.tsx
@@ -42,6 +42,9 @@ export type SidebarItemRowProps = {
  * that is not colour-only (a `StatusDot`, a count), not rely on this
  * component to supply one.
  *
+ * The row is an `<li>`: render it inside a `SidebarPanelSection` or another
+ * `<ul>`.
+ *
  * Not `ui/sidebar`'s `SidebarItem` — that's the single-column family's row.
  */
 export function SidebarItemRow({
diff --git a/src/ui/sidebar-panel.test.tsx b/src/ui/sidebar-panel.test.tsx
new file mode 100644
index 00000000..57eab1cd
--- /dev/null
+++ b/src/ui/sidebar-panel.test.tsx
@@ -0,0 +1,27 @@
+import { expect, test } from "bun:test";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+
+import { SidebarItemRow } from "./sidebar-item-row.js";
+import { SidebarPanelSection } from "./sidebar-panel.js";
+
+test("SidebarPanelSection gives its rows a labelled list parent", () => {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(
+      <SidebarPanelSection label="Channels">
+        <SidebarItemRow name="general" />
+        <SidebarItemRow name="eng" />
+      </SidebarPanelSection>,
+    );
+  });
+  const list = host.querySelector("ul");
+  expect(list?.getAttribute("aria-label")).toBe("Channels");
+  const rows = host.querySelectorAll("li");
+  expect(rows.length).toBe(2);
+  for (const row of rows) expect(row.parentElement).toBe(list);
+  act(() => root.unmount());
+  host.remove();
+});
diff --git a/src/ui/sidebar-panel.tsx b/src/ui/sidebar-panel.tsx
index e8a57d91..dadc20fc 100644
--- a/src/ui/sidebar-panel.tsx
+++ b/src/ui/sidebar-panel.tsx
@@ -4,8 +4,8 @@ import { cn } from "../lib/utils.js";
 
 /**
  * The second column's shell. Composable parts, like `ui/sidebar` — a consumer
- * assembles `SidebarPanelHeader`, `SidebarPanelPins`, `SidebarPanelBody` and
- * `SidebarPanelFooter` in whatever combination the active page calls for, and
+ * assembles `SidebarPanelHeader`, `SidebarPanelPins`, `SidebarPanelBody`,
+ * `SidebarPanelSection` and `SidebarPanelFooter` in whatever combination the active page calls for, and
  * the root only supplies the width, the border and the flex column.
  */
 export function SidebarPanel({
@@ -84,6 +84,39 @@ export function SidebarPanelBody({
   );
 }
 
+export type SidebarPanelSectionProps = React.ComponentProps<"ul"> & {
+  /** A visible heading that also names the list for assistive tech. */
+  readonly label?: string;
+};
+
+/**
+ * The list that holds `SidebarItemRow`s, in `SidebarPanelPins` or
+ * `SidebarPanelBody`. Each row is an `<li>`, so it needs this `<ul>` around it
+ * for a screen reader to announce the list and its length.
+ */
+export function SidebarPanelSection({
+  label,
+  className,
+  children,
+  ...props
+}: SidebarPanelSectionProps) {
+  return (
+    <div data-slot="sidebar-panel-section" className={className}>
+      {label === undefined ? null : (
+        <p
+          aria-hidden
+          className="px-2 py-1 text-[11px] font-semibold tracking-[0.12em] text-muted-foreground uppercase"
+        >
+          {label}
+        </p>
+      )}
+      <ul aria-label={label} className="flex flex-col" {...props}>
+        {children}
+      </ul>
+    </div>
+  );
+}
+
 /** Not `ui/sidebar`'s `SidebarFooter` — that's the single-column family's footer slot. */
 export function SidebarPanelFooter({
   className,
diff --git a/stories/primitives/sidebar-rail-and-panel.stories.tsx b/stories/primitives/sidebar-rail-and-panel.stories.tsx
index ad8750f6..e8c71c85 100644
--- a/stories/primitives/sidebar-rail-and-panel.stories.tsx
+++ b/stories/primitives/sidebar-rail-and-panel.stories.tsx
@@ -10,6 +10,7 @@ import {
   SidebarPanelFooter,
   SidebarPanelHeader,
   SidebarPanelPins,
+  SidebarPanelSection,
 } from "../../src/ui/sidebar-panel.js";
 import { StatusDot } from "../../src/ui/status-dot.js";
 
@@ -28,36 +29,42 @@ export const ChannelsPanel = () => {
           }
         />
         <SidebarPanelPins>
-          <SidebarItemRow
-            leading={<Pin className="text-muted-foreground" />}
-            name="#launch-week"
-            selected={selectedId === "launch-week"}
-            onSelect={() => setSelectedId("launch-week")}
-          />
+          <SidebarPanelSection aria-label="Pinned">
+            <SidebarItemRow
+              leading={<Pin className="text-muted-foreground" />}
+              name="#launch-week"
+              selected={selectedId === "launch-week"}
+              onSelect={() => setSelectedId("launch-week")}
+            />
+          </SidebarPanelSection>
         </SidebarPanelPins>
         <SidebarPanelBody>
-          {[
-            { id: "general", name: "general", unread: true },
-            { id: "eng", name: "eng", unread: false },
-            { id: "design", name: "design", unread: false },
-          ].map((channel) => (
+          <SidebarPanelSection aria-label="Channels">
+            {[
+              { id: "general", name: "general", unread: true },
+              { id: "eng", name: "eng", unread: false },
+              { id: "design", name: "design", unread: false },
+            ].map((channel) => (
+              <SidebarItemRow
+                key={channel.id}
+                leading={<Hash className="text-muted-foreground" />}
+                name={channel.name}
+                unread={channel.unread}
+                meta={
+                  channel.unread ? <Badge tone="accent">3</Badge> : undefined
+                }
+                selected={selectedId === channel.id}
+                onSelect={() => setSelectedId(channel.id)}
+              />
+            ))}
             <SidebarItemRow
-              key={channel.id}
-              leading={<Hash className="text-muted-foreground" />}
-              name={channel.name}
-              unread={channel.unread}
-              meta={channel.unread ? <Badge tone="accent">3</Badge> : undefined}
-              selected={selectedId === channel.id}
-              onSelect={() => setSelectedId(channel.id)}
+              leading={<MessagesSquare className="text-muted-foreground" />}
+              name="Priya Shah"
+              meta={<StatusDot label="Online" tone="emphasis" size="xs" />}
+              selected={selectedId === "priya"}
+              onSelect={() => setSelectedId("priya")}
             />
-          ))}
-          <SidebarItemRow
-            leading={<MessagesSquare className="text-muted-foreground" />}
-            name="Priya Shah"
-            meta={<StatusDot label="Online" tone="emphasis" size="xs" />}
-            selected={selectedId === "priya"}
-            onSelect={() => setSelectedId("priya")}
-          />
+          </SidebarPanelSection>
         </SidebarPanelBody>
         <SidebarPanelFooter>
           <button
@@ -125,22 +132,24 @@ export const LiveRows = () => {
       <SidebarPanel>
         <SidebarPanelHeader title="Routines activity" />
         <SidebarPanelBody>
-          {runs.map((run) => (
-            <SidebarItemRow
-              key={run.id}
-              leading={<StatusDot label="Running" tone="emphasis" live />}
-              name={run.name}
-              meta={
-                <time
-                  dateTime={run.startedAt}
-                  className="font-mono text-xs text-muted-foreground tabular-nums"
-                >
-                  {formatRelativeTime(run.startedAt, now)}
-                </time>
-              }
-              leaving={run.leaving}
-            />
-          ))}
+          <SidebarPanelSection aria-label="Running routines">
+            {runs.map((run) => (
+              <SidebarItemRow
+                key={run.id}
+                leading={<StatusDot label="Running" tone="emphasis" live />}
+                name={run.name}
+                meta={
+                  <time
+                    dateTime={run.startedAt}
+                    className="font-mono text-xs text-muted-foreground tabular-nums"
+                  >
+                    {formatRelativeTime(run.startedAt, now)}
+                  </time>
+                }
+                leaving={run.leaving}
+              />
+            ))}
+          </SidebarPanelSection>
         </SidebarPanelBody>
       </SidebarPanel>
     </div>

From 6a5452b8e2ff917d68e7e570d004a53edfb8f3ba Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Mon, 19 Oct 2026 16:49:18 +0530
Subject: [PATCH 4/7] fix(tool-picker): keep loading and empty copy out of the
 listbox

A listbox may only own options and groups. Status copy now renders beside
it as role="status", and the listbox hides and the combobox reports
aria-expanded=false while there are no options.
---
 src/ui/tool-picker.test.tsx |  20 +++++++
 src/ui/tool-picker.tsx      | 109 +++++++++++++++++++-----------------
 2 files changed, 79 insertions(+), 50 deletions(-)

diff --git a/src/ui/tool-picker.test.tsx b/src/ui/tool-picker.test.tsx
index 015a9e2e..0000e5eb 100644
--- a/src/ui/tool-picker.test.tsx
+++ b/src/ui/tool-picker.test.tsx
@@ -171,6 +171,26 @@ describe("ToolPicker", () => {
     unmount();
   });
 
+  test("status copy sits outside the listbox, which hides while it has no options", () => {
+    for (const props of [{ loading: true }, { items: [] }]) {
+      const { container, unmount } = mount(props);
+      const listbox = container.querySelector(
+        '[role="listbox"]',
+      ) as HTMLElement;
+      const status = container.querySelector('[role="status"]');
+      expect(listbox.hidden).toBe(true);
+      expect(listbox.childElementCount).toBe(0);
+      expect(status).not.toBeNull();
+      expect(listbox.contains(status)).toBe(false);
+      expect(
+        container
+          .querySelector('[role="combobox"]')
+          ?.getAttribute("aria-expanded"),
+      ).toBe("false");
+      unmount();
+    }
+  });
+
   test("a search with no hits shows no-matches copy", () => {
     const { container, unmount } = mount();
     const input = container.querySelector("input") as HTMLInputElement;
diff --git a/src/ui/tool-picker.tsx b/src/ui/tool-picker.tsx
index f1792e9e..b08d5f9a 100644
--- a/src/ui/tool-picker.tsx
+++ b/src/ui/tool-picker.tsx
@@ -157,6 +157,7 @@ export function ToolPicker({
 
   const emptyCatalog = items.length === 0;
   const noMatches = !emptyCatalog && filtered.length === 0;
+  const hasOptions = !loading && filtered.length > 0;
 
   return (
     <div
@@ -170,7 +171,7 @@ export function ToolPicker({
         placeholder={searchPlaceholder}
         aria-label={searchLabel}
         role="combobox"
-        aria-expanded
+        aria-expanded={hasOptions}
         aria-autocomplete="list"
         aria-controls={`${baseId}-list`}
         aria-activedescendant={
@@ -183,63 +184,71 @@ export function ToolPicker({
         spellCheck={false}
       />
 
+      {/* Status copy sits beside the listbox, not in it: a listbox may only own
+          options and groups, so it is hidden while it has none. */}
+      {loading ? (
+        <p
+          role="status"
+          className="px-2 py-8 text-center text-sm text-muted-foreground"
+        >
+          Loading…
+        </p>
+      ) : emptyCatalog ? (
+        <div role="status">
+          {empty ?? (
+            <EmptyState
+              title="No tools"
+              description="Nothing in the catalog yet."
+            />
+          )}
+        </div>
+      ) : noMatches ? (
+        <p
+          role="status"
+          className="px-2 py-8 text-center text-sm text-muted-foreground"
+        >
+          No tools match — try a different search.
+        </p>
+      ) : null}
+
       <div
         ref={listRef}
         id={`${baseId}-list`}
         role="listbox"
         aria-label="Tools"
         aria-multiselectable={multiple}
-        className="flex min-h-0 flex-1 flex-col gap-3 overflow-auto"
+        hidden={!hasOptions}
+        className={cn(
+          "flex min-h-0 flex-1 flex-col gap-3 overflow-auto",
+          !hasOptions && "hidden",
+        )}
       >
-        {loading ? (
-          <p
-            role="presentation"
-            className="px-2 py-8 text-center text-sm text-muted-foreground"
-          >
-            Loading…
-          </p>
-        ) : emptyCatalog ? (
-          <div role="presentation">
-            {empty ?? (
-              <EmptyState
-                title="No tools"
-                description="Nothing in the catalog yet."
-              />
-            )}
-          </div>
-        ) : noMatches ? (
-          <p
-            role="presentation"
-            className="px-2 py-8 text-center text-sm text-muted-foreground"
-          >
-            No tools match — try a different search.
-          </p>
-        ) : (
-          groups.map((group) => (
-            <div
-              key={group.id}
-              role="presentation"
-              className="flex flex-col gap-1"
-            >
-              <p className="px-3.5 py-1.5 text-[11px] font-semibold uppercase tracking-[0.1em] text-muted-foreground">
-                {groupHeading(group.id)}
-              </p>
-              <div className="flex flex-col gap-1">
-                {group.items.map((item) => (
-                  <ToolPickerOption
-                    key={item.id}
-                    id={optionId(item.id)}
-                    item={item}
-                    selected={selectedIds.has(item.id)}
-                    active={navigation.activeId === item.id}
-                    onSelect={() => toggle(item)}
-                    onPointerMove={() => navigation.setActiveId(item.id)}
-                  />
-                ))}
+        {hasOptions
+          ? groups.map((group) => (
+              <div
+                key={group.id}
+                role="presentation"
+                className="flex flex-col gap-1"
+              >
+                <p className="px-3.5 py-1.5 text-[11px] font-semibold uppercase tracking-[0.1em] text-muted-foreground">
+                  {groupHeading(group.id)}
+                </p>
+                <div className="flex flex-col gap-1">
+                  {group.items.map((item) => (
+                    <ToolPickerOption
+                      key={item.id}
+                      id={optionId(item.id)}
+                      item={item}
+                      selected={selectedIds.has(item.id)}
+                      active={navigation.activeId === item.id}
+                      onSelect={() => toggle(item)}
+                      onPointerMove={() => navigation.setActiveId(item.id)}
+                    />
+                  ))}
+                </div>
               </div>
-            </div>
-          ))
-        )}
+            ))
+          : null}
       </div>
     </div>
   );

From a83e2436e646dab515f1c122dafca5b7ffa0f72d Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Mon, 19 Oct 2026 16:49:18 +0530
Subject: [PATCH 5/7] fix: let the keyboard scroll page-panel, tool-block and
 stepper regions

Each scroll container takes tabIndex=0 so it can be scrolled without a
pointer. The page panel and the stepper rail draw the focus ring inset,
since an overflow-hidden parent and the edge mask hide an outset ring.
---
 src/ui/horizontal-stepper.tsx |  5 ++++-
 src/ui/page-panel.tsx         |  6 +++++-
 src/ui/tool-block.test.tsx    | 15 +++++++++++++++
 src/ui/tool-block.tsx         |  7 +++++--
 4 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/src/ui/horizontal-stepper.tsx b/src/ui/horizontal-stepper.tsx
index 07f7964a..b4c2fb38 100644
--- a/src/ui/horizontal-stepper.tsx
+++ b/src/ui/horizontal-stepper.tsx
@@ -48,9 +48,12 @@ export function HorizontalStepper({
 
   return (
     <div className={cn("border-b border-border bg-card px-6 py-5", className)}>
+      {/* Focusable so a rail too long for the screen scrolls by keyboard; the
+          ring is inset because the edge mask hides anything drawn outside. */}
       <ol
         aria-label="Workflow progress"
-        className="flex items-center gap-2 overflow-x-auto [mask-image:linear-gradient(to_right,transparent,black_12px,black_calc(100%-12px),transparent)] md:gap-3"
+        tabIndex={0}
+        className="flex items-center gap-2 overflow-x-auto focus-visible:-outline-offset-2 [mask-image:linear-gradient(to_right,transparent,black_12px,black_calc(100%-12px),transparent)] md:gap-3"
       >
         {steps.map((step, index) => (
           <li
diff --git a/src/ui/page-panel.tsx b/src/ui/page-panel.tsx
index 0d69db8e..8f7897b4 100644
--- a/src/ui/page-panel.tsx
+++ b/src/ui/page-panel.tsx
@@ -57,10 +57,14 @@ export function PagePanel({
   const fill = surface === "card" ? "bg-card" : "bg-background";
   return (
     <div className={cn("flex h-full overflow-hidden", fill)}>
+      {/* A scrolling panel takes focus so the keyboard can scroll it even when
+          it holds no focusable content; the ring is inset because the outer
+          fill clips anything drawn outside the panel. */}
       <section
         data-slot="page-panel"
+        tabIndex={scroll ? 0 : undefined}
         className={cn(
-          "flex flex-col",
+          "flex flex-col focus-visible:-outline-offset-2",
           fill,
           sizing,
           overflow,
diff --git a/src/ui/tool-block.test.tsx b/src/ui/tool-block.test.tsx
index a09fef38..66a5ff8b 100644
--- a/src/ui/tool-block.test.tsx
+++ b/src/ui/tool-block.test.tsx
@@ -115,6 +115,21 @@ describe("ToolBlock", () => {
     mounted.unmount();
   });
 
+  test("detail boxes take focus so the keyboard can scroll long output", () => {
+    const mounted = render(
+      <ToolBlock
+        name="search"
+        input={{ query: "invoices" }}
+        state={{ status: "output-available", output: "3 results" }}
+        defaultOpen
+      />,
+    );
+    const boxes = [...mounted.container.querySelectorAll("pre")];
+    expect(boxes.length).toBe(2);
+    for (const box of boxes) expect(box.tabIndex).toBe(0);
+    mounted.unmount();
+  });
+
   test("carries its status as a data attribute for state-based styling", () => {
     const mounted = render(
       <ToolBlock name="search" state={{ status: "running" }} />,
diff --git a/src/ui/tool-block.tsx b/src/ui/tool-block.tsx
index 289c5c08..3aa58015 100644
--- a/src/ui/tool-block.tsx
+++ b/src/ui/tool-block.tsx
@@ -223,8 +223,11 @@ function Detail({ title, children }: { title: string; children: string }) {
         {title}
       </p>
       {/* Scrolls in its own box: a long tool result must never make the page
-          scroll sideways. */}
-      <pre className="max-h-48 overflow-auto rounded-md bg-muted p-2 font-mono text-[11px] whitespace-pre-wrap">
+          scroll sideways. Focusable so the keyboard can scroll it too. */}
+      <pre
+        tabIndex={0}
+        className="max-h-48 overflow-auto rounded-md bg-muted p-2 font-mono text-[11px] whitespace-pre-wrap"
+      >
         {children}
       </pre>
     </div>

From 556e78227af233b30e132609e3b2c834877c1c47 Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Mon, 19 Oct 2026 16:49:18 +0530
Subject: [PATCH 6/7] fix(theme): darken light ok and warn to clear text
 contrast

warn colours the medium RiskBadge label and measured 3.30:1 on the card.
The contrast gate now checks ok and warn as text on the page and the card,
and the light values move to #2f7c40 and #966319 to pass it.
---
 scripts/contrast-test.mjs | 15 +++++++++++++++
 src/theme.css             |  8 ++++----
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/scripts/contrast-test.mjs b/scripts/contrast-test.mjs
index 46a63780..c2f8be22 100644
--- a/scripts/contrast-test.mjs
+++ b/scripts/contrast-test.mjs
@@ -179,6 +179,21 @@ function checksFor(tokens) {
     }
   }
 
+  // 3b. The status-text tokens are text by contract (a medium/high RiskBadge
+  //     label is `warn`), so they clear text contrast on the same surfaces.
+  for (const text of ["ok", "warn"]) {
+    for (const surface of ["background", "card"]) {
+      if (has(text) && has(surface)) {
+        checks.push([
+          `${text} on ${surface}`,
+          tokens[text],
+          tokens[surface],
+          AA_TEXT,
+        ]);
+      }
+    }
+  }
+
   // 4. Control boundaries and the focus ring must clear the UI-component threshold.
   for (const line of ["input", "ring"]) {
     for (const surface of ["background", "card"]) {
diff --git a/src/theme.css b/src/theme.css
index 61cb7a4d..37b7e322 100644
--- a/src/theme.css
+++ b/src/theme.css
@@ -85,10 +85,10 @@
      state needs to read as "good"/"caution" beyond what --success/--destructive
      already carry (those are fills). --warn also colours a medium/high
      RiskBadge; low risk stays --muted-foreground so only the levels worth
-     flagging draw the eye. Matches Workbench's app.css exactly, so a block
-     lifted from a consumer app keeps its colours. */
-  --ok: #37904a;
-  --warn: #b7791f;
+     flagging draw the eye. Both clear 4.5:1 on the page and the card (the
+     contrast gate checks them as text). */
+  --ok: #2f7c40;
+  --warn: #966319;
 
   /* The chrome's elevation. The design is flat — floating chrome separates
      itself with --border-strong, not depth — so the token ships as `none`

From 7f656b6a30ef24c6aa6065bfa3f7ec47fea51b0f Mon Sep 17 00:00:00 2001
From: 0xPratik <sariapratik@gmail.com>
Date: Mon, 19 Oct 2026 16:49:18 +0530
Subject: [PATCH 7/7] test(e2e): empty the stories a11y known-violations list

---
 e2e/stories-a11y.known.json | 60 +------------------------------------
 e2e/stories-a11y.spec.ts    |  2 +-
 2 files changed, 2 insertions(+), 60 deletions(-)

diff --git a/e2e/stories-a11y.known.json b/e2e/stories-a11y.known.json
index b7e368d8..fe51488c 100644
--- a/e2e/stories-a11y.known.json
+++ b/e2e/stories-a11y.known.json
@@ -1,59 +1 @@
-[
-  "chat-block-card--risk-levels (light): color-contrast",
-  "chat-tool-block--long-output-scrolls-in-place (dark): scrollable-region-focusable",
-  "chat-tool-block--long-output-scrolls-in-place (light): scrollable-region-focusable",
-  "primitives-badge--workflow-status (dark): role-img-alt",
-  "primitives-badge--workflow-status (light): role-img-alt",
-  "primitives-page-panel--scrolling (dark): scrollable-region-focusable",
-  "primitives-page-panel--scrolling (light): scrollable-region-focusable",
-  "primitives-select--default (dark): select-name",
-  "primitives-select--default (light): select-name",
-  "primitives-select--disabled (dark): select-name",
-  "primitives-select--disabled (light): select-name",
-  "primitives-select--disabled-invalid (dark): label-title-only",
-  "primitives-select--disabled-invalid (dark): select-name",
-  "primitives-select--disabled-invalid (light): label-title-only",
-  "primitives-select--disabled-invalid (light): select-name",
-  "primitives-select--disabled-with-description (dark): label-title-only",
-  "primitives-select--disabled-with-description (dark): select-name",
-  "primitives-select--disabled-with-description (light): label-title-only",
-  "primitives-select--disabled-with-description (light): select-name",
-  "primitives-select--focus (dark): select-name",
-  "primitives-select--focus (light): select-name",
-  "primitives-select--invalid (dark): select-name",
-  "primitives-select--invalid (light): select-name",
-  "primitives-select--invalid-with-description (dark): label-title-only",
-  "primitives-select--invalid-with-description (dark): select-name",
-  "primitives-select--invalid-with-description (light): label-title-only",
-  "primitives-select--invalid-with-description (light): select-name",
-  "primitives-sidebar-panel--channels-panel (dark): listitem",
-  "primitives-sidebar-panel--channels-panel (light): listitem",
-  "primitives-sidebar-panel--live-rows (dark): listitem",
-  "primitives-sidebar-panel--live-rows (light): listitem",
-  "primitives-textarea--auto-resize (dark): label",
-  "primitives-textarea--auto-resize (light): label",
-  "primitives-textarea--disabled (dark): label",
-  "primitives-textarea--disabled (light): label",
-  "primitives-textarea--disabled-invalid (dark): label",
-  "primitives-textarea--disabled-invalid (dark): label-title-only",
-  "primitives-textarea--disabled-invalid (light): label",
-  "primitives-textarea--disabled-invalid (light): label-title-only",
-  "primitives-textarea--disabled-with-description (dark): label",
-  "primitives-textarea--disabled-with-description (dark): label-title-only",
-  "primitives-textarea--disabled-with-description (light): label",
-  "primitives-textarea--disabled-with-description (light): label-title-only",
-  "primitives-textarea--invalid (dark): label",
-  "primitives-textarea--invalid (light): label",
-  "primitives-textarea--invalid-with-description (dark): label",
-  "primitives-textarea--invalid-with-description (dark): label-title-only",
-  "primitives-textarea--invalid-with-description (light): label",
-  "primitives-textarea--invalid-with-description (light): label-title-only",
-  "primitives-tool-picker--empty (dark): aria-required-children",
-  "primitives-tool-picker--empty (light): aria-required-children",
-  "primitives-tool-picker--loading (dark): aria-required-children",
-  "primitives-tool-picker--loading (light): aria-required-children",
-  "workflow-horizontal-stepper--many-steps (dark): scrollable-region-focusable",
-  "workflow-horizontal-stepper--many-steps (light): scrollable-region-focusable",
-  "workflow-inspector-shell--with-content (dark): role-img-alt",
-  "workflow-inspector-shell--with-content (light): role-img-alt"
-]
+[]
diff --git a/e2e/stories-a11y.spec.ts b/e2e/stories-a11y.spec.ts
index 90a82644..9439c5b1 100644
--- a/e2e/stories-a11y.spec.ts
+++ b/e2e/stories-a11y.spec.ts
@@ -7,7 +7,7 @@ const STORIES = "http://localhost:61000";
 
 // Existing violations recorded as a baseline to fix later; only a violation
 // not listed here fails.
-const KNOWN = new Set(known);
+const KNOWN = new Set<string>(known);
 
 test("every story is free of serious and critical axe violations", async ({
   page,