@astryxdesign/core 0.6.1 → 0.6.2-canary.023c3e4

package/src/Slider/Slider.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 4
 kind: component
 id: component:Slider
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-09-14
 owners: [cixzhang]
 review_triggers: [theming]
 verified_by:
@@ -29,14 +29,14 @@ system_specs: []
 ## Intent
 
 Slider presents a labeled control for selecting one numeric value or a bounded
-range. This draft records its current consumer anatomy and theming ownership
-without changing runtime behavior, styling, targets, or public API.
+range. This contract records its consumer anatomy and theming ownership, including
+an additive target for the interactive control surface.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
+- Compatibility class: additive target and state reflection only; runtime,
+  default styling, DOM semantics, and public props remain unchanged
 - Controlled/uncontrolled behavior: unchanged; Slider remains controlled
 - Migration decision: none
 
@@ -48,7 +48,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The current slider row, background track, filled range, tick marks and labels,
   thumbs, and adjacent text value presentation.
-- The existing `slider`, `slider-track`, and `slider-thumb` public targets.
+- The `slider`, `slider-control`, `slider-track`, and `slider-thumb` public
+  targets.
 
 **Does not own / non-goals**
 
@@ -61,24 +62,26 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props, modes, states, and usage
-remain documented in `Slider.doc.mjs`.
+This adds one public theming target without adding or changing a component prop,
+value domain, or behavior. Consumer props, modes, states, and usage remain
+documented in `Slider.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                       | Basis                                   | Draft review state                                 |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
-| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                           | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
-| FR2 | `Slider`, `Track`, and `Thumb` carry the existing `slider`, `slider-track`, and `slider-thumb` targets respectively.                      | Current source and public docs          | Verified current behavior; no target change        |
-| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs          | Verified current asymmetry; not ratified as policy |
-| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                              | Current source and focused tests        | Verified composition boundary                      |
+| ID  | Candidate invariant                                                                                                                                  | Basis                                   | Review state                                       |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                                      | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively. | Current source, public docs, and #6224  | Approved additive target contract                  |
+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target.            | Current source and public docs          | Verified current asymmetry; not ratified as policy |
+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                                         | Current source and focused tests        | Verified composition boundary                      |
 
 ### Observed current target asymmetry
 
 ProgressBar currently exposes targets for its fill and marks, while Slider
-exposes targets for its root row, background track, and thumbs but not its
-filled range, tick marks, mark labels, or adjacent text value display. This is
-implementation evidence for a joint audit, not approval of either target shape.
+exposes targets for its root row, interactive control, background track, and
+thumbs but not its filled range, tick marks, mark labels, or adjacent text value
+display. This is implementation evidence for a joint audit, not approval of
+either component's remaining target shape.
 
 ### Allowed variation
 
@@ -108,20 +111,21 @@ implementation evidence for a joint audit, not approval of either target shape.
 
 ## Accessibility contract
 
-This draft does not change or extend Slider's existing accessible name, value,
+This contract does not change or extend Slider's existing accessible name, value,
 range-thumb naming, description/status association, keyboard behavior, disabled
 behavior, or value-tooltip behavior.
 
 ## Design relationships
 
-| Anatomy or state        | Design requirement                                            | Representation authority        | Hierarchy role | Component contract |
-| ----------------------- | ------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
-| Label and description   | Identify and explain the numeric setting.                     | Current shared-component source | Supporting     | FR4                |
-| Slider and track        | Arrange the current interactive range control and rail.       | Current source and public docs  | Prominent      | FR1, FR2           |
-| Filled range and thumbs | Show the selected value or interval over the available range. | Current source and public docs  | Prominent      | FR1, FR2, FR3      |
-| Tick marks and labels   | Show optional supplied positions and their text.              | Current source and public docs  | Supporting     | FR1, FR3           |
-| Value presentation      | Shows the formatted value as text or a shared Tooltip.        | Current source and public docs  | Supporting     | FR3, FR4           |
-| Status message          | Presents shared validation feedback below the slider.         | Current shared-component source | Supporting     | FR4                |
+| Anatomy or state               | Design requirement                                                                             | Representation authority        | Hierarchy role | Component contract |
+| ------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
+| Label and description          | Identify and explain the numeric setting.                                                      | Current shared-component source | Supporting     | FR4                |
+| Slider and interactive control | Separate the outer row from the pointer/keyboard surface and its composite disabled treatment. | Current source and public docs  | Prominent      | FR1, FR2           |
+| Track                          | Shows the available range behind the fill.                                                     | Current source and public docs  | Prominent      | FR1, FR2           |
+| Filled range and thumbs        | Show the selected value or interval over the available range.                                  | Current source and public docs  | Prominent      | FR1, FR2, FR3      |
+| Tick marks and labels          | Show optional supplied positions and their text.                                               | Current source and public docs  | Supporting     | FR1, FR3           |
+| Value presentation             | Shows the formatted value as text or a shared Tooltip.                                         | Current source and public docs  | Supporting     | FR3, FR4           |
+| Status message                 | Presents shared validation feedback below the slider.                                          | Current shared-component source | Supporting     | FR4                |
 
 ### Theming anatomy
 
@@ -138,6 +142,7 @@ behavior, or value-tooltip behavior.
     }
   },
   "Slider": {"target": "slider"},
+  "Interactive control": {"target": "slider-control"},
   "Track": {"target": "slider-track"},
   "Filled range": {
     "none": {
@@ -172,10 +177,12 @@ behavior, or value-tooltip behavior.
 }
 ```
 
