Overview

We need to investigate how DOM cross-referencing behaves when using Web Components, especially with Shadow DOM and slotted content. This includes patterns like id/for, aria-labelledby, aria-describedby, aria-controls, and semantic ARIA role relationships such as list ↔ listitem.

The goal is to ensure that DOM references continue to work across component boundaries, regardless of whether content is slotted or encapsulated inside Shadow DOM.

Documentation of the findings will be added as an architectural decision in our GitHub Discussions.

Tasks

• Create new first level documentation section in storybook: e.g. Accessibility Practices and set it to private
• Investigate examples and workarounds
• Document findings

What to Investigate

• How common referencing patterns behave in Web Components:
  • for / id (e.g. <label for="input-id">)
  • aria-labelledby, aria-describedby, aria-controls
  • ARIA roles like role="list" with role="listitem" in slotted children
• What works by default vs. what breaks in these scenarios:
  • Both elements in the same Shadow DOM
  • One element in light DOM, the other in Shadow DOM
  • Each element in a different Shadow DOM
• Are there workarounds or patterns to fix broken references?

Example

<post-list>
  #shadow-root
    <div>Some useful content</div>
    <div role="list">
      <slot></slot>
    </div>
  <post-list-item role="listitem">Item 1</post-list-item>
</post-list>```