feat(aria): add notRecommended standards flag for needs-review by chutchins25 · Pull Request #5257 · dequelabs/axe-core

chutchins25 · 2026-07-23T16:04:05Z

Adds a reusable notRecommended: true standards flag for ARIA roles and attributes that surfaces as needs review. Mirrors the aria-no-deprecated-attr needs-review pattern from #5246 (now merged).

What & why

Per the discussion on #3341 (@WilcoFiers / Steven Lambert), axe should have a general, data-driven way to return needs review for ARIA that is valid but not recommended — rather than handling each case ad hoc.

This is additive and changes no existing behavior:

A notRecommended: true flag can be set on any role (ariaRoles) or attribute (ariaAttrs).
not-recommended-role (on the aria-allowed-role rule) returns needs-review when the element's resolved role is notRecommended.
not-recommended-attr (on the aria-allowed-attr rule) returns needs-review when the element uses a notRecommended attribute.
As with aria-deprecated-attr, a needs-review outcome yields to a sibling check's failure (e.g. an unallowed attribute still fails the rule).

Existing deprecated handling (aria-deprecated-attr, aria-deprecated-role) is untouched — deprecated and notRecommended remain distinct.

No real data yet

No role or attribute is flagged notRecommended today — this PR provides the reusable capability Steve asked for. The checks are therefore verified data-driven via axe.configure mocks (same approach as the deprecated-attr tests), not integration fixtures.

Tests

not-recommended-attr / not-recommended-role check units — mocked flag via axe.configure, single + multiple, negative case, open Shadow DOM case.
aria-allowed-attr / aria-allowed-role virtual-rules — mocked flag yields incomplete.
locales/_template.json gains exactly the two new check blocks; doc/rule-descriptions.md unchanged (no new rule); full check/commons/integration/virtual-rule suites green.

Closes #5247

Copilot

Pull request overview

This PR adds a standards-driven way to surface needs-review outcomes for ARIA roles/attributes flagged as “not recommended” (and also introduces a parallel deprecated attribute needs-review path) by wiring new checks into the existing aria-allowed-role and aria-allowed-attr rules.

Changes:

Add not-recommended-role / not-recommended-attr checks that return undefined (needs review) when standards data marks a role/attribute as notRecommended: true.
Add aria-no-deprecated-attr check and mark aria-grabbed / aria-dropeffect as deprecated: true in standards, producing needs-review for deprecated attributes under aria-allowed-attr.
Expand unit, virtual-rule, and integration fixtures to cover incomplete vs fail precedence and mocked standards via axe.configure.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/integration/virtual-rules/aria-allowed-role.js	Adds virtual-rule coverage for `notRecommended` roles producing `incomplete`.
test/integration/virtual-rules/aria-allowed-attr.js	Adds reset + coverage for deprecated and `notRecommended` attributes producing `incomplete`, plus precedence vs unallowed attrs.
test/integration/rules/aria-allowed-attr/passes.html	Removes deprecated attrs from the “passes” fixture set.
test/integration/rules/aria-allowed-attr/incomplete.json	Adds new incomplete selectors for deprecated attribute cases.
test/integration/rules/aria-allowed-attr/incomplete.html	Adds deprecated attribute fixtures expected to yield `incomplete`.
test/integration/rules/aria-allowed-attr/failures.json	Adds a new failing selector for deprecated + unallowed attribute precedence.
test/integration/rules/aria-allowed-attr/failures.html	Adds deprecated+unallowed fixture expected to fail (not incomplete).
test/checks/aria/not-recommended-role.js	Unit tests for role-based needs-review driven by `standards.ariaRoles[role].notRecommended`.
test/checks/aria/not-recommended-attr.js	Unit tests for attribute-based needs-review driven by `standards.ariaAttrs[attr].notRecommended`.
test/checks/aria/aria-no-deprecated-attr.js	Unit tests for deprecated-attribute needs-review, including a standards-driven mocked case.
locales/_template.json	Adds message templates for the new checks.
lib/standards/aria-attrs.js	Flags `aria-grabbed` and `aria-dropeffect` as deprecated in standards data.
lib/rules/aria-allowed-role.json	Wires `not-recommended-role` into `aria-allowed-role` rule evaluation.
lib/rules/aria-allowed-attr.json	Wires `aria-no-deprecated-attr` and `not-recommended-attr` into `aria-allowed-attr` rule evaluation.
lib/checks/aria/not-recommended-role.json	Declares the new `not-recommended-role` check metadata.
lib/checks/aria/not-recommended-role-evaluate.js	Implements needs-review behavior for not-recommended roles.
lib/checks/aria/not-recommended-attr.json	Declares the new `not-recommended-attr` check metadata.
lib/checks/aria/not-recommended-attr-evaluate.js	Implements needs-review behavior for not-recommended attributes.
lib/checks/aria/aria-no-deprecated-attr.json	Declares the new deprecated-attribute needs-review check metadata.
lib/checks/aria/aria-no-deprecated-attr-evaluate.js	Implements needs-review behavior for deprecated attributes via standards data.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add an additive notRecommended: true flag for ARIA roles and attributes, surfaced as needs-review (incomplete) via new not-recommended-role and not-recommended-attr checks on the aria-allowed-role and aria-allowed-attr rules. Existing deprecated handling is unchanged. No role or attribute is flagged notRecommended yet; this is reusable capability for future not-recommended-but-valid ARIA. Closes #5247

