Components: Accessibility conformance suite

Summary

Define and enforce a data-driven, package-level accessibility conformance suite for
packages/agentic/components that asserts static native accessibility output - role,
accessible name, state, disabled semantics, and any required-prop validation - uniformly
across every exported higher-order component. The suite runs inside the package's existing
Jest pass (macOS preset) with @testing-library/react-native, produces a machine-readable
per-component conformance record, and is wired into the package's declared test script so
it gates the coverage contract from
component-test-strategy.md.

Observed. Accessibility assertions already exist in most per-component test files, but
their depth, shape, and completeness vary. Seven of eighteen components do not assert the
static role in their default case. Three components assert partial state (for example,
checked without disabled). Two components warn on missing required props but the
warning assertion is isolated in a single test case with no cross-component pattern. No file
today asserts that every exported component satisfies a shared minimum accessibility
contract; the coverage is individual, not systemic.

This task defines a shared conformance contract, populates a registry of per-component
applicability and exceptions, closes the gaps in the existing per-component tests, and
adds a structural gate that prevents a newly generated component from shipping without
declaring its conformance entry. It does not build the real-platform screen-reader pipeline
(that is
research/infrastructure/tasks/storybook-e2e.md)
and does not add manual screen-reader validation steps.

Goal

Deliver a shared, data-driven conformance suite that asserts static native accessibility
output over every exported higher-order component in packages/agentic/components, backed
by an applicability registry that makes conformance decisions explicit and machine-checkable,
and gates new components through an onboarding requirement before they join the export
surface.

Stage

Stage 1 (beta foundations). The readiness model
(readiness-model.md) requires asserted accessibility semantics
as evidence for the preview tier. Without a uniform contract those assertions are
self-reported and unverifiable at scale.

Why it matters

Observed. The preview level in
readiness-model.md requires "asserted accessibility
semantics" as one of its four evidence axes, alongside runtime coverage, type test, and
spec provenance. That requirement today has no uniform definition: "asserted" means
whatever the component author happened to write.

Observed. Existing test coverage across the eighteen components shows three distinct
accessibility patterns:

• Full contract: checkbox, radio, switch, tab assert role, label, and complete
  accessibilityState in one default case, then drive state change assertions from there.
• Partial contract: button, list-item, listbox-item, tag assert accessibilityState
  but not role in the default case; role is either absent or implicit in a getByRole query.
• Thin contract: avatar, badge, divider, skeleton assert an accessible name but no
  state because their role carries no stateful axis. progress-bar and spinner assert role
  and state but omit the base disabled assertion. accordion and card assert role and
  expanded or selected state in isolation without a unified default case.
• Primitives: icon asserts accessibilityRole and role-conditional behavior.
  checkbox-indicator and focus-visual assert accessible: false via
  hiddenFromAccessibilityProps. compound-item-layout and layout-stable-text carry no
  direct accessibility assertions.

Inferred. Because the gaps are structural rather than per-component, adding more
per-component assertions without a shared contract would leave the next generated component
in the same position: the author decides what to assert, and the result is only as good as
the author's awareness of the contract.

Inferred. A registry-driven suite closes this loop permanently: each new component
declares its conformance entry before its exports are wired, the suite runs that entry
against the live output, and the gate fails if the entry is missing or if the live output
does not match the declared contract.

Observed current state

Existing accessibility assertions by component

Observed. All counts from packages/agentic/components/src on
main as retrieved. Test files are the per-component .test.tsx files;
no shared conformance runner exists today.

