Let Equals Equal Equals Let Equals Equal Equals 5/28/2026 11 minutes Setting ariaDescribedByElements on a node silently fails when the target is in a different shadow root. The spec broke = to preserve encapsulation purity. This violates the Priority of Constituencies, harms AT users, and should be fixed immediately. Reference Target is complementary and welcome, but it is not a substitute for making imperative assignment work. The Bug Here's a line of JavaScript that looks like it does something: input.ariaDescribedByElements = [helpText]; You'd expect this to work. You're holding both nodes. You wrote the assignment. The browser accepted it without complaint. But if helpText lives in a shadow root that isn't an ancestor of input's shadow root, the assignment is silently discarded. The getter returns null. No warning. No error. Assistive technology users get nothing. Browser spec authors intentionally broke =. Wait, What? The spec for reflected element references defines a "scope" rule: the target element must be in the same DOM as the source, or in a parent DOM. Siblings, cousins, children -- all silently rejected. So this works: <div id="host">
<template shadowrootmode="open">
<input id="input">
<span id="help">Help text</span>
</template>
</div> // Same shadow root: works
input.ariaDescribedByElements = [help]; And this works: <span id="outer-help">Help text</span>
<div id="host">
<template shadowrootmode="open">
<input id="input">
</template>
</div> // Referencing "up" into lighter DOM: works
input.ariaDescribedByElements = [outerHelp]; But this doesn't: <x-input>
<template shadowrootmode="open">
<input id="input">
</template>
</x-input>
<x-tooltip>
<template shadowrootmode="open">
<span id="tip">Helpful description</span>
</template>
</x-tooltip> // Sibling shadow roots: silently fails
input.ariaDescribedByElements = [tip];
// getter returns [], AT sees nothing Same API. Same syntax. Same intent. Different result, depending on tree position -- with no indication that anything went wrong. I built a codepen demonstrating the inconsistency. The results are, as Steve Orvell put it, "confusing and seemingly inconsistent." Why Does This Happen? The restriction was added to prevent leaking shadow DOM internals. The concern: if you set el.ariaActiveDescendantElement to something inside a shadow root, then anyone with access to el could read that property and walk into the shadow tree. Here's the scenario that worried spec engineers, paraphrased from Alice Boxhall's analysis: // Component sets aria reference to internal element
lightEl.ariaActiveDescendantElement = shadowChild;

