From 54fed1639bf64c8e78324b5475a644dd0583f02c Mon Sep 17 00:00:00 2001
From: freddymeta <170298698+freddymeta@users.noreply.github.com>
Date: Mon, 24 Aug 2026 06:52:55 -0700
Subject: [PATCH 01/12] feat(Table): expose theme targets for the sort and
 filter affordances
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both controls render inside their plugins, so a theme could not reach
them at all — no class, no data attribute, and no wrapper a consumer can
interpose. Adds three targets:

  astryx-table-sort-button      the sort <button>, reflecting `direction`
  astryx-table-sort-indicator   its icon wrapper, reflecting `direction`
  astryx-table-filter-button    the funnel trigger, with an `active` state

Also makes themingTargets.test.ts discover sources at any depth under
src. It walked only top-level directories, so `Table/plugins/<name>/`
was exempt — including the three targets above. Nothing was failing (no
nested source rendered a themeProps() class before this), so this closes
the hole rather than fixing a live break: 294 -> 302 assertions.

Refs #5417.
---
 .changeset/table-affordance-theme-targets.md  |  6 +++
 .changeset/theming-targets-guard-nested.md    |  6 +++
 .../plugins/filtering/useTableFiltering.tsx   | 15 ++++++--
 .../plugins/sortable/useTableSortable.tsx     | 18 ++++++---
 .../core/src/Table/useTableFiltering.doc.mjs  | 10 +++++
 .../core/src/Table/useTableSortable.doc.mjs   | 12 ++++++
 .../core/src/theme/themingTargets.test.ts     | 37 +++++++++++++++----
 7 files changed, 89 insertions(+), 15 deletions(-)
 create mode 100644 .changeset/table-affordance-theme-targets.md
 create mode 100644 .changeset/theming-targets-guard-nested.md

diff --git a/.changeset/table-affordance-theme-targets.md b/.changeset/table-affordance-theme-targets.md
new file mode 100644
index 0000000000000..2ef20673e5a04
--- /dev/null
+++ b/.changeset/table-affordance-theme-targets.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Table: the sort and filter affordances now carry stable theme targets — `astryx-table-sort-button` and `astryx-table-sort-indicator` (both reflecting `direction`), and `astryx-table-filter-button` (reflecting an `active` state). Both controls are rendered inside their plugins, so a theme had no way to restyle them at all: no class, no data attribute, and no wrapper a consumer can interpose. Purely additive; no visual change.
+@freddymeta
diff --git a/.changeset/theming-targets-guard-nested.md b/.changeset/theming-targets-guard-nested.md
new file mode 100644
index 0000000000000..594db684d4df9
--- /dev/null
+++ b/.changeset/theming-targets-guard-nested.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `themingTargets.test.ts` now discovers component sources at any depth under `src`, not only in a top-level directory. Sources nested a level down — `Table/plugins/<name>/` — were silently exempt from the guard, which is the same drift #3741 was filed to prevent. Nothing was failing (no nested source rendered a `themeProps()` class before this release), so this closes the hole rather than fixing a live break: the guard goes from 294 to 302 assertions.
+@freddymeta
diff --git a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
index 5d544b2fec22a..787a36dc5f864 100644
--- a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
+++ b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
@@ -50,6 +50,8 @@ import type {
 } from '../../types';
 import {proportional} from '../../columnUtils';
 import {useLocale, useTranslator} from '../../../i18n';
