@astryxdesign/core 0.6.1 → 0.6.2-canary.0faf070

package/src/Slider/Slider.test.tsx

@@ -13,6 +13,7 @@ import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {declaresPressedOverlay} from '../__tests__/pressState';
 import * as stylex from '@stylexjs/stylex';
 import {Slider} from './Slider';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -137,6 +138,24 @@ describe('Slider', () => {
     },
   );
 
+  it('reflects orientation and disabled state on the interactive control target', () => {
+    render(
+      <Slider
+        label="Volume"
+        value={50}
+        orientation="vertical"
+        valueDisplay="text"
+        isDisabled
+      />,
+    );
+    const control = screen.getByRole('slider').parentElement;
+    expect(control).not.toBeNull();
+    expect(control).toHaveClass('astryx-slider-control');
+    expect(control).toHaveAttribute('data-orientation', 'vertical');
+    expect(control).toHaveAttribute('data-disabled', 'disabled');
+    expect(control).not.toContainElement(screen.getByText('50'));
+  });
+
   it('range mode sets correct aria values on both thumbs', () => {
     render(
       <Slider
@@ -1083,3 +1102,130 @@ describe('Slider', () => {
     });
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay on the thumb for as long as it is dragged, from wherever the press lands', () => {
+    render(
+      <Slider label="Volume" value={50} min={0} max={100} onChange={vi.fn()} />,
+    );
+    const thumb = screen.getByRole('slider');
+    const trackContainer = thumb.parentElement!;
+    trackContainer.getBoundingClientRect = () => ({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 20,
+      width: 200,
+      height: 20,
+      x: 0,
+      y: 0,
+      toJSON: () => {},
+    });
+
+    expect(declaresPressedOverlay(thumb)).toBe(false);
+    // A slider is a drag: the press lands on the track, not the thumb, and
+    // the thumb follows it. The pressed paint follows the drag.
+    fireEvent.pointerDown(trackContainer, {
+      clientX: 20,
+      clientY: 10,
+      pointerId: 1,
+    });
+    expect(declaresPressedOverlay(thumb)).toBe(true);
+    fireEvent.pointerMove(trackContainer, {
+      clientX: 120,
+      clientY: 10,
+      pointerId: 1,
+    });
+    expect(declaresPressedOverlay(thumb)).toBe(true);
+    fireEvent.pointerUp(trackContainer, {
+      clientX: 120,
+      clientY: 10,
+      pointerId: 1,
+    });
+    expect(declaresPressedOverlay(thumb)).toBe(false);
+  });
+
+  it('paints only the thumb being dragged in a range slider', () => {
+    render(
+      <Slider
+        label="Price"
+        value={[20, 80] as [number, number]}
+        min={0}
+        max={100}
+        onChange={vi.fn()}
+      />,
+    );
+    const [start, end] = screen.getAllByRole('slider');
+    // In range mode the control is the group; each thumb sits in its own
+    // value-tooltip wrapper.
+    const trackContainer = screen.getByRole('group');
+    trackContainer.getBoundingClientRect = () => ({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 20,
+      width: 200,
+      height: 20,
+      x: 0,
+      y: 0,
+      toJSON: () => {},
+    });
+    fireEvent.pointerDown(trackContainer, {
+      clientX: 170,
+      clientY: 10,
+      pointerId: 1,
+    });
+    expect(declaresPressedOverlay(end)).toBe(true);
+    expect(declaresPressedOverlay(start)).toBe(false);
+    fireEvent.pointerUp(trackContainer, {
+      clientX: 170,
+      clientY: 10,
+      pointerId: 1,
+    });
+    expect(declaresPressedOverlay(end)).toBe(false);
+  });
+
+  it('keeps a direct press on the visible upper thumb when range values coincide', () => {
+    render(
+      <Slider
+        label="Price"
+        value={[50, 50] as [number, number]}
+        min={0}
+        max={100}
+        onChange={vi.fn()}
+      />,
+    );
+    const [start, end] = screen.getAllByRole('slider');
+    const trackContainer = screen.getByRole('group');
+    trackContainer.getBoundingClientRect = () => ({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 20,
+      width: 200,
+      height: 20,
+      x: 0,
+      y: 0,
+      toJSON: () => {},
+    });
+
+    fireEvent.pointerDown(end, {
+      clientX: 100,
+      clientY: 10,
+      pointerId: 1,
+    });
+    expect(declaresPressedOverlay(end)).toBe(true);
+    expect(declaresPressedOverlay(start)).toBe(false);
+  });
+
+  it('does not press a disabled slider', () => {
+    render(<Slider label="Volume" value={50} isDisabled onChange={vi.fn()} />);
+    const thumb = screen.getByRole('slider');
+    fireEvent.pointerDown(thumb.parentElement!, {
+      clientX: 20,
+      clientY: 10,
+      pointerId: 1,
+    });
+    expect(declaresPressedOverlay(thumb)).toBe(false);
+  });
+});

