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

package/src/ScrollableArea/modules/useScrollableArea.spec.md

@@ -10,7 +10,12 @@ approved_by: cixzhang
 approved_at: 2026-09-11
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility]
-verified_by: [packages/core/src/hooks/useScrollableArea.test.tsx]
+verified_by:
+  [
+    packages/core/src/hooks/useScrollableArea.test.tsx,
+    packages/core/src/hooks/scrollKeyboardDelegation.test.ts,
+    packages/core/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts,
+  ]
 parent_component: component:ScrollableArea
 references: [architecture:public-component-api, spec:AST-025/DEC-1]
 ---
@@ -47,24 +52,25 @@ and scroll chaining without inserting structure.
 
 ## Public API and concepts
 
-| Concept        | Closed values or states            | Meaning                               | Default                   | Owner                                     | Stability |
-| -------------- | ---------------------------------- | ------------------------------------- | ------------------------- | ----------------------------------------- | --------- |
-| axis           | `inline`, `block`, `both`          | requested logical scroll intent       | required                  | `spec:AST-025`                            | stable    |
-| keyboard owner | `content`, named `viewport`        | where keyboard scrolling is reached   | required                  | `spec:AST-025`                            | stable    |
-| overscroll     | `allow`, `contain`                 | edge propagation on effective axes    | `allow`                   | `spec:AST-025`                            | stable    |
-| axis state     | `isScrollable`, `atStart`, `atEnd` | effective ownership and logical edges | inactive, both edges true | `module:ScrollableArea/useScrollableArea` | stable    |
+| Concept        | Closed values or states                                | Meaning                                 | Default                   | Owner                                     | Stability |
+| -------------- | ------------------------------------------------------ | --------------------------------------- | ------------------------- | ----------------------------------------- | --------- |
+| axis           | `inline`, `block`, `both`                              | requested logical scroll intent         | required                  | `spec:AST-025`                            | stable    |
+| keyboard owner | `content`, named `viewport`, named `contentOrViewport` | fixed or automatic keyboard scroll path | required                  | `spec:AST-025`                            | stable    |
+| overscroll     | `allow`, `contain`                                     | edge propagation on effective axes      | `allow`                   | `spec:AST-025`                            | stable    |
+| axis state     | `isScrollable`, `atStart`, `atEnd`                     | effective ownership and logical edges   | inactive, both edges true | `module:ScrollableArea/useScrollableArea` | stable    |
 
 ## Behavioral contract
 