+import {mergeProps} from '../../../utils';
+import {themeProps} from '../../../utils/themeProps';
 import type {
   PowerSearchConfig,
   PowerSearchField,
@@ -1012,9 +1014,16 @@ function PopoverFilterTrigger({
         type="button"
         aria-label={t('@astryx.tableFiltering.filterByColumn', {header})}
         aria-haspopup="dialog"
-        {...stylex.props(
-          filterStyles.triggerButton,
-          hasValue ? filterStyles.triggerActive : filterStyles.triggerInactive,
+        {...mergeProps(
+          themeProps('table-filter-button', {
+            active: hasValue ? 'active' : null,
+          }),
+          stylex.props(
+            filterStyles.triggerButton,
+            hasValue
+              ? filterStyles.triggerActive
+              : filterStyles.triggerInactive,
+          ),
         )}>
         <Icon
           icon="funnel"
diff --git a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
index 74bfb47a7a663..5b7e46463782c 100644
--- a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
+++ b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
@@ -17,6 +17,8 @@ import {useRef, useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../../../theme/tokens.stylex';
 import {focusOutlineProps} from '../../../utils/focusOutline.stylex';
+import {mergeProps} from '../../../utils';
+import {themeProps} from '../../../utils/themeProps';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator, type TranslatorFn} from '../../../i18n';
@@ -306,15 +308,21 @@ function SortHeaderButton<T extends Record<string, unknown>>({
   return (
     <button
       type="button"
-      {...focusOutlineProps.focusVisible(sortStyles.button)}
+      {...mergeProps(
+        themeProps('table-sort-button', {direction}),
+        focusOutlineProps.focusVisible(sortStyles.button),
+      )}
       aria-label={ariaLabel}
       onClick={handleClick}>
       <span>{children}</span>
       <span
-        {...stylex.props(
-          direction != null
-            ? sortStyles.iconWrapperActive
-            : sortStyles.iconWrapperUnsorted,
+        {...mergeProps(
+          themeProps('table-sort-indicator', {direction}),
+          stylex.props(
+            direction != null
+              ? sortStyles.iconWrapperActive
+              : sortStyles.iconWrapperUnsorted,
+          ),
         )}>
         <Icon
           icon={iconName}
diff --git a/packages/core/src/Table/useTableFiltering.doc.mjs b/packages/core/src/Table/useTableFiltering.doc.mjs
index a2f5e704ee6f0..42985d0b8cd1c 100644
--- a/packages/core/src/Table/useTableFiltering.doc.mjs
+++ b/packages/core/src/Table/useTableFiltering.doc.mjs
@@ -8,6 +8,11 @@ export const docs = {
   displayName: 'useTableFiltering',
   isHiddenFromOverview: true,
   description: 'Table plugin that adds inline column filters with popover or inline controls. Pairs with useTableFilterState for managed state. Supports text, select, multi-select, date, and number filter types via PowerSearch field definitions.',
+  theming: {
+    targets: [
+      {className: 'astryx-table-filter-button', states: ['active']},
+    ],
+  },
   props: [
     {
       name: 'filters',
@@ -35,6 +40,11 @@ export const docsZh = {
   isHiddenFromOverview: true,
   displayName: 'useTableFiltering',
   description: '表格筛选插件，添加内联列过滤器（弹出式或内联控件）。与 useTableFilterState 配合使用管理状态。',
+  theming: {
+    targets: [
+      {className: 'astryx-table-filter-button', states: ['active']},
+    ],
+  },
   props: [
     {
       name: 'filters',
diff --git a/packages/core/src/Table/useTableSortable.doc.mjs b/packages/core/src/Table/useTableSortable.doc.mjs
index 8120c37fb88d2..13b70e64fdc16 100644
--- a/packages/core/src/Table/useTableSortable.doc.mjs
+++ b/packages/core/src/Table/useTableSortable.doc.mjs
@@ -7,6 +7,12 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableSortable',
   description: 'Headless multi-sort plugin for Table. Call with a config object: `useTableSortable({ sort, onSortChange })`. Returns a TablePlugin to pass to `<Table plugins={{ sort: sortPlugin }} />`.',
+  theming: {
+    targets: [
+      {className: 'astryx-table-sort-button', visualProps: ['direction']},
+      {className: 'astryx-table-sort-indicator', visualProps: ['direction']},
+    ],
+  },
   usage: {
     description: 'Call useTableSortable with a config object containing sort state and callback. Pass the returned plugin to Table via the plugins prop.',
   },
@@ -42,6 +48,12 @@ export const docsZh = {
   name: 'useTableSortable',
   displayName: 'useTableSortable',
   description: '无头多列排序插件。用户拥有排序状态并提供回调。Shift+点击启用二级排序列。排序指示器自动渲染在表头单元格中。',
+  theming: {
+    targets: [
+      {className: 'astryx-table-sort-button', visualProps: ['direction']},
+      {className: 'astryx-table-sort-indicator', visualProps: ['direction']},
+    ],
+  },
   props: [
     {
       name: 'sort',
diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.ts
index 11ba11453af75..8e5da2c109c56 100644
--- a/packages/core/src/theme/themingTargets.test.ts
+++ b/packages/core/src/theme/themingTargets.test.ts
@@ -26,7 +26,7 @@
 
 import {describe, it, expect} from 'vitest';
 import {readdirSync, readFileSync} from 'node:fs';
-import {join, relative} from 'node:path';
+import {basename, join, relative} from 'node:path';
 import ts from 'typescript';
 import {stableClassName} from '../naming';
 
@@ -350,13 +350,35 @@ function docFilesDocumenting(classNames: Set<string>): string[] {
   return matches;
 }
 
+/**
+ * Every directory under src, at any depth, relative to src.
+ *
+ * Not just the top level: a component's sources are not always its own direct
+ * children — Table's plugins render from `Table/plugins/<name>/`. Scanning only
+ * the top level exempted every one of those from this guard, which is the same
+ * silent-exemption shape #3741 was filed about.
+ */
+function sourceDirs(): string[] {
+  const out: string[] = [];
+  const walk = (rel: string): void => {
+    for (const entry of readdirSync(join(SRC_DIR, rel), {
+      withFileTypes: true,
+    })) {
+      if (entry.isDirectory()) {
+        const child = rel === '' ? entry.name : join(rel, entry.name);
+        out.push(child);
+        walk(child);
+      }
+    }
+  };
+  walk('');
+  return out;
+}
+
 function discoverComponents(): ComponentInfo[] {
   const results: ComponentInfo[] = [];
-  const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
-    .filter(d => d.isDirectory())
-    .map(d => d.name);
 
-  for (const dir of dirs) {
+  for (const dir of sourceDirs()) {
     const dirPath = join(SRC_DIR, dir);
     const dirEntries = readdirSync(dirPath);
 
@@ -387,8 +409,9 @@ function discoverComponents(): ComponentInfo[] {
     // Both paths match the on-disk listing rather than existsSync: on
     // case-insensitive filesystems existsSync would match a differently-cased
     // doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)
-    const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
-      ? [join(dirPath, `${dir}.doc.mjs`)]
+    const ownDoc = `${basename(dir)}.doc.mjs`;
+    const docFiles = dirEntries.includes(ownDoc)
+      ? [join(dirPath, ownDoc)]
       : docFilesDocumenting(new Set(sites.map(s => s.className)));
     if (docFiles.length === 0) {
       continue;

From 7d67af8aaeb75ed0966820d64a39e82e1f9a9075 Mon Sep 17 00:00:00 2001
From: freddymeta <170298698+freddymeta@users.noreply.github.com>
Date: Tue, 25 Aug 2026 03:11:01 -0700
Subject: [PATCH 02/12] Address the review: colour on the button reaches the
 glyph, and clears 3:1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the review on #5420.

**Both icons read `color="inherit"` and the buttons carry the colour.** An
`Icon` that names its own colour writes `color` on the glyph, which beats
anything the button inherits down — so a theme could resolve
`astryx-table-sort-button`, emit the rule, and watch nothing move. With the
colour on the button, the target colours the thing it is named for, and
`astryx-table-sort-indicator` is no longer needed: it existed only because the
button could not reach its own glyph. Two targets, one per affordance.

**The resting `opacity: 0.35` is gone from both.** Composited against the
header it put the arrows at 1.57:1, under the 3:1 WCAG 1.4.11 asks of a UI
component. They render at `--color-icon-secondary` instead — 4.74:1 in light,
6:1 in dark, both measured in Chromium. The affordances are now visible at rest
rather than fading in on header hover.

**The header label inside the sort button carries its own colour**, the same
`--color-text-secondary` the `<th>` sets. Without it, colouring the sort target
repaints the header text along with the arrow — the button holds both.

Sorted state is untouched: the arrow still moves to the accent colour and still
changes glyph, alongside the `aria-sort` the header already carries, so no
state is signalled by colour alone.

**`.github/scripts/affordance-color-reach.js`** holds all of it. It renders the
built Storybook in Chromium, writes `@layer astryx-theme { .<target> { color } }`
the way `Theme` does, and asserts the glyph takes it — at rest, under hover, and
without dragging the header label along — then pins the resting contrast. None
of that is visible from jsdom, which resolves no cascade: a unit test can assert
the class is on the button and the rule is in the CSS text while the glyph still
paints its own colour. Shape follows theme-var-reachability.js, the sibling
guard for documented vars; this one is for an ordinary inherited property, which
that enumeration cannot see.

Negative control, the guard against this branch's own pre-review build: six
failures across the two affordances — 1.57:1 at rest, the themed colour not
reaching either glyph, and the same on hover.
---
 .changeset/table-affordance-theme-targets.md  |   9 +-
 .github/scripts/affordance-color-reach.js     | 319 ++++++++++++++++++
 .github/workflows/ci.yml                      |  10 +
 package.json                                  |   1 +
 .../plugins/filtering/useTableFiltering.tsx   |  25 +-
 .../plugins/sortable/useTableSortable.tsx     |  46 ++-
 .../core/src/Table/useTableSortable.doc.mjs   |   2 -
 7 files changed, 367 insertions(+), 45 deletions(-)
 create mode 100755 .github/scripts/affordance-color-reach.js

diff --git a/.changeset/table-affordance-theme-targets.md b/.changeset/table-affordance-theme-targets.md
index 2ef20673e5a04..37590156e2d5a 100644
--- a/.changeset/table-affordance-theme-targets.md
+++ b/.changeset/table-affordance-theme-targets.md
@@ -2,5 +2,12 @@
 '@astryxdesign/core': patch
 ---
 
-[feat] Table: the sort and filter affordances now carry stable theme targets — `astryx-table-sort-button` and `astryx-table-sort-indicator` (both reflecting `direction`), and `astryx-table-filter-button` (reflecting an `active` state). Both controls are rendered inside their plugins, so a theme had no way to restyle them at all: no class, no data attribute, and no wrapper a consumer can interpose. Purely additive; no visual change.
+[feat] Table: the sort and filter affordances now expose stable theme targets — `astryx-table-sort-button` (reflecting `direction`) and `astryx-table-filter-button` (reflecting `active`). Both are rendered inside Table's own plugins, so there is no wrapper a consumer can interpose and no `renderX` prop to pass through: the only way to restyle either was `.astryx-table-header-cell button[aria-haspopup='dialog']`, a selector that says "the button that opens a dialog", which is the filtering funnel today and could be anything tomorrow.
+
+Setting a colour on either target now reaches the glyph. Both icons previously named their own colour, which writes `color` on the glyph and beats anything the button inherits down — so a theme could resolve the target, emit the rule, and see nothing move. Each icon reads `color="inherit"` and the button carries the colour instead, which is also why the sort target does not need a second one for its glyph.
+
+[fix] Table: the resting sort arrows and filter funnel are no longer dimmed to `opacity: 0.35`. Composited against the header that put them at **1.57:1**, below the 3:1 [WCAG 1.4.11](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) asks of a UI component; they now render at `--color-icon-secondary`, which is 4.74:1 in light and 6:1 in dark. Both affordances stay visible at rest rather than fading in on header hover. Sorted state is unchanged — the arrow still moves to the accent colour, and still changes glyph (`arrowsUpDown` → `arrowUp`/`arrowDown`) alongside the `aria-sort` the header already carries, so the state is never colour alone.
+
+The header label inside the sort button now carries `--color-text-secondary` itself, the token the `<th>` already sets, rather than inheriting it — otherwise colouring the sort target would repaint the header text along with the arrow.
+
 @freddymeta
diff --git a/.github/scripts/affordance-color-reach.js b/.github/scripts/affordance-color-reach.js
new file mode 100755
index 0000000000000..3b6b6493dfefc
--- /dev/null
+++ b/.github/scripts/affordance-color-reach.js
@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @description Asserts a colour set on an affordance's theme target reaches the glyph it names
+ * @input --storybook-dir <path> [--port <n>]
+ * @output One line per case; exit 1 if a target cannot colour its own glyph
+ *
+ * A theme target that names a button holding one icon promises the obvious
+ * thing: set a colour on it and the icon changes. That promise is easy to ship
+ * broken, because an `Icon` that names its own colour (`color="secondary"`)
+ * writes `color` on the glyph itself and beats anything the button inherits
+ * down — the target resolves, the rule emits, and nothing moves. Table's sort
+ * and filter affordances both shipped that way, which is what this guards.
+ *
+ * Nothing in the unit suite can see it. jsdom resolves no cascade, so a test
+ * there can assert the class is on the button and the rule is in the CSS text
+ * while the glyph still paints its own colour.
+ *
+ * The sibling guard, theme-var-reachability.js, asks whether a documented
+ * *var* is settable. This asks whether an ordinary inherited property reaches
+ * the descendant the target exists for, and it checks three things a var
+ * cannot:
+ *
+ *   1. the glyph takes the themed colour at rest
+ *   2. it still takes it under `:hover`, where a resting-state rule that only
+ *      fires on hover would otherwise take over
+ *   3. the elements the target must NOT repaint keep their own colour — a
+ *      button that holds both a label and a glyph must colour only the glyph
+ *
+ * It also pins the resting contrast, because the reason these two grew a
+ * `color` of their own is that the dimming they used instead (`opacity: 0.35`)
+ * put them below the 3:1 WCAG 1.4.11 asks of a UI component.
+ */
+
+const {chromium} = require('playwright');
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+
+const args = process.argv.slice(2);
+const getArg = name => {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 ? args[idx + 1] : null;
+};
+
+const storybookDir = getArg('storybook-dir') || 'apps/storybook/dist';
+const port = Number(getArg('port') || 6013);
+
+/** Distinctive enough that a coincidental match is not a concern. */
+const SENTINEL = 'rgb(1, 2, 3)';
+
+/** WCAG 1.4.11 — a UI component's states must reach 3:1 against their ground. */
+const MIN_CONTRAST = 3;
+
+const CASES = [
+  {
+    name: 'Table sort affordance',
+    story: 'core-tablefiltering--with-sorting',
+    target: 'astryx-table-sort-button',
+    // The header label shares the button with the glyph, so it has to keep the
+    // cell's colour rather than follow the affordance's.
+    unchanged: 'the header label',
+    unchangedSelector: '.astryx-table-sort-button > span:first-child',
+  },
+  {
+    name: 'Table filter affordance',
+    story: 'core-tablefiltering--with-sorting',
+    target: 'astryx-table-filter-button',
+    unchanged: null,
+    unchangedSelector: null,
+  },
+];
+
+const CONTENT_TYPES = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+};
+
+function createServer(dir, listenPort) {
+  return new Promise(resolve => {
+    const server = http.createServer((req, res) => {
+      const filePath = path
+        .join(dir, req.url === '/' ? 'index.html' : req.url)
+        .split('?')[0];
+
+      const resolved = path.resolve(filePath);
+      if (!resolved.startsWith(path.resolve(dir))) {
+        res.writeHead(403);
+        res.end('Forbidden');
+        return;
+      }
+
+      fs.readFile(resolved, (err, data) => {
+        if (err) {
+          res.writeHead(404);
+          res.end('Not found');
+          return;
+        }
+        res.writeHead(200, {
+          'Content-Type': CONTENT_TYPES[path.extname(resolved)] || 'text/plain',
+        });
+        res.end(data);
+      });
+    });
+
+    server.listen(listenPort, () => resolve(server));
+  });
+}
+
+/** WCAG relative luminance of an `rgb(r, g, b)` string. */
+function luminance(color) {
+  const [r, g, b] = (color.match(/\d+/g) || []).slice(0, 3).map(Number);
+  const channel = v => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+function contrastRatio(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return Number(((hi + 0.05) / (lo + 0.05)).toFixed(2));
+}
+
+/**
+ * In the page: read the glyph's colour, the ground it sits on, and the colour
+ * of whatever the target must leave alone. `opacity` is folded in because it
+ * composites toward the ground and is what put these two under 3:1.
+ */
+function readInPage([target, unchangedSelector]) {
+  const button = document.querySelector(`.${target}`);
+  if (!button) return {status: 'missing'};
+
+  const glyph = button.querySelector('svg');
+  if (!glyph) return {status: 'noglyph'};
+
+  let opacity = 1;
+  for (let el = glyph; el && el !== document.body; el = el.parentElement) {
+    opacity *= Number(getComputedStyle(el).opacity);
+  }
+
+  let ground = 'rgb(255, 255, 255)';
+  for (let el = button; el; el = el.parentElement) {
+    const bg = getComputedStyle(el).backgroundColor;
+    if (bg && !/rgba\(0, 0, 0, 0\)|transparent/.test(bg)) {
+      ground = bg;
+      break;
+    }
+  }
+
+  const unchanged = unchangedSelector
+    ? getComputedStyle(document.querySelector(unchangedSelector)).color
+    : null;
+
+  return {
+    status: 'ok',
+    color: getComputedStyle(glyph).color,
+    opacity: Number(opacity.toFixed(3)),
+    ground,
+    unchanged,
+  };
+}
+
+/** Composite `color` over `ground` at `opacity`, the way the screen does. */
+function composite(color, ground, opacity) {
+  const c = (color.match(/\d+/g) || []).slice(0, 3).map(Number);
+  const g = (ground.match(/\d+/g) || []).slice(0, 3).map(Number);
+  const mixed = c.map((v, i) => Math.round(v * opacity + g[i] * (1 - opacity)));
+  return `rgb(${mixed.join(', ')})`;
+}
+
+async function checkCase(context, testCase) {
+  const page = await context.newPage();
+  const failures = [];
+  const notes = [];
+
+  try {
+    await page.goto(
+      `http://localhost:${port}/iframe.html?id=${testCase.story}&viewMode=story`,
+      {waitUntil: 'networkidle', timeout: 30000},
+    );
+
+    const args = [testCase.target, testCase.unchangedSelector];
+    const rest = await page.evaluate(readInPage, args);
+
+    if (rest.status === 'missing') {
+      return {failures: [`no element carries .${testCase.target}`], notes};
+    }
+    if (rest.status === 'noglyph') {
+      return {failures: [`.${testCase.target} holds no glyph to colour`], notes};
+    }
+
+    // 1 — resting contrast, composited the way it is seen.
+    const painted = composite(rest.color, rest.ground, rest.opacity);
+    const ratio = contrastRatio(painted, rest.ground);
+    notes.push(
+      `rest ${rest.color}${rest.opacity === 1 ? '' : ` @ ${rest.opacity}`} on ${rest.ground} — ${ratio}:1`,
+    );
+    if (ratio < MIN_CONTRAST) {
+      failures.push(
+        `resting glyph is ${ratio}:1 against the header, below the ${MIN_CONTRAST}:1 ` +
+          `WCAG 1.4.11 asks of a UI component` +
+          (rest.opacity === 1
+            ? ''
+            : ` (it is dimmed to ${rest.opacity}, which composites toward the ground)`),
+      );
+    }
+
+    // 2 — a themed colour reaches the glyph.
+    await page.evaluate(css => {
+      const style = document.createElement('style');
+      style.id = 'reach-probe';
+      style.textContent = css;
+      document.head.appendChild(style);
+    }, `@layer astryx-theme { .${testCase.target} { color: ${SENTINEL}; } }`);
+
+    const themed = await page.evaluate(readInPage, args);
+    if (themed.color !== SENTINEL) {
+      failures.push(
+        `a colour on .${testCase.target} in @layer astryx-theme did not reach the glyph — ` +
+          `it stayed ${themed.color}. The glyph names its own colour, so the ` +
+          `target a theme is told to use cannot move it.`,
+      );
+    } else {
+      notes.push(`themed → ${themed.color}`);
+    }
+
+    // 3 — and still reaches it under hover.
+    const header = page.locator(`th:has(.${testCase.target})`).first();
+    await header.hover({force: true});
+    await page.waitForTimeout(120);
+    const hovered = await page.evaluate(readInPage, args);
+    if (hovered.color !== SENTINEL) {
+      failures.push(
+        `the themed colour is lost on hover — glyph went to ${hovered.color}. ` +
+          `A hover rule that re-states the resting colour takes the theme's away.`,
+      );
+    } else {
+      notes.push(`hovered → ${hovered.color}`);
+    }
+
+    // 4 — what the target must not repaint kept its own colour.
+    if (testCase.unchangedSelector) {
+      if (themed.unchanged === SENTINEL) {
+        failures.push(
+          `${testCase.unchanged} followed the target's colour. It shares the ` +
+            `element with the glyph, so it needs a colour of its own.`,
+        );
+      } else {
+        notes.push(`${testCase.unchanged} held at ${themed.unchanged}`);
+      }
+    }
+  } finally {
+    await page.close();
+  }
+
+  return {failures, notes};
+}
+
+async function run() {
+  const dir = path.resolve(process.cwd(), storybookDir);
+  if (!fs.existsSync(path.join(dir, 'index.json'))) {
+    console.error(`Storybook build not found at ${dir}`);
+    return 1;
+  }
+
+  const server = await createServer(dir, port);
+  const browser = await chromium.launch();
+  let failed = 0;
+
+  try {
+    const context = await browser.newContext({
+      viewport: {width: 1100, height: 700},
+    });
+
+    for (const testCase of CASES) {
+      const {failures, notes} = await checkCase(context, testCase);
+      if (failures.length === 0) {
+        console.log(`✓ ${testCase.name} — ${notes.join('; ')}`);
+        continue;
+      }
+      failed += 1;
+      for (const f of failures) {
+        console.error(`✗ ${testCase.name}: ${f}`);
+      }
+      if (notes.length > 0) {
+        console.error(`  measured: ${notes.join('; ')}`);
+      }
+    }
+  } finally {
+    await browser.close();
+    server.close();
+  }
+
+  if (failed > 0) {
+    console.error(
+      `\nFailing: ${failed} affordance target(s). A target that names a button ` +
+        `holding one icon has to be able to colour that icon — otherwise the ` +
+        `documented seam does nothing and says nothing.`,
+    );
+    return 1;
+  }
+  console.log(`\nAll ${CASES.length} affordance targets colour their own glyph.`);
+  return 0;
+}
+
+run()
+  .then(code => {
+    process.exitCode = code;
+  })
+  .catch(e => {
+    console.error('Affordance colour reachability guard failed:', e);
+    process.exit(1);
+  });
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 19734dcbe34f0..b8b54af02fcea 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -513,6 +513,16 @@ jobs:
       - name: Run theme var reachability guard
         run: node .github/scripts/theme-var-reachability.js --storybook-dir apps/storybook/dist
 
+      # A target that names a button holding one icon promises that a colour set
+      # on it reaches that icon. An `Icon` naming its own colour writes `color`
+      # on the glyph and beats what the button inherits down, so the rule emits
+      # and nothing moves — the sibling guard above cannot see it, because this
+      # is an ordinary inherited property, not a documented var. Also pins the
+      # resting contrast, since dimming with `opacity` instead of a colour is
+      # what put these two under WCAG 1.4.11's 3:1.
+      - name: Run affordance colour reachability guard
+        run: node .github/scripts/affordance-color-reach.js --storybook-dir apps/storybook/dist
+
   # The layer order Astryx promises is Astryx < theme < product, and which
   # declaration paints is a cascade fact no jsdom test can settle: the build has
   # been wrong in both directions inside one week — unsplit, so StyleX outranked
diff --git a/package.json b/package.json
index 8396fe68cf33e..6322af71be204 100644
--- a/package.json
+++ b/package.json
@@ -36,6 +36,7 @@
     "lab:readiness:check": "node internal/lab-readiness/audit.mjs --check",
     "guard:modal-close": "node .github/scripts/modal-close-visibility.js",
     "guard:theme-vars": "node .github/scripts/theme-var-reachability.js",
+    "guard:affordance-color": "node .github/scripts/affordance-color-reach.js",
     "guard:theme-layers": "node .github/scripts/theme-layer-cascade.js",
     "guard:disabled-hover": "node .github/scripts/disabled-hover-audit.js",
     "guard:pressed-overlay": "node .github/scripts/pressed-overlay-cascade.js",
diff --git a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
index 787a36dc5f864..ebf2215254273 100644
--- a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
+++ b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
@@ -26,7 +26,7 @@ import {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {spacingVars, radiusVars} from '../../../theme/tokens.stylex';
+import {spacingVars, radiusVars, colorVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {Button} from '../../../Button';
 import {Popover} from '../../../Popover';
@@ -386,16 +386,13 @@ const filterStyles = stylex.create({
       minWidth: '44px',
       minHeight: '44px',
     },
-  },
-  triggerInactive: {
-    opacity: {
-      default: 0.35,
-      ':is(th:hover *)': 1,
-      ':focus-visible': 1,
-    },
+    // The funnel reads this through `color="inherit"`, so a theme setting a
+    // colour on `astryx-table-filter-button` reaches it. The button holds only
+    // the glyph, so there is nothing else here for the colour to reach.
+    color: colorVars['--color-icon-secondary'],
   },
   triggerActive: {
-    opacity: 1,
+    color: colorVars['--color-accent'],
   },
   popoverContent: {
     width: '240px',
@@ -1020,16 +1017,10 @@ function PopoverFilterTrigger({
           }),
           stylex.props(
             filterStyles.triggerButton,
-            hasValue
-              ? filterStyles.triggerActive
-              : filterStyles.triggerInactive,
+            hasValue && filterStyles.triggerActive,
           ),
         )}>
-        <Icon
-          icon="funnel"
-          size="xsm"
-          color={hasValue ? 'accent' : 'secondary'}
-        />
+        <Icon icon="funnel" size="xsm" color="inherit" />
       </button>
     </Popover>
   );
diff --git a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
index 5b7e46463782c..5ce3aceeb2ddc 100644
--- a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
+++ b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
@@ -132,21 +132,26 @@ const sortStyles = stylex.create({
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
     font: 'inherit',
-    color: 'inherit',
+    // The glyph reads this through `color="inherit"`, so a theme setting a
+    // colour on `astryx-table-sort-button` reaches the thing it is aiming at.
+    // The label carries the header's colour itself (see `label`) rather than
+    // inheriting it from here.
+    color: colorVars['--color-icon-secondary'],
     width: '100%',
     height: '100%',
     textAlign: 'inherit',
     borderRadius: radiusVars['--radius-inner'],
   },
-  iconWrapperUnsorted: {
-    display: 'inline-flex',
-    opacity: {
-      default: 0.35,
-      ':is(th:hover *)': 1,
-      ':focus-visible': 1,
-    },
+  buttonSorted: {
+    color: colorVars['--color-accent'],
   },
-  iconWrapperActive: {
+  // The header text belongs to the cell, not to the affordance. It is pinned
+  // to the token the `<th>` sets so the button's icon colour cannot bleed into
+  // it — without this, colouring the sort target repaints the header label too.
+  label: {
+    color: colorVars['--color-text-secondary'],
+  },
+  iconWrapper: {
     display: 'inline-flex',
   },
   rank: {
@@ -310,25 +315,16 @@ function SortHeaderButton<T extends Record<string, unknown>>({
       type="button"
       {...mergeProps(
         themeProps('table-sort-button', {direction}),
-        focusOutlineProps.focusVisible(sortStyles.button),
+        focusOutlineProps.focusVisible(
+          sortStyles.button,
+          direction != null && sortStyles.buttonSorted,
+        ),
       )}
       aria-label={ariaLabel}
       onClick={handleClick}>
-      <span>{children}</span>
-      <span
-        {...mergeProps(
-          themeProps('table-sort-indicator', {direction}),
-          stylex.props(
-            direction != null
-              ? sortStyles.iconWrapperActive
-              : sortStyles.iconWrapperUnsorted,
-          ),
-        )}>
-        <Icon
-          icon={iconName}
-          size="xsm"
-          color={direction != null ? 'accent' : 'secondary'}
-        />
+      <span {...stylex.props(sortStyles.label)}>{children}</span>
+      <span {...stylex.props(sortStyles.iconWrapper)}>
+        <Icon icon={iconName} size="xsm" color="inherit" />
       </span>
       {rank != null && (
         <span {...stylex.props(sortStyles.rank)} aria-hidden="true">
diff --git a/packages/core/src/Table/useTableSortable.doc.mjs b/packages/core/src/Table/useTableSortable.doc.mjs
index 13b70e64fdc16..23548cc8669c2 100644
--- a/packages/core/src/Table/useTableSortable.doc.mjs
+++ b/packages/core/src/Table/useTableSortable.doc.mjs
@@ -10,7 +10,6 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-table-sort-button', visualProps: ['direction']},
-      {className: 'astryx-table-sort-indicator', visualProps: ['direction']},
     ],
   },
   usage: {
@@ -51,7 +50,6 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-table-sort-button', visualProps: ['direction']},
-      {className: 'astryx-table-sort-indicator', visualProps: ['direction']},
     ],
   },
   props: [

From 03941ba7d3cc326c7a2ee3a0f87b81f999517e93 Mon Sep 17 00:00:00 2001
From: freddymeta <170298698+freddymeta@users.noreply.github.com>
Date: Tue, 25 Aug 2026 03:11:42 -0700
Subject: [PATCH 03/12] =?UTF-8?q?Leave=20the=20CI=20wiring=20for=20a=20mai?=
 =?UTF-8?q?ntainer=20=E2=80=94=20this=20PAT=20has=20no=20`workflow`=20scop?=
 =?UTF-8?q?e?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The guard itself and its `pnpm guard:affordance-color` entry stay; only the
`ci.yml` step comes out, because GitHub refuses a push that touches a workflow
file from a token without `workflow` scope, and mine does not have it.

It wants three lines after the theme-var reachability step in the pr-a11y job:

    - name: Run affordance colour reachability guard
      run: node .github/scripts/affordance-color-reach.js --storybook-dir apps/storybook/dist

Until that lands the guard runs locally and in review, not on every PR — so it
holds this change but does not yet hold the next one.
---
 .github/workflows/ci.yml | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b8b54af02fcea..19734dcbe34f0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -513,16 +513,6 @@ jobs:
       - name: Run theme var reachability guard
         run: node .github/scripts/theme-var-reachability.js --storybook-dir apps/storybook/dist
 
-      # A target that names a button holding one icon promises that a colour set
-      # on it reaches that icon. An `Icon` naming its own colour writes `color`
-      # on the glyph and beats what the button inherits down, so the rule emits
-      # and nothing moves — the sibling guard above cannot see it, because this
-      # is an ordinary inherited property, not a documented var. Also pins the
-      # resting contrast, since dimming with `opacity` instead of a colour is
-      # what put these two under WCAG 1.4.11's 3:1.
-      - name: Run affordance colour reachability guard
-        run: node .github/scripts/affordance-color-reach.js --storybook-dir apps/storybook/dist
-
   # The layer order Astryx promises is Astryx < theme < product, and which
   # declaration paints is a cascade fact no jsdom test can settle: the build has
   # been wrong in both directions inside one week — unsplit, so StyleX outranked

From 6c4ea0d5f80adfd879f456c5c5953589d3453c86 Mon Sep 17 00:00:00 2001
From: freddytan <freddytan@84853.od.fbinfra.net>
Date: Thu, 27 Aug 2026 17:41:52 -0700
Subject: [PATCH 04/12] fix(Table): give the sort and filter affordances the
 shared interaction states
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ruby's hold. Dropping the resting `opacity: 0.35` fixed the contrast and
took the only hover feedback with it — the affordances had no rest ->
hover -> pressed model left at all, and the filter button drew nothing
on keyboard focus either.

Both now draw what every other borderless control draws: an
`--color-overlay-hover` tint on hover, `--color-overlay-pressed` on
press, and the shared focus ring via `focusOutlineProps.focusVisible`.
The filter button gains that ring; it never had one.

Hover is guarded on `@media (hover: hover)` so a touch device does not
stick in the tint after a tap, and the glyph darkens a step alongside
the tint so the feedback survives a forced-colors mode that drops
backgrounds.

Accent stays reserved for the sorted/filtered state, so "this column is
sorted" never reads as "the pointer is here". Resting colour is
unchanged at 4.74:1.
---
 .../plugins/filtering/useTableFiltering.tsx   | 36 ++++++++++++++++-
 .../plugins/sortable/useTableSortable.tsx     | 39 ++++++++++++++++++-
 2 files changed, 72 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
index ebf2215254273..87ca331c9d182 100644
--- a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
+++ b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
@@ -26,7 +26,14 @@ import {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {spacingVars, radiusVars, colorVars} from '../../../theme/tokens.stylex';
+import {
+  spacingVars,
+  radiusVars,
+  colorVars,
+  durationVars,
+  easeVars,
+} from '../../../theme/tokens.stylex';
+import {focusOutlineProps} from '../../../utils/focusOutline.stylex';
 import {Icon} from '../../../Icon';
 import {Button} from '../../../Button';
 import {Popover} from '../../../Popover';
@@ -390,7 +397,29 @@ const filterStyles = stylex.create({
     // colour on `astryx-table-filter-button` reaches it. The button holds only
     // the glyph, so there is nothing else here for the colour to reach.
     color: colorVars['--color-icon-secondary'],
+    // Rest -> hover -> pressed, matching the sort affordance beside it.
+    backgroundColor: {
+      default: 'transparent',
+      ':active:where(:not(:disabled,[aria-disabled="true"]))':
+        colorVars['--color-overlay-pressed'],
+    },
+    transitionProperty: 'background-color, color',
+    transitionDuration: durationVars['--duration-fast'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  triggerHoverOnPointer: {
+    '@media (hover: hover)': {
+      backgroundColor: {
+        ':hover:where(:not(:disabled,[aria-disabled="true"]))':
+          colorVars['--color-overlay-hover'],
+      },
+      color: {
+        ':hover:where(:not(:disabled,[aria-disabled="true"]))':
+          colorVars['--color-text-primary'],
+      },
+    },
   },
+  // Accent is the FILTERED state and nothing else.
   triggerActive: {
     color: colorVars['--color-accent'],
   },
@@ -1015,8 +1044,11 @@ function PopoverFilterTrigger({
           themeProps('table-filter-button', {
             active: hasValue ? 'active' : null,
           }),
-          stylex.props(
+          // The ring was missing here entirely: this button is keyboard
+          // reachable and drew nothing on focus.
+          focusOutlineProps.focusVisible(
             filterStyles.triggerButton,
+            filterStyles.triggerHoverOnPointer,
             hasValue && filterStyles.triggerActive,
           ),
         )}>
diff --git a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
index 5ce3aceeb2ddc..eb3836cd584fd 100644
--- a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
+++ b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
@@ -15,7 +15,13 @@
 
 import {useRef, useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {colorVars, spacingVars, radiusVars} from '../../../theme/tokens.stylex';
+import {
+  colorVars,
+  spacingVars,
+  radiusVars,
+  durationVars,
+  easeVars,
+} from '../../../theme/tokens.stylex';
 import {focusOutlineProps} from '../../../utils/focusOutline.stylex';
 import {mergeProps} from '../../../utils';
 import {themeProps} from '../../../utils/themeProps';
@@ -141,7 +147,37 @@ const sortStyles = stylex.create({
     height: '100%',
     textAlign: 'inherit',
     borderRadius: radiusVars['--radius-inner'],
+    // Rest -> hover -> pressed, the treatment every other borderless control
+    // in the system draws. The resting state carries no tint: the affordance
+    // is legible on its colour alone (`--color-icon-secondary`, 4.74:1)
+    // rather than on the dimming that put it at 1.57:1.
+    backgroundColor: {
+      default: 'transparent',
+      ':active:where(:not(:disabled,[aria-disabled="true"]))':
+        colorVars['--color-overlay-pressed'],
+    },
+    transitionProperty: 'background-color, color',
+    transitionDuration: durationVars['--duration-fast'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  // Guarded on `hover: hover` so a touch device does not stick in the hover
+  // tint after a tap (Component Audit Rubric A8).
+  buttonHoverOnPointer: {
+    '@media (hover: hover)': {
+      backgroundColor: {
+        ':hover:where(:not(:disabled,[aria-disabled="true"]))':
+          colorVars['--color-overlay-hover'],
+      },
+      color: {
+        // The glyph darkens a step as well, so the feedback survives a
+        // forced-colors mode that drops the background tint.
+        ':hover:where(:not(:disabled,[aria-disabled="true"]))':
+          colorVars['--color-text-primary'],
+      },
+    },
   },
+  // Accent is the SORTED state and nothing else, so "this column is sorted"
+  // never reads as "the pointer is here".
   buttonSorted: {
     color: colorVars['--color-accent'],
   },
@@ -317,6 +353,7 @@ function SortHeaderButton<T extends Record<string, unknown>>({
         themeProps('table-sort-button', {direction}),
         focusOutlineProps.focusVisible(
           sortStyles.button,
+          sortStyles.buttonHoverOnPointer,
           direction != null && sortStyles.buttonSorted,
         ),
       )}

From 312eac910a23099b7061de440cea337116eb5d46 Mon Sep 17 00:00:00 2001
From: freddytan <freddytan@84853.od.fbinfra.net>
Date: Thu, 27 Aug 2026 17:47:13 -0700
Subject: [PATCH 05/12] fix(guard): assert the painted stroke/fill, and wait
 for the story to mount
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both of the review's holds on the guard.

It read `svg.color`, which is the colour the glyph INHERITS, not the one
it paints. Geometry that hardcodes a stroke leaves `color` reading the
sentinel while nothing on screen moves — the exact shape the guard
exists to catch, passing. It now collects the resolved `stroke`/`fill`
off every painted node and asserts on those, at rest and under hover,
and the resting contrast is measured on the paint too.

Verified both ways: green on this head, and with `stroke` forced to
rgb(9, 9, 9) it fails with "stroke/fill stayed rgb(9, 9, 9) while the
inherited color read rgb(1, 2, 3)" — which is the sentence the old
version could not say.

It also read before the story mounted, because Storybook settles the
network before it renders and `networkidle` was the only wait. It now
waits for the target with a glyph inside it.

One thing the paint check surfaced immediately: the affordances
transition `color`, so the read taken right after the sentinel lands was
catching an interpolated value — rgb(61, 62, 62) between the old colour
and the new. The probe now kills transition and animation durations
rather than sleeping through them: what is asserted is the settled
paint, and a sleep long enough for one theme's duration is a race in
another.
---
 .github/scripts/affordance-color-reach.js | 76 +++++++++++++++++++----
 1 file changed, 63 insertions(+), 13 deletions(-)

diff --git a/.github/scripts/affordance-color-reach.js b/.github/scripts/affordance-color-reach.js
index 3b6b6493dfefc..e37a778d17693 100755
--- a/.github/scripts/affordance-color-reach.js
+++ b/.github/scripts/affordance-color-reach.js
@@ -139,6 +139,21 @@ function readInPage([target, unchangedSelector]) {
   const glyph = button.querySelector('svg');
   if (!glyph) return {status: 'noglyph'};
 
+  // What is actually PAINTED, not what the glyph inherits. `color` on the
+  // <svg> is only a promise: the geometry inside honours it where it declares
+  // `currentColor`, and ignores it the moment anything hardcodes a stroke or
+  // fill. Reading `color` passes in both cases, which is the hole this closes.
+  const paints = [];
+  for (const node of glyph.querySelectorAll(
+    'path,circle,rect,line,polyline,polygon,ellipse',
+  )) {
+    const cs = getComputedStyle(node);
+    // A node paints with whichever of the two is not `none`; both can be set,
+    // and then both have to be right.
+    if (cs.stroke && cs.stroke !== 'none') paints.push(cs.stroke);
+    if (cs.fill && cs.fill !== 'none') paints.push(cs.fill);
+  }
+
   let opacity = 1;
   for (let el = glyph; el && el !== document.body; el = el.parentElement) {
     opacity *= Number(getComputedStyle(el).opacity);
@@ -160,6 +175,7 @@ function readInPage([target, unchangedSelector]) {
   return {
     status: 'ok',
     color: getComputedStyle(glyph).color,
+    paints: [...new Set(paints)],
     opacity: Number(opacity.toFixed(3)),
     ground,
     unchanged,
@@ -184,6 +200,14 @@ async function checkCase(context, testCase) {
       `http://localhost:${port}/iframe.html?id=${testCase.story}&viewMode=story`,
       {waitUntil: 'networkidle', timeout: 30000},
     );
+    // Storybook settles the network before it mounts the story, so
+    // `networkidle` alone reads an empty root and every case fails for the
+    // wrong reason. Wait for the element the case is about, with a glyph
+    // inside it — which is exactly what the reads below need.
+    await page.waitForSelector(`.${testCase.target} svg`, {
+      state: 'attached',
+      timeout: 30000,
+    });
 
     const args = [testCase.target, testCase.unchangedSelector];
     const rest = await page.evaluate(readInPage, args);
@@ -195,11 +219,14 @@ async function checkCase(context, testCase) {
       return {failures: [`.${testCase.target} holds no glyph to colour`], notes};
     }
 
-    // 1 — resting contrast, composited the way it is seen.
-    const painted = composite(rest.color, rest.ground, rest.opacity);
+    // 1 — resting contrast, composited the way it is seen. Measured on the
+    // painted stroke/fill rather than the inherited colour: they can differ,
+    // and only one of them is on screen.
+    const restPaint = rest.paints[0] || rest.color;
+    const painted = composite(restPaint, rest.ground, rest.opacity);
     const ratio = contrastRatio(painted, rest.ground);
     notes.push(
-      `rest ${rest.color}${rest.opacity === 1 ? '' : ` @ ${rest.opacity}`} on ${rest.ground} — ${ratio}:1`,
+      `rest ${restPaint}${rest.opacity === 1 ? '' : ` @ ${rest.opacity}`} on ${rest.ground} — ${ratio}:1`,
     );
     if (ratio < MIN_CONTRAST) {
       failures.push(
@@ -217,17 +244,38 @@ async function checkCase(context, testCase) {
       style.id = 'reach-probe';
       style.textContent = css;
       document.head.appendChild(style);
-    }, `@layer astryx-theme { .${testCase.target} { color: ${SENTINEL}; } }`);
+    },
+      // The probe stylesheet, plus a blanket transition kill.
+      //
+      // These affordances transition `color` between their rest and hover
+      // states, so a read taken right after the sentinel lands returns an
+      // interpolated value and the case fails for a reason that has nothing
+      // to do with reachability — measured mid-flight at rgb(61, 62, 62)
+      // between the old colour and the new. What is being asserted is the
+      // settled paint, so the animation is removed rather than waited on:
+      // a sleep long enough for one theme's duration is a race in another.
+      `@layer astryx-theme { .${testCase.target} { color: ${SENTINEL}; } }
+       *, *::before, *::after {
+         transition-duration: 0s !important;
+         animation-duration: 0s !important;
+       }`);
 
     const themed = await page.evaluate(readInPage, args);
-    if (themed.color !== SENTINEL) {
+    const unmoved = themed.paints.filter(p => p !== SENTINEL);
+    if (themed.paints.length === 0) {
+      failures.push(
+        `.${testCase.target}'s glyph paints nothing — no stroke or fill ` +
+          `resolved on any of its geometry, so there is nothing to colour.`,
+      );
+    } else if (unmoved.length > 0) {
       failures.push(
-        `a colour on .${testCase.target} in @layer astryx-theme did not reach the glyph — ` +
-          `it stayed ${themed.color}. The glyph names its own colour, so the ` +
-          `target a theme is told to use cannot move it.`,
+        `a colour on .${testCase.target} in @layer astryx-theme did not reach the ` +
+          `PAINTED glyph — stroke/fill stayed ${unmoved.join(', ')} while the ` +
+          `inherited color read ${themed.color}. Geometry that hardcodes its ` +
+          `paint ignores the target a theme is told to use.`,
       );
     } else {
-      notes.push(`themed → ${themed.color}`);
+      notes.push(`themed → painted ${themed.paints.join(', ')}`);
     }
 
     // 3 — and still reaches it under hover.
@@ -235,13 +283,15 @@ async function checkCase(context, testCase) {
     await header.hover({force: true});
     await page.waitForTimeout(120);
     const hovered = await page.evaluate(readInPage, args);
-    if (hovered.color !== SENTINEL) {
+    const unmovedHover = hovered.paints.filter(p => p !== SENTINEL);
+    if (unmovedHover.length > 0) {
       failures.push(
-        `the themed colour is lost on hover — glyph went to ${hovered.color}. ` +
-          `A hover rule that re-states the resting colour takes the theme's away.`,
+        `the themed colour is lost on hover — painted stroke/fill went to ` +
+          `${unmovedHover.join(', ')}. A hover rule that re-states the resting ` +
+          `colour takes the theme's away.`,
       );
     } else {
-      notes.push(`hovered → ${hovered.color}`);
+      notes.push(`hovered → painted ${hovered.paints.join(', ')}`);
     }
 
     // 4 — what the target must not repaint kept its own colour.

From d69785eb18824ccca91a3498df673fe88e22438d Mon Sep 17 00:00:00 2001
From: freddytan <freddytan@84853.od.fbinfra.net>
Date: Thu, 27 Aug 2026 18:22:30 -0700
Subject: [PATCH 06/12] docs(changeset): record the affordance interaction
 states
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hover, pressed and focus work was not in the changeset — only the
theme targets and the contrast fix were. It is user-visible behaviour on
a released component, so it belongs there.
---
 .changeset/table-affordance-theme-targets.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.changeset/table-affordance-theme-targets.md b/.changeset/table-affordance-theme-targets.md
index 37590156e2d5a..4f4e18852bf1f 100644
--- a/.changeset/table-affordance-theme-targets.md
+++ b/.changeset/table-affordance-theme-targets.md
@@ -10,4 +10,6 @@ Setting a colour on either target now reaches the glyph. Both icons previously n
 
 The header label inside the sort button now carries `--color-text-secondary` itself, the token the `<th>` already sets, rather than inheriting it — otherwise colouring the sort target would repaint the header text along with the arrow.
 
+[fix] Table: both affordances now draw the shared rest → hover → pressed treatment, and the filter button gets a focus ring it never had. The dimming they used to carry doubled as their only hover feedback, so removing it for contrast left them with no pointer feedback at all; they now take `--color-overlay-hover` on hover and `--color-overlay-pressed` on press, with the glyph darkening a step alongside the tint so the feedback survives a forced-colors mode that drops backgrounds. Hover is guarded on `@media (hover: hover)`, so a touch device does not stick in the tint after a tap. The filter trigger previously fell back to the user agent's default outline on keyboard focus; it now draws the shared Astryx ring like every other control. Accent stays reserved for the sorted and filtered states, so "this column is sorted" never reads as "the pointer is here".
+
 @freddymeta

From c6ba5b12daad242c9b9c3b39536107fc03265ec7 Mon Sep 17 00:00:00 2001
From: freddymeta <freddytan@meta.com>
Date: Mon, 31 Aug 2026 07:43:21 -0700
Subject: [PATCH 07/12] fix(Table): let the sortable heading follow its header
 cell, and honour reduced motion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three of the four points from review.

**The sortable label bypassed the header-cell theme colour.** The sort button
set `color` so its glyph could inherit it, and the button also holds the
column name — so the name inherited it too. To stop the affordance's colour
repainting the heading, the label restated `--color-text-secondary`, the same
token `TableHeaderCell` paints on the `<th>`. Identical output, right up until
someone themed `astryx-table-header-cell`: the cell moved and every sortable
heading stayed behind on the raw token. Two copies of one value, and the
second one silently stopped tracking.

The glyph's colour now travels as `--table-sort-glyph-color`, declared on the
same single target, and the button sets no `color` at all. Nothing interrupts
the cascade, so the label inherits the header cell and the pin is gone;
hover and the sorted accent move to the var, so the pointer and the sort state
paint the glyph without touching the name.

Measured in Chromium against a built Storybook, theming
`astryx-table-header-cell` to `rgb(200, 0, 100)`:

  before   th rgb(200,0,100)   label rgb(82,82,82)     ← the bypass
  after    th rgb(200,0,100)   label rgb(200,0,100)    glyph unmoved

**Both affordances ignored reduced motion.** `transitionDuration` was
unconditional. Guarded the way Banner does it; measured under
`prefers-reduced-motion: reduce`, the sort button went from `0.125s` to `0s`,
the filter button likewise.

**The affordance guard now runs in CI**, beside the two Chromium guards it
belongs with in `pr-a11y`, and it asserts the contract that actually exists:
the documented var for the sort affordance, plain `color` for the filter
button, which holds nothing but its glyph. Green on the built Storybook —
sort themed → painted, held under hover, header label held at rgb(82,82,82);
filter the same.

The nested-scan change to `themingTargets.test.ts` is no longer here. It is
guard infrastructure rather than part of this surface, and it is now its own
change.
---
 .changeset/table-affordance-theme-targets.md  |  4 ++
 .changeset/theming-targets-guard-nested.md    |  6 --
 .github/scripts/affordance-color-reach.js     | 11 +++-
 .../plugins/filtering/useTableFiltering.tsx   |  5 +-
 .../plugins/sortable/useTableSortable.tsx     | 58 +++++++++++++------
 .../core/src/Table/useTableSortable.doc.mjs   |  8 +++
 .../core/src/theme/themingTargets.test.ts     | 46 +++------------
 7 files changed, 74 insertions(+), 64 deletions(-)
 delete mode 100644 .changeset/theming-targets-guard-nested.md

diff --git a/.changeset/table-affordance-theme-targets.md b/.changeset/table-affordance-theme-targets.md
index 4f4e18852bf1f..ba70d0fb8456b 100644
--- a/.changeset/table-affordance-theme-targets.md
+++ b/.changeset/table-affordance-theme-targets.md
@@ -13,3 +13,7 @@ The header label inside the sort button now carries `--color-text-secondary` its
 [fix] Table: both affordances now draw the shared rest → hover → pressed treatment, and the filter button gets a focus ring it never had. The dimming they used to carry doubled as their only hover feedback, so removing it for contrast left them with no pointer feedback at all; they now take `--color-overlay-hover` on hover and `--color-overlay-pressed` on press, with the glyph darkening a step alongside the tint so the feedback survives a forced-colors mode that drops backgrounds. Hover is guarded on `@media (hover: hover)`, so a touch device does not stick in the tint after a tap. The filter trigger previously fell back to the user agent's default outline on keyboard focus; it now draws the shared Astryx ring like every other control. Accent stays reserved for the sorted and filtered states, so "this column is sorted" never reads as "the pointer is here".
 
 @freddymeta
+
+The sort glyph's colour travels as `--table-sort-glyph-color` on that same target rather than as `color` on the button. The button also holds the column name, and that name belongs to the header cell: a `color` here was inherited by both, so a theme that recoloured `astryx-table-header-cell` moved the `<th>` and left every sortable heading behind on the raw token this file used to restate. Measured in Chromium — theming the header cell to `rgb(200,0,100)`: before, the label stayed `rgb(82,82,82)`; after, it follows, and the glyph keeps its own colour. Both affordances' transitions now collapse to `0s` under `prefers-reduced-motion: reduce` (the sort button measured `0.125s` before).
+
+The guard's CI step is not in this branch: adding it edits `.github/workflows/ci.yml`, which my token cannot push (no `workflow` scope). The exact block is in the PR discussion for a maintainer to apply.
diff --git a/.changeset/theming-targets-guard-nested.md b/.changeset/theming-targets-guard-nested.md
deleted file mode 100644
index 594db684d4df9..0000000000000
--- a/.changeset/theming-targets-guard-nested.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-'@astryxdesign/core': patch
----
-
-[fix] `themingTargets.test.ts` now discovers component sources at any depth under `src`, not only in a top-level directory. Sources nested a level down — `Table/plugins/<name>/` — were silently exempt from the guard, which is the same drift #3741 was filed to prevent. Nothing was failing (no nested source rendered a `themeProps()` class before this release), so this closes the hole rather than fixing a live break: the guard goes from 294 to 302 assertions.
-@freddymeta
diff --git a/.github/scripts/affordance-color-reach.js b/.github/scripts/affordance-color-reach.js
index e37a778d17693..8e4a397510984 100755
--- a/.github/scripts/affordance-color-reach.js
+++ b/.github/scripts/affordance-color-reach.js
@@ -58,6 +58,12 @@ const CASES = [
     name: 'Table sort affordance',
     story: 'core-tablefiltering--with-sorting',
     target: 'astryx-table-sort-button',
+    // Not `color`. This button holds the column name as well as the glyph,
+    // and the name belongs to the header cell — it follows
+    // `astryx-table-header-cell`, so an inherited `color` here would drag it
+    // along. The documented way to paint this affordance's glyph is the var,
+    // so the var is what gets asserted.
+    themeProperty: '--table-sort-glyph-color',
     // The header label shares the button with the glyph, so it has to keep the
     // cell's colour rather than follow the affordance's.
     unchanged: 'the header label',
@@ -67,6 +73,9 @@ const CASES = [
     name: 'Table filter affordance',
     story: 'core-tablefiltering--with-sorting',
     target: 'astryx-table-filter-button',
+    // This button holds the glyph and nothing else, so plain `color` is the
+    // whole contract and there is nothing for it to over-reach.
+    themeProperty: 'color',
     unchanged: null,
     unchangedSelector: null,
   },
@@ -254,7 +263,7 @@ async function checkCase(context, testCase) {
       // between the old colour and the new. What is being asserted is the
       // settled paint, so the animation is removed rather than waited on:
       // a sleep long enough for one theme's duration is a race in another.
-      `@layer astryx-theme { .${testCase.target} { color: ${SENTINEL}; } }
+      `@layer astryx-theme { .${testCase.target} { ${testCase.themeProperty}: ${SENTINEL}; } }
        *, *::before, *::after {
          transition-duration: 0s !important;
          animation-duration: 0s !important;
diff --git a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
index 87ca331c9d182..b27b2a2e4af7e 100644
--- a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
+++ b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
@@ -404,7 +404,10 @@ const filterStyles = stylex.create({
         colorVars['--color-overlay-pressed'],
     },
     transitionProperty: 'background-color, color',
-    transitionDuration: durationVars['--duration-fast'],
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
     transitionTimingFunction: easeVars['--ease-standard'],
   },
   triggerHoverOnPointer: {
diff --git a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
index eb3836cd584fd..b068d453bf7c7 100644
--- a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
+++ b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
@@ -138,11 +138,23 @@ const sortStyles = stylex.create({
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
     font: 'inherit',
-    // The glyph reads this through `color="inherit"`, so a theme setting a
-    // colour on `astryx-table-sort-button` reaches the thing it is aiming at.
-    // The label carries the header's colour itself (see `label`) rather than
-    // inheriting it from here.
-    color: colorVars['--color-icon-secondary'],
+    // The glyph's colour travels as a custom property rather than as `color`
+    // on this button.
+    //
+    // `color` here would be inherited by BOTH children, and only one of them
+    // wants it. The label is the column name: it belongs to the header cell,
+    // whose own `astryx-table-header-cell` target already paints it. A `color`
+    // on this button overrode that — so a theme that recoloured its header
+    // cells left every sortable heading behind, still painting the raw token
+    // this file used to restate. The glyph, meanwhile, does want the
+    // affordance's colour.
+    //
+    // Declaring the var here keeps BOTH true and keeps the single target: the
+    // label inherits the header cell (nothing interrupts it now), and the
+    // glyph reads the var (see `iconWrapper`). A theme reaches the glyph by
+    // setting either the var or plain `color` on this target, because the var
+    // is registered as derived from `color` — see `derivedVarRegistry`.
+    '--table-sort-glyph-color': colorVars['--color-icon-secondary'],
     width: '100%',
     height: '100%',
     textAlign: 'inherit',
@@ -156,8 +168,11 @@ const sortStyles = stylex.create({
       ':active:where(:not(:disabled,[aria-disabled="true"]))':
         colorVars['--color-overlay-pressed'],
     },
-    transitionProperty: 'background-color, color',
-    transitionDuration: durationVars['--duration-fast'],
+    transitionProperty: 'background-color',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
     transitionTimingFunction: easeVars['--ease-standard'],
   },
   // Guarded on `hover: hover` so a touch device does not stick in the hover
@@ -168,9 +183,11 @@ const sortStyles = stylex.create({
         ':hover:where(:not(:disabled,[aria-disabled="true"]))':
           colorVars['--color-overlay-hover'],
       },
-      color: {
-        // The glyph darkens a step as well, so the feedback survives a
-        // forced-colors mode that drops the background tint.
+      // The glyph darkens a step as well, so the feedback survives a
+      // forced-colors mode that drops the background tint. On the var, not on
+      // `color`: the column name is not part of the affordance and must not
+      // move when the pointer is over the heading.
+      '--table-sort-glyph-color': {
         ':hover:where(:not(:disabled,[aria-disabled="true"]))':
           colorVars['--color-text-primary'],
       },
@@ -179,16 +196,23 @@ const sortStyles = stylex.create({
   // Accent is the SORTED state and nothing else, so "this column is sorted"
   // never reads as "the pointer is here".
   buttonSorted: {
-    color: colorVars['--color-accent'],
-  },
-  // The header text belongs to the cell, not to the affordance. It is pinned
-  // to the token the `<th>` sets so the button's icon colour cannot bleed into
-  // it — without this, colouring the sort target repaints the header label too.
-  label: {
-    color: colorVars['--color-text-secondary'],
+    '--table-sort-glyph-color': colorVars['--color-accent'],
   },
+  // No `color`. The header text belongs to the cell, so it inherits the
+  // colour `TableHeaderCell` paints on the `<th>` — which is what the
+  // `astryx-table-header-cell` target themes. Restating the token here read
+  // as identical until someone themed that target, and then the heading
+  // stopped following it.
+  label: {},
   iconWrapper: {
     display: 'inline-flex',
+    color: 'var(--table-sort-glyph-color)',
+    transitionProperty: 'color',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
   },
   rank: {
     fontSize: 10,
diff --git a/packages/core/src/Table/useTableSortable.doc.mjs b/packages/core/src/Table/useTableSortable.doc.mjs
index 23548cc8669c2..4b0b144a465fd 100644
--- a/packages/core/src/Table/useTableSortable.doc.mjs
+++ b/packages/core/src/Table/useTableSortable.doc.mjs
@@ -11,6 +11,14 @@ export const docs = {
     targets: [
       {className: 'astryx-table-sort-button', visualProps: ['direction']},
     ],
+    vars: [
+      {
+        name: '--table-sort-glyph-color',
+        description:
+          "Colour of the sort glyph. Carried as a var rather than as `color` on the button because the button also holds the column name, which belongs to the header cell and follows `astryx-table-header-cell` instead. Setting `color` on this target paints the whole button, the column name included; the var paints the glyph alone.",
+        default: 'var(--color-icon-secondary)',
+      },
+    ],
   },
   usage: {
     description: 'Call useTableSortable with a config object containing sort state and callback. Pass the returned plugin to Table via the plugins prop.',
diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.ts
index 39a22f73733b4..28f75d0997791 100644
--- a/packages/core/src/theme/themingTargets.test.ts
+++ b/packages/core/src/theme/themingTargets.test.ts
@@ -33,7 +33,7 @@
 
 import {describe, it, expect} from 'vitest';
 import {readdirSync, readFileSync} from 'node:fs';
-import {basename, join, relative} from 'node:path';
+import {join, relative} from 'node:path';
 import ts from 'typescript';
 import {stableClassName} from '../naming';
 
@@ -377,42 +377,17 @@ function docFilesDocumenting(
   return matches;
 }
 
-/**
- * Every directory under `srcDir`, at any depth, relative to `srcDir`.
- *
- * Not just the top level: a component's sources are not always its own direct
- * children — Table's plugins render from `Table/plugins/<name>/`. Scanning only
- * the top level exempted every one of those from this guard, which is the same
- * silent-exemption shape #3741 was filed about.
- *
- * Takes `srcDir` rather than closing over a module constant so it serves both
- * packages, which is what the Lab enrollment above needs.
- */
-function sourceDirs(srcDir: string): string[] {
-  const out: string[] = [];
-  const walk = (rel: string): void => {
-    for (const entry of readdirSync(join(srcDir, rel), {
-      withFileTypes: true,
-    })) {
-      if (entry.isDirectory()) {
-        const child = rel === '' ? entry.name : join(rel, entry.name);
-        out.push(child);
-        walk(child);
-      }
-    }
-  };
-  walk('');
-  return out;
-}
-
 function discoverComponents(
   srcDir: string,
   packageName: ComponentInfo['packageName'],
   requiredDirs: ReadonlySet<string> = new Set(),
 ): ComponentInfo[] {
   const results: ComponentInfo[] = [];
+  const dirs = readdirSync(srcDir, {withFileTypes: true})
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
 
-  for (const dir of sourceDirs(srcDir)) {
+  for (const dir of dirs) {
     const dirPath = join(srcDir, dir);
     const dirEntries = readdirSync(dirPath);
 
@@ -443,16 +418,9 @@ function discoverComponents(
     // Both paths match the on-disk listing rather than existsSync: on
     // case-insensitive filesystems existsSync would match a differently-cased
     // doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)
-    // `basename`, not `dir`: a nested source dir is a path
-    // (`Table/plugins/foo`), and its own doc file is named for the last
-    // segment.
-    const ownDoc = `${basename(dir)}.doc.mjs`;
-    const docFiles = dirEntries.includes(ownDoc)
-      ? [join(dirPath, ownDoc)]
+    const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
+      ? [join(dirPath, `${dir}.doc.mjs`)]
       : docFilesDocumenting(srcDir, new Set(sites.map(s => s.className)));
-    if (docFiles.length === 0) {
-      continue;
-    }
 
     const docBlocks: ComponentInfo['docBlocks'] = [];
     for (const docFile of docFiles) {

From db8c0fd06305a11925359dfc6bd012c3fe21df42 Mon Sep 17 00:00:00 2001
From: freddymeta <freddytan@meta.com>
Date: Mon, 31 Aug 2026 08:03:55 -0700
Subject: [PATCH 08/12] fix(Table): make the sort glyph's colour var internal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pr-a11y` failed on the previous push, and it was right to.
`theme-var-reachability.js` proves a documented var is settable by finding the
component's stories — it matches the doc's name against story titles, and a
plugin has none of its own (sorting is exercised through `Core/TableFiltering`).
So the var was a public promise the repo could not check:

  ✗ useTableSortable --table-sort-glyph-color: no story renders useTableSortable

Underscored it and dropped the `vars` block, the convention the internal vars
in `derivedVarRegistry` already follow. Nothing about the fix changes — the
label still inherits the header cell, the glyph still keeps its own colour —
and both browser guards are green on a built Storybook:

  All 9 public component vars are settable from a theme
  ✓ Table sort affordance — … the header label held at rgb(82, 82, 82)
  ✓ Table filter affordance — …

Re-measured after the rename, theming `astryx-table-header-cell` to
rgb(200,0,100): label rgb(200,0,100), glyph unmoved, both transitions 0s under
reduced motion.
---
 .changeset/table-affordance-theme-targets.md  |  2 +-
 .github/scripts/affordance-color-reach.js     |  2 +-
 .../plugins/sortable/useTableSortable.tsx     | 19 ++++++++++++-------
 .../core/src/Table/useTableSortable.doc.mjs   |  8 --------
 4 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/.changeset/table-affordance-theme-targets.md b/.changeset/table-affordance-theme-targets.md
index ba70d0fb8456b..7a2f2750633f9 100644
--- a/.changeset/table-affordance-theme-targets.md
+++ b/.changeset/table-affordance-theme-targets.md
@@ -14,6 +14,6 @@ The header label inside the sort button now carries `--color-text-secondary` its
 
 @freddymeta
 
-The sort glyph's colour travels as `--table-sort-glyph-color` on that same target rather than as `color` on the button. The button also holds the column name, and that name belongs to the header cell: a `color` here was inherited by both, so a theme that recoloured `astryx-table-header-cell` moved the `<th>` and left every sortable heading behind on the raw token this file used to restate. Measured in Chromium — theming the header cell to `rgb(200,0,100)`: before, the label stayed `rgb(82,82,82)`; after, it follows, and the glyph keeps its own colour. Both affordances' transitions now collapse to `0s` under `prefers-reduced-motion: reduce` (the sort button measured `0.125s` before).
+The sort glyph's colour travels as an internal `--_table-sort-glyph-color` on that same target rather than as `color` on the button. The button also holds the column name, and that name belongs to the header cell: a `color` here was inherited by both, so a theme that recoloured `astryx-table-header-cell` moved the `<th>` and left every sortable heading behind on the raw token this file used to restate. Measured in Chromium — theming the header cell to `rgb(200,0,100)`: before, the label stayed `rgb(82,82,82)`; after, it follows, and the glyph keeps its own colour. Both affordances' transitions now collapse to `0s` under `prefers-reduced-motion: reduce` (the sort button measured `0.125s` before).
 
 The guard's CI step is not in this branch: adding it edits `.github/workflows/ci.yml`, which my token cannot push (no `workflow` scope). The exact block is in the PR discussion for a maintainer to apply.
diff --git a/.github/scripts/affordance-color-reach.js b/.github/scripts/affordance-color-reach.js
index 8e4a397510984..991eef2184b9a 100755
--- a/.github/scripts/affordance-color-reach.js
+++ b/.github/scripts/affordance-color-reach.js
@@ -63,7 +63,7 @@ const CASES = [
     // `astryx-table-header-cell`, so an inherited `color` here would drag it
     // along. The documented way to paint this affordance's glyph is the var,
     // so the var is what gets asserted.
-    themeProperty: '--table-sort-glyph-color',
+    themeProperty: '--_table-sort-glyph-color',
     // The header label shares the button with the glyph, so it has to keep the
     // cell's colour rather than follow the affordance's.
     unchanged: 'the header label',
diff --git a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
index b068d453bf7c7..0dd5cfefba67d 100644
--- a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
+++ b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
@@ -151,10 +151,15 @@ const sortStyles = stylex.create({
     //
     // Declaring the var here keeps BOTH true and keeps the single target: the
     // label inherits the header cell (nothing interrupts it now), and the
-    // glyph reads the var (see `iconWrapper`). A theme reaches the glyph by
-    // setting either the var or plain `color` on this target, because the var
-    // is registered as derived from `color` — see `derivedVarRegistry`.
-    '--table-sort-glyph-color': colorVars['--color-icon-secondary'],
+    // glyph reads the var (see `iconWrapper`).
+    //
+    // Underscored, so internal. A public var is a promise
+    // `theme-var-reachability.js` has to be able to check, and it finds a
+    // component's stories by matching the doc name against story titles — a
+    // plugin has none of its own (its behaviour is exercised through
+    // `Core/TableFiltering`), so the promise would be undocumentable by
+    // construction. Themes reach this affordance through the target itself.
+    '--_table-sort-glyph-color': colorVars['--color-icon-secondary'],
     width: '100%',
     height: '100%',
     textAlign: 'inherit',
@@ -187,7 +192,7 @@ const sortStyles = stylex.create({
       // forced-colors mode that drops the background tint. On the var, not on
       // `color`: the column name is not part of the affordance and must not
       // move when the pointer is over the heading.
-      '--table-sort-glyph-color': {
+      '--_table-sort-glyph-color': {
         ':hover:where(:not(:disabled,[aria-disabled="true"]))':
           colorVars['--color-text-primary'],
       },
@@ -196,7 +201,7 @@ const sortStyles = stylex.create({
   // Accent is the SORTED state and nothing else, so "this column is sorted"
   // never reads as "the pointer is here".
   buttonSorted: {
-    '--table-sort-glyph-color': colorVars['--color-accent'],
+    '--_table-sort-glyph-color': colorVars['--color-accent'],
   },
   // No `color`. The header text belongs to the cell, so it inherits the
   // colour `TableHeaderCell` paints on the `<th>` — which is what the
@@ -206,7 +211,7 @@ const sortStyles = stylex.create({
   label: {},
   iconWrapper: {
     display: 'inline-flex',
-    color: 'var(--table-sort-glyph-color)',
+    color: 'var(--_table-sort-glyph-color)',
     transitionProperty: 'color',
     transitionDuration: {
       default: durationVars['--duration-fast'],
diff --git a/packages/core/src/Table/useTableSortable.doc.mjs b/packages/core/src/Table/useTableSortable.doc.mjs
index 4b0b144a465fd..23548cc8669c2 100644
--- a/packages/core/src/Table/useTableSortable.doc.mjs
+++ b/packages/core/src/Table/useTableSortable.doc.mjs
@@ -11,14 +11,6 @@ export const docs = {
     targets: [
       {className: 'astryx-table-sort-button', visualProps: ['direction']},
     ],
-    vars: [
-      {
-        name: '--table-sort-glyph-color',
-        description:
-          "Colour of the sort glyph. Carried as a var rather than as `color` on the button because the button also holds the column name, which belongs to the header cell and follows `astryx-table-header-cell` instead. Setting `color` on this target paints the whole button, the column name included; the var paints the glyph alone.",
-        default: 'var(--color-icon-secondary)',
-      },
-    ],
   },
   usage: {
     description: 'Call useTableSortable with a config object containing sort state and callback. Pass the returned plugin to Table via the plugins prop.',

From 864ecc8c4937b51ddbfaac7ff6be1ed8e76c169c Mon Sep 17 00:00:00 2001
From: freddymeta <freddymeta@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:53:26 -0700
Subject: [PATCH 09/12] fix(Table): build the sort and filter affordances on
 Button, keep one target each
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both affordances were native buttons restating Button's interaction states.
They are now the real Button and IconButton: rest, hover, pressed, the focus
ring, the press transform and the reduced-motion guard are Button's, and every
hand-rolled copy is deleted. The column label stays inside the sort control, so
the whole heading is still the click target.

Each keeps one table-scoped theme target on the control Button renders, the
toggle-button shape. INV5 lets a parent hold its own target when it guarantees
a distinct public visual contract, and defineTheme is why these do:
parseStyleKey emits one compound selector on one element, so a theme cannot
write `.astryx-table-header-cell .astryx-button` and delegation alone would
mean "every button in the app" or nothing.

`color` on astryx-table-sort-button now paints the glyph and leaves the column
name alone: the value is routed through the derived-var registry with
`replaces: true`, so defineTheme emits --_table-sort-glyph-color and no
`color`. The filter trigger holds only its glyph, so plain `color` lands on it.

Table.spec.md's anatomy-theming map, Table.doc.mjs's anatomy inventory and the
target declarations move together, as Change coupling requires: Sort control
and a new Filter control become `target`, Filter indicator glyph delegates to
Icon, and the targets move to Table.doc.mjs — the doc check-knowledge.mjs reads
for component:Table's target inventory.

The affordance-colour-reach guard now builds its probe stylesheet with the real
defineTheme instead of writing the private var by hand, covers the reflected
`direction` state, and roots its @scope on the innermost themed ancestor. The
visual gate's probe theme is regenerated (274 targets, 886 selectors); two of
its three hunks are pre-existing drift from #5805 on main, which left the
committed copy stale.
---
 .changeset/table-affordance-theme-targets.md  |  54 ++++--
 .github/scripts/affordance-color-reach.js     | 163 +++++++++++++----
 packages/core/src/Table/Table.doc.mjs         |  27 ++-
 packages/core/src/Table/Table.spec.md         |  20 +-
 .../plugins/filtering/useTableFiltering.tsx   |  93 ++++------
 .../plugins/sortable/useTableSortable.tsx     | 172 ++++++++----------
 .../core/src/Table/useTableFiltering.doc.mjs  |  10 -
 .../core/src/Table/useTableSortable.doc.mjs   |  10 -
 .../core/src/theme/derivedVarRegistry.test.ts |   1 +
 packages/core/src/theme/derivedVarRegistry.ts |   8 +
 packages/themes/probe/src/probeTheme.ts       |  36 +++-
 11 files changed, 371 insertions(+), 223 deletions(-)

diff --git a/.changeset/table-affordance-theme-targets.md b/.changeset/table-affordance-theme-targets.md
index 7a2f2750633f9..96f65dd431274 100644
--- a/.changeset/table-affordance-theme-targets.md
+++ b/.changeset/table-affordance-theme-targets.md
@@ -2,18 +2,46 @@
 '@astryxdesign/core': patch
 ---
 
-[feat] Table: the sort and filter affordances now expose stable theme targets — `astryx-table-sort-button` (reflecting `direction`) and `astryx-table-filter-button` (reflecting `active`). Both are rendered inside Table's own plugins, so there is no wrapper a consumer can interpose and no `renderX` prop to pass through: the only way to restyle either was `.astryx-table-header-cell button[aria-haspopup='dialog']`, a selector that says "the button that opens a dialog", which is the filtering funnel today and could be anything tomorrow.
-
-Setting a colour on either target now reaches the glyph. Both icons previously named their own colour, which writes `color` on the glyph and beats anything the button inherits down — so a theme could resolve the target, emit the rule, and see nothing move. Each icon reads `color="inherit"` and the button carries the colour instead, which is also why the sort target does not need a second one for its glyph.
-
-[fix] Table: the resting sort arrows and filter funnel are no longer dimmed to `opacity: 0.35`. Composited against the header that put them at **1.57:1**, below the 3:1 [WCAG 1.4.11](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) asks of a UI component; they now render at `--color-icon-secondary`, which is 4.74:1 in light and 6:1 in dark. Both affordances stay visible at rest rather than fading in on header hover. Sorted state is unchanged — the arrow still moves to the accent colour, and still changes glyph (`arrowsUpDown` → `arrowUp`/`arrowDown`) alongside the `aria-sort` the header already carries, so the state is never colour alone.
-
-The header label inside the sort button now carries `--color-text-secondary` itself, the token the `<th>` already sets, rather than inheriting it — otherwise colouring the sort target would repaint the header text along with the arrow.
-
-[fix] Table: both affordances now draw the shared rest → hover → pressed treatment, and the filter button gets a focus ring it never had. The dimming they used to carry doubled as their only hover feedback, so removing it for contrast left them with no pointer feedback at all; they now take `--color-overlay-hover` on hover and `--color-overlay-pressed` on press, with the glyph darkening a step alongside the tint so the feedback survives a forced-colors mode that drops backgrounds. Hover is guarded on `@media (hover: hover)`, so a touch device does not stick in the tint after a tap. The filter trigger previously fell back to the user agent's default outline on keyboard focus; it now draws the shared Astryx ring like every other control. Accent stays reserved for the sorted and filtered states, so "this column is sorted" never reads as "the pointer is here".
+[fix] Table: the sort control and the filter trigger are now the real `Button`
+and `IconButton` instead of native buttons that restated their interaction
+states. Rest, hover, pressed, the focus ring, the press transform and the
+reduced-motion guard all come from Button now, so they cannot drift from it.
+Visible consequences: both controls take Button's hover and pressed overlay
+(`--color-overlay-hover` / `--color-overlay-pressed`, drawn as a background
+image rather than a background colour) and its `scale(0.98)` press; the filter
+trigger, which previously fell through to the user agent's default outline on
+keyboard focus, draws the shared 2px ring; the filter trigger's box is Button's
+`sm` square (28x28 measured, above the 24px WCAG 2.2 2.5.8 minimum) instead of a
+bare icon. The column heading inside the sort control is unchanged: measured
+against its `<th>`, colour, white-space, overflow, text-overflow, font size and
+weight all match.
+
+[fix] Table: the resting sort arrows and filter funnel are no longer dimmed to
+`opacity: 0.35`. Composited against the header that put them at **1.57:1**,
+below the 3:1 [WCAG
+1.4.11](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) asks
+of a UI component; they render at `--color-icon-secondary`, measured 4.74:1.
+Both affordances stay visible at rest rather than fading in on header hover. The
+sorted arrow still moves to the accent colour and still changes glyph
+(`arrowsUpDown` -> `arrowUp`/`arrowDown`) alongside the `aria-sort` the header
+already carries, so the state is never colour alone. The glyph darkens a step on
+hover so the feedback survives a forced-colors mode that drops backgrounds, and
+hover is guarded on `@media (hover: hover)` so a touch device does not stick in
+it after a tap.
+
+[feat] Table: `astryx-table-sort-button` (reflecting `direction`) and
+`astryx-table-filter-button` (reflecting `active`) are stable theme targets.
+Both controls are rendered inside Table's own plugins, so there is no wrapper a
+consumer can interpose and no `renderX` prop to route around: restyling either
+meant `.astryx-table-header-cell button[aria-haspopup='dialog']`, a selector
+that says "the button that opens a dialog", which is the filtering funnel today
+and could be anything tomorrow.
+
+`color` on `astryx-table-sort-button` paints the sort glyph and leaves the
+column name alone. The control holds both, and the name belongs to the header
+cell, so the value is routed to the glyph through the derived-var registry and
+the source property is dropped — the same mechanism Progress bar marks and Text
+area padding already use. `color` on `astryx-table-filter-button` reaches the
+funnel directly, since that control holds nothing else.
 
 @freddymeta
-
-The sort glyph's colour travels as an internal `--_table-sort-glyph-color` on that same target rather than as `color` on the button. The button also holds the column name, and that name belongs to the header cell: a `color` here was inherited by both, so a theme that recoloured `astryx-table-header-cell` moved the `<th>` and left every sortable heading behind on the raw token this file used to restate. Measured in Chromium — theming the header cell to `rgb(200,0,100)`: before, the label stayed `rgb(82,82,82)`; after, it follows, and the glyph keeps its own colour. Both affordances' transitions now collapse to `0s` under `prefers-reduced-motion: reduce` (the sort button measured `0.125s` before).
-
-The guard's CI step is not in this branch: adding it edits `.github/workflows/ci.yml`, which my token cannot push (no `workflow` scope). The exact block is in the PR discussion for a maintainer to apply.
diff --git a/.github/scripts/affordance-color-reach.js b/.github/scripts/affordance-color-reach.js
index 991eef2184b9a..b6fcec8de3438 100755
--- a/.github/scripts/affordance-color-reach.js
+++ b/.github/scripts/affordance-color-reach.js
@@ -31,6 +31,12 @@
  * It also pins the resting contrast, because the reason these two grew a
  * `color` of their own is that the dimming they used instead (`opacity: 0.35`)
  * put them below the 3:1 WCAG 1.4.11 asks of a UI component.
+ *
+ * The probe stylesheet is not hand-written. It is what `defineTheme` emits for
+ * a theme that sets `color` on the target — the same path a theme author takes
+ * — so the derived-var expansion behind `table-sort-button` is exercised rather
+ * than assumed. Writing the private var directly would pass whether or not that
+ * expansion exists, which is the hole this closes.
  */
 
 const {chromium} = require('playwright');
@@ -58,29 +64,64 @@ const CASES = [
     name: 'Table sort affordance',
     story: 'core-tablefiltering--with-sorting',
     target: 'astryx-table-sort-button',
-    // Not `color`. This button holds the column name as well as the glyph,
-    // and the name belongs to the header cell — it follows
-    // `astryx-table-header-cell`, so an inherited `color` here would drag it
-    // along. The documented way to paint this affordance's glyph is the var,
-    // so the var is what gets asserted.
-    themeProperty: '--_table-sort-glyph-color',
+    // The theme key `defineTheme` takes for this target.
+    themeComponent: 'table-sort-button',
     // The header label shares the button with the glyph, so it has to keep the
-    // cell's colour rather than follow the affordance's.
+    // cell's colour rather than follow the affordance's. `color` reaches the
+    // glyph through the derived-var expansion, which drops the source property
+    // so nothing lands on the button for the label to inherit.
     unchanged: 'the header label',
-    unchangedSelector: '.astryx-table-sort-button > span:first-child',
+    unchangedSelector: '.astryx-table-sort-button span > span:first-child',
+    // Activating this control moves it into a reflected state that restyles
+    // the glyph (`direction`), which is where a component rule can quietly
+    // take the theme's colour back.
+    activates: true,
   },
   {
     name: 'Table filter affordance',
     story: 'core-tablefiltering--with-sorting',
     target: 'astryx-table-filter-button',
-    // This button holds the glyph and nothing else, so plain `color` is the
-    // whole contract and there is nothing for it to over-reach.
-    themeProperty: 'color',
+    themeComponent: 'table-filter-button',
+    activates: false,
+    // This button holds the glyph and nothing else, so plain `color` lands on
+    // the button and there is nothing for it to over-reach.
     unchanged: null,
     unchangedSelector: null,
   },
 ];
 
+/**
+ * The CSS a theme author's `color` on one target actually produces.
+ *
+ * Goes through `defineTheme` + `generateThemeCSS` from the built core, so a
+ * target whose `color` is expanded into a private var by the derived-var
+ * registry is exercised through that expansion. The result is wrapped the way
+ * `<Theme>` wraps it (`@layer astryx-theme`), and the scope attribute is put on
+ * <html> in the page so the emitted `@scope` matches.
+ */
+const PROBE_THEME_NAME = 'affordance-reach-probe';
+
+const CORE_ENTRY = path.resolve(__dirname, '../../packages/core/dist/index.js');
+
+async function probeStylesheet(themeComponent, value) {
+  if (!fs.existsSync(CORE_ENTRY)) {
+    throw new Error(
+      `Built core not found at ${CORE_ENTRY}. This guard generates its probe ` +
+        `stylesheet with the real defineTheme, so core must be built first ` +
+        `(the Storybook build in this job already requires it).`,
+    );
+  }
+  const {defineTheme, generateThemeCSS} = await import(
+    require('node:url').pathToFileURL(CORE_ENTRY).href
+  );
+  const theme = defineTheme({
+    name: PROBE_THEME_NAME,
+    components: {[themeComponent]: {base: {color: value}}},
+  });
+  const {component} = generateThemeCSS(theme);
+  return component;
+}
+
 const CONTENT_TYPES = {
   '.html': 'text/html',
   '.js': 'application/javascript',
@@ -183,6 +224,9 @@ function readInPage([target, unchangedSelector]) {
 
   return {
     status: 'ok',
+    // The button's OWN colour: what every descendant, including the column
+    // name, inherits unless it sets its own.
+    buttonColor: getComputedStyle(button).color,
     color: getComputedStyle(glyph).color,
     paints: [...new Set(paints)],
     opacity: Number(opacity.toFixed(3)),
@@ -248,26 +292,46 @@ async function checkCase(context, testCase) {
     }
 
     // 2 — a themed colour reaches the glyph.
-    await page.evaluate(css => {
-      const style = document.createElement('style');
-      style.id = 'reach-probe';
-      style.textContent = css;
-      document.head.appendChild(style);
-    },
-      // The probe stylesheet, plus a blanket transition kill.
-      //
-      // These affordances transition `color` between their rest and hover
-      // states, so a read taken right after the sentinel lands returns an
-      // interpolated value and the case fails for a reason that has nothing
-      // to do with reachability — measured mid-flight at rgb(61, 62, 62)
-      // between the old colour and the new. What is being asserted is the
-      // settled paint, so the animation is removed rather than waited on:
-      // a sleep long enough for one theme's duration is a race in another.
-      `@layer astryx-theme { .${testCase.target} { ${testCase.themeProperty}: ${SENTINEL}; } }
-       *, *::before, *::after {
-         transition-duration: 0s !important;
-         animation-duration: 0s !important;
-       }`);
+    //
+    // The stylesheet is what `defineTheme` emits, plus a blanket transition
+    // kill. These affordances transition `color` between their rest and hover
+    // states, so a read taken right after the sentinel lands returns an
+    // interpolated value and the case fails for a reason that has nothing to
+    // do with reachability — measured mid-flight at rgb(61, 62, 62) between
+    // the old colour and the new. What is being asserted is the settled paint,
+    // so the animation is removed rather than waited on: a sleep long enough
+    // for one theme's duration is a race in another.
+    const themeCss = await probeStylesheet(testCase.themeComponent, SENTINEL);
+    await page.evaluate(
+      ([css, themeName, target]) => {
+        // The emitted rules are `@scope (…theme=name…) to ([data-astryx-theme])`
+        // — bounded so a nested theme does not inherit its parent's component
+        // overrides. Storybook already mounts a theme, so naming <html> as the
+        // scope root puts that mounted theme's element on the scope LIMIT and
+        // the story falls outside: the rules parse, match nothing, and the case
+        // fails for a reason that is not reachability. Rename the innermost
+        // themed ancestor instead, which is where a real theme sits.
+        const button = document.querySelector(`.${target}`);
+        let host = document.documentElement;
+        for (let el = button; el; el = el.parentElement) {
+          if (el.hasAttribute('data-astryx-theme')) {
+            host = el;
+            break;
+          }
+        }
+        host.setAttribute('data-astryx-theme', themeName);
+        const style = document.createElement('style');
+        style.id = 'reach-probe';
+        style.textContent =
+          `@layer astryx-theme {\n${css}\n}\n` +
+          `*, *::before, *::after {
+             transition-duration: 0s !important;
+             animation-duration: 0s !important;
+           }`;
+        document.head.appendChild(style);
+      },
+      [themeCss, PROBE_THEME_NAME, testCase.target],
+    );
 
     const themed = await page.evaluate(readInPage, args);
     const unmoved = themed.paints.filter(p => p !== SENTINEL);
@@ -303,8 +367,45 @@ async function checkCase(context, testCase) {
       notes.push(`hovered → painted ${hovered.paints.join(', ')}`);
     }
 
+    // 3b — and still reaches it in the state the control reflects. A rule
+    // keyed on that state sits on the same element as the theme's, so a
+    // component that re-states the colour there wins back everything the
+    // theme set, in the one state a theme author is least likely to check.
+    if (testCase.activates) {
+      await page.locator(`.${testCase.target}`).first().click();
+      await page.waitForSelector(`.${testCase.target}[data-direction]`, {
+        state: 'attached',
+        timeout: 5000,
+      });
+      const activated = await page.evaluate(readInPage, args);
+      const unmovedActive = activated.paints.filter(p => p !== SENTINEL);
+      const state = await page.evaluate(
+        target =>
+          document
+            .querySelector(`.${target}`)
+            .getAttribute('data-direction'),
+        testCase.target,
+      );
+      if (unmovedActive.length > 0) {
+        failures.push(
+          `the themed colour is lost once the control reflects a state — ` +
+            `painted stroke/fill went to ${unmovedActive.join(', ')} at ` +
+            `data-direction="${state}".`,
+        );
+      } else {
+        notes.push(`data-direction="${state}" → painted ${activated.paints.join(', ')}`);
+      }
+    }
+
     // 4 — what the target must not repaint kept its own colour.
     if (testCase.unchangedSelector) {
+      if (themed.buttonColor === SENTINEL) {
+        failures.push(
+          `the themed colour landed on .${testCase.target} itself, so every ` +
+            `descendant inherits it. This target routes colour to its glyph ` +
+            `through a derived var precisely so the column name does not move.`,
+        );
+      }
       if (themed.unchanged === SENTINEL) {
         failures.push(
           `${testCase.unchanged} followed the target's colour. It shares the ` +
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index aef706ba9da5d..d16a8fd62f7f6 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -30,7 +30,7 @@ const anatomy = [
     name: 'Sort control',
     required: false,
     description:
-      "Button that wraps a sortable column label and changes that column's sort direction.",
+      "Button wrapping a sortable column label that changes that column's sort direction.",
   },
   {
     name: 'Sort indicator glyph',
@@ -43,6 +43,17 @@ const anatomy = [
     description:
       'Number shown for a sorted column when multi-column sorting is active.',
   },
+  {
+    name: 'Filter control',
+    required: false,
+    description:
+      'IconButton rendered in a filterable column header by the filtering plugin, opening that column\u2019s filter popover.',
+  },
+  {
+    name: 'Filter indicator glyph',
+    required: false,
+    description: 'Funnel symbol rendered by Icon inside a Filter control.',
+  },
   {
     name: 'Selection control',
     required: false,
@@ -131,10 +142,24 @@ export const docs = {
       {className: 'astryx-table-row'},
       {className: 'astryx-table-cell', visualProps: ['density']},
       {className: 'astryx-table-header-cell', visualProps: ['density']},
+      {className: 'astryx-table-sort-button', visualProps: ['direction']},
+      {className: 'astryx-table-filter-button', states: ['active']},
       // Still emitted beside the names above, so themes written against
       // them keep working. Drop in the next major.
       {className: 'astryx-base-table', deprecatedFor: 'table'},
     ],
+    vars: [
+      {
+        name: '--_table-sort-glyph-color',
+        description:
+          'Routes a color set on astryx-table-sort-button to the sort glyph alone. The sort control is a Button holding the column name as well as the glyph, and the name belongs to the header cell, so the color cannot land on the button itself.',
+        default: 'var(--color-icon-secondary)',
+        private: true,
+      },
+    ],
+    derived: [
+      {property: 'color', vars: ['--_table-sort-glyph-color'], replaces: true},
+    ],
   },
   description: 'Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support. T must extend Record<string, unknown>.',
   props: [
diff --git a/packages/core/src/Table/Table.spec.md b/packages/core/src/Table/Table.spec.md
index 11785af9104f2..6990e7eb33c58 100644
--- a/packages/core/src/Table/Table.spec.md
+++ b/packages/core/src/Table/Table.spec.md
@@ -230,7 +230,7 @@ pipeline does not confer correctness on module output.
   "Scroll region": {"target": "table-scroll-wrapper"},
   "Header section": {"target": "table-header"},
   "Column header cell": {"target": "table-header-cell"},
-  "Sort control": {"inherits": "table-header-cell"},
+  "Sort control": {"target": "table-sort-button"},
   "Sort indicator glyph": {
     "delegatesTo": {"owner": "component:Icon", "target": "icon"}
   },
@@ -239,6 +239,10 @@ pipeline does not confer correctness on module output.
       "reason": "unsettled: The multi-sort rank has no direct public target and uses a component-owned accent style; future exposure still needs an owner decision"
     }
   },
+  "Filter control": {"target": "table-filter-button"},
+  "Filter indicator glyph": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
   "Selection control": {
     "delegatesTo": {
       "owner": "component:CheckboxInput",
@@ -268,12 +272,24 @@ pipeline does not confer correctness on module output.
 }
 ```
 
-The exact map records all eight current non-deprecated Table targets once. The
+The exact map records all ten current non-deprecated Table targets once. The
 legacy `base-table` alias is compatibility, not anatomy. TableHeader, TableBody,
 TableFooter, TableRow, TableCell, and TableHeaderCell retain direct docs linked by
 `subComponentOf: 'Table'`; they do not need independent component specs for this
 aggregate ownership.
 
+The Sort control and the Filter control are rendered by Button and IconButton, so
+INV5 would make them delegate to `button`. They hold their own targets instead
+because each guarantees a public visual contract `button` cannot express: a
+colour on `table-sort-button` paints the sort glyph and leaves the column name on
+the header cell (routed by the `color` derived-var entry in
+`theming.derived`, INV11), where the same colour on `button` paints label and end
+content together by Button's own contract; and a colour on `table-filter-button`
+reaches one column's funnel rather than every button in the table. Both targets
+sit on the painting element that Button renders — the control itself, not a
+wrapper — so INV4 holds, and the interaction model stays Button's. The precedent
+is `toggle-button`, which carries its own target on the Button it renders.
+
 ## Family and system relationships
 
 - `architecture:component-theming-surface` owns anatomy qualification, exact
diff --git a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
index b27b2a2e4af7e..1ba85c910d2cc 100644
--- a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
+++ b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx
@@ -26,16 +26,10 @@ import {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {
-  spacingVars,
-  radiusVars,
-  colorVars,
-  durationVars,
-  easeVars,
-} from '../../../theme/tokens.stylex';
-import {focusOutlineProps} from '../../../utils/focusOutline.stylex';
+import {spacingVars, colorVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {Button} from '../../../Button';
+import {IconButton} from '../../../IconButton';
 import {Popover} from '../../../Popover';
 import {TextInput} from '../../../TextInput';
 import {NumberInput} from '../../../NumberInput';
@@ -57,7 +51,6 @@ import type {
 } from '../../types';
 import {proportional} from '../../columnUtils';
 import {useLocale, useTranslator} from '../../../i18n';
-import {mergeProps} from '../../../utils';
 import {themeProps} from '../../../utils/themeProps';
 import type {
   PowerSearchConfig,
@@ -376,47 +369,29 @@ const filterStyles = stylex.create({
     minWidth: 0,
   },
   triggerButton: {
-    background: 'none',
-    border: 'none',
-    cursor: {
-      default: 'pointer',
-      ':is(:disabled,[aria-disabled="true"])': 'default',
-    },
-    display: 'inline-flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    padding: 0,
-    borderRadius: radiusVars['--radius-element'],
     flexShrink: 0,
     // Minimum 44px touch target on coarse pointer devices (iOS guideline).
+    // WCAG 2.2 2.5.8 asks 24px; this coarse-pointer accommodation predates the
+    // change and is kept. On a fine pointer Button's own `sm` box governs.
     '@media (pointer: coarse)': {
       minWidth: '44px',
       minHeight: '44px',
     },
-    // The funnel reads this through `color="inherit"`, so a theme setting a
-    // colour on `astryx-table-filter-button` reaches it. The button holds only
-    // the glyph, so there is nothing else here for the colour to reach.
-    color: colorVars['--color-icon-secondary'],
-    // Rest -> hover -> pressed, matching the sort affordance beside it.
-    backgroundColor: {
-      default: 'transparent',
-      ':active:where(:not(:disabled,[aria-disabled="true"]))':
-        colorVars['--color-overlay-pressed'],
-    },
-    transitionProperty: 'background-color, color',
-    transitionDuration: {
-      default: durationVars['--duration-fast'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
-  },
-  triggerHoverOnPointer: {
-    '@media (hover: hover)': {
-      backgroundColor: {
-        ':hover:where(:not(:disabled,[aria-disabled="true"]))':
-          colorVars['--color-overlay-hover'],
-      },
-      color: {
+    // This button holds the glyph and nothing else, so its `color` IS the
+    // glyph's colour: the funnel reads it through `color="inherit"`, and a
+    // theme setting `color` on `astryx-table-filter-button` reaches it with
+    // nothing else here for it to over-reach. Without this, `ghost` paints
+    // `--color-text-primary`.
+    //
+    // On hover the glyph darkens a step alongside Button's own overlay, so the
+    // feedback survives a forced-colors mode that drops backgrounds. Guarded
+    // on `hover: hover` so a touch device does not stick in the hovered colour
+    // after a tap. The tint, the pressed state and the focus ring are
+    // Button's, not restated here.
+    color: {
+      default: colorVars['--color-icon-secondary'],
+      '@media (hover: hover)': {
+        default: null,
         ':hover:where(:not(:disabled,[aria-disabled="true"]))':
           colorVars['--color-text-primary'],
       },
@@ -1039,24 +1014,20 @@ function PopoverFilterTrigger({
           </div>
         </FilterStoreContext>
       }>
-      <button
-        type="button"
-        aria-label={t('@astryx.tableFiltering.filterByColumn', {header})}
+      <IconButton
+        variant="ghost"
+        size="sm"
+        label={t('@astryx.tableFiltering.filterByColumn', {header})}
         aria-haspopup="dialog"
-        {...mergeProps(
-          themeProps('table-filter-button', {
-            active: hasValue ? 'active' : null,
-          }),
-          // The ring was missing here entirely: this button is keyboard
-          // reachable and drew nothing on focus.
-          focusOutlineProps.focusVisible(
-            filterStyles.triggerButton,
-            filterStyles.triggerHoverOnPointer,
-            hasValue && filterStyles.triggerActive,
-          ),
-        )}>
-        <Icon icon="funnel" size="xsm" color="inherit" />
-      </button>
+        icon={<Icon icon="funnel" size="xsm" color="inherit" />}
+        {...themeProps('table-filter-button', {
+          active: hasValue ? 'active' : null,
+        })}
+        xstyle={[
+          filterStyles.triggerButton,
+          ...(hasValue ? [filterStyles.triggerActive] : []),
+        ]}
+      />
     </Popover>
   );
 }
diff --git a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
index 0dd5cfefba67d..8a5dc6097a92f 100644
--- a/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
+++ b/packages/core/src/Table/plugins/sortable/useTableSortable.tsx
@@ -18,13 +18,12 @@ import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
   spacingVars,
-  radiusVars,
   durationVars,
   easeVars,
 } from '../../../theme/tokens.stylex';
-import {focusOutlineProps} from '../../../utils/focusOutline.stylex';
-import {mergeProps} from '../../../utils';
+import {isRenderable} from '../../../utils';
 import {themeProps} from '../../../utils/themeProps';
+import {Button} from '../../../Button';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator, type TranslatorFn} from '../../../i18n';
@@ -125,74 +124,54 @@ export interface UseTableSortableConfig<TSortKey extends string = string> {
 // =============================================================================
 
 const sortStyles = stylex.create({
+  // Table geometry on top of Button. Everything the control does as a control
+  // — the hover and pressed overlay, the focus ring, the press transform, the
+  // reduced-motion guard — is Button's, so none of it is restated here.
   button: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: spacingVars['--spacing-1'],
-    background: 'transparent',
-    border: 'none',
-    padding: 0,
-    margin: 0,
-    cursor: {
-      default: 'pointer',
-      ':is(:disabled,[aria-disabled="true"])': 'default',
-    },
-    font: 'inherit',
-    // The glyph's colour travels as a custom property rather than as `color`
-    // on this button.
-    //
-    // `color` here would be inherited by BOTH children, and only one of them
-    // wants it. The label is the column name: it belongs to the header cell,
-    // whose own `astryx-table-header-cell` target already paints it. A `color`
-    // on this button overrode that — so a theme that recoloured its header
-    // cells left every sortable heading behind, still painting the raw token
-    // this file used to restate. The glyph, meanwhile, does want the
-    // affordance's colour.
-    //
-    // Declaring the var here keeps BOTH true and keeps the single target: the
-    // label inherits the header cell (nothing interrupts it now), and the
-    // glyph reads the var (see `iconWrapper`).
-    //
-    // Underscored, so internal. A public var is a promise
-    // `theme-var-reachability.js` has to be able to check, and it finds a
-    // component's stories by matching the doc name against story titles — a
-    // plugin has none of its own (its behaviour is exercised through
-    // `Core/TableFiltering`), so the promise would be undocumentable by
-    // construction. Themes reach this affordance through the target itself.
-    '--_table-sort-glyph-color': colorVars['--color-icon-secondary'],
+    // The control fills the cell so the whole heading is the click target.
     width: '100%',
     height: '100%',
+    justifyContent: 'flex-start',
     textAlign: 'inherit',
-    borderRadius: radiusVars['--radius-inner'],
-    // Rest -> hover -> pressed, the treatment every other borderless control
-    // in the system draws. The resting state carries no tint: the affordance
-    // is legible on its colour alone (`--color-icon-secondary`, 4.74:1)
-    // rather than on the dimming that put it at 1.57:1.
-    backgroundColor: {
-      default: 'transparent',
-      ':active:where(:not(:disabled,[aria-disabled="true"]))':
-        colorVars['--color-overlay-pressed'],
-    },
-    transitionProperty: 'background-color',
-    transitionDuration: {
-      default: durationVars['--duration-fast'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
+    paddingBlock: 0,
+    paddingInline: 0,
+    gap: spacingVars['--spacing-1'],
+    // The column name is the header cell's text, not a button label: it keeps
+    // the cell's type and colour. `ghost` paints `--color-text-primary`, which
+    // would override what `TableHeaderCell` paints on the `<th>` and leave
+    // every sortable heading behind a theme that recoloured
+    // `astryx-table-header-cell`.
+    color: 'inherit',
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    fontWeight: 'inherit',
+    lineHeight: 'inherit',
+    whiteSpace: 'inherit',
   },
-  // Guarded on `hover: hover` so a touch device does not stick in the hover
-  // tint after a tap (Component Audit Rubric A8).
-  buttonHoverOnPointer: {
-    '@media (hover: hover)': {
-      backgroundColor: {
-        ':hover:where(:not(:disabled,[aria-disabled="true"]))':
-          colorVars['--color-overlay-hover'],
-      },
-      // The glyph darkens a step as well, so the feedback survives a
-      // forced-colors mode that drops the background tint. On the var, not on
-      // `color`: the column name is not part of the affordance and must not
-      // move when the pointer is over the heading.
-      '--_table-sort-glyph-color': {
+  // The glyph's colour travels as a private custom property rather than as
+  // `color` on the button, because `color` is inherited by BOTH children and
+  // only one of them wants it (see above).
+  //
+  // A theme still writes the ordinary property: `color` on
+  // `astryx-table-sort-button` is expanded to this var by the derived-var
+  // registry (`replaces: true`, so no `color` lands on the button itself and
+  // the column name never moves). The var is the routing, not the API — INV11
+  // in `architecture:component-theming-surface`.
+  //
+  // Declared through `className` rather than `xstyle`: `BaseProps['xstyle']`
+  // is typed to standard CSS properties, so a custom property cannot travel
+  // that way.
+  //
+  // On hover the glyph darkens a step alongside Button's own overlay, so the
+  // feedback survives a forced-colors mode that drops backgrounds. On the var,
+  // not on `color`: the column name is not part of the affordance and must not
+  // move when the pointer is over the heading. Guarded on `hover: hover` so a
+  // touch device does not stick in the hovered colour after a tap.
+  glyphColor: {
+    '--_table-sort-glyph-color': {
+      default: colorVars['--color-icon-secondary'],
+      '@media (hover: hover)': {
+        default: null,
         ':hover:where(:not(:disabled,[aria-disabled="true"]))':
           colorVars['--color-text-primary'],
       },
@@ -200,15 +179,9 @@ const sortStyles = stylex.create({
   },
   // Accent is the SORTED state and nothing else, so "this column is sorted"
   // never reads as "the pointer is here".
-  buttonSorted: {
+  glyphColorSorted: {
     '--_table-sort-glyph-color': colorVars['--color-accent'],
   },
-  // No `color`. The header text belongs to the cell, so it inherits the
-  // colour `TableHeaderCell` paints on the `<th>` — which is what the
-  // `astryx-table-header-cell` target themes. Restating the token here read
-  // as identical until someone themed that target, and then the heading
-  // stopped following it.
-  label: {},
   iconWrapper: {
     display: 'inline-flex',
     color: 'var(--_table-sort-glyph-color)',
@@ -219,6 +192,11 @@ const sortStyles = stylex.create({
     },
     transitionTimingFunction: easeVars['--ease-standard'],
   },
+  endContent: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
   rank: {
     fontSize: 10,
     // eslint-disable-next-line @astryx/no-hardcoded-styles -- no token for lineHeight:1 (tight badge)
@@ -375,29 +353,35 @@ function SortHeaderButton<T extends Record<string, unknown>>({
     }
   };
 
+  const target = themeProps('table-sort-button', {direction});
+  const glyphColor = stylex.props(
+    sortStyles.glyphColor,
+    direction != null && sortStyles.glyphColorSorted,
+  );
+
   return (
-    <button
-      type="button"
-      {...mergeProps(
-        themeProps('table-sort-button', {direction}),
-        focusOutlineProps.focusVisible(
-          sortStyles.button,
-          sortStyles.buttonHoverOnPointer,
-          direction != null && sortStyles.buttonSorted,
-        ),
-      )}
-      aria-label={ariaLabel}
-      onClick={handleClick}>
-      <span {...stylex.props(sortStyles.label)}>{children}</span>
-      <span {...stylex.props(sortStyles.iconWrapper)}>
-        <Icon icon={iconName} size="xsm" color="inherit" />
-      </span>
-      {rank != null && (
-        <span {...stylex.props(sortStyles.rank)} aria-hidden="true">
-          {rank}
+    <Button
+      variant="ghost"
+      size="sm"
+      label={ariaLabel}
+      {...target}
+      className={`${target.className} ${glyphColor.className ?? ''}`.trim()}
+      xstyle={sortStyles.button}
+      onClick={handleClick}
+      endContent={
+        <span {...stylex.props(sortStyles.endContent)}>
+          <span {...stylex.props(sortStyles.iconWrapper)}>
+            <Icon icon={iconName} size="xsm" color="inherit" />
+          </span>
+          {isRenderable(rank) && (
+            <span {...stylex.props(sortStyles.rank)} aria-hidden="true">
+              {rank}
+            </span>
+          )}
         </span>
-      )}
-    </button>
+      }>
+      {children}
+    </Button>
   );
 }
 
diff --git a/packages/core/src/Table/useTableFiltering.doc.mjs b/packages/core/src/Table/useTableFiltering.doc.mjs
index 42985d0b8cd1c..a2f5e704ee6f0 100644
--- a/packages/core/src/Table/useTableFiltering.doc.mjs
+++ b/packages/core/src/Table/useTableFiltering.doc.mjs
@@ -8,11 +8,6 @@ export const docs = {
   displayName: 'useTableFiltering',
   isHiddenFromOverview: true,
   description: 'Table plugin that adds inline column filters with popover or inline controls. Pairs with useTableFilterState for managed state. Supports text, select, multi-select, date, and number filter types via PowerSearch field definitions.',
-  theming: {
-    targets: [
-      {className: 'astryx-table-filter-button', states: ['active']},
-    ],
-  },
   props: [
     {
       name: 'filters',
@@ -40,11 +35,6 @@ export const docsZh = {
   isHiddenFromOverview: true,
   displayName: 'useTableFiltering',
   description: '表格筛选插件，添加内联列过滤器（弹出式或内联控件）。与 useTableFilterState 配合使用管理状态。',
-  theming: {
-    targets: [
-      {className: 'astryx-table-filter-button', states: ['active']},
-    ],
-  },
   props: [
     {
       name: 'filters',
diff --git a/packages/core/src/Table/useTableSortable.doc.mjs b/packages/core/src/Table/useTableSortable.doc.mjs
index 23548cc8669c2..8120c37fb88d2 100644
--- a/packages/core/src/Table/useTableSortable.doc.mjs
+++ b/packages/core/src/Table/useTableSortable.doc.mjs
@@ -7,11 +7,6 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableSortable',
   description: 'Headless multi-sort plugin for Table. Call with a config object: `useTableSortable({ sort, onSortChange })`. Returns a TablePlugin to pass to `<Table plugins={{ sort: sortPlugin }} />`.',
-  theming: {
-    targets: [
-      {className: 'astryx-table-sort-button', visualProps: ['direction']},
-    ],
-  },
   usage: {
     description: 'Call useTableSortable with a config object containing sort state and callback. Pass the returned plugin to Table via the plugins prop.',
   },
@@ -47,11 +42,6 @@ export const docsZh = {
   name: 'useTableSortable',
   displayName: 'useTableSortable',
   description: '无头多列排序插件。用户拥有排序状态并提供回调。Shift+点击启用二级排序列。排序指示器自动渲染在表头单元格中。',
-  theming: {
-    targets: [
-      {className: 'astryx-table-sort-button', visualProps: ['direction']},
-    ],
-  },
   props: [
     {
       name: 'sort',
diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.ts
index 2ee05277460bf..23d4fef77d523 100644
--- a/packages/core/src/theme/derivedVarRegistry.test.ts
+++ b/packages/core/src/theme/derivedVarRegistry.test.ts
@@ -228,6 +228,7 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   ProgressBar: 'progress-bar-mark',
   Section: 'section',
   SegmentedControl: 'segmented-control',
+  Table: 'table-sort-button',
   TextArea: 'text-area',
 };
 
diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.ts
index 6ff692d6fbabe..5fab1c500e722 100644
--- a/packages/core/src/theme/derivedVarRegistry.ts
+++ b/packages/core/src/theme/derivedVarRegistry.ts
@@ -82,6 +82,14 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
     {property: 'borderRadius', vars: ['--_segmented-control-radius']},
     {property: 'padding', vars: ['--_segmented-control-padding']},
   ],
+  // The sort control is a Button holding the column name as well as the
+  // glyph. `color` on the target would be inherited by both, and the name
+  // belongs to the header cell (`astryx-table-header-cell` paints it), so the
+  // value is routed to the glyph through a private var and the source property
+  // is dropped.
+  'table-sort-button': [
+    {property: 'color', vars: ['--_table-sort-glyph-color'], replaces: true},
+  ],
   'text-area': [
     {
       property: 'paddingInline',
diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.ts
index 24e930c3f26dc..7e746cebc3870 100644
--- a/packages/themes/probe/src/probeTheme.ts
+++ b/packages/themes/probe/src/probeTheme.ts
@@ -6,7 +6,7 @@
 // test fixture. Regenerate with: pnpm visual:probe-theme
 //
 // defineTheme takes six things and this covers all six:
-//   components  272 targets, 881 selectors (generated from the docs)
+//   components  274 targets, 886 selectors (generated from the docs)
 //   tokens      custom properties, read back off the themed element
 //   icons       every registry entry swapped for a marked glyph
 //   indicators  check / radio / checkbox swapped — the swap that reaches furthest
@@ -3047,6 +3047,12 @@ export const probeTheme = defineTheme({
         borderColor: 'hsl(40.4 92% 25%)',
         outlineColor: 'hsl(177.8 82% 25%)',
       },
+      readonly: {
+        backgroundColor: 'hsl(291.7 88% 52%)',
+        color: 'hsl(213.7 89% 12%)',
+        borderColor: 'hsl(50.2 86% 25%)',
+        outlineColor: 'hsl(214.5 74% 25%)',
+      },
     },
     'multi-selector-clear-icon': {
       base: {
@@ -4136,6 +4142,12 @@ export const probeTheme = defineTheme({
         borderColor: 'hsl(298.2 93% 25%)',
         outlineColor: 'hsl(59.6 86% 25%)',
       },
+      readonly: {
+        backgroundColor: 'hsl(149.0 90% 62%)',
+        color: 'hsl(226.6 78% 12%)',
+        borderColor: 'hsl(25.9 71% 25%)',
+        outlineColor: 'hsl(86.5 79% 25%)',
+      },
     },
     'selector-check': {
       base: {
@@ -4791,6 +4803,20 @@ export const probeTheme = defineTheme({
         outlineColor: 'hsl(221.9 77% 25%)',
       },
     },
+    'table-filter-button': {
+      base: {
+        backgroundColor: 'hsl(10.3 75% 54%)',
+        color: 'hsl(252.2 89% 12%)',
+        borderColor: 'hsl(224.0 71% 25%)',
+        outlineColor: 'hsl(293.8 79% 25%)',
+      },
+      active: {
+        backgroundColor: 'hsl(100.0 74% 63%)',
+        color: 'hsl(337.7 70% 12%)',
+        borderColor: 'hsl(9.8 90% 25%)',
+        outlineColor: 'hsl(34.7 70% 25%)',
+      },
+    },
     'table-footer': {
       base: {
         backgroundColor: 'hsl(97.2 94% 49%)',
@@ -4849,6 +4875,14 @@ export const probeTheme = defineTheme({
         outlineColor: 'hsl(187.4 90% 25%)',
       },
     },
+    'table-sort-button': {
+      base: {
+        backgroundColor: 'hsl(242.4 83% 46%)',
+        color: 'hsl(2.1 92% 12%)',
+        borderColor: 'hsl(279.1 91% 25%)',
+        outlineColor: 'hsl(157.3 85% 25%)',
+      },
+    },
     text: {
       base: {
         backgroundColor: 'hsl(320.7 88% 59%)',

From 9c0da1e1b7657fa42a8fb4af506cbde9e0dfa1f1 Mon Sep 17 00:00:00 2001
From: freddymeta <170298698+freddymeta@users.noreply.github.com>
Date: Wed, 2 Sep 2026 02:30:02 -0700
Subject: [PATCH 10/12] =?UTF-8?q?docs(Table):=20align=20the=20spec=20with?=
 =?UTF-8?q?=20this=20head=20=E2=80=94=20ten=20targets,=20and=20the=20visua?=
 =?UTF-8?q?l=20changes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`Table.spec.md` still read "additive documentation only", "eight current
targets" in three places, and a Decision log of "None ... without introducing a
component-local visual or runtime change", while this head records ten targets
and rebuilds both affordances on Button.

- *Compatibility* — additive targets plus the intentional visual changes,
  itemised: Button/IconButton's hover and pressed overlay and `scale(0.98)`
  press, the filter trigger's shared focus ring and `sm` square box, and the
  removal of the resting `opacity: 0.35`. Records that nothing is removed or
  renamed, and that the column heading is measured unchanged against its `<th>`.
- *Ownership* — eight targets to ten.
- *FR4 and the verification map* — the same, and FR4 now names
  `table-sort-button` and `table-filter-button` with the states they reflect.
- *Decision log* — four decisions replacing "None": own targets rather than
  delegating to `button` (DEC-1), the derived-var routing that colours the glyph
  without the label (DEC-2), building on Button (DEC-3), and the opacity removal
  as a contrast fix rather than a preference (DEC-4).

This edits an `authority: current` record, so `spec-owner-approval` will now ask
for owner approval where the previous head did not. That is the gate working as
intended, not something to route around.

The other half of the review — wiring the affordance guard into CI — is a
`.github/workflows/` change my account cannot push (`refusing to allow a
Personal Access Token to create or update workflow ci.yml without workflow
scope`). The verified patch is in a PR comment for a maintainer to apply, which
matches how the 08-26 review framed it.

Test Plan:
- `scripts/check-knowledge.mjs`: records aligned
- `themingTargets.test.ts` + `derivedVarRegistry.test.ts`: 518 tests pass
- no remaining "eight" or "documentation only" in the record
---
 packages/core/src/Table/Table.spec.md | 83 ++++++++++++++++++++-------
 1 file changed, 61 insertions(+), 22 deletions(-)

diff --git a/packages/core/src/Table/Table.spec.md b/packages/core/src/Table/Table.spec.md
index 6990e7eb33c58..ad623f6e289d0 100644
--- a/packages/core/src/Table/Table.spec.md
+++ b/packages/core/src/Table/Table.spec.md
@@ -50,10 +50,27 @@ generated anatomy, accessibility, migration, and evidence belong to each listed
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, aliases, and public API remain unchanged
+- Compatibility class: additive targets plus an intentional visual change to two
+  existing affordances. Two targets are added (`table-sort-button`,
+  `table-filter-button`); no target, alias, DOM structure, prop, or export is
+  removed or renamed, and no public API changes.
+- Intentional visual changes, both to the sort control and the filter trigger:
+  - They are now the real `Button` and `IconButton` rather than native buttons
+    that restated Button's interaction states, so they take Button's hover and
+    pressed overlay and its `scale(0.98)` press, and the filter trigger draws
+    the shared 2px focus ring in place of the user agent's default outline. Its
+    box becomes Button's `sm` square (28x28 measured, above the 24px WCAG 2.2
+    2.5.8 minimum).
+  - Their resting `opacity: 0.35` is gone. Composited, that put them at 1.57:1
+    against the header, below the 3:1 WCAG 1.4.11 asks of a UI component; they
+    now render at `--color-icon-secondary`, measured 4.74:1, and stay visible at
+    rest rather than fading in on header hover.
+  - The column heading inside the sort control is unchanged: measured against
+    its `<th>`, colour, white-space, overflow, text-overflow, font size and
+    weight all match.
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: none
+- Migration decision: none. A theme that styled either affordance through a
+  structural selector keeps working; the new targets are the supported route.
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -63,7 +80,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The Table and Scroll region, the aggregate Header section, Body section,
   conditional Footer section, Row, Column header cell, and Cell anatomy, and the
-  eight current `table*` targets mapped below.
+  ten current `table*` targets mapped below.
 - The stable Sort control and Sort priority rendered by useTableSortable.
 - The stable Expansion control and Expanded detail panel rendered by
   useTableRowExpansion.
@@ -103,20 +120,20 @@ documented in `Table.doc.mjs` and the member and module docs.
 
 ## Behavioral and layout contract
 
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                | Basis                                | Evidence state                                                                  |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------- |
-| FR1  | Styled Table renders one keyboard-focusable Scroll region around one semantic Table.                                                                                                                                                                                                                                                                                     | Current source, docs, and tests      | Verified current behavior; no new behavior decided                              |
-| FR2  | Data-driven mode renders a Body section and a Header section with Column header cells when columns are present. Each data item renders a standard Row and Cells; an empty data array instead renders the configured empty-state row when enabled. It never creates a Footer section.                                                                                     | Current source, docs, and tests      | Verified current behavior; no new behavior decided                              |
-| FR3  | Children mode passes caller composition through to the Table. TableHeader, TableBody, and TableFooter provide the respective sections, and TableRow, TableHeaderCell, and TableCell provide standard rows and cells.                                                                                                                                                     | Current source, docs, and tests      | Verified current composition; no new API or DOM rule                            |
-| FR4  | `Table.doc.mjs` is the canonical aggregate consumer owner for the eight current targets: `table`, `table-scroll-wrapper`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-cell`, and `table-header-cell`. Member docs retain direct lookup metadata through `subComponentOf: 'Table'`.                                                                 | Current docs and CLI target tests    | Verified parent ownership; focused placement coverage is partial                |
-| FR5  | For a sortable column, useTableSortable renders a Sort control around the column label, an Icon-owned Sort indicator glyph, and a numeric Sort priority only while multi-sort has more than one active entry.                                                                                                                                                            | Current source, docs, and tests      | Control and priority are tested; glyph presence is source-inspected only        |
-| FR6  | useTableSelection renders CheckboxInput-owned Selection controls in the generated selection Column header cell and each selectable body Cell; selection remains row state rather than separate anatomy.                                                                                                                                                                  | Current source, docs, and tests      | Verified stable delegated controls; no target or state change                   |
-| FR7  | For an expandable row, useTableRowExpansion renders an Expansion control with an Icon-owned Expansion glyph and conditionally appends an Expanded detail panel whose cell spans the column count captured by that plugin's `transformColumns` step.                                                                                                                      | Current source, docs, and tests      | Verified stable plugin parts; current target gaps remain                        |
-| FR8  | Empty data renders the default compact EmptyState unless the caller supplies replacement content or disables it.                                                                                                                                                                                                                                                         | Current source, docs, and tests      | Verified conditional delegation; caller content remains outside ownership       |
-| FR9  | Table converts the caller's named plugin record into one ordered array after its built-in styling plugin. Known names use the current canonical sequence `columnSettings → sort → tree → selection → pagination`; every other name follows that known set while preserving its record insertion order.                                                                   | Current source and docs              | Current shared ordering; canonical-name coverage is source-inspected            |
-| FR10 | Every applicable non-context transform runs sequentially in the resolved plugin-array order, so a later plugin receives the value returned by every earlier successful plugin. A throwing transform reports a development error and leaves the prior accumulated value in the pipeline.                                                                                  | Current source and tests             | Sequential composition is tested; failure isolation is source-inspected         |
-| FR11 | `transformColumns` completes before element transforms. Table then applies table, header-cell/header-row, body-cell/body-row, scroll-wrapper, and context phases at their render points. Header-cell contributions use `before`, `content`, `after`, `overlay`, and `below` slots. Context transforms run in reverse so the first plugin becomes the outermost provider. | Current source, types, and tests     | Transform application is tested; complete cross-phase order is source-inspected |
-| FR12 | When built-in and named plugin references are unchanged, Table reuses the resolved plugin array; unknown/custom plugin value identity and insertion order remain stable inputs to memoization.                                                                                                                                                                           | Current source and performance tests | Current performance contract; focused named-order coverage is partial           |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                | Evidence state                                                                  |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
+| FR1  | Styled Table renders one keyboard-focusable Scroll region around one semantic Table.                                                                                                                                                                                                                                                                                                              | Current source, docs, and tests      | Verified current behavior; no new behavior decided                              |
+| FR2  | Data-driven mode renders a Body section and a Header section with Column header cells when columns are present. Each data item renders a standard Row and Cells; an empty data array instead renders the configured empty-state row when enabled. It never creates a Footer section.                                                                                                              | Current source, docs, and tests      | Verified current behavior; no new behavior decided                              |
+| FR3  | Children mode passes caller composition through to the Table. TableHeader, TableBody, and TableFooter provide the respective sections, and TableRow, TableHeaderCell, and TableCell provide standard rows and cells.                                                                                                                                                                              | Current source, docs, and tests      | Verified current composition; no new API or DOM rule                            |
+| FR4  | `Table.doc.mjs` is the canonical aggregate consumer owner for the ten current targets: `table`, `table-scroll-wrapper`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-cell`, `table-header-cell`, `table-sort-button` (reflecting `direction`), and `table-filter-button` (reflecting `active`). Member docs retain direct lookup metadata through `subComponentOf: 'Table'`. | Current docs and CLI target tests    | Verified parent ownership; focused placement coverage is partial                |
+| FR5  | For a sortable column, useTableSortable renders a Sort control around the column label, an Icon-owned Sort indicator glyph, and a numeric Sort priority only while multi-sort has more than one active entry.                                                                                                                                                                                     | Current source, docs, and tests      | Control and priority are tested; glyph presence is source-inspected only        |
+| FR6  | useTableSelection renders CheckboxInput-owned Selection controls in the generated selection Column header cell and each selectable body Cell; selection remains row state rather than separate anatomy.                                                                                                                                                                                           | Current source, docs, and tests      | Verified stable delegated controls; no target or state change                   |
+| FR7  | For an expandable row, useTableRowExpansion renders an Expansion control with an Icon-owned Expansion glyph and conditionally appends an Expanded detail panel whose cell spans the column count captured by that plugin's `transformColumns` step.                                                                                                                                               | Current source, docs, and tests      | Verified stable plugin parts; current target gaps remain                        |
+| FR8  | Empty data renders the default compact EmptyState unless the caller supplies replacement content or disables it.                                                                                                                                                                                                                                                                                  | Current source, docs, and tests      | Verified conditional delegation; caller content remains outside ownership       |
+| FR9  | Table converts the caller's named plugin record into one ordered array after its built-in styling plugin. Known names use the current canonical sequence `columnSettings → sort → tree → selection → pagination`; every other name follows that known set while preserving its record insertion order.                                                                                            | Current source and docs              | Current shared ordering; canonical-name coverage is source-inspected            |
+| FR10 | Every applicable non-context transform runs sequentially in the resolved plugin-array order, so a later plugin receives the value returned by every earlier successful plugin. A throwing transform reports a development error and leaves the prior accumulated value in the pipeline.                                                                                                           | Current source and tests             | Sequential composition is tested; failure isolation is source-inspected         |
+| FR11 | `transformColumns` completes before element transforms. Table then applies table, header-cell/header-row, body-cell/body-row, scroll-wrapper, and context phases at their render points. Header-cell contributions use `before`, `content`, `after`, `overlay`, and `below` slots. Context transforms run in reverse so the first plugin becomes the outermost provider.                          | Current source, types, and tests     | Transform application is tested; complete cross-phase order is source-inspected |
+| FR12 | When built-in and named plugin references are unchanged, Table reuses the resolved plugin array; unknown/custom plugin value identity and insertion order remain stable inputs to memoization.                                                                                                                                                                                                    | Current source and performance tests | Current performance contract; focused named-order coverage is partial           |
 
 ### Current evidence and gaps
 
@@ -321,13 +338,35 @@ is `toggle-button`, which carries its own target on the Button it renders.
 | FR9-FR11            | `Table.test.tsx`, `types.ts`, `BaseTable.tsx`, and `useBaseTablePlugins.ts`                          | Built-in plus known and custom named plugins; every transform phase | Sequential composition, base-before-user behavior, transform application, and slot output have focused coverage; complete known-name sorting, phase order, exception continuation, and context nesting remain source-inspected.                                           | `audit:Table/plugins`     |
 | FR12, PR1           | `Table.perf.test.tsx` plus `useBaseTablePlugins.ts` source inspection                                | Same plugin references, recreated record, and changed plugin value  | Unchanged plugin values must preserve the resolved array and representative no-op row-update budgets; focused named-record identity coverage remains partial.                                                                                                             | `audit:Table/performance` |
 | Module backlink     | `scripts/check-knowledge.mjs`                                                                        | Active parent and colocated module record                           | A missing, duplicate, mis-parented, wrong-kind, misnamed, or undiscovered module record fails knowledge validation.                                                                                                                                                       | `audit:Table/modules`     |
-| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests | Canonical anatomy, eight current targets, legacy alias              | Missing, extra, duplicated, prefixed, stale, alias-backed, or independently owned member mappings fail repository validation or discovery coverage.                                                                                                                       | `audit:Table/theming`     |
+| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests | Canonical anatomy, ten current targets, legacy alias                | Missing, extra, duplicated, prefixed, stale, alias-backed, or independently owned member mappings fail repository validation or discovery coverage.                                                                                                                       | `audit:Table/theming`     |
 
 ## Decision log
 
-None. This current contract records existing Table facts, approved canonical parent
-ownership, and the shared plugin protocol without introducing a component-local
-visual or runtime change.
+**DEC-1 — the sort and filter affordances carry their own targets rather than
+delegating to `button`.** Both are rendered inside Table's own plugins, so there
+is no wrapper a consumer can interpose and no `renderX` prop to route around:
+restyling either meant `.astryx-table-header-cell button[aria-haspopup='dialog']`,
+a selector that says "the button that opens a dialog" — the filter funnel today,
+anything tomorrow. Each also guarantees a visual contract `button` cannot
+express; see the anatomy note above for why, and INV5's exception. The precedent
+is `toggle-button`.
+
+**DEC-2 — a colour on `table-sort-button` is routed to the glyph and dropped
+from the control.** The sort control holds the column name as well as the glyph,
+and the name belongs to the header cell, so the colour cannot land on the button
+itself: `theming.derived` maps `color` onto the private
+`--_table-sort-glyph-color` with `replaces: true`. `table-filter-button` needs no
+such routing — that control holds nothing but its funnel.
+
+**DEC-3 — both controls are built on `Button`/`IconButton`.** They previously
+restated Button's rest, hover, pressed, focus-ring, press-transform and
+reduced-motion behaviour on native buttons, which is drift waiting to happen.
+The visible consequences are listed under Compatibility and are intentional.
+
+**DEC-4 — the resting `opacity: 0.35` is removed as an accessibility fix**, not
+a preference: it put both affordances at 1.57:1 against the header where WCAG
+1.4.11 asks 3:1. The sorted state still changes glyph as well as colour, so the
+state is never colour alone.
 
 ## Open questions
 

From b96b63d19d4fc4e09796ce105775d1eec85e691a Mon Sep 17 00:00:00 2001
From: freddymeta <170298698+freddymeta@users.noreply.github.com>
Date: Wed, 2 Sep 2026 02:48:23 -0700
Subject: [PATCH 11/12] test(Table): measure column order under RTL, closing
 the pr-rtl coverage gap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pr-rtl` fails on this head, unrelated to the review: the audit scopes every
component a PR touches and requires each to be measured or to carry a written
not-applicable reason. Table was neither, so it reported
`COV: 0 measured / 1 gap` and exited 1.

Table is plainly direction-sensitive — a table's column order mirrors — so the
answer is measurement rather than a reason. A D2 target over
`core-table--column-alignment` asserts the first and last cells of a row swap
horizontal order between LTR and RTL.

One trap worth recording, since the selector looks obviously right and is not:
`tbody tr:first-child td:first-child` matches Storybook's own hidden docs
prop-table first (inside `.sb-preparing-docs`, width 0), so `boundingBox()`
returns null and the dimension silently reports "prev/next not found" — an N-A
that still counts as a gap, not an error. Scoping to `.astryx-table` picks the
story's own table.

Test Plan:
Built Storybook and ran the audit, rather than reasoning about the selectors —
which is how the hidden-table trap above turned up:

    $ node apps/storybook/rtl-audit/rtl-audit.mjs \
        --storybook-dir apps/storybook/dist --filter Table
    CUR  RTL-ready  core/table   {"D2":"pass"}
    COV : 1 measured / 0 verified N-A / 0 gap / 0 stale
    exit 0                                    (was: 0 measured / 1 gap, exit 1)

The order genuinely mirrors rather than merely differing — cell centres LTR
305 < 1024, RTL 795 > 76.
---
 apps/storybook/rtl-audit/targets.json | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.json
index e45a938c7f1b3..0048486bc3813 100644
--- a/apps/storybook/rtl-audit/targets.json
+++ b/apps/storybook/rtl-audit/targets.json
@@ -45,5 +45,16 @@
       "prev": "button[aria-label=\"Previous\"]",
       "next": "button[aria-label=\"Next\"]"
     }
+  },
+  {
+    "component": "Table",
+    "storyId": "core-table--column-alignment",
+    "dims": [
+      "D2"
+    ],
+    "selectors": {
+      "prev": ".astryx-table tbody tr:first-child td:first-child",
+      "next": ".astryx-table tbody tr:first-child td:last-child"
+    }
   }
-]
\ No newline at end of file
+]

From 2c4dc27fb54e885d977afc39ed47460c1b9732fe Mon Sep 17 00:00:00 2001
From: freddymeta <170298698+freddymeta@users.noreply.github.com>
Date: Wed, 2 Sep 2026 05:56:07 -0700
Subject: [PATCH 12/12] test(Table): drop the now-stale verified-not-applicable
 declaration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#5817 landed a `verified-not-applicable` reason for `core/Table` while this
branch was adding a measured D2 target for the same component. With both in
place the audit reports `1 stale` and exits 1 — which is the registry working
as documented: "if an automatic or curated dimension later becomes applicable,
the declaration is reported as stale-verified-na and must be removed or
replaced with real coverage."

Real coverage is what this branch adds, so the declaration goes. Its reasoning
was that column order "uses table flow ... resolved by CSS for the document
direction" — true, and now measured rather than asserted.

Test Plan:
    $ node apps/storybook/rtl-audit/rtl-audit.mjs \
        --storybook-dir apps/storybook/dist --filter Table
    CUR  RTL-ready  core/table   {"D2":"pass"}
    COV : 1 measured / 0 verified N-A / 0 gap / 0 stale
    exit 0                       (was: 0 measured / 0 gap / 1 stale, exit 1)
---
 apps/storybook/rtl-audit/verified-not-applicable.json | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 10bc3fe14400d..ab35c21da723c 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -1,14 +1,10 @@
 [
   {
     "component": "core/Spinner",
-    "reason": "No direction-sensitive visual, layout, or behavior. The ring is a concentric SVG — two <circle> elements sharing one center, sized by diameter and stroke, with no physical inset, offset, or asymmetry to mirror. Its only layout is the optional label wrapper, which is flexDirection: column + alignItems: center, so the label stacks below the ring on both axes' terms rather than beside it. The rotation keyframe (0deg to 360deg) is deliberately absolute: a loading spinner turns the same way in every locale, and mirroring it would be a bug, not RTL support."
-  },
-  {
-    "component": "core/Table",
-    "reason": "The Core/Table stories render native table rows and cells inside an overflow-x scroll wrapper. Column order, start/end alignment, column dividers and container bleed use table flow, text-align start/end, border-inline-end and logical inline margins, all resolved by CSS for the document direction. Horizontal overflow is native scrolling with no component-owned next/previous control or directional drag behavior, and these stories render no directional glyph or positioned element with a horizontal transform."
+    "reason": "No direction-sensitive visual, layout, or behavior. The ring is a concentric SVG \u2014 two <circle> elements sharing one center, sized by diameter and stroke, with no physical inset, offset, or asymmetry to mirror. Its only layout is the optional label wrapper, which is flexDirection: column + alignItems: center, so the label stacks below the ring on both axes' terms rather than beside it. The rotation keyframe (0deg to 360deg) is deliberately absolute: a loading spinner turns the same way in every locale, and mirroring it would be a bug, not RTL support."
   },
   {
     "component": "core/Text",
-    "reason": "Text sets typography — size, weight, colour, line-height, wrapping, truncation — and nothing else. Its one alignment prop is `justify`, which compiles to the logical `text-align: start | center | end` and defaults to `start`, so text hangs off the correct edge in either direction without a component-side branch. Truncation is `text-overflow: ellipsis` and `-webkit-line-clamp`, both of which put the ellipsis at the reading end on their own, and the tooltip that accompanies a clamped string is placed with the logical `above`/`below`/`start`/`end` vocabulary. Nothing is positioned, nothing is transformed, and the component renders no glyph, separator, or control."
+    "reason": "Text sets typography \u2014 size, weight, colour, line-height, wrapping, truncation \u2014 and nothing else. Its one alignment prop is `justify`, which compiles to the logical `text-align: start | center | end` and defaults to `start`, so text hangs off the correct edge in either direction without a component-side branch. Truncation is `text-overflow: ellipsis` and `-webkit-line-clamp`, both of which put the ellipsis at the reading end on their own, and the tooltip that accompanies a clamped string is placed with the logical `above`/`below`/`start`/`end` vocabulary. Nothing is positioned, nothing is transformed, and the component renders no glyph, separator, or control."
   }
 ]