package/src/Slider/Slider.tsx

@@ -288,6 +288,15 @@ const styles = stylex.create({
       },
     },
   },
+  // Pressed: the system's pressed overlay over the thumb's fill for as long
+  // as the thumb is being dragged. A slider is a drag, not a tap — the finger
+  // lands anywhere on the track and the thumb follows it — so the pressed
+  // paint follows the drag state the pointer handlers already keep, on a
+  // mouse and on a finger alike, rather than `:active` on the thumb itself
+  // (which a press on the track never activates).
+  thumbPressed: {
+    backgroundImage: `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
+  },
   thumbDisabled: {
     backgroundColor: colorVars['--color-background-muted'],
     cursor: 'default',
@@ -701,17 +710,25 @@ export function Slider({ref, ...props}: SliderProps) {
       const newVal = markEl
         ? Number(markEl.dataset.markValue)
         : getValueFromPosition(e.clientX, e.clientY);
-      const thumbIndex = getClosestThumb(newVal);
+      const track = trackRef.current;
+      const thumbs = track?.querySelectorAll<HTMLElement>('[role="slider"]');
+      const pressedThumb = (e.target as Element).closest<HTMLElement>(
+        '[role="slider"]',
+      );
+      const pressedThumbIndex =
+        pressedThumb == null || thumbs == null
+          ? -1
+          : Array.from(thumbs).indexOf(pressedThumb);
+      // A direct thumb press owns that thumb even when range values coincide.
+      // Track and mark presses still choose the nearest value.
+      const thumbIndex =
+        pressedThumbIndex >= 0 ? pressedThumbIndex : getClosestThumb(newVal);
       draggingThumbRef.current = thumbIndex;
       setDraggingThumb(thumbIndex);
       updateValue(thumbIndex, newVal);
 
-      // Focus the closest thumb
-      const track = trackRef.current;
-      if (track) {
-        const thumbs = track.querySelectorAll<HTMLElement>('[role="slider"]');
-        thumbs[thumbIndex]?.focus();
-      }
+      // Focus the thumb that owns this drag.
+      thumbs?.[thumbIndex]?.focus();
       // Also clear it explicitly: focusing an already-focused thumb fires no
       // focus event, so a thumb the user had tabbed to would keep its ring
       // through the drag.
@@ -908,6 +925,7 @@ export function Slider({ref, ...props}: SliderProps) {
               ? styles.thumbHorizontal
               : rtlStyles.centerInline('50%'),
             !isDisabled && styles.thumbHover,
+            !isDisabled && draggingThumb === thumbIndex && styles.thumbPressed,
             !isDisabled &&
               keyboardFocusThumb === thumbIndex &&
               focusOutlineStyles.focusVisible,
@@ -1029,12 +1047,18 @@ export function Slider({ref, ...props}: SliderProps) {
           onPointerMove={handlePointerMove}
           onPointerUp={handlePointerUp}
           onPointerCancel={handlePointerUp}
-          {...stylex.props(
-            styles.trackContainer,
-            isHorizontal
-              ? styles.trackContainerHorizontal
-              : styles.trackContainerVertical,
-            isDisabled && styles.trackContainerDisabled,
+          {...mergeProps(
+            themeProps('slider-control', {
+              orientation,
+              disabled: isDisabled ? 'disabled' : null,
+            }),
+            stylex.props(
+              styles.trackContainer,
+              isHorizontal
+                ? styles.trackContainerHorizontal
+                : styles.trackContainerVertical,
+              isDisabled && styles.trackContainerDisabled,
+            ),
           )}>
           {/* Background track */}
           <div

package/src/Spinner/Spinner.doc.mjs

@@ -30,7 +30,7 @@ export const docs = {
       name: 'aria-label',
       type: 'string',
       description:
-        'Accessible name for screen readers. Defaults to label (if string) or "Loading".',
+        'Accessible name for screen readers. Defaults to label (if string) or a translated "Loading" from the i18n catalog.',
       default: "'Loading'",
     },
     {
@@ -48,6 +48,7 @@ export const docs = {
       {name: '--spinner-stroke-width', description: 'Stroke width of both circles the ring is drawn from: the moving arc and the track behind it. Set it per size alongside the diameter. One stroke width drives both, so 0 is honoured as a zero-width stroke and paints nothing at all rather than falling back to the default; for an arc with no track behind it, set --spinner-track-color to transparent instead.', default: '2px (sm), 3px (md), 3px (lg), 4px (xl)'},
       {name: '--spinner-color', description: "Color of the moving arc. Defaults to the shade's token, so set it on a shade-variant target to retheme one shade (spinner: { 'shade:subtle': { '--spinner-color': 'var(--color-text-tertiary)' } }), or on the base target to retheme all four. Accepts any color notation, including var(), color-mix() and currentColor.", default: 'var(--color-accent) (default), var(--color-text-secondary) (subtle), var(--color-on-dark) (onMedia), currentColor (inherit)'},
       {name: '--spinner-track-color', description: 'Color of the track the arc travels on. Set it to `transparent` for an arc with no track. The onMedia and inherit shades draw the track at reduced alpha (30%) so it reads against an arbitrary backdrop; that fade applies to a themed color too.', default: 'var(--color-track) (default, subtle), var(--color-on-dark) (onMedia), currentColor (inherit)'},
+      {name: '--spinner-arc-fraction', description: "Fraction of the ring the moving arc covers, as a plain number (not a percentage or angle). Set it on a size-variant target the same way as --spinner-diameter, e.g. spinner: { 'size:xl': { '--spinner-arc-fraction': '0.75' } } for a 270deg sweep. Only takes effect once the stylesheet loads; a render with no CSS (SSR, no-JS) always draws the default 135deg arc.", default: '0.375 (135deg), same for every size'},
     ],
   },
   usage: {
@@ -87,7 +88,7 @@ export const docsZh = {
     {
       name: 'aria-label',
       type: 'string',
-      description: '屏幕阅读器的无障碍名称。默认为 label（如果是字符串）或 "Loading"。',
+      description: '屏幕阅读器的无障碍名称。默认为 label（如果是字符串）或来自 i18n 词条的已翻译 "Loading"。',
       default: "'Loading'",
     },
     {
@@ -106,6 +107,7 @@ export const docsZh = {
       {name: '--spinner-stroke-width', description: '绘制环的两个圆——移动圆弧与其后的轨道——的描边宽度。与直径一起按尺寸设置。同一个描边宽度同时驱动两者，因此 0 会被采纳为零宽描边——什么都不绘制，而不会回退到默认值；若想要没有轨道的圆弧，请改将 --spinner-track-color 设为 transparent。', default: '2px (sm), 3px (md), 3px (lg), 4px (xl)'},
       {name: '--spinner-color', description: "运动圆弧的颜色。默认取所在 shade 的令牌，因此可在 shade 变体目标上设置以重新定义单个 shade——spinner: { 'shade:subtle': { '--spinner-color': 'var(--color-text-tertiary)' } }——或在 base 目标上设置以覆盖全部四种。接受任意颜色写法，包括 var()、color-mix() 与 currentColor。", default: 'var(--color-accent)（default）、var(--color-text-secondary)（subtle）、var(--color-on-dark)（onMedia）、currentColor（inherit）'},
       {name: '--spinner-track-color', description: '圆弧所在轨道的颜色。设为 `transparent` 可得到无轨道的圆弧。onMedia 与 inherit 两种 shade 会以降低的透明度（30%）绘制轨道，以便在任意背景上可辨；该淡化同样作用于主题化的颜色。', default: 'var(--color-track)（default、subtle）、var(--color-on-dark)（onMedia）、currentColor（inherit）'},
+      {name: '--spinner-arc-fraction', description: "运动圆弧覆盖圆环的比例，为纯数字（非百分比或角度）。在尺寸变体目标上设置，方式与 --spinner-diameter 相同，例如 spinner: { 'size:xl': { '--spinner-arc-fraction': '0.75' } } 可得到 270 度的圆弧。仅在样式表加载后生效；无 CSS 的渲染（SSR、无 JS）始终绘制默认的 135 度圆弧。", default: '0.375（135 度），各尺寸相同'},
     ],
   },
   usage: {
@@ -136,7 +138,8 @@ export const docsDense = {
     size: 'Spinner size: ring diameter (10px, 14px, 18px, 28px).',
     shade: 'Color shade for light or dark backgrounds.',
     label: 'Visible content below spinner. String auto-sets aria-label.',
-    'aria-label': 'A11y name for screen readers. Defaults to label or "Loading".',
+    'aria-label':
+      'A11y name for screen readers. Defaults to label or a translated "Loading".',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
   },
 };

package/src/Spinner/Spinner.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Spinner} from './Spinner';
+import {InternationalizationProvider} from '../i18n';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 
@@ -72,6 +73,34 @@ describe('Spinner', () => {
     expect(spinner).toHaveAttribute('data-shade', 'inherit');
   });
 
+  it('localizes the default assistive label through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.spinner.loading': 'Chargement'}}}>
+        <Spinner data-testid="spinner" />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByTestId('spinner')).toHaveAttribute(
+      'aria-label',
+      'Chargement',
+    );
+  });
+
+  it('keeps an explicit aria-label over the localized default', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.spinner.loading': 'Chargement'}}}>
+        <Spinner aria-label="Veuillez patienter" data-testid="spinner" />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByTestId('spinner')).toHaveAttribute(
+      'aria-label',
+      'Veuillez patienter',
+    );
+  });
+
   it('does not duplicate a visible string label as aria-label', () => {
     render(<Spinner label="Fetching data" data-testid="spinner" />);
     const status = screen.getByRole('status');
@@ -204,6 +233,14 @@ describe('Spinner', () => {
         '.astryx-spinner {\n    --spinner-color: var(--color-brand);',
       );
     });
+
+    it('scopes a themed arc fraction to that size variant (#5819)', () => {
+      expect(
+        cssFor({spinner: {'size:xl': {'--spinner-arc-fraction': '0.75'}}}),
+      ).toContain(
+        '.astryx-spinner[data-size="xl"] {\n    --spinner-arc-fraction: 0.75;',
+      );
+    });
   });
 });
 

package/src/Spinner/Spinner.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Spinner.tsx
- * @input Uses React, StyleX, SVG rendering
+ * @input Uses React, i18n (useTranslator), StyleX, SVG rendering
  * @output Exports Spinner component, SpinnerProps, SpinnerSize, SpinnerShade types
  * @position Core implementation of spinner loading indicator
  *
@@ -22,6 +22,7 @@ import {colorVars, durationVars, spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Text} from '../Text/Text';
 import {mergeProps} from '../utils';
+import {useTranslator} from '../i18n';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -29,20 +30,17 @@ import {themeProps} from '../utils/themeProps';
 // =============================================================================
 
 /**
- * Fraction of the ring the moving arc covers. The canvas ring this replaces
- * swept 135deg, not the 270deg its constant's comment claimed.
+ * Default fraction of the ring the moving arc covers. The canvas ring this
+ * replaces swept 135deg, not the 270deg its constant's comment claimed.
+ *
+ * Themeable via `--spinner-arc-fraction`, declared alongside the other public
+ * vars in `sizeStyles` below. Only the inline `strokeDasharray` attribute
+ * (the pre-stylesheet render — see its own comment) still reads this
+ * constant directly; the CSS side composes the dash from the live var.
  */
 const ARC_FRACTION = 0.375;
 
-/**
- * The dash pattern, per unit of diameter: one arc, then the gap that closes
- * the circle. The circumference is `pi x diameter`, so multiplying the
- * resolved diameter by these two constants gives exactly the lengths the
- * default render has always used, and scales them with a themed diameter.
- */
 const PI = 3.141592653589793;
-const ARC_DASH = PI * ARC_FRACTION;
-const ARC_GAP = PI * (1 - ARC_FRACTION);
 
 const SIZES = {
   sm: {diameter: 10, border: 2},
@@ -322,10 +320,16 @@ const styles = stylex.create({
   // of the circle — 87.398 against the 87.965 of pi x 28 — which shortens the
   // default arc by 0.64% and moves the cap by half a pixel. Composing the
   // lengths keeps the default byte-identical to what it drew before.
+  //
+  // The fraction itself also rides a public var (`--spinner-arc-fraction`),
+  // unregistered like the other three color/geometry public vars — it is
+  // read as a bare `<number>` multiplier here, never summed with a unitless
+  // `0` the way the registered length pair guards against, so it needs no
+  // registration.
   arc: {
     stroke: 'var(--spinner-color)',
     transform: 'rotate(-90deg)',
-    strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${ARC_DASH}) calc(var(${RESOLVED_DIAMETER}) * ${ARC_GAP})`,
+    strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${PI} * var(--spinner-arc-fraction)) calc(var(${RESOLVED_DIAMETER}) * ${PI} * (1 - var(--spinner-arc-fraction)))`,
   },
   track: {stroke: 'var(--spinner-track-color)'},
 });
@@ -348,22 +352,30 @@ const styles = stylex.create({
 // cost of its own — with nothing declaring the var,
 // `theme-var-reachability.js` cannot find an element to check, so a documented
 // var reads as unreachable.
+// Arc fraction is not itself size-dependent, but it declares alongside the
+// two vars that are, on the same per-size condition (`!hasLabel` gate at the
+// call site) — it needs a home on whichever element carries the theme
+// target, and this is the object already wired to be there.
 const sizeStyles = stylex.create({
   sm: {
     '--spinner-diameter': `${SIZES.sm.diameter}px`,
     '--spinner-stroke-width': `${SIZES.sm.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
   md: {
     '--spinner-diameter': `${SIZES.md.diameter}px`,
     '--spinner-stroke-width': `${SIZES.md.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
   lg: {
     '--spinner-diameter': `${SIZES.lg.diameter}px`,
     '--spinner-stroke-width': `${SIZES.lg.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
   xl: {
     '--spinner-diameter': `${SIZES.xl.diameter}px`,
     '--spinner-stroke-width': `${SIZES.xl.border}px`,
+    '--spinner-arc-fraction': `${ARC_FRACTION}`,
   },
 });
 
@@ -484,6 +496,7 @@ export function Spinner({
   const arcLength = circumference * ARC_FRACTION;
   const hasLabel = label != null;
   const labelId = useId();
+  const t = useTranslator();
 
   // When a visible string label renders (and no explicit aria-label is set),
   // name the status element from the visible Text via aria-labelledby instead
@@ -492,9 +505,13 @@ export function Spinner({
   const namedByVisibleLabel =
     hasLabel && typeof label === 'string' && ariaLabel == null;
 
-  // Resolve accessible name: explicit aria-label > string label > "Loading"
+  // Resolve accessible name: explicit aria-label > string label > the
+  // localized default. The fallback is AT-facing text, so it goes through the
+  // translation runtime like visible text does.
   const resolvedAriaLabel =
-    ariaLabel ?? (typeof label === 'string' ? label : undefined) ?? 'Loading';
+    ariaLabel ??
+    (typeof label === 'string' ? label : undefined) ??
+    t('@astryx.spinner.loading');
 
   const spinner = (
     <span

package/src/Switch/Switch.doc.mjs

@@ -210,6 +210,17 @@ export const docs = {
     ],
   },
   usage: {
+    accessibility: [
+      {
+        name: 'Track and thumb',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'The on and off tracks must each have at least 3:1 contrast with the surface behind them, and the thumb with its track. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied.',
+      },
+    ],
     anatomy,
     description:
       'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',

package/src/Switch/Switch.test.tsx

@@ -30,6 +30,7 @@ import {
   getAllInjectedCss,
   getForcedColorsRules,
 } from '../__tests__/forcedColors';
+import {hasPressedArm} from '../__tests__/pressState';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -755,6 +756,21 @@ describe('Switch', () => {
     });
   });
 
+  describe('pressed state', () => {
+    it('paints the pressed overlay on the track and the thumb while the row is pressed', () => {
+      const {container} = render(
+        <Switch label="Notifications" value={false} onChange={() => {}} />,
+      );
+      const track = container.querySelector('.astryx-switch');
+      const thumb = container.querySelector('.astryx-switch-thumb');
+      if (track == null || thumb == null) {
+        throw new Error('the switch has no track or thumb to press');
+      }
+      expect(hasPressedArm(track)).toBe(true);
+      expect(hasPressedArm(thumb)).toBe(true);
+    });
+  });
+
   describe('coarse pointer and RTL hit-target positioning', () => {
     it.each([
       ['sm', 'ltr'],

package/src/Switch/Switch.tsx

@@ -122,6 +122,15 @@ const thumbOnSizeStyles = stylex.create({
   },
 });
 
+// The pressed overlay, painted as a gradient layer OVER the track's and
+// thumb's own fills so it composes with the on/off colors and the hover tint
+// instead of replacing them. Same token Button's overlay paints with. The
+// switch is a two-part control whose focusable input sits beside the track,
+// so the press is read off the shared scope marker (the row), the way the
+// hover tint already is: pressing the input, the track or the label all
+// activate the row.
+const pressedImage = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
+
 const labelWrapperSizeStyles = stylex.create({
   sm: {
     minHeight: 20,
@@ -207,6 +216,15 @@ const styles = stylex.create({
       default: null,
       '@media (forced-colors: active)': 'CanvasText',
     },
+    // Pressed: the overlay rides on top of the on/off fill. Gated like the
+    // hover tint so forced colors keeps its system-color track.
+    backgroundImage: {
+      default: null,
+      [stylex.when.ancestor(':active', switchScope)]: {
+        default: null,
+        '@media (forced-colors: none)': pressedImage,
+      },
+    },
   },
   // The one ring in the system not drawn by focusOutlineStyles. The focusable
   // input is a sibling of the track, so the condition has to reach the shared
@@ -278,6 +296,16 @@ const styles = stylex.create({
       '@media (prefers-reduced-motion: reduce)': '0s',
     },
     transitionTimingFunction: easeVars['--ease-standard'],
+    // Pressed: the same overlay as the track, so the whole control darkens
+    // under the finger rather than the thumb standing out against a darker
+    // track.
+    backgroundImage: {
+      default: null,
+      [stylex.when.ancestor(':active', switchScope)]: {
+        default: null,
+        '@media (forced-colors: none)': pressedImage,
+      },
+    },
   },
   // The thumb fill lives on the on/off styles (not the shared thumb style)
   // because forced colors needs a per-state system color: CanvasText on the

package/src/TabList/Tab.tsx

@@ -137,6 +137,15 @@ const styles = stylex.create({
       [stylex.when.ancestor(':hover', tabScope)]: {
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
+      // Pressed: the same layer steps up to the pressed overlay, read off the
+      // tab the way the hover is, so a press paints on a finger too. Repeated
+      // inside the hover-capable branch so it outranks the hover rule there
+      // (a media-nested rule carries extra generated priority; see
+      // interactionOverlay.stylex.ts).
+      [stylex.when.ancestor(':active', tabScope)]: {
+        default: colorVars['--color-overlay-pressed'],
+        '@media (hover: hover)': colorVars['--color-overlay-pressed'],
+      },
     },
     transitionProperty: 'background-color',
     transitionDuration: durationVars['--duration-fast'],
@@ -249,6 +258,7 @@ export function Tab({
   xstyle,
   className,
   style,
+  onClick,
   ...restProps
 }: TabProps) {
   const tabListCtx = useTabListContext();
@@ -263,9 +273,23 @@ export function Tab({
   const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
   const hasVisibleLabel = !isLabelHidden && label !== '';
 
-  const handleSelect = useCallback(() => {
-    tabListCtx.onChange(value);
-  }, [tabListCtx, value]);
+  const isDisabled =
+    restProps['aria-disabled'] === true ||
+    restProps['aria-disabled'] === 'true';
+
+  const handleSelect = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => {
+      if (isDisabled) {
+        event.preventDefault();
+        return;
+      }
+      onClick?.(event as React.MouseEvent<HTMLButtonElement>);
+      if (!event.defaultPrevented) {
+        tabListCtx.onChange(value);
+      }
+    },
+    [isDisabled, onClick, tabListCtx, value],
+  );
 
   useDevWarning(
     'Tab',
@@ -339,7 +363,7 @@ export function Tab({
         sizeStyles[size],
         isSelected && styles.selected,
         isFill && layoutStyles.fill,
-        tabScope,
+        !isDisabled && tabScope,
         xstyle,
       ),
       className,
@@ -382,10 +406,14 @@ export function Tab({
   ) : null;
 
   if (isLink) {
+    // A disabled link tab must not reach a router component: some routers reject
+    // a missing destination, while others treat it as the current route. A
+    // plain anchor without href preserves the element shape but cannot navigate.
+    const LinkRoot = isDisabled ? 'a' : LinkComponent;
     return (
-      <LinkComponent
+      <LinkRoot
         ref={ref}
-        href={href}
+        href={isDisabled ? undefined : href}
         onClick={handleSelect}
         {...sharedProps}>
         {hoverBgElement}
@@ -393,7 +421,7 @@ export function Tab({
         {labelElement}
         {endContentElement}
         {indicatorElement}
-      </LinkComponent>
+      </LinkRoot>
     );
   }
 

package/src/TabList/TabList.doc.mjs

@@ -103,6 +103,17 @@ export const docs = {
     {name: 'TabMenu'},
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Tab label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down', 'Selected'],
+        description:
+          'Each label must have at least 4.5:1 contrast with the tab surface behind it. For Hover and Pointer down, measure the final background after the overlay layer is applied.',
+      },
+    ],
     description:
       'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
     bestPractices: [