-`Filled range`, `Tick mark`, `Mark label`, and `Value display` remain stable
-consumer anatomy, but no current Slider target reaches them. The map records
-those gaps without making their absence intentional. `Value display` names the
-adjacent text mode; the separately listed value tooltip retains Tooltip's target.
+`Interactive control` names the pointer/keyboard hit surface and the composite
+opacity boundary around the rail, fill, marks, and thumbs. `Filled range`, `Tick
+mark`, `Mark label`, and `Value display` remain stable consumer anatomy, but no
+current Slider target reaches them. The map records those gaps without making
+their absence intentional. `Value display` names the adjacent text mode; the
+separately listed value tooltip retains Tooltip's target.
 
 ## Family and system relationships
 
@@ -191,24 +198,31 @@ adjacent text mode; the separately listed value tooltip retains Tooltip's target
 
 ## Verification map
 
-| Contract            | Verification                                                                           | Representative states                             | Mutation or failure expectation                                                                                      | Audit section          |
-| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                   | Single, range, horizontal, vertical, marks        | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                             | `audit:Slider/anatomy` |
-| FR2                 | `themingTargets.test.ts`                                                               | Root, track, and thumb target call sites          | Source and public target metadata drift fails the target guard.                                                      | `audit:Slider/theming` |
-| FR3                 | Source and consumer-doc review                                                         | Filled range, marks, labels, adjacent text value  | A missing target is inaccurately documented as present or intentionally permanent.                                   | `audit:Slider/theming` |
-| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only | Label, status, value tooltip, disabled reason     | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage. | `audit:Slider/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                          | Canonical anatomy and three current local targets | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                   | `audit:Slider/theming` |
+| Contract            | Verification                                                                           | Representative states                                                 | Mutation or failure expectation                                                                                      | Audit section          |
+| ------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                   | Single, range, horizontal, vertical, marks                            | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                             | `audit:Slider/anatomy` |
+| FR2                 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium       | Root, horizontal/vertical control, disabled control, track, and thumb | A target class/state is missing, undocumented, or placed outside its owning anatomy.                                 | `audit:Slider/theming` |
+| FR3                 | Source and consumer-doc review                                                         | Filled range, marks, labels, adjacent text value                      | A missing target is inaccurately documented as present or intentionally permanent.                                   | `audit:Slider/theming` |
+| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only | Label, status, value tooltip, disabled reason                         | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage. | `audit:Slider/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                          | Canonical anatomy and four current local targets                      | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                   | `audit:Slider/theming` |
 
-The focused Slider suite does not separately assert the exact `slider`,
-`slider-track`, or `slider-thumb` class placement. The source/metadata target
-guard covers those declarations. It also covers only the disabled-reason
-Tooltip path, not the `valueDisplay="tooltip"` composition; that anatomy is
-source-inspected and remains missing focused test coverage.
+The focused Slider suite asserts the `slider-control` target's orientation and
+disabled state. Source/metadata guards cover all four target declarations. The
+suite covers only the disabled-reason Tooltip path, not the
+`valueDisplay="tooltip"` composition; that anatomy is source-inspected and
+remains missing focused test coverage.
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-family, theming, or API decision.
+### DEC-1 — Interactive control is public Slider anatomy
+
+**Reference:** `component:Slider/DEC-1`
+**Decider:** cixzhang, 2026-09-14
+
+The stable pointer/keyboard interaction and compositing surface is a
+consumer-recognizable part, so it carries `slider-control`. `Thumb` remains
+separate anatomy and continues to carry `slider-thumb`. This adds no default
+behavior or styling change.
 
 ## Open questions
 

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;',
+      );
+    });
   });
 });
 
@@ -367,6 +404,10 @@ describe('Spinner ring', () => {
       frames.forEach(cb => cb(0));
       expect(animations).toHaveLength(5);
       expect(animations.every(a => a.startTime === 0)).toBe(true);
+      // The dash animation lives on the arc <circle>, a descendant of the
+      // <svg> this ref sits on, not the <svg> itself (#6253) — subtree:true
+      // is what lets getAnimations() find it from here.
+      expect(getAnimations).toHaveBeenCalledWith({subtree: true});
       // The pin runs on the branch the other shade cases cannot reach, so the
       // no-read assertion is made here too.
       expect(