@astryxdesign/core 0.6.1 → 0.6.2

package/src/Markdown/utils.ts

@@ -16,9 +16,15 @@ export {
 
 export type {
   InlineNode,
+  InlineNodeWithMath,
+  MathInlineNode,
   BlockNode,
+  BlockNodeWithMath,
+  MathBlockNode,
   ListItemNode,
   TableCellNode,
   TableAlignment,
+  ParseOptions,
+  MathParseOptions,
   IncrementalState,
 } from './parser';

package/src/Slider/Slider.doc.mjs

@@ -19,6 +19,12 @@ const anatomy = [
     description:
       'Control row containing the track, thumb or thumbs, and optional text value.',
   },
+  {
+    name: 'Interactive control',
+    required: true,
+    description:
+      'Pointer and keyboard interaction surface containing the rail, fill, marks, and thumbs.',
+  },
   {
     name: 'Track',
     required: true,
@@ -235,6 +241,11 @@ export const docs = {
         visualProps: ['orientation'],
         states: ['disabled'],
       },
+      {
+        className: 'astryx-slider-control',
+        visualProps: ['orientation'],
+        states: ['disabled'],
+      },
       {className: 'astryx-slider-track', visualProps: ['orientation']},
       {
         className: 'astryx-slider-thumb',
@@ -416,6 +427,11 @@ export const docsZh = {
         visualProps: ['orientation'],
         states: ['disabled'],
       },
+      {
+        className: 'astryx-slider-control',
+        visualProps: ['orientation'],
+        states: ['disabled'],
+      },
       {className: 'astryx-slider-track', visualProps: ['orientation']},
       {
         className: 'astryx-slider-thumb',

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

@@ -137,6 +137,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

package/src/Slider/Slider.tsx

@@ -1029,12 +1029,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/theme/derivedVarRegistry.test.ts

@@ -310,15 +310,17 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([
   // It is one component of one shadow in the list, so no standard property
   // maps onto it either — a theme sets it beside the fill it has to contrast.
   '--selectable-card-ring-color',
-  // The spinner's ring is drawn as an SVG circle, so none of its four vars is
+  // The spinner's ring is drawn as an SVG circle, so none of its five vars is
   // a CSS property of the element carrying the theme target: `width` and
-  // `borderWidth` would name a box the ring is not, and a `color` mapping
-  // would take the label's text color with it. They are public vars a theme
-  // sets directly under a size- or shade-variant key.
+  // `borderWidth` would name a box the ring is not, a `color` mapping would
+  // take the label's text color with it, and the arc fraction is a pure
+  // dash-length multiplier with no standard property to attach to. They are
+  // public vars a theme sets directly under a size- or shade-variant key.
   '--spinner-diameter',
   '--spinner-stroke-width',
   '--spinner-color',
   '--spinner-track-color',
+  '--spinner-arc-fraction',
 ]);
 
 // ---------------------------------------------------------------------------