@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/Slider/Slider.tsx

@@ -5,7 +5,7 @@
 /**
  * @file Slider.tsx
  * @input Uses React, useId, useRef, useCallback, useEffect, Field, Tooltip, useTooltip, VisuallyHidden
- * @output Exports Slider and its props; unfilled marks share the track token; modifier-only key presses do not restore the thumb focus ring; a drag belongs to the pointer that started it
+ * @output Exports Slider and its props; unfilled marks share the track token; modifier-only key presses do not restore the thumb focus ring; a drag belongs to the pointer that started it; two coincident range thumbs separate toward the press or the first movement
  * @position Core implementation; consumed by index.ts, tested by Slider.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -45,10 +45,7 @@ import type {InputStatus} from '../Field/types';
 import {mergeProps, rtlStyles} from '../utils';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {joinAriaIDs} from '../utils/inputAria';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {isRtlElement} from '../hooks/isRtlElement';
 import {
   type FieldInputBaseProps,
@@ -58,6 +55,8 @@ import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import {useTranslator} from '../i18n';
 // =============================================================================
 // Types
 // =============================================================================
@@ -512,6 +511,7 @@ export function Slider({ref, ...props}: SliderProps) {
     'aria-describedby': ariaDescribedByProp,
     ...restWithRange
   } = props;
+  const t = useTranslator();
   const {minStepsBetweenThumbs: _minSteps, ...restProps} =
     restWithRange as typeof restWithRange & {minStepsBetweenThumbs?: number};
   const {rest, container} = useFieldInputStyling('Slider', restProps, {
@@ -557,16 +557,14 @@ export function Slider({ref, ...props}: SliderProps) {
     null,
   );
 
-  useInteractionModalityTracking();
+  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
 
   const handleThumbFocus = useCallback(
     (thumbIndex: number, _e: FocusEvent<HTMLDivElement>) => {
       // A focused disabled thumb still shows the ring (spec:AST-085 FR6).
-      setKeyboardFocusThumb(
-        getInteractionModality() === 'keyboard' ? thumbIndex : null,
-      );
+      setKeyboardFocusThumb(readModality() === 'keyboard' ? thumbIndex : null);
     },
-    [],
+    [readModality],
   );
 
   const handleThumbBlur = useCallback((_e: FocusEvent<HTMLDivElement>) => {
@@ -591,7 +589,9 @@ export function Slider({ref, ...props}: SliderProps) {
   // role="slider" in WAI-ARIA 1.2, so the thumb instead points its
   // aria-describedby at a visually hidden "Required" span — mirroring the
   // Field label's visible indicator (where isOptional takes precedence).
-  const conveysRequired = isRequired && !isOptional;
+  // A surrounding FormLayout's defaultOptionality="required" makes an unmarked
+  // field required too (FormLayout FR5).
+  const conveysRequired = useResolvedRequired({isRequired, isOptional});
 
   // Build aria-describedby
   const describedByParts: string[] = [];
@@ -667,8 +667,24 @@ export function Slider({ref, ...props}: SliderProps) {
     [isRange, values],
   );
 
+  // The pointer's value at a press on two coincident thumbs, while no
+  // movement has said which way the drag goes; the first value off it picks
+  // the thumb that can travel that way (see handlePointerMove).
+  const coincidentDragRef = useRef<number | null>(null);
+  // Whether the drag in progress began on two coincident thumbs: such a drag
+  // can always follow the pointer, so when the dragged thumb is held against
+  // the other one and the pointer passes it, the other thumb takes the drag.
+  const coincidentOriginRef = useRef(false);
+
   const updateValue = useCallback(
-    (thumbIndex: number, newVal: number, snap = true) => {
+    (
+      thumbIndex: number,
+      newVal: number,
+      snap = true,
+      // The other thumb's values to start from, when one event moves both
+      // (a drag handed from one coincident thumb to the other).
+      from: ReadonlyArray<number> = values,
+    ) => {
       if (isDisabled) {
         return;
       }
@@ -682,7 +698,7 @@ export function Slider({ref, ...props}: SliderProps) {
       );
 
       if (isRange) {
-        const currentValues = [...values] as [number, number];
+        const currentValues = [...from] as [number, number];
         currentValues[thumbIndex] = clamped;
 
         // Enforce minStepsBetweenThumbs
@@ -760,6 +776,8 @@ export function Slider({ref, ...props}: SliderProps) {
         detachLostCaptureRef.current = null;
         draggingThumbRef.current = null;
         dragPointerRef.current = null;
+        coincidentDragRef.current = null;
+        coincidentOriginRef.current = false;
         setDraggingThumb(null);
         fireChangeEnd();
       }
@@ -799,13 +817,41 @@ export function Slider({ref, ...props}: SliderProps) {
         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 =
+      // A direct thumb press owns that thumb; track and mark presses choose
+      // the nearest value. Two thumbs on one value are the exception: only
+      // one of them can travel toward where the pointer goes. A track press
+      // beside them picks the thumb on its side. A press on the thumbs
+      // themselves (or on their shared value) moves nothing: the pressed
+      // thumb holds the press until the pointer moves, and the direction of
+      // that first movement from the press picks the thumb.
+      const isCoincident = isRange && values[0] === values[1];
+      let thumbIndex =
         pressedThumbIndex >= 0 ? pressedThumbIndex : getClosestThumb(newVal);
+      const parks =
+        isCoincident && (pressedThumbIndex >= 0 || newVal === values[0]);
+      // Until the first movement, a parked press is held by the upper thumb,
+      // the one drawn over the lower one, wherever it landed: on the thumbs
+      // (which the upper thumb covers) or on their shared value elsewhere,
+      // such as its mark label. So its pressed paint shows, and a press that
+      // never moves leaves focus on the same thumb.
+      if (parks && pressedThumbIndex < 0) {
+        thumbIndex = 1;
+      }
+      // The first movement is measured from the pointer itself, not from a
+      // mark it pressed (a wide label sits away from its mark's value).
+      coincidentDragRef.current = parks
+        ? getValueFromPosition(e.clientX, e.clientY)
+        : null;
+      // Only a drag that began on the shared thumbs, the press that waited for
+      // the first movement, hands itself to the other thumb (FR6); a track
+      // press beside them already picked its thumb.
+      coincidentOriginRef.current = parks;
+      if (isCoincident && !parks) {
+        thumbIndex = newVal > values[0] ? 1 : 0;
+      }
       draggingThumbRef.current = thumbIndex;
       setDraggingThumb(thumbIndex);
-      updateValue(thumbIndex, newVal);
+      updateValue(thumbIndex, parks ? values[thumbIndex] : newVal);
 
       // Focus the thumb that owns this drag.
       thumbs?.[thumbIndex]?.focus();
@@ -834,7 +880,15 @@ export function Slider({ref, ...props}: SliderProps) {
         (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
       }
     },
-    [isDisabled, getValueFromPosition, getClosestThumb, updateValue, endDrag],
+    [
+      isDisabled,
+      isRange,
+      values,
+      getValueFromPosition,
+      getClosestThumb,
+      updateValue,
+      endDrag,
+    ],
   );
 
   const handlePointerMove = useCallback(
@@ -847,6 +901,48 @@ export function Slider({ref, ...props}: SliderProps) {
         return;
       }
       const newVal = getValueFromPosition(e.clientX, e.clientY);
+      // Hands the drag to a thumb, with its focus and pressed paint.
+      const handTo = (thumbIndex: number) => {
+        if (thumbIndex === draggingThumbRef.current) {
+          return;
+        }
+        draggingThumbRef.current = thumbIndex;
+        setDraggingThumb(thumbIndex);
+        const thumbs =
+          trackRef.current?.querySelectorAll<HTMLElement>('[role="slider"]');
+        thumbs?.[thumbIndex]?.focus();
+        setKeyboardFocusThumb(null);
+      };
+      const pressValue = coincidentDragRef.current;
+      if (pressValue !== null) {
+        if (newVal === pressValue) {
+          return;
+        }
+        // The first movement from a press on coincident thumbs hands the
+        // drag to the thumb that can travel that way.
+        coincidentDragRef.current = null;
+        handTo(newVal > pressValue ? 1 : 0);
+      } else if (coincidentOriginRef.current) {
+        // A drag that began on coincident thumbs follows the pointer either
+        // way: once the pointer passes the other thumb, the dragged one stops
+        // against it and the other takes the drag (a first step that drifted
+        // the wrong way never sticks the drag).
+        const current = valuesRef.current;
+        const dragging = draggingThumbRef.current;
+        const other = dragging === 0 ? 1 : 0;
+        if (
+          (dragging === 0 && newVal > current[1]) ||
+          (dragging === 1 && newVal < current[0])
+        ) {
+          // The dragged thumb ends against the other one, as if it had
+          // followed the pointer there, and the other follows the pointer on.
+          const from = [...current];
+          from[dragging] = current[other];
+          handTo(other);
+          updateValue(other, newVal, true, from);
+          return;
+        }
+      }
       updateValue(draggingThumbRef.current, newVal);
     },
     [isDisabled, getValueFromPosition, updateValue],
@@ -874,7 +970,7 @@ export function Slider({ref, ...props}: SliderProps) {
         !e.metaKey &&
         !e.altKey &&
         !e.ctrlKey &&
-        getInteractionModality() === 'keyboard'
+        readModality() === 'keyboard'
       ) {
         setKeyboardFocusThumb(thumbIndex);
       }
@@ -954,6 +1050,7 @@ export function Slider({ref, ...props}: SliderProps) {
       minStepsBetweenThumbs,
       updateValue,
       fireChangeEnd,
+      readModality,
     ],
   );
 
@@ -980,8 +1077,8 @@ export function Slider({ref, ...props}: SliderProps) {
     // name from the visible label element via aria-labelledby.
     const thumbLabel = isRange
       ? thumbIndex === 0
-        ? 'Minimum value'
-        : 'Maximum value'
+        ? t('@astryx.slider.minimumThumb')
+        : t('@astryx.slider.maximumThumb')
       : undefined;
 
     // ARIA bounds must agree with the movement clamping in updateValue: in
@@ -1065,7 +1162,11 @@ export function Slider({ref, ...props}: SliderProps) {
           placement={tooltipPlacement}
           delay={0}
           focusTrigger="always"
-          isOpen={draggingThumb === thumbIndex ? true : undefined}>
+          // A drag keeps its own thumb's value showing and closes the other
+          // thumb's, which a drag handed over from it may have forced open.
+          isOpen={
+            draggingThumb === null ? undefined : draggingThumb === thumbIndex
+          }>
           {thumbElement}
         </Tooltip>
       );
@@ -1169,6 +1270,7 @@ export function Slider({ref, ...props}: SliderProps) {
           ref={useMergedRefs(
             isRange ? ref : undefined,
             trackRef,
+            modalityRef,
             disabledMessageTooltip.ref,
           )}
           {...(isRange

package/src/Spinner/Spinner.tsx

@@ -21,8 +21,8 @@ import * as stylex from '@stylexjs/stylex';
 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 {mergeProps} from '../utils/mergeProps';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -334,7 +334,9 @@ const styles = stylex.create({
     // it (a frozen spinner reads as broken), matching ProgressBar's approach.
     // The role="status" + "Loading" label still convey busy state (obs-6).
     animationDuration: {
-      default: durationVars['--duration-slow-min'],
+      // The loop reads the duration before a theme's tempo scales it
+      // (spec:AST-108 FR4).
+      default: `var(--_astryx-pre-tempo-duration-slow-min, ${durationVars['--duration-slow-min']})`,
       '@media (prefers-reduced-motion: reduce)': '3s',
     },
     animationIterationCount: 'infinite',

package/src/Stack/Stack.tsx

@@ -30,7 +30,7 @@ import {
   paddingBlockStartStyles,
   paddingBlockEndStyles,
 } from '../Layout/padding.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const overflowStyles = stylex.create({

package/src/Stack/StackItem.tsx

@@ -19,7 +19,7 @@ import {
   type StackItemCrossAlignSelf,
   type StackItemSize,
 } from './stackItem.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const overflowStyles = stylex.create({

package/src/StatusDot/StatusDot.spec.md

@@ -28,22 +28,22 @@ architecture:
     architecture:theme-tokens,
   ]
 contributing: []
-system_specs: [spec:AST-009]
+system_specs: [spec:AST-009, spec:AST-094]
 ---
 
 # StatusDot component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                             |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | A fixed 8px status dot with a required theme-extensible `variant` and a required `label`, plus optional `isPulsing`, `tooltip`, and `icon`.                                                          |
-| Behavior                | The dot is an image named by `label`; a renderable `icon` paints inside it in the variant's ink and is hidden from assistive technology; a tooltip is reachable by hover, touch, and keyboard (FR5). |
-| End-user impact         | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark.                                                    |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                         |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Three gaps are listed under Current-state impact.                                                                         |
-| Review checks           | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target.       |
-| Governing rules         | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:theme-tokens/INV11`; WCAG 2.2 2.1.1.                                     |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A fixed 8px status dot with a required theme-extensible `variant` and a required `label`, plus optional `isPulsing`, `tooltip`, and `icon`.                                                                                                                                                                                                                                                                                                                 |
+| Behavior                | The dot is an image named by `label`; a renderable `icon` paints inside it in the variant's ink and is hidden from assistive technology; a standalone dot with a tooltip is a button named by `label` whose press pins the tooltip (`pressTrigger="toggle"`), so the tooltip is reachable by hover, touch, and keyboard; inside a button, link, menu item, or option, the dot stays an image and the host's accessible name carries the tooltip text (FR5). |
+| End-user impact         | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark. Inside a button, link, menu item, or option, sighted touch users lose the dot's visible tooltip text, and the host's accessible name carries the status for screen readers (FR5).                                                                                                                         |
+| Builder impact          | StatusDot decides by placement. A standalone dot with a tooltip is a toggle button; inside a button, link, menu item, or option, the host carries the status in its accessible name, so a control never nests another control (FR5). A host named by `aria-label`, such as a Tab with `isLabelHidden`, takes no name from its content, so its caller includes the status in that label.                                                                     |
+| Compatibility/readiness | No API or default change; a standalone dot with a tooltip becomes a button trigger with `pressTrigger="toggle"` no later than `component:Tooltip` FR5's walk ships, and a dot inside an interactive element hands its tooltip text to the host (FR5, not yet built). Three gaps are listed under Current-state impact.                                                                                                                                      |
+| Review checks           | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target.                                                                                                                                                                                                                                                              |
+| Governing rules         | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:theme-tokens/INV11`; WCAG 2.2 2.1.1.                                                                                                                                                                                                                                                                                            |
 
 This table is a review projection; the body below is authoritative.
 
@@ -56,8 +56,11 @@ optional pulse, optional inner mark, and its accessible name.
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes. The dot emits only the canonical `status-dot`
+- Compatibility class: no public prop, default, or styling output change; with a
+  `tooltip`, a standalone dot becomes a button named by `label` inside Tooltip
+  with `pressTrigger="toggle"`, adopted no later than `component:Tooltip`
+  FR5's walk ships with its CLN-0024, and a dot inside a button, link, menu item, or option
+  stays an image whose tooltip text joins the host's accessible name (FR5). The dot emits only the canonical `status-dot`
   target; the `statusdot` alias is not emitted
 - Controlled/uncontrolled behavior: not applicable; StatusDot holds no state
 - Migration decision: none
@@ -74,7 +77,14 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **Tooltip not reachable by keyboard (FR5).** The dot has no tab stop, so
   Tooltip attaches no focus trigger and sighted keyboard users cannot reveal
   the tooltip text, where WCAG 2.2 2.1.1 expects functionality to be keyboard
-  operable. The accessible name still carries the status.
+  operable. The accessible name still carries the status. Today a tap opens a
+  dot's tooltip, because the dot performs no action and Tooltip's default
+  `auto` opens on such a tap, and a standalone dot does not yet take
+  `pressTrigger="toggle"`, so its tooltip has no pin for touch or keyboard.
+  FR5 changes a dot inside a button, link, menu item, or option to an image
+  whose tooltip previews on hover only, so sighted touch users lose its visible
+  tooltip text there; the host's accessible name carries the status for screen
+  readers.
 - **Accent and neutral dots in forced colors (FR2).** The `accent` and
   `neutral` dots draw no border, so in forced-colors mode they lose their plate
   and disappear; no current record sets their treatment (OQ1). The accessible
@@ -89,7 +99,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 - The pulse and its reduced-motion suppression.
 - The assistive-technology-hidden wrapper that places optional icon content
   inside the dot.
-- The dot's image role and accessible name.
+- The dot's image role, its button role when it is standalone with a tooltip,
+  and its accessible name.
 
 **Does not own / non-goals**
 
@@ -103,23 +114,23 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept          | Closed values or states                                             | Meaning                                                             | Availability by variant/orientation/state | Default  | Owner                 | Stability | Invalid-value behavior                                                                                                                      |
-| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tone (`variant`) | `success`, `warning`, `error`, `accent`, `neutral`; theme additions | Selects the plate color and the ink an icon paints with.            | All dots                                  | Required | `component:StatusDot` | Stable    | A theme-added value is reflected on `status-dot` and keeps a safe theme-independent baseline (FR2); TypeScript rejects unregistered values. |
-| Pulse            | resting; pulsing                                                    | Signals ongoing activity by fading the dot in and out.              | All tones                                 | resting  | `component:StatusDot` | Stable    | —                                                                                                                                           |
-| Status icon      | present when `icon` is renderable; absent                           | Adds a non-color mark inside the dot.                               | All tones                                 | absent   | `component:StatusDot` | Stable    | `false`, `true`, `null`, `undefined`, and `''` render no icon wrapper.                                                                      |
-| Tooltip          | present when `tooltip` is a non-empty string; absent                | Explains the status; reachable by hover, touch, and keyboard (FR5). | All tones                                 | absent   | `component:StatusDot` | Stable    | An empty string renders no tooltip.                                                                                                         |
+| Concept          | Closed values or states                                             | Meaning                                                                                                                                                                             | Availability by variant/orientation/state | Default  | Owner                 | Stability | Invalid-value behavior                                                                                                                      |
+| ---------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tone (`variant`) | `success`, `warning`, `error`, `accent`, `neutral`; theme additions | Selects the plate color and the ink an icon paints with.                                                                                                                            | All dots                                  | Required | `component:StatusDot` | Stable    | A theme-added value is reflected on `status-dot` and keeps a safe theme-independent baseline (FR2); TypeScript rejects unregistered values. |
+| Pulse            | resting; pulsing                                                    | Signals ongoing activity by fading the dot in and out.                                                                                                                              | All tones                                 | resting  | `component:StatusDot` | Stable    | —                                                                                                                                           |
+| Status icon      | present when `icon` is renderable; absent                           | Adds a non-color mark inside the dot.                                                                                                                                               | All tones                                 | absent   | `component:StatusDot` | Stable    | `false`, `true`, `null`, `undefined`, and `''` render no icon wrapper.                                                                      |
+| Tooltip          | present when `tooltip` is a non-empty string; absent                | Explains the status; a standalone dot becomes a button whose press pins it, reachable by hover, touch, and keyboard; inside an interactive element the host carries the text (FR5). | All tones                                 | absent   | `component:StatusDot` | Stable    | An empty string renders no tooltip.                                                                                                         |
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                    |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
-| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
-| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests |
-| FR5 | A non-empty `tooltip` wraps the dot in Tooltip with that text; otherwise no tooltip renders. A tooltip opens from the keyboard as well as on hover and touch (WCAG 2.2 2.1.1). Implementation gap: the dot has no tab stop, so the tooltip opens on hover and touch only (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
-| FR6 | `ref` reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                               |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests                            |
+| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests                            |
+| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests                            |
+| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source and tests                            |
+| FR5 | A non-empty `tooltip` renders by placement; without one, no tooltip renders. A standalone dot is wrapped in Tooltip with that text and `pressTrigger="toggle"` and is the toggle's button trigger, named by `label`, so hover and keyboard focus preview the tooltip and a tap, click, Enter, or Space pins it (`component:Tooltip` FR9), and keyboard users reach it (WCAG 2.2 2.1.1). StatusDot adopts the toggle no later than `component:Tooltip` FR5's walk ships, so a standalone dot's tooltip stays reachable on touch. A dot inside an interactive element (a button, link, menu item, or option) is a non-interactive image wrapped in Tooltip without the toggle, because a control cannot nest another control: its tooltip previews on hover only, and its tooltip text joins the host's accessible name, so the host carries the status for screen readers (`architecture:interaction-modality` INV4). A host named by `aria-label` takes no name from its content, so its caller includes the status in that label. Implementation gap: the dot has no tab stop and uses Tooltip's default touch trigger, so the tooltip opens on hover and touch only (Current-state impact). | Current source and tests; `component:Tooltip` DEC-1 |
+| FR6 | `ref` reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests                            |
 
 ### Allowed variation
 
@@ -130,33 +141,45 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State        | Required invariant                                                     | Allowed variation |
-| ------------ | ---------------------------------------------------------------------- | ----------------- |
-| Plain dot    | Childless image named by `label`; not focusable.                       | Tone.             |
-| With icon    | Icon inside an `aria-hidden` wrapper; the dot keeps its role and name. | Artwork.          |
-| Pulsing      | Opacity pulse runs; with reduced motion requested, it does not.        | Tone.             |
-| With tooltip | Dot keeps its role and name; Tooltip owns the surface.                 | Tooltip text.     |
+| State            | Required invariant                                                                                                                       | Allowed variation |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| Plain dot        | Childless image named by `label`; not focusable.                                                                                         | Tone.             |
+| With icon        | Icon inside an `aria-hidden` wrapper; the dot keeps its role and name.                                                                   | Artwork.          |
+| Pulsing          | Opacity pulse runs; with reduced motion requested, it does not.                                                                          | Tone.             |
+| With tooltip     | A standalone dot is a button named by `label` with `aria-expanded`; a press pins the tooltip; Tooltip owns the surface.                  | Tooltip text.     |
+| Inside a control | Inside a button, link, menu item, or option, the dot is an image with no tab stop; the host's accessible name includes the tooltip text. | Host component.   |
 
 ### Transformation and precedence order
 
-- **ORD1 — Dot attributes.** `role="img"` and `aria-label` → component class and
-  `data-variant` → component styles → `xstyle` → `className` → `style` →
-  caller props.
+- **ORD1 — Dot attributes.** The role first follows placement: a standalone dot
+  with a tooltip is the toggle's `button`; a dot without a tooltip, or inside
+  a button, link, menu item, or option, is `role="img"`. Then `aria-label` → component
+  class and `data-variant` → component styles → `xstyle` → `className` →
+  `style` → caller props.
 
 ### Performance and resources
 
 - **PR1 — CSS-only motion.** The pulse is a CSS animation; StatusDot registers
-  no listener, observer, or timer of its own.
+  no listener, observer, or timer of its own beyond the shared hit-area watch
+  AR2 requires for a standalone dot with a tooltip.
 
 ## Accessibility contract
 
 - **AR1 — Name without hover.** The dot exposes `role="img"` with `label` as its
-  accessible name for every variant, with or without a tooltip or icon; a caller
-  `role` or `aria-label` replaces them (FR6).
+  accessible name for every variant, with or without an icon; standalone with a
+  tooltip it is a button with the same name, and inside an interactive element
+  its tooltip text joins the host's accessible name (FR5). A caller `role` or `aria-label`
+  replaces them (FR6).
 - **AR2 — Tab stop.** A dot without a tooltip is a static image and adds no
-  tab stop of its own. For a dot with a tooltip, FR5 governs: the tooltip is
-  reachable from the keyboard, and today the dot adds no tab stop, which is the
-  FR5 gap. A caller `tabIndex` passes through (FR6).
+  tab stop of its own. A standalone dot with a tooltip is a button in the tab
+  order whose press pins the tooltip (FR5), and a dot inside an interactive
+  element never adds a tab stop; today the dot adds no tab stop, which is the
+  FR5 gap. Under a coarse pointer, a standalone dot with a tooltip reaches 44 px
+  through an invisible hit area from the shared hit-area watch where its
+  neighbors leave room: the hit area never overlaps a neighbor's target and is
+  clamped to half the gap between close neighbors (`spec:AST-094` FR42);
+  implementation gap: not yet built. A caller `tabIndex`
+  passes through (FR6).
 - **AR3 — Decorative icon.** The icon wrapper is `aria-hidden`, so the label
   alone names the status.
 - **AR4 — Color is not the only carrier.** The accessible name carries the
@@ -196,20 +219,20 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Verification map
 
-| Contract            | Verification                                                          | Representative states                | Mutation or failure expectation                                                                                                                                                                                                                                            | Audit section             |
-| ------------------- | --------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1, FR6            | `StatusDot.test.tsx` render, ref, test-id, and target suites          | Every tone                           | Removing the dot, a lost ref or test id, or a second target fails. Gap: the 8px size test asserts presence only, and no test fails if the styling order (ORD1) changes; size is visible in `StatusDot.stories.tsx`.                                                        | `audit:StatusDot/anatomy` |
-| FR2                 | `StatusDot.test.tsx` variant-ink suite; `extensibleAxes.test.ts`      | Warning plate and ink; map wiring    | Dropping `variant` reflection fails. The warning-ink test pins the `--color-warning` plate with `--color-on-warning` ink, and the forced-colors test asserts the compiled `CanvasText` outline. Gap: other tones' paint and the unthemed fallback have no automated check. | `audit:StatusDot/theming` |
-| FR3, AR5            | `StatusDot.stories.tsx` in a browser, with and without reduced motion | Resting and pulsing                  | Gap: the pulsing unit tests assert presence only; a missing pulse or reduced-motion rule is visible only in the rendered fixture.                                                                                                                                          | `audit:StatusDot/motion`  |
-| FR4, AR3            | `StatusDot.test.tsx` custom-icon suite                                | Icon, falsy values                   | Exposing the icon or rendering a wrapper for a falsy value fails.                                                                                                                                                                                                          | `audit:StatusDot/anatomy` |
-| FR5, AR1, AR2       | `StatusDot.test.tsx` focusability and accessible-name suites          | Every tone, with and without tooltip | A missing name, a tab stop on a dot without a tooltip, or a name that depends on the tooltip fails. Gap: the tooltip test asserts only that the dot renders, so dropping the Tooltip wrap passes, and no test covers a caller `role` or `aria-label` override.             | `audit:StatusDot/a11y`    |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                         | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                                                      | `audit:StatusDot/theming` |
-| AR4, PR1            | Source review; `StatusDot.stories.tsx`                                | Plain dot, dot with icon             | Gap: no automated check covers the non-color mark guidance or fails if StatusDot adds its own listener, observer, or timer.                                                                                                                                                | `audit:StatusDot/a11y`    |
-| AR1, AR3            | Accessibility-tree evidence (`spec:AST-009` FR3)                      | Every tone, with icon and tooltip    | Gap: no accessibility-tree check proves the image role and name or the hidden icon; the unit tests query the DOM.                                                                                                                                                          | `audit:StatusDot/a11y`    |
+| Contract            | Verification                                                                                                                                                                                                | Representative states                                                                                              | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Audit section             |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR6            | `StatusDot.test.tsx` render, ref, test-id, and target suites                                                                                                                                                | Every tone                                                                                                         | Removing the dot, a lost ref or test id, or a second target fails. Gap: the 8px size test asserts presence only, and no test fails if the styling order (ORD1) changes; size is visible in `StatusDot.stories.tsx`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `audit:StatusDot/anatomy` |
+| FR2                 | `StatusDot.test.tsx` variant-ink suite; `extensibleAxes.test.ts`                                                                                                                                            | Warning plate and ink; map wiring                                                                                  | Dropping `variant` reflection fails. The warning-ink test pins the `--color-warning` plate with `--color-on-warning` ink, and the forced-colors test asserts the compiled `CanvasText` outline. Gap: other tones' paint and the unthemed fallback have no automated check.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `audit:StatusDot/theming` |
+| FR3, AR5            | `StatusDot.stories.tsx` in a browser, with and without reduced motion                                                                                                                                       | Resting and pulsing                                                                                                | Gap: the pulsing unit tests assert presence only; a missing pulse or reduced-motion rule is visible only in the rendered fixture.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `audit:StatusDot/motion`  |
+| FR4, AR3            | `StatusDot.test.tsx` custom-icon suite                                                                                                                                                                      | Icon, falsy values                                                                                                 | Exposing the icon or rendering a wrapper for a falsy value fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `audit:StatusDot/anatomy` |
+| FR5, AR1, AR2       | `StatusDot.test.tsx` focusability and accessible-name suites; evidence gap until built: standalone toggle cases and the coarse-pointer hit area; a dot with a tooltip inside a Button and inside a MenuItem | Every tone, with and without tooltip; a standalone dot with a tooltip; a dot inside a Button and inside a MenuItem | A missing name, a tab stop on a dot without a tooltip, or a name that depends on the tooltip fails. Gap: the tooltip test asserts only that the dot renders, so dropping the Tooltip wrap passes, and no test covers a caller `role` or `aria-label` override. Once FR5 is built, a standalone dot with a tooltip that is not a named button, that a tap, click, Enter, or Space does not pin, fails. A dot inside a Button or a MenuItem that renders a nested button or tab stop, opens its tooltip on a tap, or whose host's accessible name lacks the status, fails. A standalone dot with a tooltip whose coarse-pointer hit area stays under 44 px where its neighbors leave room, or reaches a neighbor's target, fails. | `audit:StatusDot/a11y`    |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                               | Canonical anatomy and current target                                                                               | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `audit:StatusDot/theming` |
+| AR4, PR1            | Source review; `StatusDot.stories.tsx`                                                                                                                                                                      | Plain dot, dot with icon                                                                                           | Gap: no automated check covers the non-color mark guidance or fails if StatusDot adds its own listener, observer, or timer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `audit:StatusDot/a11y`    |
+| AR1, AR3            | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                                                                                                            | Every tone, with icon and tooltip                                                                                  | Gap: no accessibility-tree check proves the image role and name or the hidden icon; the unit tests query the DOM.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `audit:StatusDot/a11y`    |
 
 ## Decision log
 
-None recorded. The record describes shipped behavior.
+None recorded. The tooltip's toggle follows `component:Tooltip` DEC-1.
 
 ## Open questions