Component	Role asserted	Name asserted	Base state asserted	Disabled asserted	Required-prop warning
accordion	button (header)	accessibilityLabel	{ expanded: false }	no	no
avatar	image via getByRole	accessibilityLabel	none (decorative)	n/a	no
badge	image via getByRole	accessibilityLabel	none (decorative)	n/a	yes (icon-only)
button	implicit in getByRole	accessibilityLabel	{ disabled: false }	yes	yes (icon-only)
card	button or group	accessibilityLabel	{ disabled: false, selected: false }	no	no
checkbox	checkbox explicit	accessibilityLabel	{ checked: false, disabled: false }	yes	no
divider	separator via getByRole	accessibilityLabel	none (structural)	n/a	no
input	textbox via getByRole	none	{ disabled: false, invalid: undefined, readOnly: false }	yes	no
list-item	implicit in getByRole	none	{ disabled: false, selected: false }	yes	no
listbox-item	implicit in getByRole	none	{ disabled: false }	no	no
menu-item	menuitem explicit	none	none in default case	no	no
progress-bar	progressbar explicit	none	{}	n/a	no
radio	radio via getByRole	accessibilityLabel	{ checked: false, disabled: false }	yes	no
skeleton	none (decorative)	none	accessible: false	n/a	no
spinner	progressbar via getByRole	accessibilityLabel	{ busy: true }	n/a	yes (label required)
switch	switch via getByRole	accessibilityLabel	{ checked: false, disabled: false }	yes	no
tab	tab explicit	accessibilityLabel	{ disabled: false, selected: false }	yes	no
tag	implicit in getByRole	accessibilityLabel	{ disabled: false }	yes	yes (icon-only)

