Expose implicit ARIA semantics (browser-defaults and ElementInternals)

[benbeaudry]

Description of bug or feature request

Accessibility testing frameworks currently have no way to query the ARIA semantics applied through ElementInternals within custom elements. This results in false positives and undetected issues across a growing ecosystem of web components that use ElementInternals to set accessibility roles and properties. Automated accessibility testing is typically performed by JavaScript libraries (e.g., axe-core) that run directly in the page context or in CI systems, and therefore must be able to query all author-provided accessibility information via standard DOM APIs.

This limitation has been raised in several issues, including aria#2656, aria#2655, and whatwg#11040. Proposals to address this at the ElementInternals level (e.g., relaxing encapsulation) have been discussed, but were met with valid concerns around encapsulation and design.

The goal of this issue is to gather thoughts from the ARIA WG about the feasibility of a proposed solution, and/or brainstorm about other solutions.

Proposal: Introduce a new get-only API surface (tentatively named implicitAria) to expose browser-default (or author-modified browser-default) accessibility semantics for DOM elements, including those defined via ElementInternals. Unlike standard ARIA reflection (which exposes explicitly set aria-* attributes), implicitAria would expose the implicit or default semantics the browser applies. This would be ideal for accessibility testing libraries such as axe-core.

Here are examples to demonstrate the idea:

1. Native with no explicit role

<button id="b1">Save</button>
<script>
const b1 = document.getElementById('b1');

// ARIA reflection (explicit only): no role attribute present
console.log(b1.role);               // undefined

// Proposed implicit semantics:
console.log(b1.implicitAria.role);  // "button" (from native semantics)
</script>

2. Custom element that sets role via ElementInternals

<script>
class CustomButton extends HTMLElement {
  constructor() {
    super();
    this._internals = this.attachInternals();
    this._internals.role = 'button'; // author-provided implicit role
  }
}
customElements.define('custom-button', CustomButton);
</script>

<custom-button id="b2"></custom-button>
<script>
const b2 = document.getElementById('b2');

// No explicit role attribute on the host:
console.log(b2.role);               // undefined

// Proposed implicit semantics reflect ElementInternals:
console.log(b2.implicitAria.role);  // "button" (from ElementInternals)
</script>

3. Native with an explicit role

<button id="b3" role="checkbox">Toggle</button>
<script>
const b3 = document.getElementById('b3');

// ARIA reflection exposes exactly what the author set:
console.log(b3.role);               // "checkbox"

// Proposed implicit semantics still show the native default:
console.log(b3.implicitAria.role);  // "button"
</script>

This solution doesn't require the browser to build the accessibility tree, it works similarly to how ARIA reflections work but for default values. I believe it stays clear from the privacy and performance issues we once discussed around AOM and the AccessibleNode proposal. It wouldn't leak the accessibility needs of a specific user, and is reasonably scoped. We could use a get-only version of the ARIAMixin interface to expose the full set of aria attributes.

Will this require a change to CORE-AAM?

No.

Will this require a change to the ARIA authoring guide?

It shouldn't.

[jcsteh]

There are a lot of similarities here to the original, abandoned version of accessibleNode. A major problem here is that computing this information is generally handled by a browser's accessibility engine, which isn't always running for performance reasons; e.g. if there are no accessibility clients running on the system. We can't simply return nothing when the accessibility engine isn't running because that would provide a very obvious way to detect whether an AT is running, which violates the web Platform Design Principle 2.11. Don’t reveal that assistive technologies are being used. On the flip side, starting the accessibility engine to answer such a query is a performance concern and the timing involved there could also easily reveal whether a user is using AT.

That said, it is important that we can test computed properties. Thus, it has been proposed that we have a test-only interface for this. This wouldn't be exposed to the web at large, only to automated tests. There is active (albeit slow) development on a WebDriver based solution in WICG/aom#203.

[dbjorge]

Speaking on behalf of Deque Systems (maintainers of axe-core):

We are strongly in favor of this proposal.

