Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Component Audit] ChatLayoutScrollButton: themes restyle the pill instead of an invisible row behind it (#6482)

Cindy Zhang2c831e44c29b
diff --git a/.changeset/chatlayoutscrollbutton-audit-theme-target.md b/.changeset/chatlayoutscrollbutton-audit-theme-target.md
new file mode 100644
index 0000000000..04bd87508f
--- /dev/null
+++ b/.changeset/chatlayoutscrollbutton-audit-theme-target.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Make a theme that styles `chat-layout-scroll-button` actually restyle the chat scroll-to-bottom pill. The documented target sat on the invisible full-width row that centres the pill, so a `backgroundColor` override painted a band across the chat dock while the pill kept the surface the theme asked to replace — and every automated check passed, because the override did reach _an_ element. The target now rides the pill, which is what paints the fill, elevation, and radius (`architecture:component-theming-surface` INV4). The target keeps its name, stays a single target, and the component's props, DOM shape, ref target, and consumer passthrough are unchanged. A Chromium spec pins the placement and proves the repair by moving the target back and showing the pill go unstyled under a theme. (#6482)
+
+@cixzhang
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index a293110793..df34ca05ce 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -240,7 +240,7 @@
"component": "core/ChatLayout",
"reason": "ChatLayout is a block-flow shell: a flex column whose message area centers with marginInline auto and whose dock spans the full inline width using insetInlineStart/insetInlineEnd and logical padding. It scrolls on the block axis only (overflowY auto with overflowX hidden), owns no directional glyph, no physical inline offset or transform, no inline reordering, no horizontal scrolling or dragging, no side-placed overlay, and no horizontal keyboard behavior. Density selects block-axis blur height and symmetric inline padding. Message, composer, and scroll-affordance direction remain with their own owners.",
"evidence": {
- "apps/storybook/stories/ChatLayout.stories.tsx": "sha256:e269ccea468b27e9dc20abd5e7998233c6726d2f84d88b9c6d64fefac74fc9b8",
+ "apps/storybook/stories/ChatLayout.stories.tsx": "sha256:aa1ebf3f4c7d97d41e0029a0a25d7d40f45083fdbb90c2388f4da7bc21e050e8",
"packages/core/src/Chat/ChatLayout.tsx": "sha256:bc5fbef0379c622adaf46dc7119d327100eb40c2440664b3bc288bab758b116b",
"packages/core/src/Chat/index.ts": "sha256:0f4a9d3ee08b4fcd43698ad017460aad109c500d2411913f509506d2a27387bb"
}
@@ -249,8 +249,8 @@
"component": "core/ChatLayoutScrollButton",
"reason": "ChatLayoutScrollButton is a centered pill on the block axis. Its only glyph is the block-axis chevronDown, which points along the axis RTL does not mirror, so mirroring it would be wrong rather than missing. The wrapper centers with justifyContent center, the pill sizes from logical maxWidth and the element-size token, and the labelled form uses logical paddingInline/paddingInlineEnd so the icon leads and the text trails in both directions. It owns no left/right glyph, physical inline positioning, inline ordering, horizontal scrolling or dragging, overlay placement, or horizontal keyboard behavior.",
"evidence": {
- "apps/storybook/stories/ChatLayout.stories.tsx": "sha256:e269ccea468b27e9dc20abd5e7998233c6726d2f84d88b9c6d64fefac74fc9b8",
- "packages/core/src/Chat/ChatLayoutScrollButton.tsx": "sha256:33e69782520576df24846e01712628788eb5b1ccade74db6a836fd47a1eba92d",
+ "apps/storybook/stories/ChatLayout.stories.tsx": "sha256:aa1ebf3f4c7d97d41e0029a0a25d7d40f45083fdbb90c2388f4da7bc21e050e8",
+ "packages/core/src/Chat/ChatLayoutScrollButton.tsx": "sha256:cb604bf1b1df34dee472865372eb0bec876e6cb733029e3b10f6da97dd33fb2c",
"packages/core/src/Chat/index.ts": "sha256:0f4a9d3ee08b4fcd43698ad017460aad109c500d2411913f509506d2a27387bb"
}
}
diff --git a/apps/storybook/stories/ChatLayout.stories.tsx b/apps/storybook/stories/ChatLayout.stories.tsx
index ba1a149539..19cbff6e10 100644
--- a/apps/storybook/stories/ChatLayout.stories.tsx
+++ b/apps/storybook/stories/ChatLayout.stories.tsx
@@ -3,6 +3,7 @@
import type {Meta, StoryObj} from '@storybook/react';
import {
ChatLayout,
+ ChatLayoutScrollButton,
ChatMessageList,
ChatMessage,
ChatMessageBubble,
@@ -955,3 +956,56 @@ export const ScrollAffordanceStates: StoryObj = {
</div>
),
};
+
+/**
+ * The scroll affordance's own rendered configurations, side by side, so the
+ * hidden, collapsed, labelled, and long-label pills can be compared in one
+ * frame and in one theme switch.
+ *
+ * `ScrollAffordanceStates` above owns the *behavioral* fixture — a real
+ * scroller whose position drives the affordance. This one owns the *rendered*
+ * fixture: the labelled pill is only reachable inside ChatLayout when new
+ * messages arrive during a scroll, which no static story can stage, and the
+ * hidden pill occupies no visible place there at all. Rendering the component
+ * directly is what makes those configurations photographable and lets a theme
+ * be judged against the surface it is supposed to paint.
+ *
+ * The long label is deliberately past the pill's expanded ceiling: text
+ * expansion is a real locale outcome, and the frame records what a reader sees
+ * when it happens.
+ */
+export const ScrollButtonStates: StoryObj = {
+ name: 'Scroll Button States',
+ parameters: {layout: 'centered'},
+ render: () => (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 12,
+ padding: 24,
+ width: 360,
+ }}>
+ <div data-scroll-button-state="hidden">
+ <ChatLayoutScrollButton isVisible={false} onClick={() => {}} />
+ </div>
+ <div data-scroll-button-state="visible-collapsed">
+ <ChatLayoutScrollButton isVisible onClick={() => {}} />
+ </div>
+ <div data-scroll-button-state="visible-labelled">
+ <ChatLayoutScrollButton
+ isVisible
+ label="New messages"
+ onClick={() => {}}
+ />
+ </div>
+ <div data-scroll-button-state="visible-long-label">
+ <ChatLayoutScrollButton
+ isVisible
+ label="Neue Nachrichten unterhalb dieser Stelle"
+ onClick={() => {}}
+ />
+ </div>
+ </div>
+ ),
+};
diff --git a/packages/core/src/Chat/ChatLayoutScrollButton.spec.md b/packages/core/src/Chat/ChatLayoutScrollButton.spec.md
new file mode 100644
index 0000000000..f50e722d6f
--- /dev/null
+++ b/packages/core/src/Chat/ChatLayoutScrollButton.spec.md
@@ -0,0 +1,338 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChatLayoutScrollButton
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming, testing]
+verified_by:
+ [
+ packages/core/src/Chat/ChatLayoutScrollButton.test.tsx,
+ packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts,
+ packages/core/src/Chat/__tests__/ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts,
+ apps/storybook/stories/ChatLayout.stories.tsx,
+ apps/storybook/rtl-audit/verified-not-applicable.json,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:component-style-authoring,
+ architecture:component-theming-surface,
+ architecture:theme-tokens,
+ architecture:component-test-sufficiency,
+ architecture:knowledge-contracts,
+ ]
+contributing: []
+system_specs: [spec:AST-029]
+---
+
+# ChatLayoutScrollButton component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `isVisible`, `label`, and `onClick`, plus root `div` passthrough, styles, and ref. No public surface changes here. |
+| Behavior | A pill holding one ghost Button. Hidden state paints nothing and leaves the tab order; a non-empty `label` expands the pill and becomes the visible text; omitted or empty renders icon-only. |
+| End-user impact | A theme that restyles the documented target now repaints the pill a reader sees instead of an invisible full-width row behind it. |
+| Builder impact | None. Props, defaults, DOM shape, ref target, and passthrough element are unchanged. |
+| Compatibility/readiness | Patch-compatible repair. The public target keeps its name and stays a single target; it moves onto the element that paints, which no `guaranteedProperties` declaration existed to promise before. Three inherited violations remain open (FR1a, FR3a, FR6a). |
+| Review checks | Reject a target on the centring row, a hidden pill that keeps keyboard focus, a non-empty label that is not also the accessible name, or a state that paints identically to its opposite. FR1a, FR3a, and FR6a are recorded open violations, not acceptances. |
+| Governing rules | `architecture:component-theming-surface/INV4, INV6`; `architecture:component-style-authoring/INV1, INV5`; `architecture:public-component-api/INV5, INV6, INV8`; WCAG 2.2 SC 2.4.7 and SC 2.5.8 (AA). |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChatLayoutScrollButton is the floating return-to-newest affordance for a chat
+transcript. It owns the pill's appearance and its visible/hidden presentation;
+it owns no scroll state. ChatLayout composes it with `useChatStreamScroll` and
+`useChatNewMessages` by default, and a caller may replace or remove it through
+`ChatLayout`'s `scrollButton` slot.
+
+This record is an observational backfill written during the 2026-09-23
+whole-component audit. It describes verified shipped behavior and the one
+objective repair that travels with it. It adds no behavior, default,
+compatibility promise, or design decision.
+
+## Compatibility and migration
+
+- Released default preserved: yes — `@astryxdesign/[email protected]` ships
+ `isVisible`, `label`, and `onClick` with the same meanings.
+- Compatibility class: theming repair. The target name, its documentation entry,
+ and its count are unchanged; only the element carrying it moves, from the
+ centring row to the pill it centres.
+- Controlled/uncontrolled behavior: unchanged — visibility is a required caller
+ input, and the component holds no state.
+- Migration decision: `component:ChatLayoutScrollButton/DEC-1`
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The pill surface: its fill, elevation, radius, resolved height, and the
+ collapsed/expanded width ceiling.
+- The visible/hidden presentation, including removal from sequential focus
+ navigation while hidden.
+- The default accessible name when the caller supplies no `label`.
+- Centring within its parent, and the gap between the pill and what sits below.
+
+**Does not own / non-goals**
+
+- Scroll position, lock state, and new-message detection — owned by
+ `useChatStreamScroll` and `useChatNewMessages`.
+- Placement in the chat dock and whether the affordance renders at all — owned
+ by `component:ChatLayout` through its `scrollButton` slot.
+- Action semantics, focus ring, press feedback, size geometry, and variant
+ surface — owned by `component:Button`, which this component composes.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------------- | --------------------------- | -------------------------------------------------------------------- | ----------------------------------------- | ------------------- | ----------------------------------- | --------- | ------------------------------------------------- |
+| `isVisible` | `true`, `false` | Whether the affordance is presented and operable | always | required | `component:ChatLayoutScrollButton` | stable | required boolean; no fallback |
+| `label` — omitted | `undefined` | Icon-only; the translated default becomes the accessible name | always | this is the default | `component:ChatLayoutScrollButton` | stable | — |
+| `label` — non-empty | any non-empty string | Visible text, which is also the accessible name | always | — | `component:ChatLayoutScrollButton` | stable | — |
+| `label` — empty | `''` | Icon-only with an empty accessible name — see FR1a | always | — | `component:ChatLayoutScrollButton` | stable | no fallback is applied; the control is unnamed |
+| `onClick` | `() => void` | Activation callback; receives no event | always | required | `component:ChatLayoutScrollButton` | stable | required; no default action |
+| root `div` | `BaseProps<HTMLDivElement>` | `ref`, `xstyle`, `className`, `style`, and remaining DOM passthrough | always | none | `architecture:public-component-api` | stable | `onClick` is omitted from the inherited DOM props |
+
+Consumer syntax and prop defaults remain in `ChatLayoutScrollButton.doc.mjs`.
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision. A `current` contract contains no unresolved rows.
+
+| ID | Candidate invariant | Basis | Draft review state |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------- |
+| FR1 | The control MUST expose a non-empty accessible name in every reachable state. | WCAG 2.2 SC 4.1.2 | settled obligation |
+| FR1a | `label` omitted uses the translated default; a non-empty `label` is the name. **`label=''` currently satisfies neither** — see below. | current behavior, which violates FR1 | **violation of FR1** |
+| FR2 | While `isVisible` is false the pill MUST paint nothing and MUST NOT accept focus, programmatic or sequential. | current behavior; WCAG 2.2 SC 2.4.7 | settled |
+| FR3 | While `isVisible` is true the pill MUST remain keyboard reachable and activate on Enter. | current behavior; WCAG 2.2 SC 2.1.1 | settled |
+| FR3a | A focused control MUST paint a visible focus indicator. **The ring is currently clipped away entirely** — see below. | WCAG 2.2 SC 2.4.7; `spec:AST-020/FR1` | **violation of FR3a** |
+| FR4 | A **non-empty** `label` MUST render as visible text; omitted or empty renders icon-only with no visible text. | current behavior | settled |
+| FR5 | The pill MUST take its resolved height from the element-size token so no theme scale makes it clip the Button it wraps. | current behavior | settled |
+| FR6 | The public theming target MUST sit on the pill — the element painting fill, elevation, and radius — not on the row that centres it. | `architecture:component-theming-surface/INV4` | settled |
+| FR6a | The target MUST expose the state axes that drive its painted styles. **Currently it reflects none** — see below. | `architecture:component-theming-surface/INV6` | **violation of INV6** |
+| FR7 | The transition between states MUST collapse to `0s` under `prefers-reduced-motion: reduce`. | current behavior | settled |
+| FR8 | The collapsed control MUST fit a 24x24 CSS-px square. | WCAG 2.2 SC 2.5.8 (AA) | settled |
+| FR9 | Consumer `ref`, styles, and remaining DOM props MUST reach the component's outer element. | current behavior; `architecture:public-component-api/INV5, INV6, INV8` | settled |
+
+**FR1a — the empty-label naming gap.** `label=''` is permitted by the public
+type and is what ordinary caller code produces from an empty or not-yet-loaded
+string. It reaches the Button as `label=''`, `aria-label=''`, and
+`isIconOnly={true}`, because `??` passes an empty string through. Button sets
+its own `aria-label` only when `label !== ''`, so the caller's empty
+`aria-label` survives; icon-only renders no visible text; and the chevron Icon
+carries no `label`, so it is `aria-hidden="true"`. The result is a focusable,
+operable control with no accessible name.
+
+This record states the obligation and records the current behavior as violating
+it. Closing the gap means choosing between falling back to the default name,
+rejecting the value, or treating an empty label as a caller error — a public
+API and compatibility decision that belongs to the owner, not to an audit. See
+OQ7.
+
+**FR3a — the clipped focus ring.** The composed Button declares a focus ring
+as an `outline` at a positive `outline-offset`, so it is painted entirely
+outside the button's border box. The button fills the pill exactly (measured
+32x32 in 32x32 collapsed, 149x32 in 149x32 labelled), and the pill clips with
+`overflow: hidden`, which it needs to keep the collapse/expand animation inside
+its own rounded shape. There is therefore no room for the ring on any side and
+none of it is painted: captured frames of the focused control are byte-identical
+to the resting control in both configurations and both color modes.
+
+Keyboard access itself is intact — the control takes focus and activates — so
+this is a visibility defect, not a reachability one. The remedy is a production
+change to how the pill clips or where the ring is drawn, and the choice between
+those changes rendered geometry, so it needs a visual review rather than a
+settled correction. `spec:AST-029/FR7` would allow a settled objective fix to
+travel with an audit; this one is not settled, so it is outside **this** PR.
+Recorded as OQ8.
+
+**FR6a — the unreflected state axes.** `isVisible` selects visible/hidden
+styles and `label` selects collapsed/expanded styles, both on the painting
+target, and `themeProps('chat-layout-scroll-button')` is called with no state
+argument. A theme can therefore restyle the pill but cannot address either
+state. Naming those axes is new public theming surface, so the shape belongs to
+the owner. See OQ1.
+
+### Allowed variation
+
+- **AV1 — Expanded width.** The labelled pill's width ceiling is a component
+ design decision, not a theme value. What happens to a label past that ceiling
+ is not settled here; see OQ3.
+- **AV2 — Resolved geometry.** Height, radius, spacing, and duration resolve
+ from theme tokens, so absolute values differ by theme without becoming
+ regressions.
+- **AV3 — Composition.** ChatLayout renders this by default, but a caller may
+ substitute any node or remove the affordance entirely.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------- |
+| hidden | paints nothing, refuses focus, keeps its layout box (FR2) | transition duration |
+| visible, label omitted | named from the default, focusable, fits a 24px square, no visible text (FR1, FR3, FR4, FR8) | resolved pill size |
+| visible, non-empty label | the label is both the visible text and the accessible name (FR1, FR4) | expanded width up to the ceiling |
+| visible, empty label | **fails FR1** — icon-only with an empty accessible name (FR1a) | none; this is a recorded defect |
+| visible, hovered | the pointer paints a state distinct from rest | the overlay the theme resolves |
+| visible, keyboard-focused | **fails FR3a** — focus is held and `:focus-visible` matches, but the ring is clipped away and paints nothing | none; this is a recorded defect |
+| visible, pressed | the press paints a state distinct from hover and rest | the pressed treatment |
+| any visible state, themed | the documented target repaints the pill (FR6); its state axes are unreachable (FR6a) | which properties a theme declares |
+
+### Performance and resources
+
+- **PR1 — No state, no effects, no observers.** The component derives every
+ rendered difference from its props during render and registers no listener,
+ timer, observer, or animation frame.
+
+Current measurements belong in the audit record; this subsection owns only
+durable constraints and their verification target.
+
+## Accessibility contract
+
+- **AR1 — Named.** The control MUST expose a non-empty accessible name in every
+ reachable state (WCAG 2.2 SC 4.1.2) (FR1). Omitted and non-empty `label`
+ satisfy this; `label=''` does not, and that gap is recorded as FR1a rather
+ than resolved here.
+- **AR2 — Focus follows paint.** A control that paints nothing MUST NOT be
+ focusable, because focus landing on it would have no visible indicator
+ (WCAG 2.2 SC 2.4.7). `opacity` and `pointer-events` do not achieve this;
+ `visibility` does (FR2).
+- **AR3a — Focus is visible.** A focused control MUST paint a focus indicator
+ (WCAG 2.2 SC 2.4.7). The ring is declared but clipped away; recorded as FR3a
+ rather than resolved here.
+- **AR3 — Target size.** The collapsed control MUST fit a 24x24 CSS-px square
+ (WCAG 2.2 SC 2.5.8 AA) (FR8).
+- **AR4 — Reduced motion.** The state transition MUST collapse to `0s` under
+ `prefers-reduced-motion: reduce` (FR7).
+- **AR5 — Translated strings.** The default accessible name MUST resolve through
+ the translator catalog, never a literal.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| pill surface | floating affordance over the transcript | unsettled | supporting | FR5, FR6 |
+| hidden state | absent rather than dimmed | unsettled | supporting | FR2, AR2 |
+| labelled state | text accompanies the glyph on the same pill | unsettled | supporting | FR4 |
+
+The component implements design requirements without copying their rationale.
+An `unsettled` representation remains a human decision; principles do not let an
+agent invent the answer. No `authority: current` design record covers a floating
+scroll affordance today, so these rows record the gap rather than a requirement.
+
+## Family and system relationships
+
+- `family:buttons` owns the action surface this component composes through
+ `component:Button`. This component is not a member: its public purpose is a
+ transcript affordance that contains a button, and the family's membership rule
+ excludes components that merely use a Button as an action slot. See OQ4.
+- `architecture:component-theming-surface` owns the target/anatomy relationship
+ this component's theming must satisfy; FR6 adopts INV4 directly.
+- `spec:AST-029` owns the audit flow that produced this observational record.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1, FR4 | `ChatLayoutScrollButton.test.tsx` role/name and visible-text cases | label omitted; non-empty label | dropping `isIconOnly` renders the translated name as clipped visible text, and the name case still passes | `audit:ChatLayoutScrollButton/a11y` |
+| FR1a | **no oracle in any lane today.** Derived from source across three files (`??` passing `''` through, Button's `label !== ''` guard, the Icon's decorative default). A checked-in fixture would add an unnamed control to the shared story set and a new axe baseline entry, so the audit did not add one. | label empty | a fallback added here would make the derivation stale without any test failing | `audit:ChatLayoutScrollButton/a11y` |
+| FR2, FR3 | `ChatLayoutScrollButton.test.tsx` tab cases; `ChatLayoutScrollButton.a11y.chromium.spec.ts` | hidden at rest; scrolled up; re-hidden | replacing `visibility` with `opacity` alone leaves the invisible control in the tab order | `audit:ChatLayoutScrollButton/a11y` |
+| FR3a | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` interaction pass: the focused frame's bytes are compared with a rest frame captured from the same page, and the ring's outward reach is measured against the clipping ancestor's room (recorded as `ringChangedPixels`, `outreach`, `roomPx`) | collapsed and labelled, light and dark | the result is recorded and annotated, never asserted, so repairing the clip cannot turn this check red | `audit:ChatLayoutScrollButton/a11y` |
+| FR5 | `ChatLayoutScrollButton.a11y.chromium.spec.ts` two-theme geometry pair and its pre-fix arm | neutral and butter | a literal height lets a larger element scale clip the Button the pill wraps | `audit:ChatLayoutScrollButton/theming` |
+| FR6 | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` placement and probe-theme reach tests | visible, collapsed, neutral and probe | moving the target back to the centring row leaves the pill unchanged under the probe theme | `audit:ChatLayoutScrollButton/theming` |
+| FR6a | source: `themeProps()` is called with no state argument, and `Chat.doc.mjs` declares the target with no `visualProps`/`states` | visible/hidden; collapsed/expanded | adding either axis is new public theming surface, so no test may assert its shape before the owner decides | `audit:ChatLayoutScrollButton/theming` |
+| hover, pressed | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` interaction pass — each frame asserts the pseudo-class matched and that the captured bytes differ from a rest frame of the same page | collapsed and labelled, light and dark | a frame captured after release, or with the pointer elsewhere, fails its own engagement assertion | `audit:ChatLayoutScrollButton/design` |
+| FR7 | source declaration plus `holdMotionStill` capture conditions | any transition | removing the reduced-motion branch restores animation for readers who asked for none | `audit:ChatLayoutScrollButton/a11y` |
+| FR8 | `ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts` measured target box | visible, collapsed | a smaller resolved size drops the control below the AA minimum | `audit:ChatLayoutScrollButton/a11y` |
+| FR9 | `ChatLayoutScrollButton.test.tsx` passthrough case | any | dropping `...rest` silently discards `data-*`, `id`, and ARIA the caller set | `audit:ChatLayoutScrollButton/public-api` |
+
+## Decision log
+
+### DEC-1 — The public theming target rides the pill, not the row that centres it
+
+**Reference:** `component:ChatLayoutScrollButton/DEC-1`
+**Decider:** `cixzhang`, `2026-09-23`
+
+`architecture:component-theming-surface/INV4` requires a target to sit on a
+stable visible element that paints theme-controlled output. The component
+renders two elements: a full-width row that centres the pill and holds the gap
+below it, and the pill itself, which paints the fill, elevation, and radius. The
+target sat on the row, so a theme that styled the documented name painted a band
+across the chat dock while the pill kept the surface the theme asked to replace.
+
+The name, the documentation entry, and the target count are unchanged, and no
+`guaranteedProperties` declaration existed to promise the old element, so this
+repairs a reachability gap rather than removing a compatibility path.
+
+Rejected: adding a second target for the pill. That is new public theming
+surface for a component that needs exactly one, and it would leave the
+non-painting target in place.
+
+Rejected: moving consumer passthrough to the pill alongside the target.
+`ref`, `xstyle`, `className`, `style`, and the remaining DOM props keep
+landing on the outer element, which is the element the released type, the
+existing passthrough test, and `architecture:public-component-api/INV5, INV8`
+name as the contract's owner. Relocating them would change where a caller's
+`id`, `data-*`, and ref resolve, which is a compatibility decision and not part
+of this repair.
+
+## Open questions
+
+- **OQ1 — Should the target reflect its style-driving states?** (`human-api`)
+ The pill selects between visible/hidden and collapsed/expanded style objects,
+ and `themeProps` reflects neither, so a theme cannot address either state.
+ Exposing them means adding `visualProps`/`states` to a public target, which is
+ new theming surface rather than a repair.
+- **OQ2 — Is `isVisible` the right name on a non-layer component?** (`human-api`)
+ The shared convention reserves `isOpen`/`isVisible` for layer components. The
+ prop is released in `@astryxdesign/[email protected]`, so any change is breaking and
+ needs a compatibility decision.
+- **OQ3 — What should happen to a label past the expanded ceiling?** (`human-design`)
+ The pill clips at its width ceiling with no ellipsis and no wrap. The
+ accessible name survives, so only sighted readers lose text, and locale
+ expansion is the realistic trigger. No `authority: current` design record
+ covers truncation for this surface.
+- **OQ4 — Does this component belong to `family:buttons`?** (`human-api`)
+ Its public purpose is a transcript affordance, and it is absent from the
+ family's member list, but it is a single composed Button with no other
+ content. The family contract's exclusion for "components that merely use a
+ Button as a trigger or action slot" is the reading applied above.
+- **OQ5 — Is animating the pill's `max-width` acceptable?** (`human-design`)
+ Expanding and collapsing animates a layout property. Reduced motion is
+ honored and the subtree is one button, but the record that would govern
+ animated properties, `design:motion`, is `authority: draft`.
+- **OQ6 — The consumer doc has no anatomy inventory.** (`human-api`)
+ `architecture:component-theming-surface` records this as open migration work
+ across Core, so no `### Theming anatomy` block is written here: there are no
+ published anatomy names for it to map.
+
+- **OQ8 — How should the focus ring escape the pill's clip?** (`human-design`)
+ The pill needs `overflow: hidden` for its collapse/expand animation, and the
+ Button's ring is drawn outside its border box, so the two are in direct
+ conflict. Candidate answers — inset the button so the ring fits, draw the
+ ring on the pill, or clip on a different element — each change rendered
+ geometry and belong to a visual review.
+- **OQ7 — What should `label=''` do?** (`human-api`)
+ It currently produces an unnamed control (FR1a). The candidate answers — fall
+ back to the translated default, reject the value in the type, or treat it as
+ a caller error — are a public API and compatibility decision on a released
+ prop, so the audit recorded the violation instead of choosing one.
+
+## 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.
diff --git a/packages/core/src/Chat/ChatLayoutScrollButton.tsx b/packages/core/src/Chat/ChatLayoutScrollButton.tsx
index 72f2e2c4b0..f79025b815 100644
--- a/packages/core/src/Chat/ChatLayoutScrollButton.tsx
+++ b/packages/core/src/Chat/ChatLayoutScrollButton.tsx
@@ -139,20 +139,25 @@ export function ChatLayoutScrollButton({
}: ChatLayoutScrollButtonProps) {
const t = useTranslator();
return (
+ // Two elements, two responsibilities. The outer one centres the pill and
+ // holds the gap above the composer — spacing outside the pill's border
+ // box, which the pill cannot own itself. The inner one is the pill: it is
+ // what a reader sees, so it carries the painted surface AND the public
+ // theming target. Keeping the target on the outer element would satisfy
+ // every automated check while leaving a theme styling an invisible
+ // full-width row (architecture:component-theming-surface INV4).
<div
ref={ref}
- {...mergeProps(
- themeProps('chat-layout-scroll-button'),
- stylex.props(styles.wrapper, xstyle),
- className,
- style,
- )}
+ {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
{...rest}>
<div
- {...stylex.props(
- styles.container,
- isVisible ? styles.visible : styles.hidden,
- label ? styles.expanded : styles.collapsed,
+ {...mergeProps(
+ themeProps('chat-layout-scroll-button'),
+ stylex.props(
+ styles.container,
+ isVisible ? styles.visible : styles.hidden,
+ label ? styles.expanded : styles.collapsed,
+ ),
)}>
<Button
label={label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')}
diff --git a/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts b/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts
index d161d81e5d..7ff56b2772 100644
--- a/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts
+++ b/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts
@@ -38,8 +38,12 @@ import {
const OUTPUT = path.resolve('test-results/chat-layout-audit-evidence');
const STORY_ID = 'core-chatlayout--scroll-affordance-states';
-/** The pill wrapper: the element whose visibility and height are the claims. */
-const PILL = '.astryx-chat-layout-scroll-button > div';
+/**
+ * The pill: the element wrapping the Button, whose visibility and height are
+ * the claims below. It also carries the public theming target, so the class is
+ * a stable handle for it.
+ */
+const PILL = '.astryx-chat-layout-scroll-button';
/** One observed tab stop, identified structurally rather than by its text. */
type FocusStop = {
diff --git a/packages/core/src/Chat/__tests__/ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts b/packages/core/src/Chat/__tests__/ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..c1cecc673e
--- /dev/null
+++ b/packages/core/src/Chat/__tests__/ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts
@@ -0,0 +1,740 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts
+ * @input Uses the ChatLayout scroll-button states story and a built Storybook
+ * @output Rendered evidence that the documented theming target reaches the
+ * element painting the pill, plus the audited state frames and their receipts
+ * @position Real-Chromium evidence for the 2026-09-23 ChatLayoutScrollButton
+ * audit. Frames land under the component-audit evidence directory that CI
+ * already uploads, in a `scroll-button/` subdirectory so this manifest never
+ * merges with the sibling ChatLayout manifest.
+ *
+ * The claim under test is `architecture:component-theming-surface` INV4:
+ * "A target belongs on a stable visible element that paints theme-controlled
+ * output—not an event wrapper, speculative internal structure, or a node
+ * created only for layout plumbing."
+ *
+ * This is not observable in the unit lane and not observable to the probe-reach
+ * gate either. jsdom resolves no cascade, so it cannot say which element paints.
+ * The gate's reach check asks whether a target's override lands on the element
+ * carrying the class, and it does — that element simply is not the one a reader
+ * sees. Only a real engine can be asked the question that matters: does styling
+ * the documented target change the pill?
+ *
+ * The pill is identified structurally, as the button's parent element, so every
+ * measurement below is independent of where the class currently sits.
+ */
+
+import {createHash} from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve(
+ 'test-results/chat-layout-audit-evidence/scroll-button',
+);
+const STORY_ID = 'core-chatlayout--scroll-button-states';
+
+/** The rendered configurations the story stages, in capture order. */
+const STATES = [
+ 'hidden',
+ 'visible-collapsed',
+ 'visible-labelled',
+ 'visible-long-label',
+] as const;
+
+type State = (typeof STATES)[number];
+
+/** How an interaction frame was driven. `rest` is the undriven baseline. */
+type Interaction = 'rest' | 'hover' | 'focus-visible' | 'pressed';
+
+/** The two configurations whose interaction states the audit grades. */
+const INTERACTION_STATES = ['visible-collapsed', 'visible-labelled'] as const;
+
+type Shot = {
+ file: string;
+ sha256: string;
+ /** Decoded from the PNG's own IHDR — the image's pixels, not the viewport. */
+ width: number;
+ height: number;
+};
+
+type Receipt = {
+ state: string;
+ storyId: string;
+ theme: string;
+ colorMode: string;
+ direction: string;
+ /** The window, recorded in its own row so it can never be read as the image. */
+ viewport: {width: number; height: number};
+ devicePixelRatio: number;
+ rendered: Record<string, unknown>;
+ geometry: {selectorCount: number; width: number; height: number};
+ settled: {fontsReady: boolean; pageErrors: number};
+ image: Shot;
+};
+
+const receipts: Receipt[] = [];
+const pageErrors: string[] = [];
+let storybook: StaticServer;
+let browserVersion = 'unknown';
+
+test.beforeAll(async () => {
+ // Do NOT wipe: Playwright restarts the worker after a failing test and
+ // re-runs this hook, which would delete the frames already banked — exactly
+ // when a failing audit needs them most.
+ fs.mkdirSync(OUTPUT, {recursive: true});
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ const manifestPath = path.join(OUTPUT, 'manifest.json');
+ const previous = fs.existsSync(manifestPath)
+ ? (JSON.parse(fs.readFileSync(manifestPath, 'utf8')).frames ?? [])
+ : [];
+ const merged = [...previous, ...receipts].filter(
+ (frame, index, all) =>
+ all.findIndex(other => other.state === frame.state) === index,
+ );
+ fs.writeFileSync(
+ manifestPath,
+ `${JSON.stringify(
+ {
+ version: 1,
+ component: 'core/ChatLayoutScrollButton',
+ headSha:
+ process.env.ASTRYX_HEAD_SHA ??
+ process.env.GITHUB_SHA ??
+ 'local-working-copy',
+ checkoutSha: process.env.GITHUB_SHA ?? 'local-working-copy',
+ browser: browserVersion,
+ frames: merged,
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ await storybook?.close();
+});
+
+async function openStory(
+ page: Page,
+ {theme = 'neutral', colorMode = 'light'} = {},
+): Promise<void> {
+ page.on('pageerror', error => pageErrors.push(String(error)));
+ browserVersion = page.context().browser()?.version() ?? 'unknown';
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=${STORY_ID}&viewMode=story` +
+ `&globals=colorMode:${colorMode};astryxTheme:${theme}`,
+ );
+ await page.locator(`[data-scroll-button-state="hidden"]`).waitFor();
+ await holdMotionStill(page);
+ await page.evaluate(async () => document.fonts.ready);
+}
+
+function instance(page: Page, state: State): Locator {
+ return page.locator(`[data-scroll-button-state="${state}"]`);
+}
+
+/**
+ * Read one staged instance: which element carries the public target, whether
+ * that element is the one painting the pill, and what each of them paints.
+ *
+ * The pill is `button.parentElement` — the element that clips the Button and
+ * carries the surface a reader sees. Naming it structurally rather than by
+ * class is the whole point: the question is *where the class is*, so the
+ * measurement cannot be allowed to depend on the answer.
+ */
+async function readInstance(page: Page, state: State) {
+ return instance(page, state).evaluate(host => {
+ const button = host.querySelector('button');
+ const pill = button?.parentElement ?? null;
+ const themed = host.querySelector('.astryx-chat-layout-scroll-button');
+ const root = host.firstElementChild;
+
+ const describe = (element: Element | null) => {
+ if (element == null) {
+ return null;
+ }
+ const styles = getComputedStyle(element);
+ const box = element.getBoundingClientRect();
+ return {
+ backgroundColor: styles.backgroundColor,
+ boxShadow: styles.boxShadow,
+ borderRadius: styles.borderTopLeftRadius,
+ visibility: styles.visibility,
+ width: Math.round(box.width),
+ height: Math.round(box.height),
+ };
+ };
+
+ return {
+ targetCount: host.querySelectorAll('.astryx-chat-layout-scroll-button')
+ .length,
+ /** Is the public target on the element that paints the pill? */
+ targetIsPill: themed != null && themed === pill,
+ /** Or is it on the component's outermost layout node? */
+ targetIsRoot: themed != null && themed === root,
+ themed: describe(themed),
+ pill: describe(pill),
+ root: describe(root),
+ button: (() => {
+ if (button == null) {
+ return null;
+ }
+ const box = button.getBoundingClientRect();
+ const label = button.querySelector('span, p, div');
+ return {
+ width: Math.round(box.width),
+ height: Math.round(box.height),
+ accessibleName: button.getAttribute('aria-label'),
+ textOverflowing:
+ label != null ? label.scrollWidth > label.clientWidth + 1 : false,
+ };
+ })(),
+ };
+ });
+}
+
+/**
+ * Where the focus ring would be drawn, and whether anything clips it away.
+ *
+ * `outline` is painted OUTSIDE the element's border box, starting at
+ * `outline-offset` and extending `outline-width` further. If an ancestor with
+ * `overflow: hidden` has no room between the button's border box and its own
+ * padding box, every pixel of that ring is clipped and the computed style is a
+ * promise the page never keeps.
+ */
+async function readFocusRingRoom(page: Page, state: State) {
+ return instance(page, state)
+ .locator('button')
+ .evaluate(element => {
+ const styles = getComputedStyle(element);
+ const offset = Number.parseFloat(styles.outlineOffset) || 0;
+ const width = Number.parseFloat(styles.outlineWidth) || 0;
+
+ let clipper: Element | null = element.parentElement;
+ while (clipper != null) {
+ const overflow = getComputedStyle(clipper).overflow;
+ if (overflow !== 'visible') {
+ break;
+ }
+ clipper = clipper.parentElement;
+ }
+ if (clipper == null) {
+ return {outreach: offset + width, clipped: false, roomPx: null};
+ }
+
+ const button = element.getBoundingClientRect();
+ const clip = clipper.getBoundingClientRect();
+ // Smallest gap on any side between the button's box and the clip box.
+ const room = Math.min(
+ button.top - clip.top,
+ button.left - clip.left,
+ clip.right - button.right,
+ clip.bottom - button.bottom,
+ );
+ return {
+ outreach: offset + width,
+ roomPx: Math.round(room),
+ clipperOverflow: getComputedStyle(clipper).overflow,
+ clipperClass:
+ [...clipper.classList].find(name => name.startsWith('astryx-')) ??
+ null,
+ clipped: room < offset + width,
+ };
+ });
+}
+
+/** `rgba(r, g, b, 0)` and `transparent` both mean "this element paints no fill". */
+function isTransparent(color: string): boolean {
+ return color === 'transparent' || /,\s*0\)$/.test(color);
+}
+
+/**
+ * What the Button is painting right now: the four properties its interaction
+ * states actually move. Recorded per frame so a reader can confirm from the
+ * receipt that the state engaged, rather than trusting the file name.
+ *
+ * Read from the `<button>` rather than the pill: the pill owns the surface and
+ * the theming target, while hover, focus, and press are Button's own treatment.
+ */
+async function readButtonPaint(page: Page, state: State) {
+ return instance(page, state)
+ .locator('button')
+ .evaluate(element => {
+ const styles = getComputedStyle(element);
+ return {
+ backgroundColor: styles.backgroundColor,
+ backgroundImage: styles.backgroundImage,
+ transform: styles.transform,
+ outlineWidth: styles.outlineWidth,
+ outlineStyle: styles.outlineStyle,
+ isFocused: document.activeElement === element,
+ matchesFocusVisible: element.matches(':focus-visible'),
+ matchesHover: element.matches(':hover'),
+ matchesActive: element.matches(':active'),
+ };
+ });
+}
+
+/**
+ * Tab from the top of the document until focus lands inside `state`.
+ *
+ * Keyboard is the only modality that yields `:focus-visible` — a synthetic
+ * `focus()` call does not, and a click sets pointer modality and suppresses
+ * it. The page must therefore be freshly loaded with no pointer press behind
+ * it, which is why the caller reloads before asking for a focus frame.
+ */
+async function tabTo(
+ page: Page,
+ state: State,
+ maxPresses = 8,
+): Promise<boolean> {
+ for (let index = 0; index < maxPresses; index += 1) {
+ await page.keyboard.press('Tab');
+ const landed = await page.evaluate(selector => {
+ const active = document.activeElement;
+ return active != null && active.closest(selector) != null;
+ }, `[data-scroll-button-state="${state}"]`);
+ if (landed) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/**
+ * Read a PNG's real pixel dimensions out of its IHDR header.
+ *
+ * These are ELEMENT screenshots, so their size is the subject's box, not the
+ * window's. The viewport keeps its own receipt row; publishing it as the image
+ * size would be a false claim about the bytes on disk.
+ */
+function pngShot(file: string, bytes: Buffer): Shot {
+ return {
+ file,
+ sha256: createHash('sha256').update(bytes).digest('hex'),
+ width: bytes.readUInt32BE(16),
+ height: bytes.readUInt32BE(20),
+ };
+}
+
+async function capture(
+ page: Page,
+ state: State,
+ frameName: string,
+ rendered: Record<string, unknown>,
+ {theme = 'neutral', colorMode = 'light'} = {},
+): Promise<Receipt> {
+ const host = instance(page, state);
+ const box = await host.boundingBox();
+ if (box == null) {
+ throw new Error(`${frameName}: the staged instance has no layout box`);
+ }
+ const bytes = await host.screenshot({animations: 'disabled'});
+ const file = `chat-layout-scroll-button__${frameName}.png`;
+ fs.writeFileSync(path.join(OUTPUT, file), bytes);
+
+ const window = await page.evaluate(() => ({
+ width: globalThis.innerWidth,
+ height: globalThis.innerHeight,
+ dpr: globalThis.devicePixelRatio,
+ }));
+
+ const receipt: Receipt = {
+ state: frameName,
+ storyId: STORY_ID,
+ theme: await page.evaluate(
+ () =>
+ document
+ .querySelector('[data-astryx-theme]')
+ ?.getAttribute('data-astryx-theme') ?? 'neutral',
+ ),
+ colorMode: await page.evaluate(
+ () => getComputedStyle(document.documentElement).colorScheme,
+ ),
+ direction: await host.evaluate(
+ element => getComputedStyle(element).direction,
+ ),
+ viewport: {width: window.width, height: window.height},
+ devicePixelRatio: window.dpr,
+ rendered: {
+ requestedTheme: theme,
+ requestedColorMode: colorMode,
+ ...rendered,
+ },
+ geometry: {
+ selectorCount: await host.count(),
+ width: Math.round(box.width),
+ height: Math.round(box.height),
+ },
+ settled: {fontsReady: true, pageErrors: pageErrors.length},
+ image: pngShot(file, bytes),
+ };
+ receipts.push(receipt);
+ return receipt;
+}
+
+test('the documented theming target sits on the element that paints the pill', async ({
+ page,
+}) => {
+ await openStory(page);
+ const state: State = 'visible-collapsed';
+ const reading = await readInstance(page, state);
+
+ // The frame is banked BEFORE the assertions, so a failing run still publishes
+ // the picture of what it found.
+ await capture(page, state, 'target-placement-neutral', {
+ targetIsPill: reading.targetIsPill,
+ targetIsRoot: reading.targetIsRoot,
+ themed: reading.themed,
+ pill: reading.pill,
+ });
+
+ expect(reading.targetCount, 'exactly one element carries the target').toBe(1);
+
+ // INV4, read directly: the target is on the painting element, and that
+ // element is the pill rather than the full-width row that centres it.
+ expect(
+ reading.targetIsPill,
+ 'architecture:component-theming-surface INV4 — the public target must sit ' +
+ 'on the element that paints the pill, not on the layout node that centres it',
+ ).toBe(true);
+
+ expect(
+ isTransparent(reading.themed?.backgroundColor ?? 'transparent'),
+ 'the themed element must paint a fill a theme can replace',
+ ).toBe(false);
+ expect(
+ reading.themed?.boxShadow,
+ 'the themed element must own the pill elevation',
+ ).not.toBe('none');
+
+ // A target on the centring row is as wide as the dock; a target on the pill
+ // is as wide as the pill. The numbers separate the two without naming either.
+ expect(reading.themed?.width).toBe(reading.pill?.width);
+ expect(reading.themed?.height).toBe(reading.pill?.height);
+
+ expect(pageErrors).toEqual([]);
+});
+
+test('a theme that styles the documented target repaints the pill', async ({
+ page,
+}) => {
+ const state: State = 'visible-collapsed';
+
+ // The probe theme exists precisely to answer this: it styles every declared
+ // target with a loud generated colour, so "did the override reach the pixels
+ // a reader sees" is an equality test rather than a judgement.
+ await openStory(page, {theme: 'neutral'});
+ const neutral = await readInstance(page, state);
+ await capture(page, state, 'theme-reach-neutral', {
+ pillBackground: neutral.pill?.backgroundColor,
+ rootBackground: neutral.root?.backgroundColor,
+ });
+
+ await openStory(page, {theme: 'probe'});
+ const probe = await readInstance(page, state);
+ await capture(
+ page,
+ state,
+ 'theme-reach-probe',
+ {
+ pillBackground: probe.pill?.backgroundColor,
+ rootBackground: probe.root?.backgroundColor,
+ targetIsPill: probe.targetIsPill,
+ },
+ {theme: 'probe'},
+ );
+
+ expect(
+ probe.pill?.backgroundColor,
+ 'the probe theme must actually change the surface the reader sees; an ' +
+ 'unchanged pill means the override landed somewhere else',
+ ).not.toBe(neutral.pill?.backgroundColor);
+
+ // ---- regression arm -----------------------------------------------------
+ // ARM: pre-fix target placement
+ // BASE: this head, probe theme, same page
+ // DELTA: the target class is moved from the pill back up to the component's
+ // outer layout node — one `classList` move, and nothing else.
+ // UNRELATED DELTA: none
+ const armMoved = await instance(page, state).evaluate(host => {
+ const root = host.firstElementChild;
+ const themed = host.querySelector('.astryx-chat-layout-scroll-button');
+ if (root == null || themed == null || themed === root) {
+ return false;
+ }
+ themed.classList.remove('astryx-chat-layout-scroll-button');
+ root.classList.add('astryx-chat-layout-scroll-button');
+ return true;
+ });
+ expect(
+ armMoved,
+ 'the arm must actually relocate the target, or it proves nothing',
+ ).toBe(true);
+
+ const arm = await readInstance(page, state);
+ await capture(
+ page,
+ state,
+ 'theme-reach-probe-prefix-placement',
+ {
+ arm: 'pre-fix placement (target on the outer layout node)',
+ pillBackground: arm.pill?.backgroundColor,
+ rootBackground: arm.root?.backgroundColor,
+ rootWidth: arm.root?.width,
+ pillWidth: arm.pill?.width,
+ },
+ {theme: 'probe'},
+ );
+
+ // What the fix prevents: the theme colour lands on the invisible centring
+ // row — painting a band the width of the dock — while the pill a reader
+ // actually sees keeps the colour the theme asked to replace.
+ expect(arm.pill?.backgroundColor).toBe(neutral.pill?.backgroundColor);
+ expect(arm.root?.backgroundColor).not.toBe(neutral.root?.backgroundColor);
+ expect(arm.root?.width).toBeGreaterThan(arm.pill?.width ?? 0);
+
+ expect(pageErrors).toEqual([]);
+});
+
+test('every audited state renders in light and dark, and the target meets WCAG 2.5.8', async ({
+ page,
+}) => {
+ for (const colorMode of ['light', 'dark'] as const) {
+ await openStory(page, {colorMode});
+ for (const state of STATES) {
+ const reading = await readInstance(page, state);
+ await capture(
+ page,
+ state,
+ `${state}__${colorMode}`,
+ {
+ pillVisibility: reading.pill?.visibility,
+ pillWidth: reading.pill?.width,
+ pillHeight: reading.pill?.height,
+ buttonWidth: reading.button?.width,
+ buttonHeight: reading.button?.height,
+ accessibleName: reading.button?.accessibleName,
+ labelTextOverflowing: reading.button?.textOverflowing,
+ },
+ {colorMode},
+ );
+
+ if (state === 'visible-collapsed') {
+ // WCAG 2.2 SC 2.5.8 (AA): a 24x24 CSS-px square fits inside the
+ // target. Measured rather than derived from the size token, because
+ // the token is a theme dial and the criterion is not.
+ expect(
+ reading.button?.width ?? 0,
+ `${colorMode}: the collapsed target must fit a 24px square`,
+ ).toBeGreaterThanOrEqual(24);
+ expect(
+ reading.button?.height ?? 0,
+ `${colorMode}: the collapsed target must fit a 24px square`,
+ ).toBeGreaterThanOrEqual(24);
+ }
+ }
+ }
+
+ expect(pageErrors).toEqual([]);
+});
+
+/**
+ * The interaction states, driven for real and photographed while they are
+ * engaged.
+ *
+ * Twelve frames: the two visible configurations x hover, keyboard
+ * focus-visible, and a held press x light and dark. Every frame asserts that
+ * the state actually engaged — `:hover`, `:focus-visible`, or `:active`
+ * matched — and compares the captured bytes against a rest frame taken from
+ * the same page moments earlier.
+ *
+ * The byte comparison is the point. An earlier revision proved hover and press
+ * from computed style and accepted a non-zero `outline-width` as proof of a
+ * visible focus ring. That was a false positive: this component's focus ring
+ * is painted entirely outside the button's border box, and the pill that wraps
+ * it clips with `overflow: hidden`, so all four focused frames came back
+ * byte-identical to rest while every computed reading said the ring was there.
+ * Computed style says what was declared; only the frame says what was painted.
+ *
+ * Order within a color mode is deliberate. Hover comes first; the pointer then
+ * moves away before the focus pass, or the hovered element would still paint
+ * hover underneath the focus ring. Press comes last, because a pointer press
+ * sets pointer modality and suppresses `:focus-visible` for the rest of the
+ * page's life — so the page is reloaded before the focus pass to guarantee the
+ * keyboard modality the ring depends on.
+ */
+test('the interaction states are driven and photographed while engaged', async ({
+ page,
+}) => {
+ for (const colorMode of ['light', 'dark'] as const) {
+ /** Rest, for the same page and color mode, as the comparison baseline. */
+ await openStory(page, {colorMode});
+ // Park the pointer FIRST. A reload does not move the physical mouse, so
+ // without this the second color mode reads its "rest" through whichever
+ // button the previous pass left the cursor over — and that reading is a
+ // hover reading, which then makes hover look like it paints nothing. The
+ // engagement assertion below caught exactly that, so it is load-bearing.
+ await page.mouse.move(0, 0);
+ const rest: Record<
+ string,
+ Awaited<ReturnType<typeof readButtonPaint>>
+ > = {};
+ for (const state of INTERACTION_STATES) {
+ rest[state] = await readButtonPaint(page, state);
+ expect(
+ rest[state].matchesHover,
+ `${state}/${colorMode}: the rest baseline must not itself be hovered`,
+ ).toBe(false);
+ }
+
+ // ---- hover ------------------------------------------------------------
+ for (const state of INTERACTION_STATES) {
+ const restBytes = await instance(page, state).screenshot({
+ animations: 'disabled',
+ });
+ const restSha = createHash('sha256').update(restBytes).digest('hex');
+
+ await instance(page, state).locator('button').hover();
+ const paint = await readButtonPaint(page, state);
+ const interaction: Interaction = 'hover';
+ const receipt = await capture(
+ page,
+ state,
+ `${state}__${interaction}__${colorMode}`,
+ {interaction, paint, restPaint: rest[state]},
+ {colorMode},
+ );
+ receipt.rendered.restSha256 = restSha;
+ receipt.rendered.changedPixels = receipt.image.sha256 !== restSha;
+
+ expect(
+ paint.matchesHover,
+ `${state}/${colorMode}: the pointer must actually be over the button`,
+ ).toBe(true);
+ // Pixels, not computed style. That distinction is the whole lesson of
+ // the focus finding below.
+ expect(
+ receipt.image.sha256 !== restSha,
+ `${state}/${colorMode}: the hovered frame must differ from rest`,
+ ).toBe(true);
+ }
+
+ // ---- keyboard focus-visible -------------------------------------------
+ // Reload rather than move the mouse: this pass must run with no pointer
+ // interaction behind it at all.
+ await openStory(page, {colorMode});
+ await page.mouse.move(0, 0);
+ for (const state of INTERACTION_STATES) {
+ // The rest bytes for THIS page, taken before focus is driven. Held in
+ // memory: it is the comparison subject, not a frame worth publishing.
+ const restBytes = await instance(page, state).screenshot({
+ animations: 'disabled',
+ });
+ const restSha = createHash('sha256').update(restBytes).digest('hex');
+
+ const reached = await tabTo(page, state);
+ expect(reached, `${state}/${colorMode}: Tab must reach the button`).toBe(
+ true,
+ );
+ const paint = await readButtonPaint(page, state);
+ const room = await readFocusRingRoom(page, state);
+ const interaction: Interaction = 'focus-visible';
+ const receipt = await capture(
+ page,
+ state,
+ `${state}__${interaction}__${colorMode}`,
+ {interaction, paint, restPaint: rest[state], focusRing: room},
+ {colorMode},
+ );
+
+ // Keyboard reachability is real and must not regress.
+ expect(
+ paint.isFocused && paint.matchesFocusVisible,
+ `${state}/${colorMode}: the button must hold keyboard-visible focus`,
+ ).toBe(true);
+
+ // What the ring actually does to the pixels. An earlier revision of this
+ // spec asserted `outlineStyle !== 'none' && outlineWidth !== '0px'` and
+ // called that proof of a visible ring. It is not: a computed outline is
+ // a declaration, and this one is painted entirely outside the button's
+ // border box, where an ancestor clips it away. The frame is the only
+ // thing that can answer the question, so the frame is what is compared.
+ const ringChangedPixels = receipt.image.sha256 !== restSha;
+ receipt.rendered.restSha256 = restSha;
+ receipt.rendered.ringChangedPixels = ringChangedPixels;
+
+ if (!ringChangedPixels) {
+ // Deliberately NOT an assertion, in either direction. Asserting a pass
+ // would be the false positive again; asserting the failure would turn
+ // the repair into a red check and enshrine the defect as the baseline.
+ // It is recorded in the receipt, annotated on the run, and reported as
+ // an open BLOCK in the audit.
+ const note =
+ `KNOWN FAILURE — ${state}/${colorMode}: the focused frame is ` +
+ `byte-identical to rest, so the keyboard focus indicator paints ` +
+ `nothing (WCAG 2.2 SC 2.4.7; spec:AST-020/FR1). The ring reaches ` +
+ `${room.outreach}px beyond the button's border box and the ` +
+ `clipping ancestor leaves ${room.roomPx}px of room ` +
+ `(overflow: ${room.clipperOverflow}). Open BLOCK, not accepted.`;
+ console.warn(note);
+ test
+ .info()
+ .annotations.push({type: 'known-failure', description: note});
+ }
+ }
+
+ // ---- held press -------------------------------------------------------
+ // Captured with the button still down. Releasing first would photograph
+ // the state the press returns to, not the press.
+ for (const state of INTERACTION_STATES) {
+ await openStory(page, {colorMode});
+ const button = instance(page, state).locator('button');
+ const box = await button.boundingBox();
+ if (box == null) {
+ throw new Error(`${state}: the button has no layout box`);
+ }
+ const restBytes = await instance(page, state).screenshot({
+ animations: 'disabled',
+ });
+ const restSha = createHash('sha256').update(restBytes).digest('hex');
+ await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+ await page.mouse.down();
+ const paint = await readButtonPaint(page, state);
+ const interaction: Interaction = 'pressed';
+ const receipt = await capture(
+ page,
+ state,
+ `${state}__${interaction}__${colorMode}`,
+ {interaction, paint, restPaint: rest[state]},
+ {colorMode},
+ );
+ await page.mouse.up();
+ receipt.rendered.restSha256 = restSha;
+ receipt.rendered.changedPixels = receipt.image.sha256 !== restSha;
+
+ expect(
+ paint.matchesActive,
+ `${state}/${colorMode}: the button must still be held down`,
+ ).toBe(true);
+ expect(
+ receipt.image.sha256 !== restSha,
+ `${state}/${colorMode}: the pressed frame must differ from rest`,
+ ).toBe(true);
+ }
+ }
+
+ expect(pageErrors).toEqual([]);
+});