Skip to content

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

TypeScript

test(a11y): add Carousel semantic contract (#6599)

Cindy Zhang9f45321e2480
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 936d5df6ea..feef65e993 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1768,6 +1768,55 @@ jobs:
retention-days: 30
if-no-files-found: warn
+ # The carousel contract's collection and slide names, off-screen slide
+ # exposure, scroll-area keyboard entry and exit, and control focus are
+ # accessibility-tree and engine facts that jsdom cannot observe. Run the
+ # contract's own fixture proof and the Carousel binding whenever Carousel
+ # source, the binding's stories, or the contract changes. Its own --output
+ # directory; the JSON report is the head-bound record, uploaded next.
+ - name: Run Carousel accessibility contract
+ id: carousel-contract
+ if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+ env:
+ BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ PLAYWRIGHT_JSON_OUTPUT_FILE: carousel-contract/report.json
+ run: |
+ should_run=false
+ # Carousel and the contract are matched by file name.
+ # The helper comes from the base, since an older PR head lacks it.
+ # Exit 1 means out of scope; 0 in scope; 2 unknown, so run.
+ scope=2
+ helper="$(mktemp)"
+ if git fetch --quiet --no-tags --depth=1 origin "$BASE_SHA" \
+ && git show "$BASE_SHA:.github/scripts/pr-scope-touches.sh" > "$helper"; then
+ scope=0
+ bash "$helper" "$BASE_SHA" \
+ '^(internal/a11y-spec/src/patterns/carousel|packages/core/src/Carousel/|apps/storybook/stories/CarouselA11y)' || scope=$?
+ fi
+ if [ "$scope" != 1 ]; then
+ should_run=true
+ fi
+ echo "should_run=${should_run}" >> "$GITHUB_OUTPUT"
+ if [ "$should_run" != true ]; then
+ echo "Carousel and the carousel contract are not in PR scope; skipping carousel evidence."
+ exit 0
+ fi
+ pnpm exec playwright test \
+ internal/a11y-spec/src/patterns/carousel.chromium.spec.ts \
+ packages/core/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts \
+ --project chromium \
+ --reporter list,json \
+ --output carousel-contract-output
+
+ - name: Upload Carousel accessibility contract evidence
+ if: ${{ !cancelled() && steps.carousel-contract.outputs.should_run == 'true' }}
+ uses: actions/upload-artifact@v7
+ with:
+ name: carousel-contract-evidence-${{ needs.build-storybook.outputs.short_hash }}
+ path: carousel-contract/
+ retention-days: 30
+ if-no-files-found: warn
+
# The link contract's role, name, Tab, Enter, and pointer-release outcomes
# are accessibility-tree and real-browser facts that jsdom cannot observe.
# Run the contract's own fixture proof and the Link binding whenever Link
diff --git a/apps/storybook/stories/CarouselA11y.stories.tsx b/apps/storybook/stories/CarouselA11y.stories.tsx
new file mode 100644
index 0000000000..1bffbb9126
--- /dev/null
+++ b/apps/storybook/stories/CarouselA11y.stories.tsx
@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CarouselA11y.stories.tsx
+ * @input Uses the shared Carousel binding inventory and render map
+ * @output One checked-in reproduction story for every Carousel contract state
+ * @position Stable real-browser fixtures required by AST-009 FR30 and AST-021.
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {CAROUSEL_STATE_RENDERS} from '../../../packages/core/src/Carousel/__tests__/Carousel.a11y.renders';
+import {CAROUSEL_BINDING_STATES} from '../../../packages/core/src/Carousel/__tests__/Carousel.a11y.states';
+
+function storyFor(id: string): StoryObj {
+ const state = CAROUSEL_BINDING_STATES.find(candidate => candidate.id === id);
+ if (state == null) {
+ throw new Error(`no binding state "${id}" — see Carousel.a11y.states.ts`);
+ }
+ return {
+ name: `Carousel — ${state.id}`,
+ render: () => CAROUSEL_STATE_RENDERS[state.id](),
+ };
+}
+
+const meta: Meta = {
+ title: 'a11y/Carousel pattern',
+ tags: ['no-visual'],
+ parameters: {
+ docs: {
+ description: {
+ component:
+ 'Binding states for the non-rotating Carousel accessibility contract.',
+ },
+ },
+ },
+};
+
+export default meta;
+
+export const ContainerLabelled = storyFor('container-labelled');
+export const SlideVisible = storyFor('slide-visible');
+export const SlideOffscreen = storyFor('slide-offscreen');
+export const ScrollerKeyboard = storyFor('scroller-keyboard');
+export const NextControlFocus = storyFor('next-control-focus');
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
index 977047505c..1fcde17d05 100644
--- a/internal/a11y-spec/README.md
+++ b/internal/a11y-spec/README.md
@@ -51,6 +51,7 @@ src/
├── listbox.* listbox, group, and option semantics
├── spinbutton.* numeric role, value, bounds, state, and arrow stepping
├── disclosure.* standalone disclosure state/content semantics
+ ├── carousel.* non-rotating collection, slide, off-screen, and focus semantics
├── tree-view.* a tree's roles, names, expanded state, one Tab stop, and arrow/Home/End/Enter-or-Space/typeahead movement
├── slider.* a thumb's role, name, values, text, orientation, and arrow/Page/Home/End keys (RTL-mirrored arrows)
├── accordion.* a group's header role and name, panel state, single-expansion collapse, page Tab order
@@ -80,6 +81,7 @@ src/
| `landmark` | WCAG 2.2 semantics; [APG Landmark Regions](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/) as context | LayoutHeader, LayoutContent, LayoutFooter, and LayoutPanel caller-declared landmarks |
| `slider` | [APG Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/) role, values, name, orientation and keys | Slider thumbs: role, name, now/min/max, value text, orientation, arrows (RTL-mirrored), Page, Home/End, disabled keeps value |
| `treeview` | [APG Tree View](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) structure and keyboard model | TreeList rows: tree/treeitem/group, aria-expanded, level/position, one Tab stop, Up/Down, Right/Left (RTL-mirrored), Home/End, Enter or Space, typeahead |
+| `carousel` | [APG Carousel](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) and WCAG 2.2 semantics | Carousel container, slides, scroll area, and stable navigation-control focus |
| `link` | WCAG 2.2 semantics; [APG Link](https://www.w3.org/WAI/ARIA/apg/patterns/link/) role and Enter mechanics | Link, including LinkProvider and `as` router components |
The toggle-button contract owns the persistent-action extension of button
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
index bd4e8a246a..4c58483056 100644
--- a/internal/a11y-spec/src/index.ts
+++ b/internal/a11y-spec/src/index.ts
@@ -4,7 +4,8 @@
* @file index.ts
* @input Re-exports the browser-free surface of @astryxdesign/a11y-spec
* @output Contract vocabulary, completeness checklist, harness seam, runner,
- * report, the jsdom harness, and the authored pattern contracts. A pattern
+ * report, the jsdom harness, and the authored pattern contracts, including
+ * Carousel collection, slide, and focus semantics. A pattern
* exports a helper here only when a BINDING needs it — a helper the contract
* uses internally stays module-private.
* @position Package entry point. The Chromium harness is deliberately NOT here:
@@ -141,6 +142,7 @@ export {
export {SLIDER_PATTERN, type SliderStateFacts} from './patterns/slider';
export {TREE_VIEW_PATTERN, type TreeViewStateFacts} from './patterns/tree-view';
+export {CAROUSEL_PATTERN, type CarouselStateFacts} from './patterns/carousel';
export {
ACCORDION_PATTERN,
type AccordionStateFacts,
diff --git a/internal/a11y-spec/src/patterns/carousel.chromium.spec.ts b/internal/a11y-spec/src/patterns/carousel.chromium.spec.ts
new file mode 100644
index 0000000000..e67c2b86a9
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/carousel.chromium.spec.ts
@@ -0,0 +1,131 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file carousel.chromium.spec.ts
+ * @input Uses @playwright/test, the Carousel contract, fixtures, and Chromium harness
+ * @output Real-browser positive and mutation proof for every Carousel expectation
+ * @position Contract self-test; proves the reusable contract, not Astryx components.
+ */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {describeExpectation, requiredLayers} from '../contract';
+import {
+ CHROMIUM_OBSERVES,
+ createChromiumHarness,
+ holdMotionStill,
+} from '../harness/chromium';
+import {CAROUSEL_PATTERN} from './carousel';
+import {
+ CAROUSEL_MUTATIONS,
+ CAROUSEL_SUBJECT_SELECTOR,
+ CONFORMING_CAROUSEL_FIXTURES,
+ carouselFixture,
+ expectedCarouselMutationFailure,
+ type CarouselFixture,
+} from './carousel.fixtures';
+
+function relatedFor(page: Page, target: CarouselFixture) {
+ return Object.fromEntries(
+ target.facts.slideRelations.map(name => [
+ name,
+ page.locator(`[data-a11y-related="${name}"]`),
+ ]),
+ );
+}
+
+async function results(
+ page: Page,
+ cdp: CDPSession,
+ target: CarouselFixture,
+ only?: readonly string[],
+): Promise<readonly ExpectationResult[]> {
+ const run = await checkAccessibilitySpec({
+ spec: CAROUSEL_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ only,
+ mount: async () => {
+ await page.setContent(
+ `<!doctype html><html lang="en"><body>${target.html}</body></html>`,
+ );
+ await holdMotionStill(page);
+ return createChromiumHarness({
+ page,
+ subject: page.locator(CAROUSEL_SUBJECT_SELECTOR),
+ cdp,
+ related: relatedFor(page, target),
+ });
+ },
+ });
+ return run.results;
+}
+
+test.describe('Carousel contract — conforming fixtures', () => {
+ for (const id of CONFORMING_CAROUSEL_FIXTURES) {
+ test(`${id}: every applicable expectation passes`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const observed = await results(page, cdp, carouselFixture(id));
+ expect(
+ observed.filter(
+ result =>
+ result.status !== 'pass' && result.status !== 'not-applicable',
+ ),
+ ).toEqual([]);
+ });
+ }
+});
+
+test('every expectation passes against at least one conforming fixture', async ({
+ page,
+}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const withoutPass: string[] = [];
+ for (const expectation of CAROUSEL_PATTERN.expectations) {
+ if (
+ !requiredLayers(expectation).every(layer =>
+ CHROMIUM_OBSERVES.includes(layer),
+ )
+ ) {
+ continue;
+ }
+ let passed = false;
+ for (const id of CONFORMING_CAROUSEL_FIXTURES) {
+ const [result] = await results(page, cdp, carouselFixture(id), [
+ expectation.id,
+ ]);
+ if (result?.status === 'pass') {
+ passed = true;
+ break;
+ }
+ }
+ if (!passed) {
+ withoutPass.push(expectation.id);
+ }
+ }
+ expect(withoutPass).toEqual([]);
+});
+
+test.describe('Carousel contract — deliberately violating fixtures', () => {
+ for (const [expectationId, fixtures] of Object.entries(CAROUSEL_MUTATIONS)) {
+ const expectation = CAROUSEL_PATTERN.expectations.find(
+ candidate => candidate.id === expectationId,
+ );
+ for (const fixtureId of fixtures) {
+ test(`${expectationId} rejects ${fixtureId}`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const [result] = await results(page, cdp, carouselFixture(fixtureId), [
+ expectationId,
+ ]);
+ expect(result?.status).toBe('fail');
+ expect(result?.detail).toBe(
+ expectedCarouselMutationFailure(expectationId, fixtureId),
+ );
+ if (expectation != null) {
+ expect(result?.description).toBe(describeExpectation(expectation));
+ }
+ });
+ }
+ }
+});
diff --git a/internal/a11y-spec/src/patterns/carousel.fixtures.ts b/internal/a11y-spec/src/patterns/carousel.fixtures.ts
new file mode 100644
index 0000000000..85184bbe8d
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/carousel.fixtures.ts
@@ -0,0 +1,325 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file carousel.fixtures.ts
+ * @input Uses CarouselStateFacts
+ * @output Plain-HTML conforming and deliberately violating Carousel fixtures
+ * @position Mutation proof for the reusable contract; no Astryx component code.
+ */
+
+import type {CarouselStateFacts} from './carousel';
+
+const SUBJECT_ATTRIBUTE = 'data-a11y-subject';
+export const CAROUSEL_SUBJECT_SELECTOR = `[${SUBJECT_ATTRIBUTE}]`;
+
+export interface CarouselFixture {
+ readonly id: string;
+ readonly summary: string;
+ readonly facts: CarouselStateFacts;
+ readonly html: string;
+}
+
+function facts(overrides: Partial<CarouselStateFacts>): CarouselStateFacts {
+ return {
+ part: 'container',
+ expectedName: 'Featured work',
+ slideRelations: ['slide-1', 'slide-2', 'slide-3'],
+ offscreen: false,
+ scrollable: false,
+ focusable: false,
+ preservesControlFocus: false,
+ ...overrides,
+ };
+}
+
+interface FixtureOptions {
+ readonly subject?: 'container' | 'slide-1' | 'slide-3' | 'scroller' | 'next';
+ readonly containerRole?: string;
+ readonly containerLabel?: string;
+ readonly containerRoleDescription?: string;
+ readonly slideRole?: string;
+ readonly slideLabel?: string;
+ readonly slideRoleDescription?: string;
+ readonly detachFirstSlide?: boolean;
+ readonly hideThirdSlide?: boolean;
+ readonly scrollerTabIndex?: number;
+ readonly scrollerRole?: string | null;
+ readonly scrollerLabel?: string | null;
+ readonly trapTab?: boolean;
+ readonly moveFocusOnNext?: boolean;
+}
+
+function fixtureHtml(options: FixtureOptions = {}): string {
+ const {
+ subject = 'container',
+ containerRole = 'region',
+ containerLabel = 'Featured work',
+ containerRoleDescription = 'carousel',
+ slideRole = 'group',
+ slideLabel = 'Slide 1 of 3',
+ slideRoleDescription = 'slide',
+ detachFirstSlide = false,
+ hideThirdSlide = false,
+ scrollerTabIndex = 0,
+ scrollerRole = 'group',
+ scrollerLabel = 'Slides',
+ trapTab = false,
+ moveFocusOnNext = false,
+ } = options;
+ const mark = (part: FixtureOptions['subject']) =>
+ subject === part ? ` ${SUBJECT_ATTRIBUTE}` : '';
+ const first = `<div${mark('slide-1')} data-a11y-related="slide-1" role="${slideRole}" aria-roledescription="${slideRoleDescription}" aria-label="${slideLabel}" style="flex:0 0 100px">One</div>`;
+ return `
+ <button type="button">Before</button>
+ <div${mark('container')} role="${containerRole}"${containerLabel === '' ? '' : ` aria-label="${containerLabel}"`}${containerRoleDescription === '' ? '' : ` aria-roledescription="${containerRoleDescription}"`}>
+ <div${mark('scroller')} data-a11y-related="scroller"${scrollerRole == null ? '' : ` role="${scrollerRole}"`}${scrollerLabel == null ? '' : ` aria-label="${scrollerLabel}"`} tabindex="${scrollerTabIndex}" style="display:flex;width:120px;overflow-x:auto"${trapTab ? ` onkeydown="if (event.key === 'Tab') event.preventDefault()"` : ''}>
+ ${detachFirstSlide ? '' : first}
+ <div data-a11y-related="slide-2" role="group" aria-roledescription="slide" aria-label="Slide 2 of 3" style="flex:0 0 100px">Two</div>
+ <div${mark('slide-3')} data-a11y-related="slide-3" role="group" aria-roledescription="slide" aria-label="Slide 3 of 3" style="flex:0 0 100px"${hideThirdSlide ? ' aria-hidden="true"' : ''}>Three</div>
+ </div>
+ <button${mark('next')} data-a11y-related="next" type="button"${moveFocusOnNext ? ` onclick="document.getElementById('after').focus()"` : ''}>Next slide</button>
+ </div>
+ ${detachFirstSlide ? first : ''}
+ <button id="after" type="button">After</button>
+ `;
+}
+
+export const CAROUSEL_FIXTURES: readonly CarouselFixture[] = [
+ {
+ id: 'conforming-container',
+ summary: 'a labelled carousel region containing three slides',
+ facts: facts({}),
+ html: fixtureHtml(),
+ },
+ {
+ id: 'conforming-slide',
+ summary: 'a visible positional slide',
+ facts: facts({
+ part: 'slide',
+ expectedName: 'Slide 1 of 3',
+ slideRelations: [],
+ }),
+ html: fixtureHtml({subject: 'slide-1'}),
+ },
+ {
+ id: 'conforming-offscreen-slide',
+ summary: 'an off-screen slide that remains in the accessibility tree',
+ facts: facts({
+ part: 'slide',
+ expectedName: 'Slide 3 of 3',
+ slideRelations: [],
+ offscreen: true,
+ }),
+ html: fixtureHtml({subject: 'slide-3'}),
+ },
+ {
+ id: 'conforming-scroller',
+ summary: 'a scroll container reachable by and escapable with Tab',
+ facts: facts({
+ part: 'scroller',
+ scrollable: true,
+ expectedName: '',
+ slideRelations: [],
+ focusable: true,
+ }),
+ html: fixtureHtml({subject: 'scroller'}),
+ },
+ {
+ id: 'conforming-next-control',
+ summary: 'a next control that keeps focus after activation',
+ facts: facts({
+ part: 'control',
+ expectedName: 'Next slide',
+ slideRelations: [],
+ focusable: true,
+ preservesControlFocus: true,
+ }),
+ html: fixtureHtml({subject: 'next'}),
+ },
+ {
+ id: 'violating-container-role',
+ summary: 'a carousel exposed as main',
+ facts: facts({}),
+ html: fixtureHtml({containerRole: 'main'}),
+ },
+ {
+ id: 'violating-container-name',
+ summary: 'an unnamed carousel region',
+ facts: facts({}),
+ html: fixtureHtml({containerLabel: ''}),
+ },
+ {
+ id: 'violating-container-roledescription',
+ summary: 'a carousel without its role description',
+ facts: facts({}),
+ html: fixtureHtml({containerRoleDescription: ''}),
+ },
+ {
+ id: 'violating-slide-role',
+ summary: 'a slide exposed as an article',
+ facts: facts({
+ part: 'slide',
+ expectedName: 'Slide 1 of 3',
+ slideRelations: [],
+ }),
+ html: fixtureHtml({subject: 'slide-1', slideRole: 'article'}),
+ },
+ {
+ id: 'violating-slide-name',
+ summary: 'an unnamed slide',
+ facts: facts({
+ part: 'slide',
+ expectedName: 'Slide 1 of 3',
+ slideRelations: [],
+ }),
+ html: fixtureHtml({subject: 'slide-1', slideLabel: ''}),
+ },
+ {
+ id: 'violating-slide-roledescription',
+ summary: 'a slide without its role description',
+ facts: facts({
+ part: 'slide',
+ expectedName: 'Slide 1 of 3',
+ slideRelations: [],
+ }),
+ html: fixtureHtml({subject: 'slide-1', slideRoleDescription: ''}),
+ },
+ {
+ id: 'violating-detached-slide',
+ summary: 'a declared slide outside the carousel container',
+ facts: facts({}),
+ html: fixtureHtml({detachFirstSlide: true}),
+ },
+ {
+ id: 'violating-offscreen-hidden',
+ summary: 'an off-screen slide removed from the accessibility tree',
+ facts: facts({
+ part: 'slide',
+ expectedName: 'Slide 3 of 3',
+ slideRelations: [],
+ offscreen: true,
+ }),
+ html: fixtureHtml({subject: 'slide-3', hideThirdSlide: true}),
+ },
+ {
+ id: 'violating-scroller-unnamed',
+ summary: 'a focusable scroll container with no role and no accessible name',
+ facts: facts({
+ part: 'scroller',
+ scrollable: true,
+ expectedName: '',
+ slideRelations: [],
+ focusable: true,
+ }),
+ html: fixtureHtml({
+ subject: 'scroller',
+ scrollerRole: null,
+ scrollerLabel: null,
+ }),
+ },
+ {
+ id: 'violating-scroller-unreachable',
+ summary: 'a scroll container outside the tab sequence',
+ facts: facts({
+ part: 'scroller',
+ scrollable: true,
+ expectedName: '',
+ slideRelations: [],
+ focusable: true,
+ }),
+ html: fixtureHtml({subject: 'scroller', scrollerTabIndex: -1}),
+ },
+ {
+ id: 'violating-scroller-trap',
+ summary: 'a scroll container that traps Tab',
+ facts: facts({
+ part: 'scroller',
+ scrollable: true,
+ expectedName: '',
+ slideRelations: [],
+ focusable: true,
+ }),
+ html: fixtureHtml({subject: 'scroller', trapTab: true}),
+ },
+ {
+ id: 'violating-control-focus',
+ summary: 'a next control that moves focus elsewhere',
+ facts: facts({
+ part: 'control',
+ expectedName: 'Next slide',
+ slideRelations: [],
+ focusable: true,
+ preservesControlFocus: true,
+ }),
+ html: fixtureHtml({subject: 'next', moveFocusOnNext: true}),
+ },
+];
+
+export const CONFORMING_CAROUSEL_FIXTURES = CAROUSEL_FIXTURES.filter(fixture =>
+ fixture.id.startsWith('conforming-'),
+).map(fixture => fixture.id);
+
+export const CAROUSEL_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
+ 'carousel.container.role-exposed': ['violating-container-role'],
+ 'carousel.container.name-exposed': ['violating-container-name'],
+ 'carousel.container.roledescription': ['violating-container-roledescription'],
+ 'carousel.slide.role-exposed': ['violating-slide-role'],
+ 'carousel.slide.name-exposed': ['violating-slide-name'],
+ 'carousel.slide.roledescription': ['violating-slide-roledescription'],
+ 'carousel.collection.contains-slides': ['violating-detached-slide'],
+ 'carousel.slide.offscreen-exposed': ['violating-offscreen-hidden'],
+ 'carousel.scroller.role-and-name': ['violating-scroller-unnamed'],
+ 'carousel.scroller.reachable-and-escapable': [
+ 'violating-scroller-unreachable',
+ 'violating-scroller-trap',
+ ],
+ 'carousel.control.focus-preserved': ['violating-control-focus'],
+};
+
+const EXPECTED_FAILURES: Readonly<Record<string, string>> = {
+ 'carousel.container.role-exposed:violating-container-role':
+ 'the browser exposes this container as "main", not as a region or group',
+ 'carousel.container.name-exposed:violating-container-name':
+ 'the browser computes no accessible name for this carousel',
+ 'carousel.container.roledescription:violating-container-roledescription':
+ 'the carousel has no aria-roledescription="carousel"',
+ 'carousel.slide.role-exposed:violating-slide-role':
+ 'the browser exposes this slide as "article", not as a group',
+ 'carousel.slide.name-exposed:violating-slide-name':
+ 'the browser computes no accessible name for this slide',
+ 'carousel.slide.roledescription:violating-slide-roledescription':
+ 'the slide has no aria-roledescription="slide"',
+ 'carousel.collection.contains-slides:violating-detached-slide':
+ 'the binding’s "slide-1" is not contained by the carousel',
+ 'carousel.slide.offscreen-exposed:violating-offscreen-hidden':
+ 'the off-screen slide is absent from the accessibility tree',
+ 'carousel.scroller.role-and-name:violating-scroller-unnamed':
+ 'the browser exposes the focusable scroll container with no role',
+ 'carousel.scroller.reachable-and-escapable:violating-scroller-unreachable':
+ '10 presses of Tab never reached the scroll container',
+ 'carousel.scroller.reachable-and-escapable:violating-scroller-trap':
+ 'Tab did not leave the scroll container',
+ 'carousel.control.focus-preserved:violating-control-focus':
+ 'activating the carousel control moved focus away from it',
+};
+
+export function expectedCarouselMutationFailure(
+ expectation: string,
+ fixture: string,
+): string {
+ const failure = EXPECTED_FAILURES[`${expectation}:${fixture}`];
+ if (failure == null) {
+ throw new Error(
+ `no expected Carousel mutation failure for ${expectation}:${fixture}`,
+ );
+ }
+ return failure;
+}
+
+export function carouselFixture(id: string): CarouselFixture {
+ const fixture = CAROUSEL_FIXTURES.find(candidate => candidate.id === id);
+ if (fixture == null) {
+ throw new Error(`unknown Carousel fixture "${id}"`);
+ }
+ return fixture;
+}
diff --git a/internal/a11y-spec/src/patterns/carousel.jsdom.test.ts b/internal/a11y-spec/src/patterns/carousel.jsdom.test.ts
new file mode 100644
index 0000000000..29976d0e62
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/carousel.jsdom.test.ts
@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file carousel.jsdom.test.ts
+ * @input Uses the Carousel contract, plain fixtures, jsdom harness, and checker
+ * @output DOM-layer positive/negative proof and honest higher-layer results
+ * @position Contract self-test; proves the contract rather than Astryx components.
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {
+ citeSource,
+ describeExpectation,
+ requiredLayers,
+ unansweredDimensions,
+} from '../contract';
+import {createJsdomHarness, JSDOM_OBSERVES} from '../harness/jsdom';
+import {CAROUSEL_PATTERN} from './carousel';
+import {
+ CAROUSEL_MUTATIONS,
+ CAROUSEL_SUBJECT_SELECTOR,
+ CONFORMING_CAROUSEL_FIXTURES,
+ carouselFixture,
+ expectedCarouselMutationFailure,
+ type CarouselFixture,
+} from './carousel.fixtures';
+
+const observableHere = CAROUSEL_PATTERN.expectations.filter(expectation =>
+ requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
+);
+
+afterEach(() => document.body.replaceChildren());
+
+async function resultsFor(target: CarouselFixture) {
+ const container = document.createElement('div');
+ document.body.append(container);
+ const run = await checkAccessibilitySpec({
+ spec: CAROUSEL_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ mount: async () => {
+ container.innerHTML = target.html;
+ const subject = container.querySelector(CAROUSEL_SUBJECT_SELECTOR);
+ if (subject == null) {
+ throw new Error(`fixture "${target.id}" marks no subject`);
+ }
+ const related = Object.fromEntries(
+ target.facts.slideRelations.map(name => {
+ const element = container.querySelector(
+ `[data-a11y-related="${name}"]`,
+ );
+ if (element == null) {
+ throw new Error(`fixture "${target.id}" has no relation "${name}"`);
+ }
+ return [name, element];
+ }),
+ );
+ return createJsdomHarness({subject, related});
+ },
+ unmount: () => {
+ container.innerHTML = '';
+ },
+ });
+ return run.results;
+}
+
+function resultFor(
+ results: readonly ExpectationResult[],
+ id: string,
+): ExpectationResult {
+ const result = results.find(candidate => candidate.expectation === id);
+ if (result == null) {
+ throw new Error(`no result for ${id}`);
+ }
+ return result;
+}
+
+describe('Carousel contract — completeness', () => {
+ it('answers every checklist dimension', () => {
+ expect(unansweredDimensions(CAROUSEL_PATTERN)).toEqual([]);
+ });
+
+ it('gives every expectation a deliberately violating fixture', () => {
+ expect(
+ CAROUSEL_PATTERN.expectations
+ .filter(
+ expectation =>
+ (CAROUSEL_MUTATIONS[expectation.id] ?? []).length === 0,
+ )
+ .map(expectation => expectation.id),
+ ).toEqual([]);
+ });
+
+ it('has an expectation for every mutation entry', () => {
+ const ids = new Set(
+ CAROUSEL_PATTERN.expectations.map(expectation => expectation.id),
+ );
+ expect(Object.keys(CAROUSEL_MUTATIONS).filter(id => !ids.has(id))).toEqual(
+ [],
+ );
+ });
+});
+
+describe('Carousel contract — jsdom evidence boundary', () => {
+ it('runs DOM expectations and reports browser-owned layers as unrun', async () => {
+ const results = await resultsFor(carouselFixture('conforming-container'));
+ expect(results.some(result => result.status === 'pass')).toBe(true);
+ expect(results.some(result => result.status === 'unrun')).toBe(true);
+ expect(results.filter(result => result.status === 'fail')).toEqual([]);
+ });
+});
+
+describe.each(observableHere.map(expectation => [expectation.id] as const))(
+ '%s',
+ id => {
+ const expectation = CAROUSEL_PATTERN.expectations.find(
+ candidate => candidate.id === id,
+ )!;
+
+ it.each(CONFORMING_CAROUSEL_FIXTURES.map(name => [name] as const))(
+ 'passes against %s (or does not apply)',
+ async name => {
+ const result = resultFor(await resultsFor(carouselFixture(name)), id);
+ expect(
+ ['pass', 'not-applicable'],
+ `${id} against ${name}: ${result.detail ?? ''}`,
+ ).toContain(result.status);
+ },
+ );
+
+ it.each((CAROUSEL_MUTATIONS[id] ?? []).map(name => [name] as const))(
+ 'fails against %s, which removes its outcome',
+ async name => {
+ const result = resultFor(await resultsFor(carouselFixture(name)), id);
+ expect(result.status, `${id} against ${name}`).toBe('fail');
+ expect(result.detail).toBe(expectedCarouselMutationFailure(id, name));
+ expect(result.description).toContain(id);
+ expect(result.description).toContain(
+ citeSource(expectation.sources[0]),
+ );
+ expect(result.description).toBe(describeExpectation(expectation));
+ },
+ );
+ },
+);
diff --git a/internal/a11y-spec/src/patterns/carousel.ts b/internal/a11y-spec/src/patterns/carousel.ts
new file mode 100644
index 0000000000..2a26451ccf
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/carousel.ts
@@ -0,0 +1,580 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file carousel.ts
+ * @input Uses the shared accessibility contract vocabulary
+ * @output CAROUSEL_PATTERN and CarouselStateFacts
+ * @position Reusable semantic and focus contract for non-rotating carousels.
+ *
+ * This first bounded slice covers the labelled collection, positional slides,
+ * off-screen slide exposure, a keyboard-reachable scroller, and the APG focus
+ * result for a navigation control that remains available. Button mechanics,
+ * scroll geometry, looping, snapping, paint, and motion stay with their named
+ * owners rather than being inferred from the Carousel pattern.
+ */
+
+import {
+ definePattern,
+ type ApgRequirement,
+ type AstryxRecord,
+ type PatternContract,
+ type WcagCriterion,
+} from '../contract';
+
+const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/carousel/';
+const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding';
+
+function wcag(
+ id: string,
+ name: string,
+ level: 'A' | 'AA',
+ slug: string,
+): WcagCriterion {
+ return {
+ standard: 'wcag',
+ id,
+ name,
+ level,
+ url: `${UNDERSTANDING}/${slug}.html`,
+ };
+}
+
+const WCAG_1_3_1 = wcag(
+ '1.3.1',
+ 'Info and Relationships',
+ 'A',
+ 'info-and-relationships',
+);
+const WCAG_2_1_1 = wcag('2.1.1', 'Keyboard', 'A', 'keyboard');
+const WCAG_2_1_2 = wcag('2.1.2', 'No Keyboard Trap', 'A', 'no-keyboard-trap');
+const WCAG_2_4_3 = wcag('2.4.3', 'Focus Order', 'A', 'focus-order');
+const WCAG_2_4_6 = wcag(
+ '2.4.6',
+ 'Headings and Labels',
+ 'AA',
+ 'headings-and-labels',
+);
+const WCAG_4_1_2 = wcag('4.1.2', 'Name, Role, Value', 'A', 'name-role-value');
+
+function apg(requirement: string): ApgRequirement {
+ return {
+ standard: 'apg',
+ pattern: 'carousel',
+ requirement,
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+ };
+}
+
+const APG_CONTAINER_ROLE = apg(
+ 'The carousel container has either role region or role group.',
+);
+const APG_CONTAINER_DESCRIPTION = apg(
+ 'The carousel container has aria-roledescription set to carousel.',
+);
+const APG_CONTAINER_LABEL = apg(
+ 'The carousel container has an accessible label provided by aria-labelledby or aria-label.',
+);
+// APG, basic carousel elements: "Each slide container has role group with
+// the property aria-roledescription set to slide." Only the carousel
+// container may choose between region and group.
+const APG_SLIDE_ROLE = apg('Each slide container has role group.');
+const APG_SLIDE_DESCRIPTION = apg(
+ 'Each slide has aria-roledescription set to slide.',
+);
+const APG_SLIDE_LABEL = apg(
+ 'Each slide has an accessible name that identifies it in the set of slides.',
+);
+const APG_CONTROL_FOCUS: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'carousel',
+ requirement:
+ 'Activating the previous or next slide control does not move browser focus from the button.',
+ url: `${APG_URL}#keyboardinteraction`,
+};
+
+export interface CarouselStateFacts {
+ readonly part: 'container' | 'slide' | 'scroller' | 'control';
+ readonly expectedName: string;
+ readonly slideRelations: readonly string[];
+ readonly offscreen: boolean;
+ readonly scrollable: boolean;
+ readonly focusable: boolean;
+ readonly preservesControlFocus: boolean;
+}
+
+const APG_NOT_FORMALLY_ADOPTED =
+ 'The current Carousel implementation and consumer docs use this APG mechanic, but no current component record adopts it as a reusable required gate.';
+const AST_025_FR12: AstryxRecord = {
+ standard: 'astryx',
+ id: 'spec:AST-025',
+ clause: 'FR12',
+ url: 'https://github.com/facebook/astryx/blob/17044ab1e814586691db43ae6fd71b8b9bb9ceb1/docs/specs/AST-025/spec.md#L137-L141',
+ requirement:
+ 'A delivery surface that assigns keyboard scrolling to the viewport MUST add it to the tab order only while at least one applicable axis is effective, and MUST provide an appropriate role and accessible name.',
+};
+const TAB_BUDGET = 10;
+
+export const CAROUSEL_PATTERN: PatternContract<CarouselStateFacts> =
+ definePattern<CarouselStateFacts>({
+ pattern: 'carousel',
+ url: APG_URL,
+ scope:
+ 'A labelled non-rotating carousel collection, its positional slides, keyboard-reachable scroll area, and navigation-control focus result.',
+ expectations: [
+ {
+ id: 'carousel.container.role-exposed',
+ outcome:
+ 'The browser exposes the collection as a region or group so its slides have a programmatic container.',
+ sources: [WCAG_1_3_1, WCAG_4_1_2, APG_CONTAINER_ROLE],
+ covers: ['1.3.1-info-and-relationships', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates the carousel container',
+ test: facts => facts.part === 'container',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {role} = await subject.computed();
+ if (role !== 'region' && role !== 'group') {
+ throw new Error(
+ `the browser exposes this container as ${role == null ? 'no role' : `"${role}"`}, not as a region or group`,
+ );
+ }
+ },
+ },
+ {
+ id: 'carousel.container.name-exposed',
+ outcome:
+ 'The carousel has an accessible name so the user knows which collection they reached.',
+ sources: [WCAG_2_4_6, WCAG_4_1_2, APG_CONTAINER_LABEL],
+ covers: ['2.4.6-headings-and-labels', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates the carousel container',
+ test: facts => facts.part === 'container',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {name} = await subject.computed();
+ if (name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for this carousel',
+ );
+ }
+ if (facts.expectedName !== '' && name !== facts.expectedName) {
+ throw new Error(
+ `the browser names this carousel "${name}" instead of "${facts.expectedName}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'carousel.container.roledescription',
+ outcome:
+ 'The container identifies itself as a carousel rather than an unnamed generic collection.',
+ sources: [APG_CONTAINER_DESCRIPTION],
+ wcagOutcome:
+ 'Supports WCAG 2.2 4.1.2 by exposing the widget type Astryx presents visually.',
+ covers: ['apg-interaction'],
+ appliesWhen: {
+ condition: 'the binding designates the carousel container',
+ test: facts => facts.part === 'container',
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'advisory',
+ advisoryBecause: APG_NOT_FORMALLY_ADOPTED,
+ run: async ({subject}) => {
+ if (
+ (await subject.attribute('aria-roledescription')) !== 'carousel'
+ ) {
+ throw new Error(
+ 'the carousel has no aria-roledescription="carousel"',
+ );
+ }
+ },
+ },
+ {
+ id: 'carousel.slide.role-exposed',
+ outcome:
+ 'The browser exposes each slide as a group so its content has a programmatic boundary.',
+ sources: [WCAG_1_3_1, WCAG_4_1_2, APG_SLIDE_ROLE],
+ covers: ['1.3.1-info-and-relationships', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates a slide',
+ test: facts => facts.part === 'slide',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {role} = await subject.computed();
+ if (role !== 'group') {
+ throw new Error(
+ `the browser exposes this slide as ${role == null ? 'no role' : `"${role}"`}, not as a group`,
+ );
+ }
+ },
+ },
+ {
+ id: 'carousel.slide.name-exposed',
+ outcome:
+ 'Each slide has an accessible name that identifies its position in the collection.',
+ sources: [WCAG_2_4_6, WCAG_4_1_2, APG_SLIDE_LABEL],
+ covers: ['2.4.6-headings-and-labels', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates a slide',
+ test: facts => facts.part === 'slide',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {name} = await subject.computed();
+ if (name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for this slide',
+ );
+ }
+ if (name !== facts.expectedName) {
+ throw new Error(
+ `the browser names this slide "${name}" instead of "${facts.expectedName}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'carousel.slide.roledescription',
+ outcome: 'Each item identifies itself as a slide within the carousel.',
+ sources: [APG_SLIDE_DESCRIPTION],
+ wcagOutcome:
+ 'Supports WCAG 2.2 4.1.2 by exposing the item type Astryx presents visually.',
+ covers: ['apg-interaction'],
+ appliesWhen: {
+ condition: 'the binding designates a slide',
+ test: facts => facts.part === 'slide',
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'advisory',
+ advisoryBecause: APG_NOT_FORMALLY_ADOPTED,
+ run: async ({subject}) => {
+ if ((await subject.attribute('aria-roledescription')) !== 'slide') {
+ throw new Error('the slide has no aria-roledescription="slide"');
+ }
+ },
+ },
+ {
+ id: 'carousel.collection.contains-slides',
+ outcome:
+ 'Every declared slide belongs to the carousel in the accessibility tree, including slides outside the viewport.',
+ sources: [WCAG_1_3_1, APG_SLIDE_ROLE],
+ covers: ['1.3.1-info-and-relationships'],
+ appliesWhen: {
+ condition: 'the container binding declares its slides',
+ test: facts =>
+ facts.part === 'container' && facts.slideRelations.length > 0,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ for (const relation of facts.slideRelations) {
+ if (
+ !(await harness.containsSemantically(
+ subject,
+ await harness.related(relation),
+ ))
+ ) {
+ throw new Error(
+ `the binding’s "${relation}" is not contained by the carousel`,
+ );
+ }
+ }
+ },
+ },
+ {
+ id: 'carousel.slide.offscreen-exposed',
+ outcome:
+ 'A slide outside the viewport remains in the accessibility tree so assistive-technology navigation does not lose it.',
+ sources: [WCAG_1_3_1],
+ covers: ['1.3.1-info-and-relationships'],
+ appliesWhen: {
+ condition: 'the binding designates an off-screen slide',
+ test: facts => facts.part === 'slide' && facts.offscreen,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {role, name} = await subject.computed();
+ if (role == null || name.trim() === '') {
+ throw new Error(
+ 'the off-screen slide is absent from the accessibility tree',
+ );
+ }
+ },
+ },
+ {
+ id: 'carousel.scroller.reachable-and-escapable',
+ outcome:
+ 'Tab reaches an overflowing scroll container and Tab again leaves it so keyboard users can operate the overflow without becoming trapped.',
+ sources: [WCAG_2_1_1, WCAG_2_1_2],
+ covers: ['2.1.1-keyboard', '2.1.2-no-keyboard-trap'],
+ appliesWhen: {
+ condition:
+ 'the binding designates a focusable, effectively scrollable container',
+ test: facts =>
+ facts.part === 'scroller' && facts.scrollable && facts.focusable,
+ },
+ evidenceLayer: 'real-browser',
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ await harness.resetFocus();
+ let reached = false;
+ for (let step = 0; step < TAB_BUDGET && !reached; step += 1) {
+ await harness.press('Tab');
+ reached = await subject.isFocused();
+ }
+ if (!reached) {
+ throw new Error(
+ `${TAB_BUDGET} presses of Tab never reached the scroll container`,
+ );
+ }
+ await harness.press('Tab');
+ if (await subject.isFocused()) {
+ throw new Error('Tab did not leave the scroll container');
+ }
+ },
+ },
+ {
+ id: 'carousel.scroller.role-and-name',
+ outcome:
+ 'A scroll container that takes keyboard focus is exposed with a role and an accessible name, so a user landing on it knows what they can scroll.',
+ sources: [WCAG_4_1_2, AST_025_FR12],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates a focusable scroll container',
+ test: facts => facts.part === 'scroller' && facts.focusable,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {role, name} = await subject.computed();
+ if (role == null || role === 'generic' || role === 'none') {
+ throw new Error(
+ 'the browser exposes the focusable scroll container with no role',
+ );
+ }
+ if (name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for the focusable scroll container',
+ );
+ }
+ },
+ },
+ {
+ id: 'carousel.control.focus-preserved',
+ outcome:
+ 'A navigation control that remains available keeps focus after activation.',
+ sources: [APG_CONTROL_FOCUS, WCAG_2_4_3],
+ wcagOutcome:
+ 'Supports WCAG 2.2 2.4.3 by keeping focus in a predictable place after navigation.',
+ covers: ['2.4.3-focus-order', 'apg-interaction'],
+ appliesWhen: {
+ condition:
+ 'the binding designates an available navigation control whose action should preserve focus',
+ test: facts =>
+ facts.part === 'control' &&
+ facts.focusable &&
+ facts.preservesControlFocus,
+ },
+ evidenceLayer: 'real-browser',
+ enforcement: 'advisory',
+ advisoryBecause: APG_NOT_FORMALLY_ADOPTED,
+ run: async ({harness, subject}) => {
+ await harness.click(subject);
+ if (!(await subject.isFocused())) {
+ throw new Error(
+ 'activating the carousel control moved focus away from it',
+ );
+ }
+ },
+ },
+ ],
+ exemptions: {
+ '1.1.1-non-text-content': {
+ owner: 'Caller slide content and nested components',
+ verifiedBy: 'Caller content review and the repository axe audit',
+ reason:
+ 'The Carousel wrapper cannot determine whether an image inside an arbitrary child is informative or decorative.',
+ },
+ '1.3.1-info-and-relationships': {
+ owner: 'Caller slide content',
+ verifiedBy: 'Component composition tests and caller content review',
+ reason:
+ 'This contract proves the collection and slide boundaries; relationships inside each arbitrary slide remain caller-owned.',
+ coversRemainderOnly: true,
+ },
+ '1.3.2-meaningful-sequence': {
+ owner: 'Carousel child order and caller content',
+ verifiedBy:
+ 'Existing child-order tests and page-level reading-order review',
+ reason:
+ 'The contract preserves declared collection membership but does not decide whether a caller supplied its slides in a meaningful order.',
+ },
+ '1.3.5-identify-input-purpose': {
+ owner: 'Forms embedded by callers',
+ verifiedBy: 'Form-purpose and autocomplete review',
+ reason: 'Carousel itself collects no personal information.',
+ },
+ '1.4.1-use-of-color': {
+ owner: 'Carousel, theme, and caller slide content',
+ verifiedBy: 'Rendered-state review and the visual gate',
+ reason:
+ 'Semantic grouping cannot prove that painted cues avoid color-only meaning.',
+ },
+ '1.4.3-contrast-minimum': {
+ owner: 'Theme and caller slide content',
+ verifiedBy: 'Repository axe audit and rendered theme review',
+ reason: 'Contrast is a rendered-pixel outcome.',
+ },
+ '1.4.11-non-text-contrast': {
+ owner: 'Carousel controls, focus styles, and theme',
+ verifiedBy: 'Repository axe audit and rendered focus/control review',
+ reason:
+ 'Control and focus-indicator contrast is not observable from this semantic contract.',
+ },
+ '2.1.1-keyboard': {
+ owner: 'Carousel scrolling and Button pattern',
+ verifiedBy:
+ 'Component scroll tests, Button contract, and real-browser Carousel binding',
+ reason:
+ 'This contract proves the scroll area is reachable; key-to-scroll behavior and button activation retain their existing owners.',
+ coversRemainderOnly: true,
+ },
+ '2.1.2-no-keyboard-trap': {
+ owner: 'Caller interactive slide content and page composition',
+ verifiedBy: 'Page-level sequential-focus review',
+ reason:
+ 'The contract proves exit from the scroller itself, not arbitrary interactive descendants supplied by callers.',
+ coversRemainderOnly: true,
+ },
+ '2.4.2-page-titled': {
+ owner: 'Page shell',
+ verifiedBy: 'Page-level accessibility review',
+ reason: 'A Carousel does not own the document title.',
+ },
+ '2.4.3-focus-order': {
+ owner: 'Page composition and Carousel edge hand-off',
+ verifiedBy:
+ 'Existing Carousel edge-focus tests and page-level focus-order review',
+ reason:
+ 'The pattern checks one stable control result; ordering before, within, and after caller content remains separately owned.',
+ coversRemainderOnly: true,
+ },
+ '2.4.4-link-purpose': {
+ owner: 'Links rendered by callers',
+ verifiedBy: 'Link contract and caller content review',
+ reason: 'Carousel itself does not create navigation links.',
+ },
+ '2.4.6-headings-and-labels': {
+ owner: 'Caller-authored wording',
+ verifiedBy: 'Content review of the collection and slide labels',
+ reason:
+ 'The contract proves names exist and match declared facts, not that the words describe the caller’s content well.',
+ coversRemainderOnly: true,
+ },
+ '2.4.7-focus-visible': {
+ owner: 'Carousel, Button, theme, and interaction-modality system',
+ verifiedBy: 'Stable visual regression and keyboard-focus review',
+ reason: 'Focus indication is a painted result.',
+ },
+ '2.4.11-focus-not-obscured': {
+ owner: 'Carousel geometry and page composition',
+ verifiedBy: 'Constrained-viewport real-browser review',
+ reason:
+ 'Occlusion depends on clipping, viewport geometry, and surrounding content.',
+ },
+ '2.5.2-pointer-cancellation': {
+ owner: 'Button pattern and native scrolling',
+ verifiedBy: 'Button contract and browser gesture tests',
+ reason:
+ 'This semantic slice does not re-own pointer activation or scrolling gestures.',
+ },
+ '2.5.3-label-in-name': {
+ owner: 'Carousel controls and caller slide content',
+ verifiedBy: 'Button contract plus visible-label review',
+ reason:
+ 'The Carousel and slide names are programmatic; visible labels inside arbitrary slides belong to their content.',
+ },
+ '2.5.8-target-size': {
+ owner: 'Button, Carousel layout, and page composition',
+ verifiedBy: 'Browser geometry and WCAG exception review',
+ reason: 'Target size and spacing require rendered geometry.',
+ },
+ '3.1.1-language-of-page': {
+ owner: 'Page shell and localization provider',
+ verifiedBy: 'Document-language integration checks',
+ reason: 'Carousel does not own the page language.',
+ },
+ '3.2.2-on-input': {
+ owner: 'Caller-owned interactive slide content',
+ verifiedBy: 'Component and page integration tests',
+ reason:
+ 'Carousel navigation changes viewport position, not the setting of a form control.',
+ },
+ '3.2.4-consistent-identification': {
+ owner: 'Design system and caller content',
+ verifiedBy: 'Cross-surface content review and shared Button contract',
+ reason:
+ 'Consistency is a property of repeated functions across a product.',
+ },
+ '3.3.1-error-identification': {
+ owner: 'Forms and status-message owners',
+ verifiedBy: 'Field and status-message contracts',
+ reason: 'Carousel defines no validation state.',
+ },
+ '3.3.2-labels-or-instructions': {
+ owner: 'Caller content',
+ verifiedBy: 'Task-level content review',
+ reason:
+ 'The component cannot know which instructions a composed task requires.',
+ },
+ '4.1.2-name-role-value': {
+ owner: 'Button pattern and caller slide descendants',
+ verifiedBy: 'Shared component contracts and the repository axe audit',
+ reason:
+ "This contract owns the collection and slide identity and the focusable scroll container's role and name; semantics of controls and arbitrary descendants remain with their own patterns.",
+ coversRemainderOnly: true,
+ },
+ '4.1.3-status-messages': {
+ owner: 'Status-message pattern and caller composition',
+ verifiedBy:
+ 'Status-message bindings and AST-009 for announcement claims',
+ reason: 'Carousel performs no live-region announcement.',
+ },
+ 'apg-interaction': {
+ owner: 'Button pattern and Carousel component tests',
+ verifiedBy:
+ 'Button contract, Carousel scrolling tests, and real-browser visual evidence',
+ reason:
+ 'This slice covers collection/slide semantics and stable control focus; rotation, picker controls, scrolling distance, looping, and snapping keep their existing owners.',
+ coversRemainderOnly: true,
+ },
+ 'forced-colors': {
+ owner: 'Carousel controls and theme',
+ verifiedBy: 'Real-browser forced-colors review',
+ reason:
+ 'Forced-color paint cannot be established by DOM or accessibility-tree semantics.',
+ },
+ 'reduced-motion': {
+ owner: 'Carousel implementation and visual/browser evidence',
+ verifiedBy:
+ 'The prefers-reduced-motion branch and real-browser motion review',
+ reason:
+ 'Motion is a rendered result over time and is not established by collection semantics.',
+ },
+ 'at-facing-strings': {
+ owner: 'Carousel localization',
+ verifiedBy:
+ 'Catalog checks and localized component tests; AST-009 for speech claims',
+ reason:
+ 'Translation completeness is a source and localization concern rather than an accessibility-tree identity check.',
+ },
+ },
+ });
diff --git a/packages/core/src/Carousel/Carousel.test.tsx b/packages/core/src/Carousel/Carousel.test.tsx
index b294301d88..a0be9fbceb 100644
--- a/packages/core/src/Carousel/Carousel.test.tsx
+++ b/packages/core/src/Carousel/Carousel.test.tsx
@@ -19,38 +19,75 @@ class MockResizeObserver {
vi.stubGlobal('ResizeObserver', MockResizeObserver);
describe('Carousel', () => {
- it('renders children', () => {
+ // Retained local tests (AST-021 FR6): the carousel contract keeps the
+ // aria-roledescription outcomes ADVISORY until a current Carousel record
+ // adopts the APG parts, so these component assertions remain the gate for
+ // the slide and region role descriptions. Removal blocker: component:Carousel
+ // adopting APG Carousel's aria-roledescription as current.
+ it('has carousel ARIA attributes', () => {
render(
- <Carousel aria-label="Test carousel">
- <div data-testid="item-1">Item 1</div>
- <div data-testid="item-2">Item 2</div>
+ <Carousel aria-label="Photos">
+ <div>Item</div>
</Carousel>,
);
- expect(screen.getByTestId('item-1')).toBeInTheDocument();
- expect(screen.getByTestId('item-2')).toBeInTheDocument();
+ const region = screen.getByRole('region', {name: 'Photos'});
+ expect(region).toHaveAttribute('aria-roledescription', 'carousel');
});
- it('has carousel ARIA attributes', () => {
+ it('exposes each slide as a group with aria-roledescription="slide" and a positional name', () => {
render(
<Carousel aria-label="Photos">
- <div>Item</div>
+ <div>One</div>
+ <div>Two</div>
+ <div>Three</div>
</Carousel>,
);
- const region = screen.getByRole('region', {name: 'Photos'});
- expect(region).toHaveAttribute('aria-roledescription', 'carousel');
+ // APG carousel pattern: each slide container is role=group with
+ // aria-roledescription="slide" and an "N of M" accessible name.
+ const slides = screen.getAllByRole('group');
+ expect(slides).toHaveLength(3);
+ slides.forEach((slide, i) => {
+ expect(slide).toHaveAttribute('aria-roledescription', 'slide');
+ expect(slide).toHaveAccessibleName(`Slide ${i + 1} of 3`);
+ });
+ });
+
+ it('renders children', () => {
+ render(
+ <Carousel aria-label="Test carousel">
+ <div data-testid="item-1">Item 1</div>
+ <div data-testid="item-2">Item 2</div>
+ </Carousel>,
+ );
+ expect(screen.getByTestId('item-1')).toBeInTheDocument();
+ expect(screen.getByTestId('item-2')).toBeInTheDocument();
});
- it('makes the scroll container keyboard-focusable', () => {
+ it('reflects the rendered child count, skipping null and boolean children', () => {
render(
<Carousel aria-label="Photos">
- <div>Item</div>
+ <div>One</div>
+ {null}
+ {false}
+ <div>Two</div>
</Carousel>,
);
- // The inner scroll container overflows, so it must be reachable by
- // keyboard (axe: scrollable-region-focusable).
- const region = screen.getByRole('region', {name: 'Photos'});
- const scroller = region.firstElementChild;
- expect(scroller).toHaveAttribute('tabindex', '0');
+ expect(
+ screen.getByRole('group', {name: 'Slide 1 of 2'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('group', {name: 'Slide 2 of 2'}),
+ ).toBeInTheDocument();
+ // Exactly two slides render: null and false children produce no empty
+ // slide (child filtering stays component-owned). The scroller is a named
+ // group too, so count the slides by their role description.
+ expect(
+ screen
+ .getAllByRole('group')
+ .filter(
+ group => group.getAttribute('aria-roledescription') === 'slide',
+ ),
+ ).toHaveLength(2);
});
it('applies data-testid', () => {
@@ -94,59 +131,6 @@ describe('Carousel', () => {
expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
});
- describe('slide semantics', () => {
- it('exposes each slide as a group with aria-roledescription="slide" and a positional name', () => {
- render(
- <Carousel aria-label="Photos">
- <div>One</div>
- <div>Two</div>
- <div>Three</div>
- </Carousel>,
- );
- // APG carousel pattern: each slide container is role=group with
- // aria-roledescription="slide" and an "N of M" accessible name.
- const slides = screen.getAllByRole('group');
- expect(slides).toHaveLength(3);
- slides.forEach((slide, i) => {
- expect(slide).toHaveAttribute('aria-roledescription', 'slide');
- expect(slide).toHaveAccessibleName(`Slide ${i + 1} of 3`);
- });
- });
-
- it('reflects the rendered child count, skipping null and boolean children', () => {
- render(
- <Carousel aria-label="Photos">
- <div>One</div>
- {null}
- {false}
- <div>Two</div>
- </Carousel>,
- );
- const slides = screen.getAllByRole('group');
- expect(slides).toHaveLength(2);
- expect(
- screen.getByRole('group', {name: 'Slide 1 of 2'}),
- ).toBeInTheDocument();
- expect(
- screen.getByRole('group', {name: 'Slide 2 of 2'}),
- ).toBeInTheDocument();
- });
-
- it('keeps the container region semantics unchanged around labelled slides', () => {
- render(
- <Carousel aria-label="Gallery">
- <div>One</div>
- <div>Two</div>
- </Carousel>,
- );
- const region = screen.getByRole('region', {name: 'Gallery'});
- expect(region).toHaveAttribute('aria-roledescription', 'carousel');
- const slides = screen.getAllByRole('group');
- expect(slides).toHaveLength(2);
- slides.forEach(slide => expect(region).toContainElement(slide));
- });
- });
-
it('disables edge scroll buttons instead of removing them from the tab order', () => {
// In jsdom there is no measurable overflow, so both edges are at rest and
// the scroll buttons are in their hidden/inert state. They must stay
@@ -932,5 +916,4 @@ describe('Carousel', () => {
);
});
});
-
});
diff --git a/packages/core/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts b/packages/core/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..297e2ba41d
--- /dev/null
+++ b/packages/core/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts
@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Carousel.a11y.chromium.spec.ts
+ * @input Uses the shared Carousel contract, Chromium harness, checked-in stories, and binding inventory
+ * @output Real-browser and accessibility-tree evidence for Carousel semantics and focus
+ * @position Browser lane required by AST-013; it makes no real-AT claim.
+ */
+
+import {
+ expect,
+ test,
+ type CDPSession,
+ type Locator,
+ type Page,
+} from '@playwright/test';
+import {
+ CAROUSEL_PATTERN,
+ blockingResults,
+ checkAccessibilitySpec,
+ formatFailures,
+ neverExercised,
+ summarize,
+ unmatchedKnownFailures,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+ createChromiumHarness,
+ holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {CAROUSEL_KNOWN_FAILURES} from './Carousel.a11y.known-failures';
+import {
+ CAROUSEL_BINDING_STATES,
+ type CarouselBindingRow,
+} from './Carousel.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+ return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+function subjectFor(page: Page, state: CarouselBindingRow): Locator {
+ const root = page.locator('#storybook-root');
+ if ('selector' in state.subject) {
+ return root.locator(state.subject.selector);
+ }
+ return root.getByRole(state.subject.role, {
+ name: state.subject.name,
+ includeHidden: true,
+ });
+}
+
+function relatedFor(
+ page: Page,
+ state: CarouselBindingRow,
+): Readonly<Record<string, Locator>> {
+ const root = page.locator('#storybook-root');
+ return Object.fromEntries(
+ Object.entries(state.relations ?? {}).map(([name, relation]) => [
+ name,
+ root.locator(relation.selector),
+ ]),
+ );
+}
+
+async function mountState(
+ page: Page,
+ state: CarouselBindingRow,
+): Promise<void> {
+ await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+ await holdMotionStill(page);
+ await subjectFor(page, state).waitFor({state: 'attached'});
+}
+
+async function runState(
+ page: Page,
+ cdp: CDPSession,
+ state: CarouselBindingRow,
+): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: CAROUSEL_PATTERN,
+ binding: 'Carousel',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: CAROUSEL_KNOWN_FAILURES,
+ mount: async () => {
+ await mountState(page, state);
+ return createChromiumHarness({
+ page,
+ subject: subjectFor(page, state),
+ cdp,
+ related: relatedFor(page, state),
+ });
+ },
+ });
+}
+
+function bindingState(id: string): CarouselBindingRow {
+ const state = CAROUSEL_BINDING_STATES.find(candidate => candidate.id === id);
+ if (state == null) {
+ throw new Error(`no Carousel binding state "${id}"`);
+ }
+ return state;
+}
+
+test('every expectation is exercised by at least one Carousel state', async ({
+ page,
+}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const results: BindingResult[] = [];
+ for (const state of CAROUSEL_BINDING_STATES) {
+ results.push(await runState(page, cdp, state));
+ }
+ expect(neverExercised(results)).toEqual([]);
+ expect(unmatchedKnownFailures(CAROUSEL_KNOWN_FAILURES, results)).toEqual([]);
+});
+
+for (const state of CAROUSEL_BINDING_STATES) {
+ test(`Carousel [${state.id}] — ${state.summary}`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const report = summarize(CAROUSEL_PATTERN, [result]);
+ // Required rows block (AST-020 FR9); advisory rows and exact known
+ // failures report.
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ expect(report.unrunLayers).toEqual([]);
+ });
+}
+
+test('the off-screen binding is outside the scroll viewport but remains exposed', async ({
+ page,
+}) => {
+ const state = bindingState('slide-offscreen');
+ await mountState(page, state);
+ const slide = subjectFor(page, state);
+ const scroller = page.locator(
+ '[data-testid="carousel-a11y"] > .astryx-carousel-scroller',
+ );
+ const [slideBox, scrollerBox] = await Promise.all([
+ slide.boundingBox(),
+ scroller.boundingBox(),
+ ]);
+ if (slideBox == null || scrollerBox == null) {
+ throw new Error(
+ 'the off-screen geometry fixture did not render measurable boxes',
+ );
+ }
+ expect(slideBox.x).toBeGreaterThanOrEqual(scrollerBox.x + scrollerBox.width);
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ expect(
+ result.results.find(
+ row => row.expectation === 'carousel.slide.offscreen-exposed',
+ )?.status,
+ ).toBe('pass');
+});
+
+test('the scroll container pans from the keyboard and honors reduced motion', async ({
+ page,
+}) => {
+ const state = bindingState('scroller-keyboard');
+ await page.emulateMedia({reducedMotion: 'reduce'});
+ await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+ const scroller = subjectFor(page, state);
+ await scroller.focus();
+ expect(
+ await scroller.evaluate(
+ element => getComputedStyle(element).scrollBehavior,
+ ),
+ ).toBe('auto');
+ const before = await scroller.evaluate(element => element.scrollLeft);
+ await page.keyboard.press('ArrowRight');
+ await expect
+ .poll(async () => scroller.evaluate(element => element.scrollLeft))
+ .toBeGreaterThan(before);
+});
diff --git a/packages/core/src/Carousel/__tests__/Carousel.a11y.known-failures.ts b/packages/core/src/Carousel/__tests__/Carousel.a11y.known-failures.ts
new file mode 100644
index 0000000000..88fe373bbc
--- /dev/null
+++ b/packages/core/src/Carousel/__tests__/Carousel.a11y.known-failures.ts
@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Carousel.a11y.known-failures.ts
+ * @input The exact carousel-contract failures the shipped Carousel produces today
+ * @output CAROUSEL_KNOWN_FAILURES — records both lanes reconcile against, so a fix shows up as an unexpected pass and any other failure stays a failure
+ * @position Known-failure ledger for the Carousel binding
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const CAROUSEL_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+ {
+ expectation: 'carousel.scroller.role-and-name',
+ binding: 'Carousel',
+ state: 'scroller-keyboard',
+ evidenceLayer: 'accessibility-tree',
+ failureEquals:
+ 'the browser exposes the focusable scroll container with no role',
+ standardsReference:
+ 'WCAG 2.2 4.1.2 Name, Role, Value; Astryx spec:AST-025 FR12 — a viewport that takes keyboard scrolling must provide an appropriate role and accessible name',
+ userImpact:
+ 'A keyboard user who tabs onto the scroll container hears nothing about where they are or what the arrow keys will do; the named region around it is the only clue.',
+ reason:
+ 'This test-only binding records the gap; naming the scroll container is a Carousel markup change that ships as its own spec-backed fix.',
+ },
+];
diff --git a/packages/core/src/Carousel/__tests__/Carousel.a11y.renders.tsx b/packages/core/src/Carousel/__tests__/Carousel.a11y.renders.tsx
new file mode 100644
index 0000000000..27ccca6adf
--- /dev/null
+++ b/packages/core/src/Carousel/__tests__/Carousel.a11y.renders.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Carousel.a11y.renders.tsx
+ * @input Uses Carousel and the binding state ids
+ * @output Stable component renders shared by jsdom and Storybook
+ * @position Checked-in reproduction seam for the Carousel accessibility contract.
+ */
+
+import type {ReactElement} from 'react';
+import {Carousel} from '../Carousel';
+import type {CarouselBindingRow} from './Carousel.a11y.states';
+
+function CarouselFixture() {
+ return (
+ <Carousel
+ data-testid="carousel-a11y"
+ hasLoop
+ hasSnap
+ aria-label="Featured work"
+ style={{width: 240}}>
+ {['One', 'Two', 'Three', 'Four'].map(label => (
+ <div key={label} style={{width: 180, minWidth: 180, height: 80}}>
+ {label}
+ </div>
+ ))}
+ </Carousel>
+ );
+}
+
+export const CAROUSEL_STATE_RENDERS: Readonly<
+ Record<CarouselBindingRow['id'], () => ReactElement>
+> = {
+ 'container-labelled': () => <CarouselFixture />,
+ 'slide-visible': () => <CarouselFixture />,
+ 'slide-offscreen': () => <CarouselFixture />,
+ 'scroller-keyboard': () => <CarouselFixture />,
+ 'next-control-focus': () => <CarouselFixture />,
+};
diff --git a/packages/core/src/Carousel/__tests__/Carousel.a11y.states.ts b/packages/core/src/Carousel/__tests__/Carousel.a11y.states.ts
new file mode 100644
index 0000000000..a5656b8936
--- /dev/null
+++ b/packages/core/src/Carousel/__tests__/Carousel.a11y.states.ts
@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Carousel.a11y.states.ts
+ * @input Uses CarouselStateFacts from @astryxdesign/a11y-spec
+ * @output The AST-021 binding inventory for Carousel semantic parts
+ * @position Data-only inventory shared by jsdom, Storybook, and Chromium bindings.
+ */
+
+import type {CarouselStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface CarouselBindingState {
+ readonly id: string;
+ readonly summary: string;
+ readonly facts: CarouselStateFacts;
+ readonly subject:
+ | {readonly role: 'region' | 'group' | 'button'; readonly name: string}
+ | {readonly selector: string};
+ readonly relations?: Readonly<Record<string, {readonly selector: string}>>;
+ readonly storyId: string;
+}
+
+export type CarouselBindingRow = CarouselBindingState;
+
+const story = (id: string) => `a11y-carousel-pattern--${id}`;
+const slideRelations = {
+ 'slide-1': {selector: '[role="group"][aria-label="Slide 1 of 4"]'},
+ 'slide-2': {selector: '[role="group"][aria-label="Slide 2 of 4"]'},
+ 'slide-3': {selector: '[role="group"][aria-label="Slide 3 of 4"]'},
+ 'slide-4': {selector: '[role="group"][aria-label="Slide 4 of 4"]'},
+} as const;
+
+export const CAROUSEL_BINDING_STATES = [
+ {
+ id: 'container-labelled',
+ summary: 'the labelled Carousel region and all four slides',
+ facts: {
+ part: 'container',
+ expectedName: 'Featured work',
+ slideRelations: Object.keys(slideRelations),
+ offscreen: false,
+ scrollable: false,
+ focusable: false,
+ preservesControlFocus: false,
+ },
+ subject: {role: 'region', name: 'Featured work'},
+ relations: slideRelations,
+ storyId: story('container-labelled'),
+ },
+ {
+ id: 'slide-visible',
+ summary: 'the first visible positional slide',
+ facts: {
+ part: 'slide',
+ expectedName: 'Slide 1 of 4',
+ slideRelations: [],
+ offscreen: false,
+ scrollable: false,
+ focusable: false,
+ preservesControlFocus: false,
+ },
+ subject: {role: 'group', name: 'Slide 1 of 4'},
+ storyId: story('slide-visible'),
+ },
+ {
+ id: 'slide-offscreen',
+ summary: 'the fourth off-screen slide that remains exposed',
+ facts: {
+ part: 'slide',
+ expectedName: 'Slide 4 of 4',
+ slideRelations: [],
+ offscreen: true,
+ scrollable: false,
+ focusable: false,
+ preservesControlFocus: false,
+ },
+ subject: {role: 'group', name: 'Slide 4 of 4'},
+ storyId: story('slide-offscreen'),
+ },
+ {
+ id: 'scroller-keyboard',
+ summary: 'the native horizontal scroll container in the tab sequence',
+ facts: {
+ part: 'scroller',
+ expectedName: '',
+ slideRelations: [],
+ offscreen: false,
+ scrollable: true,
+ focusable: true,
+ preservesControlFocus: false,
+ },
+ subject: {
+ selector: '[data-testid="carousel-a11y"] > .astryx-carousel-scroller',
+ },
+ storyId: story('scroller-keyboard'),
+ },
+ {
+ id: 'next-control-focus',
+ summary: 'the looping next control, which stays enabled and keeps focus',
+ facts: {
+ part: 'control',
+ expectedName: 'Scroll right',
+ slideRelations: [],
+ offscreen: false,
+ scrollable: false,
+ focusable: true,
+ preservesControlFocus: true,
+ },
+ subject: {role: 'button', name: 'Scroll right'},
+ storyId: story('next-control-focus'),
+ },
+] as const satisfies ReadonlyArray<CarouselBindingState>;
+
+export const CAROUSEL_EXCLUSIONS = [
+ {
+ owner: 'Button pattern',
+ classification: 'preserved',
+ reason:
+ 'Navigation-control role, name, activation, unavailable state, and pointer cancellation remain owned by the shared Button contract.',
+ },
+ {
+ owner: 'Carousel implementation and visual gate',
+ classification: 'preserved',
+ reason:
+ 'Scroll distance, snapping, looping, edge fades, focus-ring paint, target geometry, and reduced-motion behavior remain component-owned browser and visual evidence.',
+ },
+ {
+ owner: 'Caller content',
+ classification: 'out-of-scope',
+ reason:
+ 'Slide descendants keep their own image, link, control, reading-order, and language obligations.',
+ },
+ {
+ owner: 'Automatic rotation',
+ classification: 'out-of-scope',
+ reason:
+ 'Carousel does not auto-advance; the public docs explicitly tell consumers not to auto-advance items.',
+ },
+] as const;
diff --git a/packages/core/src/Carousel/__tests__/Carousel.a11y.test.tsx b/packages/core/src/Carousel/__tests__/Carousel.a11y.test.tsx
new file mode 100644
index 0000000000..e783863a37
--- /dev/null
+++ b/packages/core/src/Carousel/__tests__/Carousel.a11y.test.tsx
@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Carousel.a11y.test.tsx
+ * @input Uses the shared Carousel contract and complete Carousel binding inventory
+ * @output DOM-layer binding evidence; browser-owned outcomes remain explicitly unrun
+ * @position Fast migration lane for Carousel container, slides, scroller, and control.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+ CAROUSEL_PATTERN,
+ checkAccessibilitySpec,
+ createJsdomHarness,
+ expectAccessibilitySpec,
+ summarize,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {CAROUSEL_KNOWN_FAILURES} from './Carousel.a11y.known-failures';
+import {CAROUSEL_STATE_RENDERS} from './Carousel.a11y.renders';
+import {
+ CAROUSEL_BINDING_STATES,
+ CAROUSEL_EXCLUSIONS,
+ type CarouselBindingRow,
+} from './Carousel.a11y.states';
+
+function subjectFor(state: CarouselBindingRow): Element {
+ if ('selector' in state.subject) {
+ const element = document.querySelector(state.subject.selector);
+ if (element == null) {
+ throw new Error(`no subject for ${state.id}`);
+ }
+ return element;
+ }
+ return screen.getByRole(state.subject.role, {
+ name: state.subject.name,
+ hidden: true,
+ });
+}
+
+function relatedFor(
+ state: CarouselBindingRow,
+): Readonly<Record<string, Element>> {
+ return Object.fromEntries(
+ Object.entries(state.relations ?? {}).map(([name, relation]) => {
+ const element = document.querySelector(relation.selector);
+ if (element == null) {
+ throw new Error(`no related subject "${name}" for ${state.id}`);
+ }
+ return [name, element];
+ }),
+ );
+}
+
+async function checkState(state: CarouselBindingRow): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: CAROUSEL_PATTERN,
+ binding: 'Carousel',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: CAROUSEL_KNOWN_FAILURES,
+ mount: async () => {
+ render(CAROUSEL_STATE_RENDERS[state.id]());
+ return createJsdomHarness({
+ subject: subjectFor(state),
+ related: relatedFor(state),
+ });
+ },
+ unmount: cleanup,
+ });
+}
+
+describe('the shared Carousel pattern, jsdom lane', () => {
+ it.each(
+ CAROUSEL_BINDING_STATES.map(
+ state => [`Carousel [${state.id}]`, state.summary, state] as const,
+ ),
+ )('%s — %s', async (_id, _summary, state) => {
+ await expectAccessibilitySpec({
+ spec: CAROUSEL_PATTERN,
+ binding: 'Carousel',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: CAROUSEL_KNOWN_FAILURES,
+ render: () => {
+ render(CAROUSEL_STATE_RENDERS[state.id]());
+ },
+ subject: () => subjectFor(state),
+ related: () => relatedFor(state),
+ cleanup,
+ });
+ });
+
+ it('runs DOM expectations and reports higher layers as unrun', async () => {
+ const results: BindingResult[] = [];
+ for (const state of CAROUSEL_BINDING_STATES) {
+ results.push(await checkState(state));
+ }
+ const report = summarize(CAROUSEL_PATTERN, results);
+ expect(report.counts.pass).toBeGreaterThan(0);
+ expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+});
+
+describe('the Carousel binding inventory', () => {
+ it('names a distinct checked-in story for every state', () => {
+ const ids = CAROUSEL_BINDING_STATES.map(state => state.storyId);
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+
+ it('records every excluded owner explicitly', () => {
+ expect(CAROUSEL_EXCLUSIONS.every(row => row.owner && row.reason)).toBe(
+ true,
+ );
+ });
+
+ it('renders exactly one subject for every state', () => {
+ for (const state of CAROUSEL_BINDING_STATES) {
+ render(CAROUSEL_STATE_RENDERS[state.id]());
+ expect(subjectFor(state), state.id).toBeTruthy();
+ cleanup();
+ }
+ });
+});