Without this proposal, axe-core has no way to detect implicit ARIA semantics defined using ElementInternals. This prevents accurate accessibility testing of any custom element (even ones that don't use ElementInternals), since axe-core has to guess whether or not ElementInternals might be changing which semantics the element is meant to implement.

Today, axe-core guesses "probably not", which means it reports incorrect results for elements that actually do use ElementInternals. The inaccurate results this causes is already the most highly-upvoted issue on axe-core (by a wide margin). This will only become worse over time; ElementInternals is rapidly gaining adoption among design systems and component libraries (eg, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...). Without something like this proposal, a near-future version of axe-core will probably need to start saying "we have no way to tell what ARIA semantics any custom element actually has, so the only way to avoid false-positive scan results is to exclude all custom elements from axe-core scans."

Excluding custom elements from axe-core scans would be a huge blow to the accessibility of the web. It would prevent automated accessibility testing of web components in a massive number of projects and accessibility tools. On NPM alone axe-core is downloaded 20+ million times per week, and there are dozens of other accessibility testing tools built on top of axe-core (including some of Google's and Microsoft's).

This wide variety of projects and tools is the reason we want to join @benbeaudry in pushing for a proposal (like this one) that exposes a DOM API, and not a webextension-specific API or a webdriver-specific API. axe-core is the basis of a huge chunk of the automated accessibility testing ecosystem, and that ecosystem is extremely mixed; some of it is webextensions, some of it is bookmarklets, some of it is webdriver-based testing tools, some of it is CDP-based tools, some of it is embedding or injecting directly in sites. An API that works across all of those environments is the best way to ensure that the whole ecosystem of accessibility testing tools continues to function.

[jcsteh]

An API that works across all of those environments is the best way to ensure that the whole ecosystem of accessibility testing tools continues to function.

While I understand the concern here, as I explained above, no way has been found yet to create such an API without trivially revealing the absence/presence of AT. That is an unacceptable risk for users and users need to come first. To anticipate an argument, yes, there are other known ways to detect AT, but they are at least somewhat obscure and/or indirect. This would be very trivial and very direct.

[benbeaudry]

@jcsteh Let me be explicit: This is different from the proposal you're familiar with. We wouldn't expose the computed role or attributes, but the default ones. This key difference would allow us (at least in Chromium) to avoid starting the accessibility engine, and avoid leaking to the web platform the accessibility needs of the user.

When I say default roles, I mean the roles implied by native semantics or by author-provided ElementInternals values, before any ARIA attributes or other overrides are applied. In other words, this would surface the same information a browser already knows at parse time — what role it would assign to an element if nothing else changes — not the resolved accessibility tree state.

That distinction keeps the API lightweight, deterministic, and privacy-preserving, while still giving accessibility tooling a reliable way to introspect author intent.

[jcsteh]

Let me be explicit: This is different from the proposal you're familiar with. We wouldn't expose the computed role or attributes, but the default ones.

That clarification helps; thanks. However:

When I say default roles, I mean the roles implied by native semantics or by author-provided ElementInternals values, before any ARIA attributes or other overrides are applied. In other words, this would surface the same information a browser already knows at parse time — what role it would assign to an element if nothing else changes — not the resolved accessibility tree state.

In theory, I understand what you're saying. In practice, at least in Gecko, pretty much all of that is determined by the accessibility engine. Duplicating all of that logic is going to result in inconsistency and difficult maintenance. Conversely, separating out that logic isn't really feasible because of the complex interactions between various levels of semantics.

To use a simple example, consider something like <section>. That could have a role of generic if there's no accessible name, but if there's an accessible name, it should have a role of region. But whether it has an accessible name is pretty complicated and basically requires you to do the entire name computation algorithm, which requires a lot of accessibility information.

[jpzwarte]

What's the difference here from the issues i raised earlier (#2655, #2656)? They seem to propose the same?

I personally like the "getComputedAria()" method more than an implicitAria getter better (since it matches with existing "getComputedStyle" function). On the other hand, you could optimize reading a single ARIA property better in with the getter than the function.

[scottaohara]

added agenda label per request from @benbeaudry

[jcsteh]

What's the difference here from the issues i raised earlier (#2655, #2656)? They seem to propose the same?

One significant difference is that this issue proposes default semantics, where the other two propose fully computed semantics. Fully computed semantics absolutely suffer from the concerns I raised in #2663 (comment). It's being suggested that default semantics don't suffer from this problem, though I'm not convinced of that in practice as I outlined in #2663 (comment).

[dbjorge]

I'm definitely on board with saying "it's a requirement that whatever solution we come up with can't leak the presence of AT", and I see your point @jcsteh that it'd be problematic to meet that requirement for cases like <section> and <img> whose implicit roles rely on accessible name calculations.

What if the proposal were scoped more specifically to just custom elements? Do you think that would allow Gecko to reasonably implement it without relying on the accessibility engine?

[pkra]

Just FYI: both #2655 and #2656 were briefly discussed during last week's ARIA WG call https://www.w3.org/2025/10/16-aria-minutes.html#123a

[jcsteh]

What if the proposal were scoped more specifically to just custom elements?

That is far more likely to be feasible because we're only dealing with a clearly author specified role there, rather than the more complicated HTML-AAM and Core-AAM rules. However, #2663 (comment) noted:

Proposals to address this at the ElementInternals level (e.g., relaxing encapsulation) have been discussed, but were met with valid concerns around encapsulation and design.

I'm not quite sure what all of those concerns were and whether introducing something specific to ElementInternals would have the same concerns.

There might still be some edge cases here. In particular, if this is described as "custom elements" and not "ElementInternals", #2383 comes to mind, since it can mean that the minimum role for a custom element can be different depending on various factors which would normally be determined by the accessibility engine. There might be others too, but I'd say far less than there are for standard HTML elements and ARIA.

[benbeaudry]

I’m glad to see that we all agree on the problem statement. It also sounds like we’re all aligned on the core goals:

1. Avoid revealing whether assistive technology is active.
2. Maintain good performance (no accessibility engine startup).

That constraint rules out any solution that depends on the accessibility tree or engine. This narrows the set of solutions and, fortunately, makes the few valid options clearer.

Proposal 1: ElementInternals-scoped solution

This is the solution Dan mentioned earlier.

Expose a read-only reflection of an element’s attached ElementInternals ARIAMixin via something like:

element.internalsAria

If no internals are attached, this would return null.
If present, it would expose a readonly snapshot of the author-provided ARIA attributes set via the ElementInternals ARIAMixin.

This approach:

• Does not require the accessibility engine, maintaining privacy and performance.
• Solves the immediate need for ElementInternals-based custom elements.
• Is super easy to implement for user agents.

My one concern with this approach is that it's ElementInternals-specific. The WHATWG discussion in whatwg#11040 raised valid concerns about revisiting a solution that would "open-up" ElementInternals more, saying it would go against the spirit of encapsulation it was designed with in mind.

One could argue that the problem stems not from the closed encapsulation model of ElementInternals, but rather from the absence of a standardized mechanism for accessibility testing tools to read all author-provided ARIA values. These tools need visibility into what authors explicitly set in order to identify errors. My opinion is that this is a need the ARIAWG should explicitly be in support of.

This brings me to the second proposal.

Proposal 2: General DOM API for implicit semantics

This is the solution I proposed in my original post on this issue.

Expose a new get-only property, e.g.:

element.implicitAria

This API would return the element’s default (pre-computed) ARIA role and attributes — the values known to the browser before any explicit ARIA attributes are applied or the accessibility engine is invoked.
For example, implicitAria.role would return "button" for a native <button> or "button" for a custom element that set that role through ElementInternals, but would not account for later overrides or name computations.

To clarify what I mean by “default” or “implicit,” it’s useful to think of an element’s ARIA state in several conceptual stages, as perceived by a browser implementor: initial, explicit, computed, and exposed.

• At the initial stage, the state reflects the native or ElementInternals-defined defaults known at parse time (if any).
• At the explicit stage, it incorporates values directly set by the author using aria-* attributes.
• At the computed stage, the accessibility engine resolves those values according to the full ARIA and HTML-AAM rules.
• Finally, the exposed stage represents the final accessibility tree after platform mappings are applied.

implicitAria would expose only the initial stage — the author-intended semantics before explicit attributes are applied and before computation.
Not all attributes have defaults, and elements whose defaults require non-trivial computation (such as <section>) should be treated as having no real default and thus return null.

This approach:

• Does not require the accessibility engine, maintaining privacy and performance.
• Solves the problem at a lower level.
• Would require the WG to define what counts as a native/default value where not already specified.
• Might require user agents to refactor their default value definitions outside of the accessibility engine.
• Is scalable beyond custom elements if needed.

@jcsteh, you said:

In practice, at least in Gecko, pretty much all of that is determined by the accessibility engine.

This is also true for Chromium today — our native values live in the accessibility objects only instantiated when we run the accessibility engine. I could definitely see us refactoring those definitions outside of it in a way that avoid duplication or inconsistencies.

I'm not yet sure this solution is fully feasible, or whether my mental model of "implicit" values fully holds — which is why I really appreciate this discussion.

I have a few questions for you, Jamie, and others in the WG:

• Do we agree on the premise that the ARIAWG should support accessibility testing tools in their need to access author-provided ARIA values from a DOM API?
• Should we continue pursuing an ElementInternals-scoped solution instead of a broader ARIA-scoped one? If so, how would you justify it to the WHATWG?
• Are there other possible approaches we haven’t discussed yet?

[jpzwarte]

Slightly offtopic, but is there any documentation on the "accessibility engine"? What's the difference between devtools showing ARIA properties and starting up the accessibility engine? Doesn't every vendor's devtools have an accessibility pane within their devtools? Or show the entire a11y tree?

[benbeaudry]

There's no "formal spec" or standardized documentation for browser accessibility engines, because they're internal implementations tied closely to each browser. They're Chromium, Firefox, and Safari's way of implementing the ARIA spec and making the web accessible.

For chromium, this might be helpful: https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/modules/accessibility/readme.md?q=accessibility%2Farchitecture&ss=chromium

Chromium and Firefox are similar in how they implement the accessibility engine, in the sense that we both have it completely turned off unless we detect an assistive technology requesting information through the platform accessibility APIs. This is the default because most users don't need accessibility support. The accessibility engine is a very expensive beast in part because it must copy (and maintain a copy of that data) of each tab into the browser process. I explained it at a high-level at the BlinkOn 18 conference, which you can watch here: Challenges with Chromium Accessibility.