-| ID  | Invariant                                                                                                                                                                             | Basis                       | Acceptance and implementation state     |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------- |
-| FR1 | An axis MUST be effective only when requested, computed overflow is scroll-capable, and geometry exceeds 1px.                                                                         | `spec:AST-025` FR1–FR4      | implemented                             |
-| FR2 | Viewport and content geometry MUST be observed; invalidations MUST coalesce and preserve the last valid state while unmeasurable.                                                     | `spec:AST-025` FR5–FR9      | implemented                             |
-| FR3 | Logical edges and behavior-owned physical overflow MUST map through direction and horizontal, vertical, or sideways writing modes without requiring adopters to recreate the mapping. | `spec:AST-025` FR1, FR3–FR4 | implemented                             |
-| FR4 | The nearest registered effective owner MUST win independently by axis.                                                                                                                | `spec:AST-025` FR10, FR18   | implemented privately for future Sticky |
-| FR5 | Viewport keyboard props and overscroll containment MUST appear only while applicable requested axes are effective.                                                                    | `spec:AST-025` FR12–FR14    | implemented                             |
-| FR6 | Prop getters MUST compose refs and preserve caller handlers/classes/styles/ARIA while behavior-owned accessibility and non-cancellable behavior win conflicts.                        | `spec:AST-025` IR4          | implemented                             |
-| FR7 | The viewport prop getter MUST consume caller `xstyle` and internally compose geometry-driven `clip`/`auto`/`hidden` overflow plus explicit fitting Sticky containment.                | `spec:AST-025` FR21         | implemented                             |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                        | Basis                       | Acceptance and implementation state     |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------- |
+| FR1 | An axis MUST be effective only when requested, computed overflow is scroll-capable, and geometry exceeds 1px.                                                                                                                                                                                                                                                                    | `spec:AST-025` FR1–FR4      | implemented                             |
+| FR2 | Viewport and content geometry MUST be observed; invalidations MUST coalesce and preserve the last valid state while unmeasurable.                                                                                                                                                                                                                                                | `spec:AST-025` FR5–FR9      | implemented                             |
+| FR3 | Logical edges and behavior-owned physical overflow MUST map through direction and horizontal, vertical, or sideways writing modes without requiring adopters to recreate the mapping.                                                                                                                                                                                            | `spec:AST-025` FR1, FR3–FR4 | implemented                             |
+| FR4 | The nearest registered effective owner MUST win independently by axis.                                                                                                                                                                                                                                                                                                           | `spec:AST-025` FR10, FR18   | implemented privately for future Sticky |
+| FR5 | Viewport keyboard props and overscroll containment MUST appear only while applicable requested axes are effective.                                                                                                                                                                                                                                                               | `spec:AST-025` FR12–FR14    | implemented                             |
+| FR6 | Prop getters MUST compose refs and preserve caller handlers/classes/styles/ARIA while behavior-owned accessibility and non-cancellable behavior win conflicts.                                                                                                                                                                                                                   | `spec:AST-025` IR4          | implemented                             |
+| FR7 | The viewport prop getter MUST consume caller `xstyle` and internally compose geometry-driven `clip`/`auto`/`hidden` overflow plus explicit fitting Sticky containment.                                                                                                                                                                                                           | `spec:AST-025` FR21         | implemented                             |
+| FR8 | `contentOrViewport` MUST retain the named overflowing viewport, inspect the first sequential descendant on forward Tab entry, and delegate only to a native link/button outside navigation-key-owning surfaces. Reverse traversal from the delegated first child skips the viewport. Pointer/programmatic focus never delegates; eligibility is checked again on the next entry. | `spec:AST-025` FR12–FR13    | implemented                             |
 
 ### Transformation and precedence order
 
@@ -82,9 +88,20 @@ and scroll chaining without inserting structure.
 
 ## Accessibility contract
 
-- **AR1 — Named viewport owner.** Viewport-owned access requires a label and adds
-  the viewport to the tab order only while an applicable axis is effective.
-- **AR2 — Focus continuity.** State changes never move or blur focus.
+- **AR1 — Named viewport owner.** Fixed viewport and automatic access require a
+  label and retain `tabIndex=0` while effectively scrollable. Automatic access
+  delegates only on forward keyboard entry; the descendant retains its own name
+  inside the named viewport group/region.
+- **AR2 — Focus continuity.** Content, eligibility, and geometry changes never
+  move or blur focus. A viewport losing overflow while focused remains
+  programmatically focusable. Reverse traversal from the delegated first child
+  skips the viewport, including after visiting later descendants.
+- **AR3 — Conservative eligibility.** Inspect the first sequential target; do not
+  search past an excluded one for a link/button. Composite roles, editable
+  surfaces, native or registered nested scroll owners, positive tab ordering,
+  popup triggers, and unproven interactive roles retain the viewport path.
+- **AR4 — Native scrolling.** Delegation MUST preserve Arrow/Page access to both
+  scroll edges without implementing JavaScript scrolling.
 
 ## Design relationships
 
@@ -97,9 +114,9 @@ No visual representation is owned by this hook.
 
 ## Verification map
 