runVirtualRule has no teardown step, so the query cache (e.g. the memoized global aria attribute list) persisted across calls and could mask axe.configure() changes made before a call. Clear the cache at the start of each runVirtualRule.

chutchins25 · 2026-07-31T13:52:28Z

Heads up on the extra commit here (2a6fc32c) — flagging it since it's a small core change rather than part of the notRecommended feature.

The test_virtual_rules job was failing on the new should incomplete for a not recommended attribute test. The root cause is pre-existing and not specific to this feature: runVirtualRule has no teardown step, so axe's query cache persists across calls. getGlobalAriaAttrs() memoizes the global-attribute list, so once an earlier runVirtualRule populates it, a later axe.configure() that adds a global attr (the test's aria-fizz) isn't reflected — aria-allowed-attr then reports it as unallowed and we get a violation instead of an incomplete. It only surfaces in the Node/jsdom suite (many runVirtualRule calls in one process); it passes in the browser runner and in isolation, which is the analogous notRecommended role test already relies on.

The fix clears the cache at the start of runVirtualRule (verified: full node + browser virtual-rule suites pass). I kept it as its own commit in case you'd prefer it split into a dedicated fix PR — happy to do that.

straker · 2026-08-04T20:42:55Z

I'm not sure this is needed. We already have deprecated on aria-attrs to denote this, and currently there is not deprecated roles but if there were we'd also want to use deprecated. Is there a use case for using a valid attr or role that is not deprecated that we would want to call this out for?

Based on wilcos response to #5247 (comment), I think we should close this and the companion ticket.

WilcoFiers

I agree with Steve. This check looks for a property we never set, and so does nothing.

ARIA in HTML does have things it says are not recommended, but they are about limiting what roles / props you can use on specific HTML elements. There are no ARIA properties that are never recommended the way this PR implements it.

I'm open to have Axe-core report those not recommended prop things from ARIA in HTML, but I think that should be its own rule. Feel free to update the ticket with that. But this PR should be closed IMO. This is not in scope for 4.13 either.

chutchins25 · 2026-08-05T13:00:10Z

Closing per review. As @WilcoFiers and @straker noted, the notRecommended flag as implemented is effectively a no-op (nothing in the standards sets it), and this isn't in scope for 4.13. The "not-recommended roles/props from ARIA in HTML" idea would be better as its own rule — see #5247.

chutchins25 force-pushed the chut/3341-aria-deprecated-attr branch from 7085fc2 to b0bf114 Compare July 29, 2026 15:12

chutchins25 force-pushed the chut/5247-not-recommended-mechanism branch 2 times, most recently from b18f037 to 1d1f129 Compare July 29, 2026 16:14

chutchins25 force-pushed the chut/3341-aria-deprecated-attr branch from 1af5d3a to b0bf114 Compare July 29, 2026 16:42

chutchins25 force-pushed the chut/5247-not-recommended-mechanism branch from 1d1f129 to b18f037 Compare July 29, 2026 16:42

chutchins25 marked this pull request as ready for review July 29, 2026 17:43

chutchins25 requested a review from a team as a code owner July 29, 2026 17:43

chutchins25 marked this pull request as draft July 29, 2026 20:18

chutchins25 force-pushed the chut/5247-not-recommended-mechanism branch from 4ae26d7 to 7005c6b Compare July 30, 2026 17:17

Base automatically changed from chut/3341-aria-deprecated-attr to develop July 30, 2026 22:04

chutchins25 requested a review from Copilot July 31, 2026 12:27

Copilot started reviewing on behalf of chutchins25 July 31, 2026 12:28 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

Comment thread lib/checks/aria/not-recommended-role-evaluate.js Outdated

Comment thread lib/rules/aria-allowed-attr.json

chutchins25 force-pushed the chut/5247-not-recommended-mechanism branch from 7005c6b to 1e0710e Compare July 31, 2026 12:47

chutchins25 marked this pull request as ready for review July 31, 2026 12:49

chutchins25 requested a review from straker July 31, 2026 12:49

WilcoFiers requested changes Aug 5, 2026

View reviewed changes

chutchins25 closed this Aug 5, 2026

chutchins25 mentioned this pull request Aug 5, 2026

Add standards support to return needs-review for not-recommended-but-valid ARIA roles/attributes #5247

Closed

Navigation Menu

Uh oh!

feat(aria): add notRecommended standards flag for needs-review - #5257

feat(aria): add notRecommended standards flag for needs-review#5257
chutchins25 wants to merge 2 commits into
developfrom
chut/5247-not-recommended-mechanism

chutchins25 commented Jul 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

chutchins25 commented Jul 31, 2026

Uh oh!

straker commented Aug 4, 2026 •

edited

Loading

Uh oh!

WilcoFiers left a comment

Uh oh!

chutchins25 commented Aug 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

chutchins25 commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What & why

No real data yet

Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

chutchins25 commented Jul 31, 2026

Uh oh!

straker commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

WilcoFiers left a comment

Choose a reason for hiding this comment

Uh oh!

chutchins25 commented Aug 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

chutchins25 commented Jul 23, 2026 •

edited

Loading

straker commented Aug 4, 2026 •

edited

Loading