Skip to content

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

TypeScript

test(a11y): add Breadcrumb semantic contract (#6851)

Cindy Zhang46279ebfed5f
diff --git a/apps/storybook/stories/BreadcrumbsA11y.stories.tsx b/apps/storybook/stories/BreadcrumbsA11y.stories.tsx
new file mode 100644
index 0000000000..f4f5afa072
--- /dev/null
+++ b/apps/storybook/stories/BreadcrumbsA11y.stories.tsx
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** One checked-in Storybook fixture for every Breadcrumbs semantic state. */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {BREADCRUMB_A11Y_RENDERS} from '../../../packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.renders';
+import {BREADCRUMB_A11Y_STATES} from '../../../packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.states';
+
+function storyFor(id: (typeof BREADCRUMB_A11Y_STATES)[number]['id']): StoryObj {
+ const state = BREADCRUMB_A11Y_STATES.find(candidate => candidate.id === id);
+ if (state == null) {
+ throw new Error(`no Breadcrumbs binding state "${id}"`);
+ }
+ return {
+ name: `Breadcrumbs — ${state.id}`,
+ render: () => BREADCRUMB_A11Y_RENDERS[state.id](),
+ };
+}
+
+const meta: Meta = {
+ title: 'a11y/Breadcrumb pattern',
+ tags: ['no-visual'],
+ parameters: {layout: 'padded'},
+};
+
+export default meta;
+
+export const ExplicitCurrentDefault = storyFor('explicit-current-default');
+export const AutoCurrentCustomLabelRtl = storyFor(
+ 'auto-current-custom-label-rtl',
+);
+export const NoCurrentOptOut = storyFor('no-current-opt-out');
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
index acea52c535..c791da0c6d 100644
--- a/internal/a11y-spec/README.md
+++ b/internal/a11y-spec/README.md
@@ -50,24 +50,26 @@ src/
├── tabs.* explicit horizontal ARIA Tabs semantics
├── listbox.* listbox, group, and option semantics
├── spinbutton.* numeric role, value, bounds, state, and arrow stepping
- └── disclosure.* standalone disclosure state/content semantics
+ ├── disclosure.* standalone disclosure state/content semantics
+ └── breadcrumb.* landmark, list-trail, current-page, and separator semantics
```
## The patterns
-| Pattern | Adopted from | Bound by |
-| ---------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `radio-group` | [APG radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) | RadioList, SegmentedControl; role/state portions of DropdownMenu radio items |
-| `checkbox` | [APG checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) | CheckboxInput, CheckboxListItem, DropdownMenuCheckboxItem, SelectableCard |
-| `switch` | [APG switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | Switch |
-| `button` | [APG button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | Button, IconButton, ClickableCard, SideNavCollapseButton, ChatSendButton |
-| `text-input` | Native HTML controls and [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox) | TextInput, TextArea |
-| `modal-dialog` | [APG dialog (modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Dialog |
-| `status-message` | [WCAG 2.2 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | Toast, FieldStatus, Spinner, ChatSystemMessage, ChatTypingIndicator, ProgressBar |
-| `tabs` | [APG Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) | Explicit `role="tablist"` TabList, Tab, and caller-authored tabpanels |
-| `listbox` | [WAI-ARIA 1.2 Listbox](https://www.w3.org/TR/wai-aria-1.2/#listbox) and WCAG 2.2 semantics | Selector and MultiSelector popup listbox, group, and option parts |
-| `spinbutton` | WCAG 2.2 semantics and [APG Spinbutton](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) | NumberInput |
-| `disclosure` | [APG Disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) | Standalone Collapsible triggers and their controlled content |
+| Pattern | Adopted from | Bound by |
+| ---------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `radio-group` | [APG radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) | RadioList, SegmentedControl; role/state portions of DropdownMenu radio items |
+| `checkbox` | [APG checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) | CheckboxInput, CheckboxListItem, DropdownMenuCheckboxItem, SelectableCard |
+| `switch` | [APG switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | Switch |
+| `button` | [APG button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | Button, IconButton, ClickableCard, SideNavCollapseButton, ChatSendButton |
+| `text-input` | Native HTML controls and [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox) | TextInput, TextArea |
+| `modal-dialog` | [APG dialog (modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Dialog |
+| `status-message` | [WCAG 2.2 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | Toast, FieldStatus, Spinner, ChatSystemMessage, ChatTypingIndicator, ProgressBar |
+| `tabs` | [APG Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) | Explicit `role="tablist"` TabList, Tab, and caller-authored tabpanels |
+| `listbox` | [WAI-ARIA 1.2 Listbox](https://www.w3.org/TR/wai-aria-1.2/#listbox) and WCAG 2.2 semantics | Selector and MultiSelector popup listbox, group, and option parts |
+| `spinbutton` | WCAG 2.2 semantics and [APG Spinbutton](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) | NumberInput |
+| `disclosure` | [APG Disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) | Standalone Collapsible triggers and their controlled content |
+| `breadcrumb` | WCAG 2.2 semantics; [APG Breadcrumb](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) as context | Breadcrumbs landmarks, list trails, current-page state, and separators |
The `spinbutton` contract owns NumberInput's required role, persistent name,
committed numeric value, optional bounds and formatted value text, disabled and
@@ -84,6 +86,14 @@ unavailable-button semantics remain in the existing `button` contract. This firs
migration binds standalone Collapsible states only; CollapsibleGroup coordination
and Accordion, Table, and SideNav adoption remain outside this contract.
+The breadcrumb contract owns the named navigation landmark, list trail,
+optional current-page state, and decorative separator exposure. Its first
+Breadcrumbs binding covers explicit and automatic current-page selection, a
+custom landmark label, RTL/supporting presentation, and an intentional
+no-current-page opt-out. Link, action-button, and sibling-menu semantics stay
+with their own patterns; the APG Breadcrumb page remains context because no
+current Astryx record adopts it as an additional required gate.
+
The `listbox` contract is a bounded semantic migration, not blanket APG
interaction adoption. Its first bindings cover 21 existing scenarios across
single/multiple selection, disabled options, groups, filtering, custom content,
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
index 1e89c86c6b..38ec3b708f 100644
--- a/internal/a11y-spec/src/index.ts
+++ b/internal/a11y-spec/src/index.ts
@@ -122,3 +122,8 @@ export {
DISCLOSURE_PATTERN,
type DisclosureStateFacts,
} from './patterns/disclosure';
+
+export {
+ BREADCRUMB_PATTERN,
+ type BreadcrumbStateFacts,
+} from './patterns/breadcrumb';
diff --git a/internal/a11y-spec/src/patterns/breadcrumb.chromium.spec.ts b/internal/a11y-spec/src/patterns/breadcrumb.chromium.spec.ts
new file mode 100644
index 0000000000..da6a264e03
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/breadcrumb.chromium.spec.ts
@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Real-browser positive and mutation proof for the Breadcrumb contract. */
+
+import {
+ expect,
+ test,
+ type CDPSession,
+ type Locator,
+ type Page,
+} from '@playwright/test';
+import {describeExpectation, requiredLayers} from '../contract';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {
+ CHROMIUM_OBSERVES,
+ createChromiumHarness,
+ holdMotionStill,
+} from '../harness/chromium';
+import {BREADCRUMB_PATTERN} from './breadcrumb';
+import {
+ BREADCRUMB_CURRENT_SELECTOR,
+ BREADCRUMB_LIST_SELECTOR,
+ BREADCRUMB_MUTATIONS,
+ BREADCRUMB_SEPARATOR_SELECTOR,
+ BREADCRUMB_SUBJECT_SELECTOR,
+ CONFORMING_BREADCRUMB_FIXTURES,
+ breadcrumbFixture,
+ type BreadcrumbFixture,
+} from './breadcrumb.fixtures';
+
+function fixturePage(html: string): string {
+ return `<!doctype html><html lang="en"><body>${html}</body></html>`;
+}
+
+async function results(
+ page: Page,
+ cdp: CDPSession,
+ target: BreadcrumbFixture,
+ only?: readonly string[],
+): Promise<readonly ExpectationResult[]> {
+ const run = await checkAccessibilitySpec({
+ spec: BREADCRUMB_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ only,
+ mount: async () => {
+ await page.setContent(fixturePage(target.html));
+ await holdMotionStill(page);
+ const related: Record<string, Locator> = {
+ list: page.locator(BREADCRUMB_LIST_SELECTOR),
+ };
+ const current = page.locator(BREADCRUMB_CURRENT_SELECTOR);
+ if ((await current.count()) > 0) {
+ related.current = current;
+ }
+ const separators = page.locator(BREADCRUMB_SEPARATOR_SELECTOR);
+ for (let index = 0; index < target.facts.separatorCount; index += 1) {
+ related[`separator-${index}`] = separators.nth(index);
+ }
+ return createChromiumHarness({
+ page,
+ cdp,
+ subject: page.locator(BREADCRUMB_SUBJECT_SELECTOR),
+ related,
+ });
+ },
+ });
+ return run.results;
+}
+
+test.describe('Breadcrumb contract — conforming fixtures', () => {
+ for (const id of CONFORMING_BREADCRUMB_FIXTURES) {
+ test(`${id}: every applicable expectation passes`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const observed = await results(page, cdp, breadcrumbFixture(id));
+ expect(
+ observed
+ .filter(
+ result =>
+ result.status !== 'pass' && result.status !== 'not-applicable',
+ )
+ .map(result => `${result.expectation}: ${result.detail ?? ''}`),
+ ).toEqual([]);
+ });
+ }
+});
+
+test.describe('Breadcrumb contract — deliberately violating fixtures', () => {
+ for (const expectation of BREADCRUMB_PATTERN.expectations) {
+ if (
+ !requiredLayers(expectation).every(layer =>
+ CHROMIUM_OBSERVES.includes(layer),
+ )
+ ) {
+ continue;
+ }
+ for (const fixtureId of BREADCRUMB_MUTATIONS[expectation.id] ?? []) {
+ test(`${describeExpectation(expectation)} — fails against ${fixtureId}`, async ({
+ page,
+ }) => {
+ const cdp = await page.context().newCDPSession(page);
+ const [result] = await results(
+ page,
+ cdp,
+ breadcrumbFixture(fixtureId),
+ [expectation.id],
+ );
+ expect(result?.status, result?.detail ?? 'no result').toBe('fail');
+ expect(result?.detail ?? '').not.toBe('');
+ });
+ }
+ }
+});
diff --git a/internal/a11y-spec/src/patterns/breadcrumb.fixtures.ts b/internal/a11y-spec/src/patterns/breadcrumb.fixtures.ts
new file mode 100644
index 0000000000..1e0c2c6b89
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/breadcrumb.fixtures.ts
@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Plain-HTML positive and mutation fixtures for the Breadcrumb contract. */
+
+import type {BreadcrumbStateFacts} from './breadcrumb';
+
+export const BREADCRUMB_SUBJECT_SELECTOR = '[data-a11y-breadcrumb]';
+export const BREADCRUMB_LIST_SELECTOR = '[data-a11y-list]';
+export const BREADCRUMB_CURRENT_SELECTOR = '[data-a11y-current]';
+export const BREADCRUMB_SEPARATOR_SELECTOR = '[data-a11y-separator]';
+
+export interface BreadcrumbFixture {
+ readonly id: string;
+ readonly summary: string;
+ readonly facts: BreadcrumbStateFacts;
+ readonly html: string;
+}
+
+interface Options {
+ readonly landmark?: 'nav' | 'div';
+ readonly label?: string | null;
+ readonly list?: 'ol' | 'div';
+ readonly listOutside?: boolean;
+ readonly currentPage?: boolean;
+ readonly currentAttribute?: boolean;
+ readonly currentOutside?: boolean;
+ readonly exposedSeparator?: number;
+}
+
+function facts(
+ overrides: Partial<BreadcrumbStateFacts> = {},
+): BreadcrumbStateFacts {
+ return {
+ landmarkLabel: 'Breadcrumb',
+ currentPage: true,
+ separatorCount: 3,
+ ...overrides,
+ };
+}
+
+function html(options: Options = {}): string {
+ const landmark = options.landmark ?? 'nav';
+ const label = options.label === undefined ? 'Breadcrumb' : options.label;
+ const list = options.list ?? 'ol';
+ const currentPage = options.currentPage ?? true;
+ const currentAttribute = options.currentAttribute ?? true;
+ const separator = (index: number) =>
+ `<span data-a11y-separator ${options.exposedSeparator === index ? '' : 'aria-hidden="true"'}>/</span>`;
+ const items = `
+ <li>${separator(0)}<a href="/">Home</a></li>
+ <li>${separator(1)}<a href="/projects">Projects</a></li>
+ <li>${separator(2)}<span ${currentPage ? 'data-a11y-current' : ''} ${currentPage && currentAttribute ? 'aria-current="page"' : ''}>Current page</span></li>
+ `;
+ const trail = `<${list} data-a11y-list>${items}</${list}>`;
+ const outsideCurrent = options.currentOutside
+ ? '<span data-a11y-current aria-current="page">Current page</span>'
+ : '';
+ const landmarkContent = options.listOutside
+ ? outsideCurrent
+ : `${trail}${outsideCurrent}`;
+ return `
+ <${landmark} data-a11y-breadcrumb ${label == null ? '' : `aria-label="${label}"`}>
+ ${landmarkContent}
+ </${landmark}>
+ ${options.listOutside ? trail : ''}
+ `;
+}
+
+export const BREADCRUMB_FIXTURES: readonly BreadcrumbFixture[] = [
+ {
+ id: 'conforming-current-page',
+ summary:
+ 'a named breadcrumb landmark with an ordered trail and current page',
+ facts: facts(),
+ html: html(),
+ },
+ {
+ id: 'conforming-custom-label',
+ summary: 'a trail with a caller-provided landmark name',
+ facts: facts({landmarkLabel: 'Project location'}),
+ html: html({label: 'Project location'}),
+ },
+ {
+ id: 'conforming-no-current-page',
+ summary: 'a named ordered trail that intentionally omits a current page',
+ facts: facts({currentPage: false}),
+ html: html({currentPage: false}),
+ },
+ {
+ id: 'violating-landmark-role',
+ summary: 'a generic container instead of a navigation landmark',
+ facts: facts(),
+ html: html({landmark: 'div'}),
+ },
+ {
+ id: 'violating-landmark-name',
+ summary: 'an unnamed navigation landmark',
+ facts: facts(),
+ html: html({label: null}),
+ },
+ {
+ id: 'violating-list-role',
+ summary: 'generic content instead of a list',
+ facts: facts(),
+ html: html({list: 'div'}),
+ },
+ {
+ id: 'violating-list-containment',
+ summary: 'an ordered trail outside its navigation landmark',
+ facts: facts(),
+ html: html({listOutside: true}),
+ },
+ {
+ id: 'violating-current-page',
+ summary: 'a current page without aria-current',
+ facts: facts(),
+ html: html({currentAttribute: false}),
+ },
+ {
+ id: 'violating-current-containment',
+ summary: 'a current-page marker outside the trail',
+ facts: facts(),
+ html: html({currentPage: false, currentOutside: true}),
+ },
+ {
+ id: 'violating-separator',
+ summary: 'a visual separator exposed to assistive technology',
+ facts: facts(),
+ html: html({exposedSeparator: 1}),
+ },
+];
+
+export const CONFORMING_BREADCRUMB_FIXTURES = BREADCRUMB_FIXTURES.filter(
+ fixture => fixture.id.startsWith('conforming-'),
+).map(fixture => fixture.id);
+
+export const BREADCRUMB_MUTATIONS: Readonly<Record<string, readonly string[]>> =
+ {
+ 'breadcrumb.landmark.named': [
+ 'violating-landmark-role',
+ 'violating-landmark-name',
+ ],
+ 'breadcrumb.trail.list': [
+ 'violating-list-role',
+ 'violating-list-containment',
+ ],
+ 'breadcrumb.current-page.exposed': [
+ 'violating-current-page',
+ 'violating-current-containment',
+ ],
+ 'breadcrumb.separators.decorative': ['violating-separator'],
+ };
+
+export function breadcrumbFixture(id: string): BreadcrumbFixture {
+ const fixture = BREADCRUMB_FIXTURES.find(candidate => candidate.id === id);
+ if (fixture == null) {
+ throw new Error(`unknown Breadcrumb fixture "${id}"`);
+ }
+ return fixture;
+}
diff --git a/internal/a11y-spec/src/patterns/breadcrumb.jsdom.test.ts b/internal/a11y-spec/src/patterns/breadcrumb.jsdom.test.ts
new file mode 100644
index 0000000000..dc821c45fb
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/breadcrumb.jsdom.test.ts
@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/** Contract self-tests for Breadcrumb DOM expectations and completeness. */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {
+ citeSource,
+ describeExpectation,
+ requiredLayers,
+ unansweredDimensions,
+} from '../contract';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {JSDOM_OBSERVES, createJsdomHarness} from '../harness/jsdom';
+import {BREADCRUMB_PATTERN} from './breadcrumb';
+import {
+ BREADCRUMB_CURRENT_SELECTOR,
+ BREADCRUMB_LIST_SELECTOR,
+ BREADCRUMB_MUTATIONS,
+ BREADCRUMB_SEPARATOR_SELECTOR,
+ BREADCRUMB_SUBJECT_SELECTOR,
+ CONFORMING_BREADCRUMB_FIXTURES,
+ breadcrumbFixture,
+ type BreadcrumbFixture,
+} from './breadcrumb.fixtures';
+
+afterEach(() => document.body.replaceChildren());
+
+async function resultsFor(target: BreadcrumbFixture) {
+ const container = document.createElement('div');
+ document.body.append(container);
+ const run = await checkAccessibilitySpec({
+ spec: BREADCRUMB_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ mount: async () => {
+ container.innerHTML = target.html;
+ const subject = container.querySelector(BREADCRUMB_SUBJECT_SELECTOR);
+ const list = container.querySelector(BREADCRUMB_LIST_SELECTOR);
+ if (subject == null || list == null) {
+ throw new Error(
+ `fixture "${target.id}" is missing its landmark or list`,
+ );
+ }
+ const related: Record<string, Element> = {list};
+ const current = container.querySelector(BREADCRUMB_CURRENT_SELECTOR);
+ if (current != null) {
+ related.current = current;
+ }
+ container
+ .querySelectorAll(BREADCRUMB_SEPARATOR_SELECTOR)
+ .forEach((separator, index) => {
+ related[`separator-${index}`] = separator;
+ });
+ return createJsdomHarness({subject, related});
+ },
+ unmount: () => {
+ container.innerHTML = '';
+ },
+ });
+ return run.results;
+}
+
+function resultFor(
+ results: readonly ExpectationResult[],
+ id: string,
+): ExpectationResult {
+ const found = results.find(result => result.expectation === id);
+ if (found == null) {
+ throw new Error(`no result for ${id}`);
+ }
+ return found;
+}
+
+const observableHere = BREADCRUMB_PATTERN.expectations.filter(expectation =>
+ requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
+);
+
+describe('Breadcrumb contract — completeness', () => {
+ it('answers every completeness dimension', () => {
+ expect(unansweredDimensions(BREADCRUMB_PATTERN)).toEqual([]);
+ });
+
+ it('gives every expectation at least one deliberately violating fixture', () => {
+ expect(
+ BREADCRUMB_PATTERN.expectations
+ .filter(
+ expectation =>
+ (BREADCRUMB_MUTATIONS[expectation.id] ?? []).length === 0,
+ )
+ .map(expectation => expectation.id),
+ ).toEqual([]);
+ });
+
+ it('has an expectation for every mutation it records', () => {
+ const ids = new Set(
+ BREADCRUMB_PATTERN.expectations.map(expectation => expectation.id),
+ );
+ expect(
+ Object.keys(BREADCRUMB_MUTATIONS).filter(id => !ids.has(id)),
+ ).toEqual([]);
+ });
+});
+
+describe('Breadcrumb contract — the jsdom harness stays within its evidence boundary', () => {
+ it('runs DOM expectations and reports accessibility-tree expectations as unrun', async () => {
+ const results = await resultsFor(
+ breadcrumbFixture('conforming-current-page'),
+ );
+ expect(results.some(result => result.status === 'pass')).toBe(true);
+ const unrun = results.filter(result => result.status === 'unrun');
+ expect(unrun.length).toBeGreaterThan(0);
+ for (const result of unrun) {
+ expect(result.missingLayers).toContain('accessibility-tree');
+ }
+ });
+});
+
+describe.each(observableHere.map(expectation => [expectation.id] as const))(
+ '%s',
+ id => {
+ const expectation = BREADCRUMB_PATTERN.expectations.find(
+ candidate => candidate.id === id,
+ )!;
+
+ it.each(CONFORMING_BREADCRUMB_FIXTURES.map(name => [name] as const))(
+ 'passes against %s (or does not apply to it)',
+ async name => {
+ const result = resultFor(await resultsFor(breadcrumbFixture(name)), id);
+ expect(
+ ['pass', 'not-applicable'],
+ `${id} against ${name}: ${result.detail ?? ''}`,
+ ).toContain(result.status);
+ },
+ );
+
+ it.each((BREADCRUMB_MUTATIONS[id] ?? []).map(name => [name] as const))(
+ 'fails against %s, which removes its outcome',
+ async name => {
+ const result = resultFor(await resultsFor(breadcrumbFixture(name)), id);
+ expect(result.status, `${id} against ${name}`).toBe('fail');
+ expect(result.detail ?? '').not.toBe('');
+ },
+ );
+
+ it('carries its id and primary source into every result description', async () => {
+ const target = breadcrumbFixture(
+ BREADCRUMB_MUTATIONS[id]?.[0] ?? CONFORMING_BREADCRUMB_FIXTURES[0]!,
+ );
+ const result = resultFor(await resultsFor(target), id);
+ expect(result.description).toContain(id);
+ expect(result.description).toContain(citeSource(expectation.sources[0]));
+ expect(describeExpectation(expectation)).toBe(result.description);
+ });
+ },
+);
diff --git a/internal/a11y-spec/src/patterns/breadcrumb.ts b/internal/a11y-spec/src/patterns/breadcrumb.ts
new file mode 100644
index 0000000000..77d4d1d820
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/breadcrumb.ts
@@ -0,0 +1,353 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file breadcrumb.ts
+ * @input Uses the shared accessibility-contract vocabulary
+ * @output BREADCRUMB_PATTERN and BreadcrumbStateFacts
+ * @position Reusable semantic contract for one breadcrumb navigation landmark.
+ * Link, button, and menu interactions retain their own pattern owners.
+ *
+ * The required slice is derived from WCAG 2.2. The APG Breadcrumb page is
+ * contextual only because no current Astryx record adopts its mechanics as a
+ * separate required gate.
+ */
+
+import {
+ definePattern,
+ type PatternContract,
+ type WcagCriterion,
+} from '../contract';
+
+const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/';
+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_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');
+
+export interface BreadcrumbStateFacts {
+ /** The accessible name expected on the navigation landmark. */
+ readonly landmarkLabel: string;
+ /** Whether this trail includes the page that is current in its hierarchy. */
+ readonly currentPage: boolean;
+ /** The number of rendered separator containers owned by the binding. */
+ readonly separatorCount: number;
+}
+
+const ALWAYS = {
+ condition: 'the binding renders a breadcrumb trail',
+ test: () => true,
+};
+
+export const BREADCRUMB_PATTERN: PatternContract<BreadcrumbStateFacts> =
+ definePattern<BreadcrumbStateFacts>({
+ pattern: 'breadcrumb',
+ url: APG_URL,
+ scope:
+ 'One named navigation landmark containing a breadcrumb list trail, an optional current page, and decorative separators.',
+ expectations: [
+ {
+ id: 'breadcrumb.landmark.named',
+ outcome:
+ 'The browser exposes a named navigation landmark so the trail can be found and distinguished from other navigation.',
+ sources: [WCAG_4_1_2, WCAG_2_4_6],
+ covers: ['4.1.2-name-role-value', '2.4.6-headings-and-labels'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {role, name} = await subject.computed();
+ if (role !== 'navigation') {
+ throw new Error(
+ `the browser exposes ${role == null ? 'no role' : `"${role}"`} instead of navigation`,
+ );
+ }
+ if (name !== facts.landmarkLabel) {
+ throw new Error(
+ `the landmark should be named "${facts.landmarkLabel}", but the browser computes ${name === '' ? 'no name' : `"${name}"`}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'breadcrumb.trail.list',
+ outcome:
+ 'The navigation landmark contains a list that exposes the breadcrumb trail relationship.',
+ sources: [WCAG_1_3_1],
+ covers: ['1.3.1-info-and-relationships'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ alsoNeeds: ['dom'],
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ const list = await harness.related('list');
+ if (!(await harness.contains(subject, list))) {
+ throw new Error(
+ 'the breadcrumb list is not contained by its navigation landmark',
+ );
+ }
+ const {role} = await list.computed();
+ if (role !== 'list') {
+ throw new Error(
+ `the browser exposes the trail as ${role == null ? 'no role' : `"${role}"`} instead of a list`,
+ );
+ }
+ },
+ },
+ {
+ id: 'breadcrumb.current-page.exposed',
+ outcome:
+ 'When the trail includes the current page, that item is programmatically identified inside the trail.',
+ sources: [WCAG_4_1_2, WCAG_1_3_1],
+ covers: ['4.1.2-name-role-value', '1.3.1-info-and-relationships'],
+ appliesWhen: {
+ condition: 'the trail includes the current page',
+ test: facts => facts.currentPage,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({harness}) => {
+ const list = await harness.related('list');
+ const current = await harness.related('current');
+ if ((await current.attribute('aria-current')) !== 'page') {
+ throw new Error(
+ 'the current breadcrumb does not expose aria-current="page"',
+ );
+ }
+ if (!(await harness.contains(list, current))) {
+ throw new Error(
+ 'the current breadcrumb is not contained by the ordered trail',
+ );
+ }
+ },
+ },
+ {
+ id: 'breadcrumb.separators.decorative',
+ outcome:
+ 'Every visual separator is hidden from the accessibility tree so it does not interrupt the trail.',
+ sources: [WCAG_1_3_1],
+ covers: ['1.3.1-info-and-relationships'],
+ appliesWhen: {
+ condition: 'the binding renders one or more visual separators',
+ test: facts => facts.separatorCount > 0,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({harness, facts}) => {
+ for (let index = 0; index < facts.separatorCount; index += 1) {
+ const separator = await harness.related(`separator-${index}`);
+ if ((await separator.attribute('aria-hidden')) !== 'true') {
+ throw new Error(
+ `breadcrumb separator ${index + 1} of ${facts.separatorCount} is exposed to assistive technology`,
+ );
+ }
+ }
+ },
+ },
+ ],
+ exemptions: {
+ '1.1.1-non-text-content': {
+ owner: 'BreadcrumbItem start content and caller content',
+ verifiedBy:
+ 'Component icon tests, content review, and the repository axe audit',
+ reason:
+ 'The trail contract owns landmark, list, current-page, and separator semantics; caller-provided icons and other non-text content remain binding-specific.',
+ },
+ '1.3.1-info-and-relationships': {
+ owner: 'The link, button, menu, and composing-page owners',
+ verifiedBy:
+ 'Their pattern contracts, component tests, and page-level structure review',
+ reason:
+ 'This contract encodes the landmark, list, current-page, and decorative-separator relationships. Relationships within each destination or menu remain with those parts.',
+ coversRemainderOnly: true,
+ },
+ '1.3.2-meaningful-sequence': {
+ owner: 'Breadcrumbs and the composing page',
+ verifiedBy:
+ 'Component DOM-order tests and page-level reading-order review',
+ reason:
+ 'The binding owns item order and the page owns where the trail appears relative to its heading and content.',
+ },
+ '1.3.5-identify-input-purpose': {
+ owner: 'The composing form and caller content',
+ verifiedBy: 'Form integration review',
+ reason:
+ 'A breadcrumb trail does not collect information about the user.',
+ },
+ '1.4.1-use-of-color': {
+ owner: 'Breadcrumbs, BreadcrumbItem, and the active theme',
+ verifiedBy: 'Rendered state review and the repository visual gate',
+ reason:
+ 'Current-page emphasis and destination styling are paint outcomes outside this semantic contract.',
+ },
+ '1.4.3-contrast-minimum': {
+ owner: 'Breadcrumbs, BreadcrumbItem, and the active theme',
+ verifiedBy: 'Rendered contrast audit',
+ reason: 'Text contrast depends on resolved colors and backdrop.',
+ },
+ '1.4.11-non-text-contrast': {
+ owner: 'BreadcrumbItem controls and the active theme',
+ verifiedBy:
+ 'Rendered control, state, and focus-indicator contrast review',
+ reason:
+ 'Any control boundary, state cue, or focus indicator is a paint outcome.',
+ },
+ '2.1.1-keyboard': {
+ owner: 'The link, button, and menu-button pattern owners',
+ verifiedBy:
+ 'Their reusable contracts and BreadcrumbItem interaction tests',
+ reason:
+ 'The breadcrumb container adds no keyboard interaction; each interactive item keeps its own role-specific contract.',
+ },
+ '2.1.2-no-keyboard-trap': {
+ owner: 'The menu-button, popover, and composing-page owners',
+ verifiedBy: 'Menu dismissal tests and page-level keyboard review',
+ reason:
+ 'The trail itself creates no focus trap; popup escape and surrounding navigation are separate owners.',
+ },
+ '2.4.2-page-titled': {
+ owner: 'The page',
+ verifiedBy: 'Page-level title review',
+ reason: 'A breadcrumb component does not own the document title.',
+ },
+ '2.4.3-focus-order': {
+ owner: 'BreadcrumbItem and the composing page',
+ verifiedBy: 'Real-browser keyboard-order review',
+ reason:
+ 'Sequential focus among destinations, menus, and surrounding controls depends on item composition and page placement.',
+ },
+ '2.4.4-link-purpose': {
+ owner: 'The link pattern and caller-provided labels',
+ verifiedBy: 'Link contract bindings plus content review',
+ reason:
+ 'Breadcrumb destination purpose comes from caller text and the destination owner, not the trail container.',
+ },
+ '2.4.6-headings-and-labels': {
+ owner: 'Caller-provided landmark text and destination labels',
+ verifiedBy: 'Content review of the trail and each item label',
+ reason:
+ 'This contract proves the landmark has the declared name, not that caller wording is sufficiently descriptive.',
+ coversRemainderOnly: true,
+ },
+ '2.4.7-focus-visible': {
+ owner:
+ 'BreadcrumbItem, interaction-modality architecture, and the active theme',
+ verifiedBy: 'Rendered keyboard-focus review',
+ reason: 'Focus-indicator paint requires visual evidence.',
+ },
+ '2.4.11-focus-not-obscured': {
+ owner: 'The composing page and overlay system',
+ verifiedBy: 'Constrained-viewport and open-menu browser review',
+ reason: 'Occlusion depends on surrounding layout and open surfaces.',
+ },
+ '2.5.2-pointer-cancellation': {
+ owner: 'The link, button, and menu-button pattern owners',
+ verifiedBy: 'Their pointer activation and aborted-press tests',
+ reason: 'The breadcrumb container has no pointer action of its own.',
+ },
+ '2.5.3-label-in-name': {
+ owner: 'BreadcrumbItem and caller-provided visible labels',
+ verifiedBy:
+ 'Visible-label versus computed-name browser review for each interactive item',
+ reason:
+ 'The landmark label is normally not visible, while each visible interactive item keeps its own label-in-name owner.',
+ },
+ '2.5.8-target-size': {
+ owner: 'BreadcrumbItem and the composing page',
+ verifiedBy: 'Rendered target geometry and neighbouring-target review',
+ reason: 'Target size and spacing depend on item rendering and layout.',
+ },
+ '3.1.1-language-of-page': {
+ owner: 'The page and localization provider',
+ verifiedBy: 'Document-language checks',
+ reason: 'A breadcrumb trail does not own the document language.',
+ },
+ '3.2.2-on-input': {
+ owner: 'The link, button, menu, and caller navigation owners',
+ verifiedBy: 'Role-specific interaction tests and integration review',
+ reason:
+ 'Navigation or menu activation is owned by each item and its caller; the trail container has no input event.',
+ },
+ '3.2.4-consistent-identification': {
+ owner: 'The design system and caller content',
+ verifiedBy:
+ 'Cross-page review of repeated breadcrumb destinations and labels',
+ reason:
+ 'Consistency is a property of repeated trails and destinations, not one isolated binding.',
+ },
+ '3.3.1-error-identification': {
+ owner: 'The composing form and page',
+ verifiedBy: 'Form-level error review',
+ reason: 'The breadcrumb pattern defines no validation error state.',
+ },
+ '3.3.2-labels-or-instructions': {
+ owner: 'The composing form and caller content',
+ verifiedBy: 'Form-level label and instruction review',
+ reason: 'A breadcrumb trail is not a form input.',
+ },
+ '4.1.2-name-role-value': {
+ owner: 'The link, button, and menu-button pattern owners',
+ verifiedBy: 'Their contracts plus BreadcrumbItem-local state tests',
+ reason:
+ 'This contract encodes the navigation landmark and current-page state. Role, name, value, and state inside each interactive item remain with its own pattern.',
+ coversRemainderOnly: true,
+ },
+ '4.1.3-status-messages': {
+ owner: 'The caller and status-message pattern',
+ verifiedBy:
+ 'Status-message tests and AST-009 when spoken timing is claimed',
+ reason:
+ 'Rendering or following a breadcrumb is not itself a status message.',
+ },
+ 'apg-interaction': {
+ owner: 'Current Breadcrumbs and BreadcrumbItem product authority',
+ verifiedBy:
+ 'Required WCAG semantics here plus separate link and menu-button contracts',
+ reason:
+ 'No current Astryx record adopts the APG Breadcrumb page as an additional required interaction gate; its structure is covered here only where WCAG directly requires the outcome.',
+ },
+ 'forced-colors': {
+ owner: 'Breadcrumbs, BreadcrumbItem, and the active theme',
+ verifiedBy: 'Rendered forced-colors review',
+ reason: 'Semantic exposure does not prove forced-colors paint.',
+ },
+ 'reduced-motion': {
+ owner: 'BreadcrumbItem menu and overlay owners',
+ verifiedBy: 'Component motion tests and rendered review',
+ reason:
+ 'The trail semantics add no motion; menu motion remains separately owned.',
+ },
+ 'at-facing-strings': {
+ owner: 'Breadcrumbs localization and caller-provided item labels',
+ verifiedBy:
+ 'Catalog checks and localized component tests; AST-009 for speech claims',
+ reason:
+ 'The contract verifies a deterministic landmark name without claiming spoken wording, order, or timing.',
+ },
+ },
+ });
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx b/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx
index 507ccec126..c4f56180d6 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx
@@ -99,18 +99,6 @@ describe('Breadcrumbs', () => {
expect(separators[1].textContent).toBe('›');
});
- it('separators are aria-hidden', () => {
- const {container} = render(
- <Breadcrumbs>
- <BreadcrumbItem href="/">Home</BreadcrumbItem>
- <BreadcrumbItem isCurrent>Page</BreadcrumbItem>
- </Breadcrumbs>,
- );
- const separators = container.querySelectorAll('span[aria-hidden="true"]');
- expect(separators.length).toBeGreaterThan(0);
- expect(separators[0]).toHaveAttribute('aria-hidden', 'true');
- });
-
it('forwards ref to the nav element', () => {
const ref = {current: null as HTMLElement | null};
render(
diff --git a/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.chromium.spec.ts b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..21f48c0180
--- /dev/null
+++ b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.chromium.spec.ts
@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Real-browser and accessibility-tree binding evidence for Breadcrumbs. */
+
+import {
+ expect,
+ test,
+ type CDPSession,
+ type Locator,
+ type Page,
+} from '@playwright/test';
+import {
+ BREADCRUMB_PATTERN,
+ blockingResults,
+ checkAccessibilitySpec,
+ formatFailures,
+ neverExercised,
+ summarize,
+ 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 {
+ BREADCRUMB_A11Y_STATES,
+ type BreadcrumbA11yRow,
+} from './Breadcrumbs.a11y.states';
+
+const SUBJECT_SELECTOR = '[data-a11y-breadcrumb]';
+const SEPARATOR_SELECTOR = 'li > span:first-child';
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => storybook?.close());
+
+function storyUrl(id: string): string {
+ return `${storybook.origin}/iframe.html?id=${id}&viewMode=story`;
+}
+
+async function relatedFor(
+ page: Page,
+ state: BreadcrumbA11yRow,
+): Promise<Record<string, Locator>> {
+ const subject = page.locator(SUBJECT_SELECTOR);
+ const list = subject.locator('ol');
+ const related: Record<string, Locator> = {list};
+ const current = list.locator('[aria-current="page"]');
+ if ((await current.count()) > 0) {
+ related.current = current;
+ }
+ const separators = list.locator(SEPARATOR_SELECTOR);
+ for (let index = 0; index < state.facts.separatorCount; index += 1) {
+ related[`separator-${index}`] = separators.nth(index);
+ }
+ return related;
+}
+
+async function runState(
+ page: Page,
+ cdp: CDPSession,
+ state: BreadcrumbA11yRow,
+): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: BREADCRUMB_PATTERN,
+ binding: 'Breadcrumbs',
+ state: state.id,
+ facts: state.facts,
+ mount: async () => {
+ await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+ await holdMotionStill(page);
+ const subject = page.locator(SUBJECT_SELECTOR);
+ await subject.waitFor({state: 'attached'});
+ if (state.facts.currentPage) {
+ await subject.locator('[aria-current="page"]').waitFor({
+ state: 'attached',
+ });
+ }
+ return createChromiumHarness({
+ page,
+ cdp,
+ subject,
+ related: await relatedFor(page, state),
+ });
+ },
+ });
+}
+
+test('every Breadcrumb expectation is exercised by at least one state', async ({
+ page,
+}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const results: BindingResult[] = [];
+ for (const state of BREADCRUMB_A11Y_STATES) {
+ results.push(await runState(page, cdp, state));
+ }
+ expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of BREADCRUMB_A11Y_STATES) {
+ test(`Breadcrumbs [${state.id}] — ${state.summary}`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const report = summarize(BREADCRUMB_PATTERN, [result]);
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ expect(report.unrunLayers).toEqual([]);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+}
diff --git a/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.renders.tsx b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.renders.tsx
new file mode 100644
index 0000000000..42548d4e84
--- /dev/null
+++ b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.renders.tsx
@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/** Stable Breadcrumbs renders shared by jsdom, Storybook, and Chromium. */
+
+import type {ReactElement} from 'react';
+import {Breadcrumbs} from '../Breadcrumbs';
+import {BreadcrumbItem} from '../BreadcrumbItem';
+import type {BreadcrumbA11yRow} from './Breadcrumbs.a11y.states';
+
+export const BREADCRUMB_A11Y_RENDERS: Readonly<
+ Record<BreadcrumbA11yRow['id'], () => ReactElement>
+> = {
+ 'explicit-current-default': () => (
+ <Breadcrumbs data-a11y-breadcrumb>
+ <BreadcrumbItem href="/">Home</BreadcrumbItem>
+ <BreadcrumbItem href="/projects">Projects</BreadcrumbItem>
+ <BreadcrumbItem isCurrent>Current page</BreadcrumbItem>
+ </Breadcrumbs>
+ ),
+ 'auto-current-custom-label-rtl': () => (
+ <div dir="rtl">
+ <Breadcrumbs
+ data-a11y-breadcrumb
+ label="Project location"
+ separator="›"
+ variant="supporting">
+ <BreadcrumbItem href="/">Home</BreadcrumbItem>
+ <BreadcrumbItem href="/projects">Projects</BreadcrumbItem>
+ <BreadcrumbItem href="/projects/current">Current page</BreadcrumbItem>
+ </Breadcrumbs>
+ </div>
+ ),
+ 'no-current-opt-out': () => (
+ <Breadcrumbs data-a11y-breadcrumb>
+ <BreadcrumbItem href="/" isCurrent={false}>
+ Home
+ </BreadcrumbItem>
+ <BreadcrumbItem href="/archive" isCurrent={false}>
+ Archive
+ </BreadcrumbItem>
+ </Breadcrumbs>
+ ),
+};
diff --git a/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.states.ts b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.states.ts
new file mode 100644
index 0000000000..1e075ef987
--- /dev/null
+++ b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.states.ts
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** AST-021 state inventory for the Breadcrumbs semantic binding. */
+
+import type {BreadcrumbStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface BreadcrumbA11yState {
+ readonly id:
+ | 'explicit-current-default'
+ | 'auto-current-custom-label-rtl'
+ | 'no-current-opt-out';
+ readonly summary: string;
+ readonly facts: BreadcrumbStateFacts;
+ readonly storyId: string;
+}
+
+export type BreadcrumbA11yRow = (typeof BREADCRUMB_A11Y_STATES)[number];
+
+const story = (id: string) => `a11y-breadcrumb-pattern--${id}`;
+
+export const BREADCRUMB_A11Y_STATES = [
+ {
+ id: 'explicit-current-default',
+ summary: 'the default landmark with an explicitly current final page',
+ facts: {
+ landmarkLabel: 'Breadcrumb',
+ currentPage: true,
+ separatorCount: 3,
+ },
+ storyId: story('explicit-current-default'),
+ },
+ {
+ id: 'auto-current-custom-label-rtl',
+ summary:
+ 'a custom-named supporting trail whose final destination is auto-current under RTL',
+ facts: {
+ landmarkLabel: 'Project location',
+ currentPage: true,
+ separatorCount: 3,
+ },
+ storyId: story('auto-current-custom-label-rtl'),
+ },
+ {
+ id: 'no-current-opt-out',
+ summary: 'a trail whose items explicitly opt out of current-page state',
+ facts: {
+ landmarkLabel: 'Breadcrumb',
+ currentPage: false,
+ separatorCount: 2,
+ },
+ storyId: story('no-current-opt-out'),
+ },
+] as const satisfies ReadonlyArray<BreadcrumbA11yState>;
+
+export const BREADCRUMB_A11Y_EXCLUSIONS = [
+ {
+ owner: 'Link pattern and BreadcrumbItem destination tests',
+ reason:
+ 'Destination role, purpose, navigation, custom-router handoff, keyboard access, and pointer behavior remain with the link owner.',
+ },
+ {
+ owner: 'Button and Menu Button patterns',
+ reason:
+ 'Action-only and sibling-menu BreadcrumbItem branches are separate role-bearing parts with their own state and interaction contracts.',
+ },
+ {
+ owner: 'BreadcrumbItem API tests',
+ reason:
+ 'Explicit true, explicit false, omitted auto-current selection, conflicting prop precedence, callbacks, and rendered branch choices remain component-specific.',
+ },
+ {
+ owner: 'Breadcrumbs visual, RTL, and theme evidence',
+ reason:
+ 'Variant typography, separator glyph choice and mirroring, current-page emphasis, focus paint, contrast, and target geometry require their existing component and rendered checks.',
+ },
+ {
+ owner: 'AST-009',
+ reason:
+ 'This binding claims DOM and browser accessibility-tree exposure, not speech, braille, announcement timing, or virtual-cursor behavior.',
+ },
+] as const;
diff --git a/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.test.tsx b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.test.tsx
new file mode 100644
index 0000000000..cdc3ffbe52
--- /dev/null
+++ b/packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.test.tsx
@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/** Fast DOM binding for Breadcrumbs against the shared Breadcrumb contract. */
+
+import {cleanup, render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+ BREADCRUMB_PATTERN,
+ checkAccessibilitySpec,
+ createJsdomHarness,
+ expectAccessibilitySpec,
+ summarize,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {BREADCRUMB_A11Y_RENDERS} from './Breadcrumbs.a11y.renders';
+import {
+ BREADCRUMB_A11Y_EXCLUSIONS,
+ BREADCRUMB_A11Y_STATES,
+ type BreadcrumbA11yRow,
+} from './Breadcrumbs.a11y.states';
+
+const SUBJECT_SELECTOR = '[data-a11y-breadcrumb]';
+const SEPARATOR_SELECTOR = 'li > span:first-child';
+
+function subjectFor(): HTMLElement {
+ const subject = document.querySelector(SUBJECT_SELECTOR);
+ if (!(subject instanceof HTMLElement)) {
+ throw new Error('binding did not render one breadcrumb landmark');
+ }
+ return subject;
+}
+
+function relatedFor(state: BreadcrumbA11yRow): Record<string, Element> {
+ const subject = subjectFor();
+ const list = subject.querySelector('ol');
+ if (list == null) {
+ throw new Error(`Breadcrumbs state "${state.id}" has no ordered list`);
+ }
+ const related: Record<string, Element> = {list};
+ const current = list.querySelector('[aria-current="page"]');
+ if (current != null) {
+ related.current = current;
+ }
+ const separators = list.querySelectorAll(SEPARATOR_SELECTOR);
+ separators.forEach((separator, index) => {
+ related[`separator-${index}`] = separator;
+ });
+ return related;
+}
+
+async function checkState(state: BreadcrumbA11yRow): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: BREADCRUMB_PATTERN,
+ binding: 'Breadcrumbs',
+ state: state.id,
+ facts: state.facts,
+ mount: async () => {
+ render(BREADCRUMB_A11Y_RENDERS[state.id]());
+ return createJsdomHarness({
+ subject: subjectFor(),
+ related: relatedFor(state),
+ });
+ },
+ unmount: cleanup,
+ });
+}
+
+describe('the shared Breadcrumb pattern, jsdom lane', () => {
+ it.each(
+ BREADCRUMB_A11Y_STATES.map(
+ state => [`Breadcrumbs [${state.id}]`, state.summary, state] as const,
+ ),
+ )('%s — %s', async (_id, _summary, state) => {
+ await expectAccessibilitySpec({
+ spec: BREADCRUMB_PATTERN,
+ binding: 'Breadcrumbs',
+ state: state.id,
+ facts: state.facts,
+ render: () => {
+ render(BREADCRUMB_A11Y_RENDERS[state.id]());
+ },
+ subject: subjectFor,
+ related: () => relatedFor(state),
+ cleanup,
+ });
+ });
+
+ it('runs DOM expectations and reports accessibility-tree outcomes as unrun', async () => {
+ const results: BindingResult[] = [];
+ for (const state of BREADCRUMB_A11Y_STATES) {
+ results.push(await checkState(state));
+ }
+ const report = summarize(BREADCRUMB_PATTERN, results);
+ expect(report.counts.pass).toBeGreaterThan(0);
+ expect(report.unrunLayers).toEqual(['accessibility-tree']);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+});
+
+describe('the Breadcrumbs binding inventory', () => {
+ it('names a distinct checked-in story for every state', () => {
+ const ids = BREADCRUMB_A11Y_STATES.map(state => state.storyId);
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+
+ it('records every adjacent exclusion with an owner and reason', () => {
+ expect(
+ BREADCRUMB_A11Y_EXCLUSIONS.every(row => row.owner && row.reason),
+ ).toBe(true);
+ });
+
+ it('matches the declared separator and current-page inventory', () => {
+ for (const state of BREADCRUMB_A11Y_STATES) {
+ render(BREADCRUMB_A11Y_RENDERS[state.id]());
+ const related = relatedFor(state);
+ expect(
+ Object.keys(related).filter(key => key.startsWith('separator-')),
+ state.id,
+ ).toHaveLength(state.facts.separatorCount);
+ expect('current' in related, state.id).toBe(state.facts.currentPage);
+ cleanup();
+ }
+ });
+});