Observed. The shared accessibility helper at
src/common/accessibility.ts
exports hiddenFromAccessibilityProps (the three-property "remove from accessibility
tree" object) and hideSlotProps. These are consumed by decorative and structural
primitives but are not used as part of a conformance test.

Observed. No file in packages/agentic/components today imports from a shared
conformance runner or references a per-component conformance declaration. The
src/index.test.ts
export guard asserts that pipeline-stage symbols exist but does not touch accessibility
output.

Observed. Per-component spec/accessibility.md files exist for all 18 components.
They record the authoritative role, required attributes, disabled state contract, and
WCAG citation for each component. They are currently read by agents during authoring
but are not parsed or enforced by any automated check.

Testing infrastructure

Observed.
jest.config.cjs
extends @fluentui-react-native/scripts/jest-config with testTimeout: 10000 and
furn.jestPlatform: "macos". All tests in the package run under the macOS React Native
preset. There is no Windows or Win32 unit-test pass.

Observed. Runtime tests use @testing-library/react-native throughout. The pattern
of getByRole(<role>) followed by props.accessibilityState and props.accessibilityRole
assertions is already established in checkbox, radio, switch, tab, input,
progress-bar, spinner, badge, avatar, card, and accordion.

Observed. The on-device pipeline in
apps/storybook/windows-tests/storybook-smoke.test.cjs
asserts HasKeyboardFocus on eleven components but does not assert native accessibility
properties (role, state, label) through UI Automation. That pipeline is Windows-only,
uninvoked by any workflow, and owned by
storybook-e2e.md.

Scope

1. Define the shared accessibility conformance contract as a small set of assertion
   classes, each applicable to some subset of components, with explicit conditions:

   • Role class: the root element exposes the correct accessibilityRole value in
     its default render, queryable by getByRole.
   • Name class: a required accessible name is present when the component's
     spec/accessibility.md declares aria-label as required.
   • State class: accessibilityState contains exactly the keys declared in
     spec/accessibility.md for the default props, with none missing and no extra
     undeclared keys.
   • Disabled class: when disabled={true}, accessibilityState.disabled is
     true and the state keys match the disabled contract. Applies to every component
     whose use<Component>.ts accepts a disabled prop.
   • Decorative class: the root element sets accessible: false (or equivalent
     hiddenFromAccessibilityProps) when the component's spec/accessibility.md
     declares it decorative. Applies to skeleton and the non-interactive rendering
     of avatar and badge when accessibilityLabel is absent and the intent is
     decorative.
   • Required-prop warning class: a development-mode console.warn fires when a
     required accessible name prop is omitted, and the message matches the declared
     pattern. Applies to button (icon-only), badge (icon-only), tag (icon-only),
     and spinner (label required).

2. Create a conformance registry as a TypeScript or JSON file at
   src/conformance/accessibility-registry.ts (or .json) inside the package. Each
   entry records:

   • the component name and its root accessibilityRole;
   • the applicable assertion classes;
   • any explicit exceptions with a documented reason;
   • the default props required to produce a valid accessible render (e.g.,
     accessibilityLabel, label, content);
   • the expected accessibilityState keys and their default values.

3. Write a conformance runner at src/conformance/accessibility-conformance.test.ts
   that iterates the registry, renders each component with its declared default
   accessible props, and asserts every applicable class. Each assertion should be
   individually named so failures identify the component and the class.

4. Close the gaps in the per-component test files that the conformance runner does not
   cover because they require component-specific setup (state transitions, required-prop
   warnings, controlled props):

   • Add role assertions to the default case of button, list-item, listbox-item,
     and tag.
   • Add complete base accessibilityState assertions to accordion, card,
     menu-item, and listbox-item default cases.
   • Add disabled assertions to card, accordion, listbox-item, and menu-item.
   • Add accessibilityValue assertions to progress-bar for the indeterminate path
     (accessibilityValue must be undefined when value is absent).
   • Add the accessibilityLabelledBy assertion for progress-bar to a case that
     verifies the ref-based link is established rather than merely defined.

5. Add an onboarding gate: a structural check (usable in the package's lint or test
   script) that fails when a symbol exported from src/index.ts has no corresponding
   entry in the conformance registry. This prevents a new component from joining the
   export surface without a declared conformance entry.

6. Update
   packages/agentic/components/src/components/AGENTS.md
   to require that a new component's authoring checklist includes adding a conformance
   registry entry before wiring exports.

Out of scope

• Real-platform screen-reader validation. VoiceOver on macOS and Narrator on Windows
  announce role, name, and state at the OS level. That validation is the responsibility
  of research/infrastructure/tasks/storybook-e2e.md
  and cannot be automated inside a Jest-only pass.
• Keyboard and focus behavior. Focus assertions (HasKeyboardFocus, tab order,
  arrow-key navigation) are on-device concerns. The conformance suite asserts static
  native accessibility props only.
• WCAG contrast ratios. Token color validation is a theming concern tracked in
  research/theming/README.md.
• Coverage for packages/components, packages/experimental, and packages/native.
  Those packages have separate test infrastructure and are not in scope.
• Primitives without a role contract. compound-item-layout and layout-stable-text
  are structural and have no native accessibility role. They are covered by the decorative
  class only if the owning spec/ declares them as such. Primitives without a SPEC.md
  get a recorded exemption entry in the registry, not a generated assertion.
• Adding new component behavior to make existing components easier to assert. If an
  assertion requires a behavior change, that behavior change is its own item.

Applicability and exception registry

Inferred. The following table is the initial applicability proposal, derived from the
observed test patterns and per-component spec/accessibility.md files. Each entry should
be ratified by the owner and encoded in the machine-readable registry file.

Component	Role class	Name class	State class	Disabled class	Decorative class	Warn class
accordion	yes	conditional	yes	no	no	no
avatar	yes	yes	no	n/a	conditional (no label)	no
badge	yes	yes	no	n/a	no	yes (icon-only)
button	yes	conditional	yes	yes	no	yes (icon-only)
card	yes	yes	yes	yes	no	no
checkbox	yes	yes	yes	yes	no	no
divider	yes	conditional	no	n/a	no	no
input	yes	no	yes	yes	no	no
list-item	yes	no	yes	yes	no	no
listbox-item	yes	no	yes	yes	no	no
menu-item	yes	no	yes	yes	no	no
progress-bar	yes	no	yes	n/a	no	no
radio	yes	yes	yes	yes	no	no
skeleton	no	no	no	n/a	yes	no
spinner	yes	yes	yes	n/a	no	yes (required)
switch	yes	yes	yes	yes	no	no
tab	yes	conditional	yes	yes	no	no
tag	yes	conditional	yes	yes	no	yes (icon-only)

Exception notes:

• accordion disabled: Observed. accordion.test.tsx has no disabled prop test
  and accordion.types.ts does not declare a disabled prop. Exception: "component does
  not expose disabled"; if a disabled prop is added in future, the disabled class
  becomes required.
• avatar name: Observed. accessibilityLabel is required on Avatar per
  spec/accessibility.md only when the avatar is meaningfully identified for a screen
  reader. When decorative (no label supplied), accessible: false applies. The registry
  entry should declare both paths.
• input name: Observed. input.test.tsx does not assert an accessible name.
  The input spec defers name sourcing to the field container (aria-labelledby from
  a Label). A standalone Input has no required accessibilityLabel; the name class
  does not apply.
• skeleton role: Observed. skeleton.test.tsx asserts accessible: false. A
  skeleton is decorative by design; no role class applies, and the decorative class is
  the operative assertion.
• progress-bar disabled: ProgressBar has no disabled prop in its type signature.
  Exception: "component does not expose disabled".
• spinner disabled: Spinner has no disabled prop. Exception: "component does not
  expose disabled".

Deliverables

1. A conformance contract document at
   packages/agentic/components/src/conformance/CONFORMANCE.md defining the six assertion
   classes, the applicability conditions, and the exception format.
2. A machine-readable conformance registry at
   packages/agentic/components/src/conformance/accessibility-registry.ts (or .json)
   covering all 18 components and 5 primitives, with each exception documented.
3. A conformance runner at
   packages/agentic/components/src/conformance/accessibility-conformance.test.ts
   that iterates the registry and asserts every applicable class, named per component and
   class so failures are actionable.
4. Closed per-component gaps listed in Scope item 4: role assertions added to button,
   list-item, listbox-item, and tag; complete state assertions added to accordion,
   card, menu-item, and listbox-item; disabled assertions added to card,
   accordion, listbox-item, and menu-item.
5. An onboarding gate (structural check) that fails when a higher-order component export
   exists in src/index.ts with no conformance registry entry, wired into the package's
   declared test or lint script.
6. Updated
   packages/agentic/components/src/components/AGENTS.md
   requiring a conformance entry before export wiring as part of the component authoring
   checklist.

Acceptance criteria

• A conformance contract document exists at the stated path and defines the six
  assertion classes with applicability conditions.
• The conformance registry covers all 18 higher-order components, with every
  exception recorded and a reason given.
• The conformance runner iterates the registry, renders each component, and asserts
  every applicable class. Every assertion is individually named.
• yarn workspace @fluentui-react-native/components test runs the conformance
  runner as part of the declared test pass and fails if any assertion fails.
• The conformance runner produces a structured per-component summary (pass/fail per
  class) that can be consumed by the readiness model to satisfy the "asserted
  accessibility semantics" evidence axis.
• Every higher-order component in src/index.ts has a registry entry; the onboarding
  gate fails when one is missing.
• Per-component gap closures in Scope item 4 are applied and the affected test files
  pass yarn workspace @fluentui-react-native/components test.
• packages/agentic/components/src/components/AGENTS.md includes a conformance
  entry requirement in the authoring checklist.
• The suite does not replace the per-component test files; it adds a shared layer
  above them. Per-component files retain their interaction, state-transition, and
  component-specific assertions.
• The conformance runner is not the authoritative accessibility gate for on-device
  real-platform behavior; the task document and the conformance contract record that
  explicitly.

Dependencies and ordering

• Depends on component-test-strategy.md: the
  coverage contract must exist before the conformance suite can declare itself an
  extension of it. The conformance runner should be adopted as an artifact in the
  coverage contract.
• Feeds readiness-model.md: the per-component conformance
  summary is the machine-readable evidence the readiness model requires for the
  "asserted accessibility semantics" axis at the preview tier. Completing this task
  removes the self-reported character of that evidence axis.
• Independent of focus-zone.md,
  spec-ingestion-and-generation.md, and the
  missing-component tasks. The registry simply adds an entry for each new component.
• Independent of the Infrastructure workstream's on-device pipeline
  (storybook-e2e.md). The conformance
  suite is a static Jest check; it does not consume or replace real-platform automation.

Risks and open decisions

1. Registry format. A .ts registry imports directly from the component modules,
   giving type safety and IDE discoverability but adding a build-time dependency cycle
   risk if the registry is imported by the components themselves. A .json registry
   avoids cycles but requires a separate schema file for validation. Open decision:
   whether to use TypeScript with a structural import guard or a standalone JSON manifest.

2. Conformance runner location. A dedicated src/conformance/ directory isolates
   the suite from per-component tests. An alternative is a single file at src/ root
   alongside index.test.ts. Open decision: whether dedicated directory or root file
   is preferred.

3. Handling components with multiple root roles. card can render as role="button"
   (interactive) or role="group" (display). menu-item can render as menuitem,
   menuitemcheckbox, or menuitemradio. The registry entry must declare the variant
   map. Open decision: whether the conformance runner renders one variant per
   applicable class or multiple registry entries per role variant.

4. Primitives without a role contract. compound-item-layout and
   layout-stable-text are implementation helpers with no upstream catalog entry and no
   SPEC.md. Their registry entries can be stubs with only decorative or no-op entries.
   Open decision: whether primitives get minimal registry stubs or are excluded from
   the runner scope entirely, with the decision recorded in the registry.

5. Interaction with the coverage contract. The conformance runner is an additional
   artifact alongside per-component tests, not a replacement. The coverage contract in
   component-test-strategy.md must be updated to include
   the conformance runner as a required artifact. If that task is completed first, the
   contract update should be a deliverable here; if this task lands first, the conformance
   runner should be listed as a pending contract artifact.

Evidence and references

• packages/agentic/components/src/common/accessibility.ts
  • the shared hiddenFromAccessibilityProps and hideSlotProps helpers. The conformance
    registry should reference this module for the decorative class.
• packages/agentic/components/src/components/button/button.test.tsx
  • canonical accessibility pattern: getByRole, accessibilityState, accessibilityLabel,
    and console.warn assertions.
• packages/agentic/components/src/components/checkbox/checkbox.test.tsx
  and radio/radio.test.tsx
  • deepest existing contracts: role, label, full state tuple, disabled, and consumer
    passthrough in one file.
• packages/agentic/components/src/components/*/spec/accessibility.md
  • authoritative per-component ARIA role, required attributes, disabled contract, and
    WCAG citations. The registry entries should be derived from these files.
• packages/agentic/components/src/index.ts
  • the 175-line explicit export surface. The onboarding gate uses this file as its
    source of truth.
• packages/agentic/components/src/index.test.ts
  • the existing export guard; the onboarding check extends the same pattern.
• packages/agentic/components/jest.config.cjs
  • test execution environment; the conformance runner runs in the same pass.
• component-test-strategy.md - the coverage contract
  this suite extends.
• readiness-model.md - the consumer of the conformance summary.
• research/infrastructure/tasks/storybook-e2e.md
  • the real-platform accessibility pipeline this suite explicitly does not replace.

Sources retrieved 2026-08-21.

Start by reading the per-component spec/accessibility.md files, the existing component tests, src/common/accessibility.ts, jest.config.cjs, and src/index.test.ts. Run the existing package Jest pass to understand the macOS setup and current accessibility assertions. Done means every exported component has a declared registry entry, the shared suite verifies its applicable contract, and the test script gates missing declarations or mismatched output.