-| Contract         | Verification                                                   | Representative states                                                                 | Mutation or failure expectation                                                                                |
-| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| FR1–FR6, AR1–AR2 | `useScrollableArea.test.tsx` plus real-browser Storybook probe | horizontal/vertical/sideways, LTR/RTL, fit/overflow/edge, nested owners, focused loss | style-only or geometry-only ownership, physical-edge leakage, stale state, ref loss, or dead containment fails |
+| Contract         | Verification                                                                                                     | Representative states                                                                                                                                  | Mutation or failure expectation                                                                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR8, AR1–AR4 | `useScrollableArea.test.tsx`, `scrollKeyboardDelegation.test.ts`, and `BottomSheetKeyboard.a11y.browser.spec.ts` | horizontal/vertical/sideways, LTR/RTL, fit/overflow/edge, fixed/automatic keyboard owners, dynamic descendant eligibility, nested owners, focused loss | style-only or geometry-only ownership, physical-edge leakage, duplicate/missing keyboard path, stale state, ref loss, or dead containment fails |
 
 ## Decision log
 
@@ -111,6 +128,17 @@ No visual representation is owned by this hook.
 One returned prop object per owned element keeps refs, accessibility, handlers,
 and behavior together without making consumer spread order part of correctness.
 
+### DEC-2 — Automatic ownership is shared behavior
+
+**Reference:** `module:ScrollableArea/useScrollableArea/DEC-2`
+**Decider:** cixzhang, 2026-09-13
+
+`contentOrViewport` retains the named overflowing viewport and delegates only on
+forward Tab entry to a safe first sequential native link/button. This replaces
+continuous keyboard-eligibility observation. Geometry observation is unchanged;
+keyboard eligibility adds no subtree or ancestor observers and is inspected anew
+at each entry. BottomSheet is a proving composition of this shared behavior.
+
 ## Open questions
 
 None.

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -129,9 +129,9 @@ export const docs = {
         category: 'Color contrast',
         criterion: '1.4.3 Contrast (Minimum)',
         requirement: '4.5:1',
-        states: ['Rest', 'Hover', 'Selected'],
+        states: ['Rest', 'Hover', 'Pointer down', 'Selected'],
         description:
-          'Each label must have at least 4.5:1 contrast with its segment background. Check unselected, Hover, and selected colors as they appear on screen.',
+          'Each label must have at least 4.5:1 contrast with its segment background. Check unselected, Hover, Pointer down, and selected colors as they appear on screen. For Hover and Pointer down, measure the final background after the overlay is applied.',
       },
       {
         name: 'Essential icon',

package/src/SegmentedControl/SegmentedControl.test.tsx

@@ -15,6 +15,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {SegmentedControl} from './SegmentedControl';
 import {SegmentedControlItem} from './SegmentedControlItem';
 import {
@@ -672,3 +673,33 @@ describe('forced colors (WCAG 1.4.11)', () => {
     expect(getAllInjectedCss()).toContain('forced-color-adjust: none;');
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay on a segment while it is pressed', () => {
+    render(
+      <SegmentedControl value="grid" onChange={() => {}} label="View mode">
+        <SegmentedControlItem value="grid" label="Grid" />
+        <SegmentedControlItem value="list" label="List" />
+      </SegmentedControl>,
+    );
+    // The unselected segment is the one a press can change; it carries the
+    // system's hover and pressed overlay.
+    expect(hasPressedArm(screen.getByRole('radio', {name: 'List'}))).toBe(true);
+    // The selected segment keeps its raised surface as it is.
+    expect(hasPressedArm(screen.getByRole('radio', {name: 'Grid'}))).toBe(
+      false,
+    );
+  });
+
+  it('does not press a disabled segment', () => {
+    render(
+      <SegmentedControl value="grid" onChange={() => {}} label="View mode">
+        <SegmentedControlItem value="grid" label="Grid" />
+        <SegmentedControlItem value="list" label="List" isDisabled />
+      </SegmentedControl>,
+    );
+    expect(hasPressedArm(screen.getByRole('radio', {name: 'List'}))).toBe(
+      false,
+    );
+  });
+});

package/src/SegmentedControl/SegmentedControlItem.tsx