// Now any script can traverse into the shadow tree
lightEl.ariaActiveDescendantElement
.parentElement
.appendChild(document.createTextNode("surprise")); This is a real concern. But the solution they chose -- silently discarding the setter -- trades an encapsulation worry for an accessibility failure. And the encapsulation worry has a straightforward fix (null out the getter while preserving the internal relationship for AT), while the accessibility failure has no fix at all from the developer's perspective, short of restructuring their entire DOM. Moreover, the encapsulation concern is minor (most developers wouldn't care) while the accessibility failure is critical. The Getter Problem Has Known Solutions The spec discussion on whatwg/html#5401 explored multiple options for handling the getter when a referenced element is in a deeper shadow root: Return null from the getter, but keep the internal reference for AT -- the "attr-associated element" remains intact for the accessibility tree, even though JavaScript can't read it back. Retarget the reference to the shadow host, similar to how events retarget when crossing shadow boundaries. Alice Boxhall formalized this in WICG/aom#195, proposing that the getter retarget to the nearest visible host, with an opt-in API (getAttrAssociatedElement) to "undo" retargeting when the caller already has access to the relevant shadow root -- analogous to getComposedRanges() in the Selection API. Reference Target -- the component explicitly declares which internal element should be exposed. Alice's comprehensive analysis of ARIA relationships and shadow DOM lays out these options in detail. Options 1 and 2 solve the encapsulation leak without breaking the setter. The spec authors chose something closer to option 0: discard everything silently. Alice, who did much of the design work on ARIA element reflection, shared her frustration in a recent discussion: I agree with Nolan's suggestion in the bug that developers should get a warning supporting the cross-root case was indeed what we hoped the feature would enable; there was push-back from other standards engineers based on the reasoning I explained in the bug, so yeah it is now in something of a semi-broken state, which is very frustrating when so much work went into it perhaps we would have been better off not trying to ship it at all Imperative Means Intentional When a developer writes: input.ariaDescribedByElements = [someNode]; they already have both references. They already traversed whatever boundaries stood between them and those nodes. The assignment is an explicit, deliberate act. As Steve Orvell (Lit team) noted after discussing with Chrome engineers: this was done to hide shadow details, but I think there is room for push back since it's an imperative API and you need to be able to get access to all the nodes in question to use the API. The encapsulation was already broken the moment you obtained the reference. Having = silently un-break it doesn't restore encapsulation. It just breaks accessibility. Consider: why would anyone use the imperative API except to make a cross-root reference? If the elements were in the same scope, you'd use the aria-describedby content attribute with an ID. The entire purpose of the imperative API is to connect elements that attributes can't reach. This is also how developers have handled cross root references in userland libraries for years, e.g. highcharts or leafmap mount points. The Priority of Constituencies The W3C's HTML Design Principles establish a binding hierarchy: In case of conflict, consider users over authors over implementors over specifiers over theoretical purity. The Web Platform Design Principles reaffirm: User needs come before the needs of web page authors, which come before the needs of user agent implementors, which come before the needs of specification writers, which come before theoretical purity. The current behavior inverts this. Spec engineers chose to protect encapsulation purity over user access to accessibility features. The constituency harmed (AT users) ranks highest in the hierarchy. The constituency served (spec authors concerned about theoretical encapsulation leaks) ranks lowest. This isn't a close call. This is the worst possible violation of the highest principles of the HTML spec itself, perpetrated by spec authors, in the name of a theoretical purity that nobody asked for. Brian Kardell argued (successfully) that the PoC is more of a guideline than a binding principle, and that even then, engineering resources should be taken into account. And regardless, the existence of the WHATWG is the tacit admission that browser vendors will do whatever they want, whenever they want. But even the most nuanced, least toothy read of the PoC puts this issue squarely in the center of the cross hairs. Theoretical spec purity must not win against real user needs. "But What About Closed Shadow Roots?" The encapsulation argument leans heavily on closed shadow roots. But closed shadow roots are vanishingly rare in practice: Chrome UseCounters show open shadow DOM on ~17.5% of page loads vs closed on ~5.3%. Per the Chromium UseCounter Wiki, this figure is not inflated by UA shadow roots (internal code paths) or browser extensions (separate histogram). It's real page JS. But even this ~5% likely reflects ad-tech widgets and third-party embeds, not web component library usage. No major web component framework defaults to closed shadow roots. Lit, Stencil, FAST, Angular, Svelte, Vue -- all default to open. Several don't even support closed mode. Of 30,000+ Lit components on GitHub, roughly 5-10 use closed shadow roots. eslint-plugin-wc ships a no-closed-shadow-root rule, warning that "closed shadow roots are very rarely used and can hinder development/interaction with an element." Closed shadow roots provide no real security boundary. Browser vendors themselves ship extension APIs (dom.openOrClosedShadowRoot) to bypass them. But even setting the data aside: if I have a reference to a node in a closed shadow root, I should be able to use it. Full stop. Having the reference means someone -- the component author, a framework, my own code -- already decided to share it. The encapsulation boundary was already crossed. The platform shouldn't second-guess that decision, especially not by silently breaking an accessibility feature. The component author is a grown-up. If they expose a node reference, they accept that it might be used. And the user of assistive technology deserves to have that accessibility relationship work, regardless of what mode some attachShadow call used three layers up the DOM tree. The spec is constraining a heavily-used imperative accessibility API to protect encapsulation guarantees that almost nobody uses, that provide no real security, and that actively harm the constituency the web platform is supposed to serve first: users. For a deeper dive into the data, see my research on closed shadow root usage. What Developers Actually Need Here's a real pattern from the ARIA 1.1 Combobox example, implemented with web components: <fancy-input>
#shadow-root
<input type="text">
</fancy-input>
<fancy-listbox>
#shadow-root
<ul role="listbox">
<fancy-option>
#shadow-root
<li role="option">List item</li>
</fancy-option>
</ul>
</fancy-listbox> The <input> needs aria-activedescendant pointing to the active <li>. These shadow roots are siblings. The imperative API was supposed to solve this. It doesn't. As Nolan Lawson (Salesforce) documented in WICG/aom#192: I guess for me the question is: "Why is it acceptable for elements in separate shadow roots to be linked with aria relationships, but only if those shadow roots are in a descendant-ancestor relationship (and only in one direction)?" To me, it's not clear what benefit this particular restriction provides. This was filed in 2022. It remains open. Reference Target Is Great. Also Not Enough. Reference Target (WICG/webcomponents#1086) is a promising proposal that lets a custom element declare which internal element should be targeted by ARIA references. It's good work and I want it to ship. But Reference Target is complementary, not a substitute: Reference Target requires the component author to opt in. If a third-party component doesn't implement it, you're stuck. Reference Target addresses the declarative case (aria-describedby attributes). The imperative case (ariaDescribedByElements = [...]) should work independently. Reference Target is still in development. Phase 1 has open blockers. The imperative API exists today and is broken today. = should mean =. Reference target doesn't fix that. We should have both: Reference Target for the clean declarative path, and working imperative assignment for everything else. The Fix Make the setter work. When a developer assigns el.ariaDescribedByElements = [node], persist the internal relationship for the accessibility tree regardless of shadow root topology. Null out the getter if needed. If the referenced element is in a deeper/sibling shadow root, return null from the JavaScript getter. This preserves encapsulation for scripts while letting AT see the relationship. This approach was explored in the spec discussion and is implementable. Warn, don't fail. At minimum, emit a console warning when an assignment is silently scoped away. Nolan Lawson suggested this and it's the bare minimum: developers need to know when their accessibility code doesn't do what they wrote. Ship Reference Target too. It's the right long-term solution for the declarative case. These are not competing proposals. The Cost of Silence Here's the real damage. A developer writes: for (const node of descriptors) {
el.ariaLabelledByElements = [
...el.ariaLabelledByElements,
node,
];
} This loop looks obvious. It's not. Some iterations silently succeed, others silently fail, depending on the shadow root positions of elements that the developer may not even control. Only extensive manual testing with a screen reader will reveal the failure. Many developers won't do that testing. AT users will pay the price. When a platform API silently discards accessibility relationships, it isn't protecting users from encapsulation violations. It's protecting spec purity from users. That's backwards. Fix it. ← Introducing Backlit: Lit SSR for Drupal, Hold the Node @bp IIRC one of the central debates here was around closed vs open shadow DOM, where the principal was that new platform APIs should not make a distinction between the two. I tend to agree with you that open is the "default" so it feels a bit silly to privilege closed so much.Re: your research, is it true that UA shadow roots count as closed in the Chrome data? If so that would resolve one of the mysteries I had when I was researching this years ago. @nolan yeah that's the case. I can share more later on.But the most egregious things here are redefining setter semantics, and the flagrant, worst-of-all-possible violations of the priority of constituencues. @nolan and *even if the roots are closed* - if I already have the node references, encapsulation has been broken, there's no benefit.If you'll say they'll read it from the better: 1. *this is a crucial a11y feature* so the PoC obtains, and 2. here's a patched attachShadow which I prepared earlier. ITS JAVASCRIPT, That's how these things work. @nolan and **even if you'll say** that the PoC are non-binding guidelines, you still need strong justification to just toss it in the fire. "My opinions on software pattens oppose the PoC" is not a justification. @nolan mea culpa, those are real userland calls, but it's still vanishingly small compared to open. Moreover those called to close shadow roots are trivially defeated, and in many cases (ads) user-hostile, anyways.- **Zero major frameworks** default to closed. Lit, Stencil, FAST, Angular, Svelte, Vue all default to open. Several don't even support closed mode.- Of **30,000+ Lit components** on GitHub, roughly **5-10** use closed shadow roots.- Lit developers override shadowRootOptions for delegatesFocus **100x** more often than for mode: 'closed'.- Stencil has an open feature request for closed mode since 2023 -- 13 upvotes, never shipped.- LWC, Angular, Svelte, and Vue don't even expose a closed mode option.And ~28% of closed-mode JS results on GitHub are extensions/userscripts that *intercept* attachShadow to force closed roots back to open. Use of open to closed on github is 3:1, and when you subtract tests it's more like 9:1. There are 30000+ published web components use open, 5 or 10 use closed. Closed shadow roots were a big mistake, and that's out of scope of this discussion. Privileging their use over REAL a11y failures today is egregious @bp Yep you're preaching to the choir. 🙂 I argued much of these things years ago but didn't make much headway.I still think that "Chrome should console.warn" is the cheapest win here, since it doesn't require relitigating the "open shadow vs closed shadow" debate. I found that argument pretty unwinnable regardless of usage metrics etc. 11 messages

