Writing Accessibility Acceptance Criteria for Data Grids

“Must be accessible” is not an acceptance criterion. It cannot be tested, it means different things to different people, and it is usually left until the end of a sprint when there is no time left. Data grid stories are where vague criteria hurt most, because grids combine many interaction patterns, each with specific keyboard, announcement and visual requirements. Writing those requirements as concrete, testable criteria — in the same Given/When/Then style as functional criteria — moves accessibility into the definition of done.

This guide belongs to accessibility governance for data products.

Spec reference

Acceptance criteria translate WCAG success criteria into observable behaviour. The most commonly needed for grid stories:

  • 2.1.1 Keyboard, 2.4.3 Focus Order, 2.4.7 Focus Visible — keyboard criteria.
  • 1.3.1 Info and Relationships, 4.1.2 Name, Role, Value — structure and naming.
  • 4.1.3 Status Messages — announcement criteria.
  • 1.4.1, 1.4.3, 1.4.11 — colour and contrast.
  • 2.5.7, 2.5.8 — dragging and target size (WCAG 2.2).

Each criterion should name the success criterion it supports so testers know why it exists.

From story to testable criteria Chain: a user story adds column sorting; list the interactions; write keyboard, announcement and visual criteria; map them to WCAG; choose a test method for each. From story to testable criteriaStory"Sort invoices byany column"Interactionsactivate header;repeat to reverseCriteriakeyboard,announcement, visualWCAG2.1.1, 4.1.2, 4.1.3,2.4.7list interactionswrite criteriamapTest methodsPlaywright, axe,NVDA check
Each criterion is observable and has an owner for testing.

When to use — and when not to

Write accessibility criteria for every story that adds or changes interaction or visual presentation in a grid. Reuse a library of criteria for common patterns (sorting, selection, editing) and adapt them.

Do not paste the full WCAG list into every story; criteria should cover what the story changes. Do not write criteria that only an accessibility specialist can verify; most should be checkable by any tester with a keyboard and a screen reader.

The misapplication: one criterion reading “Meets WCAG 2.2 AA”. Nobody can test it within a story, so it is always marked done.

Vague criteria versus testable criteria Comparison: vague criteria cannot be tested and are ignored; testable criteria name the key, the expected result and the announcement. Vague criteria versus testable criteria✗ "Sorting is accessible""Works with screen readers""Good contrast""Keyboard friendly"Checked at the end, if at all✓ "Given focus on the Amount header, whenEnter is pressed, then rows sortascending""…then NVDA announces 'Amount, sortedascending' and 'Sorted by Amount, ascending'""The sort icon reaches 3:1 against the headerbackground in both themes""Tab moves from the toolbar to the grid in onestop"Checked like any functional criterion

Annotated code example

Acceptance criteria for a sorting story, written in Gherkin so they can drive automated tests:

Feature: Sort invoices by column
  # SC 2.1.1 Keyboard
  Scenario: Sort with the keyboard
    Given the invoices grid has focus on the "Amount" column header
    When I press Enter
    Then the rows are sorted by Amount ascending
    And the "Amount" header has aria-sort="ascending"                     # SC 4.1.2

  # SC 4.1.3 Status Messages
  Scenario: Sort is announced
    Given a screen reader is running
    When I sort by Amount
    Then a status message "Sorted by Amount, ascending" is present once

  # SC 2.4.3 Focus Order
  Scenario: Focus stays on the header after sorting
    When I sort by Amount
    Then focus remains on the "Amount" header

  # SC 1.4.11 / 1.4.1
  Scenario: Sort direction is visible without colour
    Then the sort icon shape indicates direction and has 3:1 contrast in light and dark themes
// Playwright step definitions for two of the scenarios
await page.getByRole('columnheader', { name: 'Amount' }).getByRole('button').press('Enter');
await expect(page.getByRole('columnheader', { name: /Amount/ })).toHaveAttribute('aria-sort', 'ascending');
await expect(page.getByRole('status')).toHaveText('Sorted by Amount, ascending');

Keyboard & AT behaviour

A criteria library for grid stories, by pattern:

Pattern Keyboard criterion Announcement criterion Visual criterion
Sorting Enter/Space on header sorts “Sorted by X, direction” Direction icon by shape, 3:1
Row selection Space toggles; Shift+Space ranges “Selected, N of M selected” Selection not colour-only
Inline editing Enter/F2 edits; Escape cancels Errors announced; value confirmed Edit state visible
Filtering Filter reachable; Tab order logical “Showing N of M rows” Active filters visible as text
Pagination Next/previous reachable “Page N of M” Current page not colour-only
Who verifies each kind of criterion Matrix of criterion types — keyboard, structure and naming, announcements, contrast, target size — against automated tests, developer checks and QA with a screen reader. Who verifies each kind of criterionAutomated testDeveloper checkQA with screen readerKeyboardPlaywrightYesSpot checkStructure and namingaxe, role queriesYesSpot checkAnnouncementsStatus text presentPartialRequiredContrastToken testsYesNot neededTarget sizeMeasurement testYesNot needed
Most criteria can be automated; announcements need a human spot check.

Integration context

Criteria come from the patterns documented across this site — for sorting, see sortable & filterable data grids; for selection, bulk selection & batch actions. Automated checks map to accessibility testing recipes. When criteria fail in testing, report them as in writing actionable accessibility bug reports.

Gotchas

Screen reader wording. Do not require exact screen reader speech (“NVDA says exactly…”) — readers vary. Require the information: header name and sort direction are announced.

Story size. Accessibility criteria can make a story look larger. That is accurate; the work was always there.

Design handoff. Visual criteria (focus, contrast, target size) should be checked in design review before development, not only in QA.

Common mistakes

  • “Must be accessible” as the only criterion.
  • Criteria that require exact screen reader phrasing.
  • Copying all of WCAG into every story.
  • Criteria with no test method.

Framework notes

Criteria are framework-agnostic, but test methods are not: map keyboard and structure criteria to Testing Library role queries in unit tests (React, Vue, Angular all supported) and to Playwright for end-to-end behaviour. Keep step definitions in a shared package so stories across teams reuse them.

Worked example

A team’s grid stories had “accessible” as a checkbox in the definition of done. In practice, accessibility bugs were found after release. The team built a criteria library of 40 statements covering sorting, filtering, selection, editing, pagination and row actions, each with a WCAG reference and test method. Product owners now pick the relevant ones during refinement; QA tests them alongside functional criteria. Post-release accessibility bugs on grid features dropped by more than half within two quarters.

Testing checklist

Design system notes

Publish acceptance criteria next to each component in the design system, so stories using a component can copy its criteria. Components with known exceptions should document them alongside.

FAQ

Who writes accessibility acceptance criteria?

Product owners with help from an accessibility specialist at first; with a criteria library, teams can do it themselves.

Should every story have accessibility criteria?

Every story that changes interaction or presentation. Back-end-only stories usually do not.

How detailed should criteria be?

Specific enough to test: key, expected result, information announced, visual property and threshold.

Do criteria replace audits?

No. They prevent most regressions; periodic audits find what criteria did not anticipate.

Can criteria be automated?

Many can: keyboard, structure, status text presence, contrast and target size. Announcement quality needs a human spot check.

How do we handle legacy features without criteria?

Write criteria when you next change the feature, and track known gaps in an accessibility backlog.

How do criteria handle different screen readers?

Name the information that must be conveyed and test with the product’s supported combinations. Record known reader differences in the criteria library so testers do not file them as bugs.

← Back to Accessibility Governance for Data Products