@@ -33,6 +33,7 @@ import {mergeProps, composeEventHandlers} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 export interface SegmentedControlItemProps extends BaseProps<HTMLButtonElement> {
   ref?: React.Ref<HTMLButtonElement>;
@@ -91,14 +92,6 @@ const styles = stylex.create({
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
   },
-  hover: {
-    backgroundColor: {
-      default: null,
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': colorVars['--color-overlay-hover'],
-      },
-    },
-  },
   selected: {
     // Forced colors (Windows High Contrast) strips the painted surface fill
     // and box shadow, which would leave the selected segment with no state
@@ -248,7 +241,11 @@ export function SegmentedControlItem({
           sizeStyles[size],
           isFill && styles.fill,
           isSelected && styles.selected,
-          !isSelected && !isItemDisabled && styles.hover,
+          // The shared hover and pressed overlay, on the segments a press can
+          // change: the selected segment keeps its raised surface as it is.
+          !isSelected &&
+            !isItemDisabled &&
+            interactionOverlayStyles.backgroundColor,
           isItemDisabled && styles.disabled,
           xstyle,
         ),

package/src/SideNav/SideNav.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
       {className: 'astryx-side-nav-section'},
     ],
   },
-  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.',
+  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible and resizable modes.',
   props: [
     {
       name: 'header',

package/src/SideNav/SideNav.test.tsx

@@ -989,6 +989,16 @@ describe('SideNav resizable', () => {
     ).toBeInTheDocument();
   });
 
+  it('clips the overlay drag handle within the resizable nav bounds', () => {
+    render(<SideNav resizable>Content</SideNav>);
+    const nav = screen.getByRole('navigation');
+    const container = nav.parentElement;
+    const handle = screen.getByTestId('astryx-sidenav-resize-handle');
+
+    expect(container).toContainElement(handle);
+    expect(getComputedStyle(container!).overflow).toBe('clip');
+  });
+
   it('does not render drag handle without resizable', () => {
     render(<SideNav>Content</SideNav>);
     expect(

package/src/SideNav/SideNav.tsx

@@ -11,7 +11,8 @@
  * Sidebar navigation container with five zones: header + topContent (sticky together),
  * children (scrollable), footer, and footerIcons (sticky bottom).
  *
- * Supports optional resize via drag handle at the inline-end edge.
+ * Supports optional resize via a drag handle at the inline-end edge. The
+ * resizable wrapper clips handle overflow while keeping its focus ring inside.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/SideNav/SideNav.doc.mjs
@@ -25,7 +26,7 @@ import {useCallback, useImperativeHandle, useRef, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
-import {spacingVars} from '../theme/tokens.stylex';
+import {focusVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {
   SideNavCollapseContext,
@@ -241,6 +242,16 @@ const styles = stylex.create({
     display: 'flex',
     flexShrink: 0,
     height: '100%',
+    overflow: 'clip',
+  },
+  resizableHandle: {
+    // Keep the shared ring inside the clipping boundary. The wrapper cannot
+    // use overflow-clip-margin: that paint allowance also contributes the
+    // overlay's half-pixel spill to AppShell's scrollable overflow.
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': `calc(0px - ${focusVars['--focus-outline-width']})`,
+    },
   },
   // Topbar mode — horizontal layout for mobile top bar
   topbar: {
@@ -658,6 +669,7 @@ export function SideNav({
         position="overlay"
         pillPlacement="end"
         isAlwaysVisible={false}
+        xstyle={styles.resizableHandle}
         resizable={resizableHook.props}
         label={t('@astryx.sideNav.resizeSidebar')}
       />

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',
@@ -244,6 +255,17 @@ export const docs = {
     ],
   },
   usage: {
+    accessibility: [
+      {
+        name: 'Thumb',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'The thumb must have at least 3:1 contrast with the track and the surface behind it. Pointer down is the whole drag: measure the thumb with the pressed overlay applied.',
+      },
+    ],
     anatomy,
     description:
       'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
@@ -416,6 +438,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