From d5ff3160242986d2fac80ed9a915390b5c69b6e1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 12 Aug 2026 11:24:00 +0000
Subject: [PATCH 1/5] feat(ui): give SegmentedControl an option hint slot
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Prerequisite for the filter contract rollout (docs/filter-contract.md,
PR #1847). The four one-of-N mode rails that are about to converge onto
this primitive — differentials, medication, applications, specifiers —
all carry a per-option count, and the primitive had nowhere to put one.
Baking it into `label` would fold the number into the truncating span
and lose the tabular alignment.

Landing it separately because it depends on none of the contract work,
and it makes each adoption a pure call-site change.

Two things worth knowing:

- The hint needs an explicit aria-label. Adjacent label and hint spans
  concatenate to "All62" in the computed accessible name, and a text
  node separator does not survive — the name computation normalises
  inter-element whitespace away. The button is therefore named
  "All (62)", the shape the differentials rail already used. Both
  behaviours are pinned by tests, including that a hintless option's
  name does not drift.
- No .design-sync regeneration is needed, contrary to expectation:
  dtsPropsFor.SegmentedControl references SegmentedControlOption<string>
  by name rather than expanding it, so adding a field leaves the pinned
  props string unchanged. Verified — all 56 design-sync tests pass.

Note for the adoption PRs: ResultFilterSheet renders option.hint the
same adjacent-span way, so its options announce "Crisis12" today. Same
fix, tracked with the rollout rather than smuggled in here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011btGFwWKYFWDs5McQkqz9J
---
 src/components/ui/segmented-control.tsx | 27 ++++++++++++++++++
 tests/ui-v2-components.dom.test.tsx     | 38 +++++++++++++++++++++++++
 2 files changed, 65 insertions(+)

diff --git a/src/components/ui/segmented-control.tsx b/src/components/ui/segmented-control.tsx
index 41d1097ebc..b3b2747b96 100644
--- a/src/components/ui/segmented-control.tsx
+++ b/src/components/ui/segmented-control.tsx
@@ -10,6 +10,18 @@ export type SegmentedControlOption<T extends string> = {
   label: string;
   icon?: LucideIcon;
   disabled?: boolean;
+  /**
+   * Trailing detail, almost always a count — "Presentations 41".
+   *
+   * Exists because the one-of-N rails this control replaces across the modes all
+   * carry a count, and baking it into `label` would fold the number into the
+   * truncating span and lose the tabular alignment. Never the only thing
+   * distinguishing two options: it joins the accessible name, so an option whose
+   * label is not unique without its hint reads as a near-duplicate to a screen
+   * reader. Mirrors `ResultFilterOption.hint`, so a mode can build one option
+   * array and hand it to both the desktop rail and the phone sheet.
+   */
+  hint?: string;
 };
 
 type AccessibleName = { label: string; ariaLabelledBy?: never } | { label?: never; ariaLabelledBy: string };
@@ -100,6 +112,11 @@ export function SegmentedControl<T extends string>({
             type="button"
             role="radio"
             aria-checked={checked}
+            // Without this the label and hint spans concatenate to "All62" in
+            // the accessible name — inter-element whitespace is normalised away
+            // by the name computation, so a text-node separator cannot fix it.
+            // Matches the `${label} (${count})` shape the mode rails used.
+            aria-label={option.hint ? `${option.label} (${option.hint})` : undefined}
             tabIndex={option.value === tabStopValue ? 0 : -1}
             disabled={option.disabled}
             data-segment-value={option.value}
@@ -116,6 +133,16 @@ export function SegmentedControl<T extends string>({
           >
             {Icon ? <Icon aria-hidden="true" className="size-icon-sm shrink-0" /> : null}
             <span className="min-w-0 truncate">{option.label}</span>
+            {option.hint ? (
+              // `nums` for tabular figures: without it the rail reflows as a
+              // count crosses a digit boundary, which on a live result set
+              // happens while the reader is aiming at it.
+              <span
+                className={cn("nums shrink-0 tabular-nums", checked ? "opacity-80" : "text-[color:var(--text-soft)]")}
+              >
+                {option.hint}
+              </span>
+            ) : null}
           </button>
         );
       })}
diff --git a/tests/ui-v2-components.dom.test.tsx b/tests/ui-v2-components.dom.test.tsx
index aceebcd14f..9e05825858 100644
--- a/tests/ui-v2-components.dom.test.tsx
+++ b/tests/ui-v2-components.dom.test.tsx
@@ -345,6 +345,44 @@ describe("SegmentedControl", () => {
     expect(screen.getByRole("radio", { name: "Comprehensive" })).toHaveFocus();
   });
 
+  // The one-of-N rails this control replaces across the modes all carry a count.
+  // Baking it into `label` would fold the number into the truncating span, so it
+  // gets its own slot — and it must reach the accessible name, or a screen
+  // reader user loses information a sighted user has.
+  it("renders an option hint and folds it into the accessible name", () => {
+    render(
+      <SegmentedControl
+        label="Result type"
+        value="all"
+        onChange={() => undefined}
+        options={[
+          { value: "all", label: "All", hint: "62" },
+          { value: "presentation", label: "Presentations", hint: "41" },
+        ]}
+        layout="fit"
+      />,
+    );
+
+    expect(screen.getByRole("radio", { name: "All (62)" })).toHaveAttribute("aria-checked", "true");
+    expect(screen.getByRole("radio", { name: "Presentations (41)" })).toBeInTheDocument();
+  });
+
+  // A hintless option must not gain stray whitespace or an empty span — the
+  // existing call sites pass no hint and their names must not drift.
+  it("leaves an option without a hint unchanged", () => {
+    render(
+      <SegmentedControl
+        label="Result type"
+        value="all"
+        onChange={() => undefined}
+        options={[{ value: "all", label: "All" }]}
+        layout="fit"
+      />,
+    );
+
+    expect(screen.getByRole("radio", { name: "All" })).toBeInTheDocument();
+  });
+
   it("keeps a controlled disabled value checked instead of remapping to the first enabled option", () => {
     render(
       <SegmentedControl

From 8f3f9cbb3c48ec454dab82ccaf36139ea73d82c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 12 Aug 2026 11:26:06 +0000
Subject: [PATCH 2/5] docs(review): record SegmentedControl hint handoff

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011btGFwWKYFWDs5McQkqz9J
---
 docs/branch-review-ledger.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/branch-review-ledger.md b/docs/branch-review-ledger.md
index 7ee6ef98c9..68b6940352 100644
--- a/docs/branch-review-ledger.md
+++ b/docs/branch-review-ledger.md
@@ -901,3 +901,4 @@ Records before 2026-07-28 were written by hand and had drifted: 146 lines carrie
 | 2026-08-12 | 1815 | 27ce96e1755055ceee2eeae02d6efdf11259fcde | babysit | fixed | Unit coverage: targeted vitest passed: tests/shared-home-empty-state.dom.test.tsx (17 passed). PR required still blocked on pre-existing check failure at old remote head before sync. |
 | 2026-08-12 | claude/rag-canary-test-review-seprbt | bcf357a96fde74d39fc4726ffabb5079a744ef28 | eval-canary review: workflow, compare tooling, snapshot builder, alias tiering, rag-behaviour docs | PR #1843 opened; no retrieval behaviour change; snapshot refresh handed off as /issues #304 | verify:pr-local (green except env-only #296), eval:rag:offline 574/574, focused suites 40/40 |
 | 2026-08-12 | codex/pr-workflow-safety-230-296 | bc0a491fdf4146775629f9b2b03e2a2cc61bd7cb | pr-1830 unblock | unblocked: merged origin/main (outstanding-issues conflict), PR body RAG impact + governance, resolved Copilot thread; merge-tree clean; required CI in progress | check:outstanding-issues pass; evaluatePullRequestPolicy ok; merge-tree clean; PR policy/mergeability/Change scope in progress |
+| 2026-08-12 | claude/segmented-control-count | d5ff3160242986d2fac80ed9a915390b5c69b6e1 | SegmentedControl option hint slot (filter rollout prerequisite) | PR #1848 opened; additive, no call site passes hint yet; fixed a concatenated accessible name (All62 -> All (62)) | lint/typecheck/test green, 80 in ui-v2-components, 56 design-sync with no regen needed, clean build, bundle-budget within tolerance |

From c65b9d91b760862c2ff9d5001974670219c5da02 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 12 Aug 2026 11:27:10 +0000
Subject: [PATCH 3/5] chore(agents): commit the next dev generated agent-rules
 block
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Regenerated by the production build run for this PR's bundle-budget
check. Written by next dev via
node_modules/next/dist/server/lib/generate-agent-files.js; left
uncommitted it re-appears on every build and leaves a dirty tree.

Its own commit rather than folded into the SegmentedControl change, so
it can be dropped independently. Note this block is not yet on main —
PR #1846 also carries it, so whichever lands first makes the other a
no-op.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011btGFwWKYFWDs5McQkqz9J
---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 88ec727f80..483df4b4c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,9 @@
 
 # This is NOT the Next.js you know
 
-This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
 
 <!-- END:nextjs-agent-rules -->
 

From c528a949831b9c258e9f498513587e6949dbc3f0 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Wed, 12 Aug 2026 20:58:52 +0800
Subject: [PATCH 4/5] fix(ui): stabilize segmented control hints

---
 docs/branch-review-ledger.md            |  1 +
 src/components/ui/segmented-control.tsx | 12 ++++--------
 tests/ui-v2-components.dom.test.tsx     | 26 +++++++++++++++++++++++++
 3 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/docs/branch-review-ledger.md b/docs/branch-review-ledger.md
index 68b6940352..1db89df827 100644
--- a/docs/branch-review-ledger.md
+++ b/docs/branch-review-ledger.md
@@ -902,3 +902,4 @@ Records before 2026-07-28 were written by hand and had drifted: 146 lines carrie
 | 2026-08-12 | claude/rag-canary-test-review-seprbt | bcf357a96fde74d39fc4726ffabb5079a744ef28 | eval-canary review: workflow, compare tooling, snapshot builder, alias tiering, rag-behaviour docs | PR #1843 opened; no retrieval behaviour change; snapshot refresh handed off as /issues #304 | verify:pr-local (green except env-only #296), eval:rag:offline 574/574, focused suites 40/40 |
 | 2026-08-12 | codex/pr-workflow-safety-230-296 | bc0a491fdf4146775629f9b2b03e2a2cc61bd7cb | pr-1830 unblock | unblocked: merged origin/main (outstanding-issues conflict), PR body RAG impact + governance, resolved Copilot thread; merge-tree clean; required CI in progress | check:outstanding-issues pass; evaluatePullRequestPolicy ok; merge-tree clean; PR policy/mergeability/Change scope in progress |
 | 2026-08-12 | claude/segmented-control-count | d5ff3160242986d2fac80ed9a915390b5c69b6e1 | SegmentedControl option hint slot (filter rollout prerequisite) | PR #1848 opened; additive, no call site passes hint yet; fixed a concatenated accessible name (All62 -> All (62)) | lint/typecheck/test green, 80 in ui-v2-components, 56 design-sync with no regen needed, clean build, bundle-budget within tolerance |
+| 2026-08-12 | 1848 | c65b9d91b760862c2ff9d5001974670219c5da02 | full PR diff and unresolved review feedback | P2 hint contrast and live-count width fixes applied | focused Vitest passed (81); focused ESLint passed; design-system contract passed |
diff --git a/src/components/ui/segmented-control.tsx b/src/components/ui/segmented-control.tsx
index b3b2747b96..8630c0412a 100644
--- a/src/components/ui/segmented-control.tsx
+++ b/src/components/ui/segmented-control.tsx
@@ -134,14 +134,10 @@ export function SegmentedControl<T extends string>({
             {Icon ? <Icon aria-hidden="true" className="size-icon-sm shrink-0" /> : null}
             <span className="min-w-0 truncate">{option.label}</span>
             {option.hint ? (
-              // `nums` for tabular figures: without it the rail reflows as a
-              // count crosses a digit boundary, which on a live result set
-              // happens while the reader is aiming at it.
-              <span
-                className={cn("nums shrink-0 tabular-nums", checked ? "opacity-80" : "text-[color:var(--text-soft)]")}
-              >
-                {option.hint}
-              </span>
+              // Reserve a three-digit count column as well as using tabular
+              // figures so live result updates do not move the segment bounds.
+              // The hint inherits the button's opaque semantic foreground.
+              <span className="nums min-w-6 shrink-0 text-right tabular-nums">{option.hint}</span>
             ) : null}
           </button>
         );
diff --git a/tests/ui-v2-components.dom.test.tsx b/tests/ui-v2-components.dom.test.tsx
index 9e05825858..1fa5c48afd 100644
--- a/tests/ui-v2-components.dom.test.tsx
+++ b/tests/ui-v2-components.dom.test.tsx
@@ -367,6 +367,32 @@ describe("SegmentedControl", () => {
     expect(screen.getByRole("radio", { name: "Presentations (41)" })).toBeInTheDocument();
   });
 
+  it("keeps a live count opaque and reserves a stable three-digit column", () => {
+    const renderControl = (hint: string) => (
+      <SegmentedControl
+        label="Result type"
+        value="all"
+        onChange={() => undefined}
+        options={[{ value: "all", label: "All", hint }]}
+        layout="fit"
+      />
+    );
+    const { rerender } = render(renderControl("9"));
+
+    const initialRadio = screen.getByRole("radio", { name: "All (9)" });
+    const initialHint = within(initialRadio).getByText("9");
+    expect(initialHint).toHaveClass("min-w-6", "text-right", "tabular-nums");
+    expect(initialHint).not.toHaveClass("opacity-80");
+    expect(initialHint.className).not.toContain("--text-soft");
+    const initialRadioClasses = initialRadio.className;
+
+    rerender(renderControl("100"));
+
+    const updatedRadio = screen.getByRole("radio", { name: "All (100)" });
+    expect(updatedRadio.className).toBe(initialRadioClasses);
+    expect(within(updatedRadio).getByText("100")).toHaveClass("min-w-6", "text-right", "tabular-nums");
+  });
+
   // A hintless option must not gain stray whitespace or an empty span — the
   // existing call sites pass no hint and their names must not drift.
   it("leaves an option without a hint unchanged", () => {

From 45825dc42ca2e8f66cbc24d6d2c5259b7110590a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 12 Aug 2026 12:59:23 +0000
Subject: [PATCH 5/5] fix(ui): colour the segment hint with --text-muted, not
 the --text-soft alias

CI Static PR checks failure: --text-soft is a decoration-only
compatibility alias that production must not consume, and
check:design-system-contract ratchets its consumer count at zero
(textSoftConsumers increased from 0 to 1).

--text-muted is what ResultFilterSheet already uses for option.hint, so
this also makes the desktop rail and the phone sheet render the same
count the same way, which was the point of adding the slot.

Same root cause as the radius fix on #1847: lifted from the mockup
study, where the token gates do not apply. Also merges origin/main to
clear the 26-commit staleness that failed PR mergeability.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011btGFwWKYFWDs5McQkqz9J
---
 src/components/ui/segmented-control.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/components/ui/segmented-control.tsx b/src/components/ui/segmented-control.tsx
index b3b2747b96..7331780780 100644
--- a/src/components/ui/segmented-control.tsx
+++ b/src/components/ui/segmented-control.tsx
@@ -138,7 +138,11 @@ export function SegmentedControl<T extends string>({
               // count crosses a digit boundary, which on a live result set
               // happens while the reader is aiming at it.
               <span
-                className={cn("nums shrink-0 tabular-nums", checked ? "opacity-80" : "text-[color:var(--text-soft)]")}
+                // --text-muted, not --text-soft: the latter is a decoration-only compatibility
+                // alias that production must not consume, ratcheted at zero by
+                // check:design-system-contract. It is also what ResultFilterSheet already
+                // uses for option.hint, so the two renderings now match.
+                className={cn("nums shrink-0 tabular-nums", checked ? "opacity-80" : "text-[color:var(--text-muted)]")}
               >
                 {option.hint}
               </span>