@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/RadioList/RadioListItem.spec.md

@@ -0,0 +1,223 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:RadioListItem
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-28
+owners: [cixzhang]
+review_triggers:
+  [
+    public-api,
+    behavior,
+    layout,
+    interaction,
+    motion,
+    theming,
+    styling,
+    accessibility,
+    visual,
+    react-runtime,
+    compatibility,
+  ]
+verified_by:
+  [
+    packages/core/src/RadioList/RadioList.test.tsx,
+    packages/core/src/RadioList/RadioListItem.press.source-build.test.mjs,
+    packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx,
+    packages/core/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts,
+  ]
+modules: []
+families: []
+design_specs: [design:user-states]
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-085]
+---
+
+# RadioListItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | None changes. RadioListItem takes `label`, `aria-label`, `value`, `description`, `isDisabled`, `startContent`, `endContent`, `align`, and base props, and must sit inside a RadioList.                                                                                   |
+| Behavior                | One option row: a visually hidden native radio drawn by the radio indicator, named by the visible label, with the whole row as its click target and the radio as its only tab stop.                                                                                      |
+| End-user impact         | People can click anywhere on an option to choose it, and keyboard users reach one control per option. An item-disabled option, or one in a group disabled without a reason, leaves the tab order; a focused disabled option shows the row outline but no indicator ring. |
+| Builder impact          | None.                                                                                                                                                                                                                                                                    |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Native `disabled`, two focus indicators, the missing indicator ring on a disabled option, and the `startContent` docs are listed under Current-state impact.                                                   |
+| Review checks           | Reject a second tab stop on the row, a link in the label that selects the option, a description that is not linked, a theme target off the painted row, or a selection while disabled.                                                                                   |
+| Governing rules         | `component:RadioList`; `spec:AST-085` FR1–FR3, FR6; `design:user-states` DR1, DR2 (pressed overlay); `architecture:interaction-modality` INV1–INV3.                                                                                                                      |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+RadioListItem is one option in a RadioList. It owns the option's native radio,
+naming and description, row-surface click delegation, item disabled state,
+pressed and hover feedback on the radio, and the `radio-list-item` target.
+Consumer usage lives in `RadioListItem.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: controlled by the parent RadioList's
+  `value`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The option's native radio, its name, description link, and form value.
+- Row-surface click delegation to the radio and `onClick` routing.
+- Item disabled state and the disabled, selected, and size reflection on
+  `radio-list-item`.
+- The radio indicator's hover tint and pressed overlay, and its focus ring (FR7,
+  OQ1).
+- The bare default row appearance.
+
+**Does not own / non-goals**
+
+- The group, its value, name, size, disabled reason, and required and status
+  semantics — owned by `component:RadioList`.
+- Row layout of label, description, start and end content — owned by Item.
+- The radio indicator's paint — owned by the Indicator registry's radio
+  indicator.
+- Use outside RadioList — not supported; it throws.
+
+## Public concepts
+
+| Concept  | Closed values or states                     | Meaning                                                        | Availability by variant/orientation/state | Default        | Owner                     | Stability | Invalid-value behavior                           |
+| -------- | ------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------------- | --------- | ------------------------------------------------ |
+| Naming   | `label` node or text; `aria-label`          | Names the radio; `aria-label` replaces the visible-label name. | Always.                                   | label required | `component:RadioListItem` | Stable    | TypeScript rejects a missing label.              |
+| Value    | string                                      | The value the group selects and submits.                       | Always.                                   | required       | `component:RadioListItem` | Stable    | TypeScript rejects a missing value.              |
+| Disabled | off, item, group, group with reason         | Blocks selection.                                              | Always.                                   | off            | `component:RadioListItem` | Stable    | Not applicable.                                  |
+| Content  | `description`, `startContent`, `endContent` | Supporting text and caller content around the label.           | Always.                                   | none           | caller                    | Stable    | A description that renders nothing adds no link. |
+
+## Behavioral and layout contract
+
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                                                                             |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| FR1  | RadioListItem throws when rendered outside a RadioList.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source                                                                    |
+| FR2  | The option renders an Item row whose start content is a visually hidden native `<input type="radio">` (the group's `name`, this `value`, checked when the group value matches) layered over the radio indicator, followed by any `startContent`.                                                                                                                                                                                                                                                                                                                                                        | Current source and tests                                                          |
+| FR3  | The radio is named by the visible label element through `aria-labelledby`, for text and node labels alike; `aria-label` replaces that name and never reaches the row. A renderable `description` is linked through `aria-describedby`; one that renders nothing adds no link.                                                                                                                                                                                                                                                                                                                           | Current tests                                                                     |
+| FR4  | The radio is the option's only tab stop. Clicks on the row surface (label, description, empty area) are delegated to the radio; links and buttons inside the label, description, or end content keep their own behavior. A caller `onClick`, typed for the row, runs on the radio for direct and delegated clicks; that routing is shipped behavior, not a requirement until OQ2 is ruled.                                                                                                                                                                                                              | WCAG 4.1.2; current tests                                                         |
+| FR5  | Selecting the radio calls the group's `onChange(value)` unless the option is disabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current tests                                                                     |
+| FR6  | Disabled when the item or the group is disabled. A disabled radio MUST stay focusable with `aria-disabled="true"`, be detached from the form, and refuse selection (`spec:AST-085` FR1–FR3); disabled options show no hover tint or pressed overlay. Implementation gap: only a group-disabled radio with a group reason renders that shape; an item-disabled radio, and a group-disabled radio without a reason, get native `disabled`, which removes them from the tab order. A focusable disabled radio also still runs a caller `onClick`, on a click or an arrow key onto it (`spec:AST-085` FR2). | `spec:AST-085`; current source and tests                                          |
+| FR7  | Keyboard focus on the radio paints the shared focus ring on the radio indicator, and Item's row focus-within outline on the row. One focus move MUST have one owning indicator (`architecture:interaction-modality` INV3); which element owns it is OQ1. Implementation gap: both paint. On a focused disabled option the indicator ring is skipped, against `spec:AST-085` FR6; only the row outline shows, and whether it is enough follows OQ1.                                                                                                                                                      | `architecture:interaction-modality` INV1–INV3; `spec:AST-085` FR6; current source |
+| FR8  | Hovering the enabled row tints the radio indicator. RadioListItem applies `design:user-states` DR1 and DR2 for the pressed overlay, painting it on the indicator while the enabled row is pressed. The row itself paints no padding, radius, hover, or press background by default.                                                                                                                                                                                                                                                                                                                     | `design:user-states`; current tests                                               |
+| FR9  | The radio's hit area is at least 24 by 24 CSS pixels on coarse pointers, and its position follows the inline direction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | WCAG 2.5.8; current tests                                                         |
+| FR10 | Under forced colors, the selected dot stays visible.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | WCAG 1.4.11; current tests                                                        |
+| FR11 | The painted row element carries `astryx-radio-list-item` (alongside Item's own target) and reflects `data-size`, `data-selected` when checked, and `data-disabled` when disabled. A theme's `radio-list-item` styles override the bare default row.                                                                                                                                                                                                                                                                                                                                                     | `architecture:component-theming-surface` INV6; current tests                      |
+| FR12 | `ref`, `className`, `style`, `xstyle`, `align`, `data-*`, `id`, and ARIA other than `aria-label` reach the row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current tests                                                                     |
+
+### Allowed variation
+
+- **AV1 — Content.** Label, description, start and end content vary within
+  their types.
+- **AV2 — Theme paint.** Themes may restore row padding, radius, hover, and
+  selected paint through `radio-list-item`.
+
+### Representative states
+
+| State         | Required invariant                                                                                                                                                                               | Allowed variation |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
+| Unselected    | Radio named by label; row click selects.                                                                                                                                                         | Content.          |
+| Selected      | Radio checked; `data-selected`; dot visible under forced colors.                                                                                                                                 | Theme paint.      |
+| Rich label    | Name from the label text; a link inside it does not select.                                                                                                                                      | —                 |
+| Item disabled | Focusable with `aria-disabled`; no hover or press feedback; the focus indicator shows under keyboard focus. Implementation gap: native `disabled`, and the indicator ring is skipped (FR6, FR7). | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Name.** `aria-label`, else the visible label element.
+- **ORD2 — Availability.** Group disabled or item disabled; only the group
+  reason keeps the radio focusable.
+
+### Performance and resources
+
+- **PR1 — Bounded resources.** The item owns no observer or global listener; its
+  press feedback uses the shared press controller.
+
+## Accessibility contract
+
+- **AR1 — Radio semantics.** Each option is a native radio with a name,
+  optional description, and checked state.
+- **AR2 — One tab stop.** FR4.
+- **AR3 — Target size.** FR9.
+- **AR4 — Non-color state.** FR10.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                      | Representation authority                                                                                | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- | ------------------ |
+| Radio            | Indicator with hover tint, pressed overlay, focus ring. | `design:user-states` for the pressed overlay; current source for the hover tint; FR7 for the focus ring | Prominent      | FR2, FR7, FR8      |
+| Label            | Names the option.                                       | Item                                                                                                    | Prominent      | FR3                |
+| Description      | Supporting text linked to the radio.                    | Item                                                                                                    | Supporting     | FR3                |
+| Row              | Bare, full-width click target.                          | Current source and tests                                                                                | Supporting     | FR4, FR8, FR11     |
+
+No design record beyond `design:user-states` governs RadioListItem.
+
+## Family and system relationships
+
+- `component:RadioList` supplies the name, value, size, and group availability.
+- `design:user-states` owns the pressed treatment the radio indicator paints.
+- `spec:AST-085` owns disabled focusability; FR6 and FR7 record the gaps.
+
+## Verification map
+
+| Contract                | Verification                                                                                                                                                                                                                                | Representative states                                          | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                 | Audit section                       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1                     | Evidence gap: no test renders RadioListItem outside a RadioList                                                                                                                                                                             | —                                                              | —                                                                                                                                                                                                                                                                                                                                                                                                               | `audit:RadioListItem/behavior`      |
+| FR2–FR5, ORD1, AR1, AR2 | `RadioList.test.tsx` selection, rich-content, and rest-forwarding cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts`                                                                                                  | Text and node labels; `aria-label`; description; link in label | A wrong name, dangling description, or link that selects fails. Evidence gap: no test asserts a caller `onClick` on the radio for direct and delegated clicks.                                                                                                                                                                                                                                                  | `audit:RadioListItem/accessibility` |
+| FR6, ORD2               | `RadioList.test.tsx` item-disabled and form cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` `radio-list-option-disabled`, `radio-list-option-group-disabled`, and `radio-list-option-disabled-with-message` states | Item and group disabled; group reason                          | A disabled option that selects, or a submitted value from a group disabled with a reason, fails; the binding expects `tabReachable: false` for `radio-list-option-group-disabled`, which fails when that gap closes. Evidence gap: no state guards item-disabled focusability, since `radio-list-option-disabled` binds a radio that is not the group's Tab stop. No form case submits an item-disabled option. | `audit:RadioListItem/accessibility` |
+| FR7                     | Evidence gap: no test of focus-ring placement on the indicator, the disabled ring, or the indicator count                                                                                                                                   | —                                                              | —                                                                                                                                                                                                                                                                                                                                                                                                               | `audit:RadioListItem/accessibility` |
+| FR8                     | `RadioList.test.tsx` pressed-state and bare-row cases; `RadioListItem.press.source-build.test.mjs`                                                                                                                                          | Enabled, disabled, touch                                       | Press paint on a disabled option, or a default row background, fails. Evidence gap: no test asserts the hover tint.                                                                                                                                                                                                                                                                                             | `audit:RadioListItem/visual`        |
+| FR9, FR10, AR3, AR4     | `RadioList.test.tsx` coarse-pointer, RTL, and forced-colors cases                                                                                                                                                                           | Coarse pointer; RTL; forced colors                             | Evidence gap: the forced-colors case passes on any matching rule (the checkbox mark supplies one), so it does not prove the dot; the coarse-pointer and RTL cases check only the direction-symmetric centering class, not the 24 by 24 minimum or RTL placement.                                                                                                                                                | `audit:RadioListItem/accessibility` |
+| FR11, FR12              | `RadioList.test.tsx` theme-target and rest-forwarding cases                                                                                                                                                                                 | Sizes; selected; disabled                                      | A target off the painted row, or a missing state, fails. Evidence gap: no test asserts `ref`, `className`, `style`, or `xstyle` on the row.                                                                                                                                                                                                                                                                     | `audit:RadioListItem/theming`       |
+| PR1                     | Evidence gap: no test asserts the absence of observers or global listeners                                                                                                                                                                  | —                                                              | —                                                                                                                                                                                                                                                                                                                                                                                                               | `audit:RadioListItem/behavior`      |
+
+## Current-state impact
+
+- **Two focus indicators (FR7).** Keyboard focus paints both Item's row outline
+  and the radio indicator ring, against `architecture:interaction-modality`
+  INV3.
+- **Caller onClick while disabled (FR6).** A focusable disabled radio still
+  runs a caller's `onClick`, against `spec:AST-085` FR2.
+- **Disabled focusability (FR6).** Item-disabled radios, and group-disabled
+  radios without a reason, use native `disabled`, against `spec:AST-085` FR1.
+- **Disabled focus ring (FR7).** The indicator ring is skipped on a focused
+  disabled option, against `spec:AST-085` FR6; only the row outline shows.
+- **Consumer docs (FR2).** `RadioListItem.doc.mjs` and the `startContent` prop
+  JSDoc in `RadioListItem.tsx` say `startContent` renders before the radio
+  circle; it renders after it.
+
+## Decision log
+
+No component-local decision.
+
+## Open questions
+
+- **OQ1 — Which element paints the option's focus ring, the row or the radio
+  indicator?** (`human-design`) `architecture:interaction-modality` INV3
+  requires one indicator; CheckboxListItem composes the same two painters.
+- **OQ2 — Which element owns a caller `onClick`?** (`human-api`) It is typed
+  for the row but runs on the radio, as CheckboxListItem's matching open
+  question records.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/RadioList/RadioListItem.tsx

@@ -38,6 +38,10 @@ import {themeProps} from '../utils/themeProps';
 // that paints it. See interactionOverlay.stylex.ts.
 const pressedOverlayImage = 'var(--_press-paint-image)';
 
+// The mouse press's paint, declared on the row and inherited by the layer
+// over the circle. Internal: not a theme hook.
+const ROW_PRESS = '--_radio-row-press';
+
 const styles = stylex.create({
   radioWrapper: {
     position: 'relative',
@@ -48,8 +52,10 @@ const styles = stylex.create({
     isolation: 'isolate',
   },
   // The row remains the large press target, but nested links and buttons keep
-  // their independent action and do not make the radio appear pressed. This
-  // owner-drawn layer also survives a theme replacing the indicator component.
+  // their independent action and do not make the radio appear pressed: the
+  // row declares the mouse press's paint (`rowStyles.press`) and this layer
+  // reads it. This owner-drawn layer also survives a theme replacing the
+  // indicator component.
   // Two pointers, two press models (see interactionOverlay.stylex.ts): a
   // mouse keeps `:active`; under a coarse pointer that arm is dropped and the
   // touch press controller writes `data-astryx-press` on the row, which this layer
@@ -63,16 +69,7 @@ const styles = stylex.create({
       inset: 0,
       borderRadius: radiusVars['--radius-full'],
       pointerEvents: 'none',
-      backgroundColor: {
-        default: 'transparent',
-        [stylex.when.ancestor(
-          ':active:not(:has(a:active,button:active,[role="button"]:active,[role="link"]:active))',
-          indicatorScope,
-        )]: {
-          default: colorVars['--color-overlay-pressed'],
-          '@media (pointer: coarse)': 'transparent',
-        },
-      },
+      backgroundColor: `var(${ROW_PRESS}, transparent)`,
       // The touch press, as an image layer over the colour: an image change is
       // discrete, so no transition can delay the onset, and the strength the
       // row's `pressedAlpha` arms own (1 while on, 1 → 0 over the release) is
@@ -152,6 +149,22 @@ const rowStyles = stylex.create({
     // circle reads it.
     backgroundImage: 'none',
   },
+  // The mouse press (a finger's lives on `data-astryx-press`): the row is
+  // pressed, but not through a nested link or button, which keep their own
+  // action. The `:has()` is on the row itself and reaches no descendant
+  // selector, so a change inside the row re-checks the row alone; the circle's
+  // layer reads the paint through inheritance rather than a relation that
+  // would restyle everything under the row.
+  press: {
+    [ROW_PRESS]: {
+      default: null,
+      ':active:not(:has(a:active,button:active,[role="button"]:active,[role="link"]:active))':
+        {
+          default: colorVars['--color-overlay-pressed'],
+          '@media (pointer: coarse)': 'transparent',
+        },
+    },
+  },
 });
 
 export interface RadioListItemProps extends BaseProps<HTMLDivElement> {
@@ -387,6 +400,7 @@ export function RadioListItem({
           // styles so it wins within the base layer; a `radio-list-item` theme
           // still overrides it from the higher `astryx-theme` layer.
           rowStyles.root,
+          !isDisabled && rowStyles.press,
           xstyle,
         ] as StyleXStyles
       }

package/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file RadioGroup.a11y.chromium.spec.ts

package/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/window-splitter|internal/a11y-spec/src/harness|packages/core/src/Resizable/|apps/storybook/stories/WindowSplitterA11y)
 
 /**
  * @file ResizeHandle.a11y.chromium.spec.ts

package/src/ScrollableArea/ScrollableArea.spec.md

@@ -75,7 +75,7 @@ shared behavior hook, not the exclusive owner of that behavior.
 | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------- |
 | FR1 | The root MUST remain the one native viewport and receive the public ref, standard container sizing props, and styling inputs through StyleX.                                                                                                                                                                                                                                                                                                   | `spec:AST-025` IR3–IR4           | implemented                         |
 | FR2 | The inner content wrapper MUST be a real normal-flow block box observed with the viewport, use a 100% minimum size, and use max-content inline sizing only when inline scrolling is requested. Children participate in that box rather than the viewport's flex/grid formatting context, and the minimum block size does not create a definite percentage-height basis; structures that must preserve those semantics adopt the hook directly. | `spec:AST-025` FR5–FR6           | implemented                         |
-| FR3 | Native scrollbar behavior MUST remain authoritative; the default thumb uses `--color-neutral`, the track is transparent, and forced colors restore platform presentation.                                                                                                                                                                                                                                                                      | `spec:AST-025` FR15              | implemented                         |
+| FR3 | Native scrollbar behavior MUST remain authoritative; with a fine pointer the default thumb uses `--color-neutral` and the track is transparent, while a coarse primary pointer and forced colors restore platform presentation.                                                                                                                                                                                                                | `spec:AST-025` FR15              | implemented                         |
 | FR4 | Scroll-state container queries MAY enhance descendant stuck/edge presentation, but hook state MUST remain the cross-browser source of truth.                                                                                                                                                                                                                                                                                                   | `spec:AST-025` platform support  | implemented progressively           |
 | FR5 | The content box MUST apply and publish logical padding with edge-over-axis-over-uniform precedence, defaulting every published edge to zero. `isFullBleed` MUST let only the viewport consume inherited inset; nested content continues to read the content box's published values.                                                                                                                                                            | `architecture:container-padding` | implemented                         |
 | FR6 | A fitting viewport MUST use `clip` on both physical axes so it prevents paint overflow without capturing native Sticky. Excess requested-axis geometry MUST activate the writing-mode-resolved `auto`/`hidden` pair. `stickyContainment="always"` MUST explicitly retain that pair while fitting.                                                                                                                                              | `spec:AST-025` FR21              | implemented                         |
@@ -95,6 +95,7 @@ shared behavior hook, not the exclusive owner of that behavior.
 | overflowing                    | named tab stop; per-axis logical edge state                                                             | one or both requested axes |
 | overflow removed while focused | remove future tab stop without moving focus                                                             | current focus remains      |
 | forced colors                  | native platform scrollbar presentation                                                                  | platform rendering         |
+| coarse primary pointer         | native platform scroll indicator                                                                        | platform rendering         |
 
 ### Transformation and precedence order
 
@@ -114,10 +115,10 @@ shared behavior hook, not the exclusive owner of that behavior.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Viewport         | platform scrollbar with token-colored thumb and transparent track | `spec:AST-025`           | supporting     | FR1, FR3           |
-| Content box      | no independent paint by default                                   | caller content           | structural     | FR2                |
+| Anatomy or state | Design requirement                                                                 | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Viewport         | platform scrollbar; with a fine pointer, token-colored thumb and transparent track | `spec:AST-025`           | supporting     | FR1, FR3           |
+| Content box      | no independent paint by default                                                    | caller content           | structural     | FR2                |
 
 ### Theming anatomy
 

package/src/ScrollableArea/ScrollableArea.test.tsx

@@ -278,6 +278,11 @@ describe('ScrollableArea', () => {
     expect(source).toContain("'@media (forced-colors: active)': 'auto'");
   });
 
+  it("keeps the platform's own scroll indicator on touch screens", () => {
+    const source = stylesSource();
+    expect(source).toContain("'@media (pointer: coarse)': 'auto'");
+  });
+
   it('guards scroll-state query containment as a progressive enhancement', () => {
     const source = stylesSource();
     expect(source).toContain("'@supports (container-type: scroll-state)'");

package/src/ScrollableArea/ScrollableArea.tsx

@@ -52,6 +52,10 @@ const styles = stylex.create({
     WebkitOverflowScrolling: 'touch',
     scrollbarColor: {
       default: `${colorVars['--color-neutral']} transparent`,
+      // Touch screens keep the platform's own scroll indicator, which iOS
+      // shows only while scrolling, as UIScrollView does. A custom colour
+      // turns it into a faint bar that also shows in the gap a pull opens.
+      '@media (pointer: coarse)': 'auto',
       '@media (forced-colors: active)': 'auto',
     },
     scrollbarWidth: 'auto',