The discussion centers on a critical inconsistency within the HTML specification regarding the operation of imperative assignments, specifically when referencing elements across shadow DOM boundaries, and the resulting conflict between theoretical encapsulation purity and accessibility requirements. The core issue arises when a property such as ariaDescribedByElements is assigned to an element, and the target element resides in a shadow root that is not an ancestor of the source element. Although the assignment operation itself completes without error, the getter function silently discards the reference, resulting in null and denying assistive technology access to the intended relationship.

The spec authors intentionally made this modification to preserve the purity of encapsulation, arguing that allowing such assignments could inadvertently expose internal shadow DOM structures, which caused concerns among specification engineers. However, this choice fundamentally violates the established Priority of Constituencies, which dictates that user needs must supersede author concerns, as users (particularly assistive technology users) are the highest constituency. The text argues that prioritizing theoretical encapsulation purity over functional accessibility results in a severe violation of these principles.

The text analyzes the conflict through the lens of the imperative assignment: when a developer explicitly writes an assignment, they have already established a deliberate connection. The failure of the getter to reflect this established relationship breaks the intended functionality, especially in scenarios involving sibling shadow roots. The discussion explores potential solutions for this broken state. One proposed fix involves allowing the setter to succeed while managing the getter behavior, such as returning null from the getter if the referenced element is in a deeper or sibling shadow root, thereby preserving the internal reference for assistive technology while maintaining script encapsulation. Another solution discussed is the explicit declaration method, Reference Target, which requires the component author to opt in to declare which internal element should be targeted, addressing the declarative aspect of the link.

Furthermore, the text addresses the ancillary concern regarding closed shadow roots. While the encapsulation argument often pivots on closed shadow roots, the author argues that their practical relevance is limited. The data presented suggests that closed shadow roots are rarely utilized by major web component frameworks, and they are often defeated by userland code, such as extensions or userscripts that manipulate the attachShadow function. Since the encapsulation boundary has already been crossed when a developer obtains a reference to a node, second-guessing this decision to suppress accessibility features is deemed unjust.

Ultimately, the argument stresses that the silence of the behavior harms users by preventing necessary accessibility links from being established, thereby framing the specification's stance as protecting abstract purity over real-world user needs. The proposed resolution emphasizes that developers should be warned, for example, by emitting a console warning when an assignment is silently scoped away, as this is the minimum requirement for transparency. The text concludes that the imperative API should function as intended, and solutions like Reference Target should be adopted alongside working imperative assignments to provide a complete and functional mechanism for cross-shadow root referencing.