docs: update a11y skill cross-root aria instructions

Author: bennypowers

.claude/skills/review-a11y/SKILL.md

@@ -147,13 +147,23 @@ For each composite element:
    (selected option, active tab, etc.)
 6. Close/collapse, snapshot again -- verify clean return to closed state
 
-**Cross-root relationships**: `aria-controls`, `aria-describedby`,
-`aria-labelledby` cannot reference IDs across shadow boundaries
-declaratively, they must (as of Spring 2026) use ARIA IDL attrs like
-`element.ariaDescribedByElements`. Verify these relationships work via
-ElementInternals ARIA IDL properties or other workarounds.
-Flag any broken cross-root references. Ensure that all ax tree states in demo
-are suitably covered by a11ySnapshot tests in element's test files.
+**Cross-root ARIA relationships**: See the reference section below for
+the full technical landscape. Key points for reviewers:
+
+- `aria-controls`, `aria-describedby`, `aria-labelledby` **cannot**
+  reference IDs across shadow boundaries declaratively.
+- ARIA IDL properties (`ariaDescribedByElements`, etc.) are the
+  intended replacement but have cross-root limitations. See
+  "Cross-Root ARIA Element Reflection" below for which directions
+  work and which silently fail.
+- Verify relationships in the **ax tree**, not by inspecting DOM
+  attributes. A relationship that appears set in JS may produce
+  nothing in the computed tree.
+- Flag any broken cross-root references and document workarounds
+  (live-region announcer, `aria-label` on trigger, Reference Target
+  when it ships).
+- Ensure all ax tree states in demos are covered by a11ySnapshot
+  tests in the element's test files.
 
 #### Cross-browser differences to flag
 
@@ -199,3 +209,125 @@ In "Critical Issues", all items should be linked to its WCAG success criterion..
 - Leave "why comments" on non-obvious ARIA decisions
 - Both browsers must produce functionally equivalent ax trees
 - Test every state, not just default
+
+## Cross-Root ARIA Element Reflection
+
+Reference material for reviewing cross-shadow-boundary ARIA
+relationships. Last updated June 2026.
+
+### The Problem
+
+Declarative ARIA ID references (`aria-describedby="some-id"`) only
+resolve within a single DOM tree. Shadow DOM boundaries prevent
+cross-root ID resolution. This affects any element where a trigger in
+light DOM needs an ARIA relationship to content in shadow DOM (or
+vice versa).
+
+### ARIA IDL Element Reflection
+
+The ARIA IDL properties (`ariaDescribedByElements`,
+`ariaLabelledByElements`, `ariaControlsElements`, etc.) accept Element
+references instead of ID strings, bypassing the ID-resolution problem.
+However, cross-root references are validated by a **shadow-including
+ancestors** algorithm that restricts which directions work.
+
+#### Which directions work
+
+| Direction | Example | Status |
+|---|---|---|
+| Same tree | Light DOM element → light DOM element | Works |
+| Shadow-to-light (child→parent) | Shadow DOM element → light DOM ancestor | Works |
+| Light-to-own-shadow (parent→child) | Light DOM trigger → shadow DOM content in same host | Permitted by spec algorithm, but **not WPT-tested** and **unreliable in practice** |
+| Sibling shadow roots | Element in shadow root A → element in shadow root B | Does NOT work |
+| Arbitrary cross-root | Unrelated shadow boundaries | Does NOT work |
+
+The parent-to-child case (light DOM trigger referencing its host's
+shadow DOM content) is technically valid per the shadow-including
+ancestors rule, but:
+
+- WPT tests at `custom-elements/element-internals-aria-element-reflection.html`
+  only cover same-tree and negative (invalid cross-tree) cases
+- WICG/webcomponents#974 explored this direction with no clear resolution
+- No browser has confirmed reliable support
+- Treat as **progressive enhancement**: set the IDL property, but don't
+  rely on it for accessible content delivery
+
+#### What to do instead
+
+When a cross-root ARIA relationship silently fails, use one of these
+workarounds depending on the element's semantics:
+
+| Relationship | Workaround |
+|---|---|
+| `describedby` (supplementary text) | Static `role="status"` live-region announcer in light DOM (see ADVICE.md "Use a static live-region announcer") |
+| `labelledby` (accessible name) | Set `aria-label` directly on the trigger element |
+| `controls` (widget relationship) | Verify the ax tree reflects the relationship via native semantics (`<details>`, `<dialog>`) or ElementInternals; if not, document the gap |
+| `none` (opt-out) | Provide a `silent` or similar boolean attribute to suppress ARIA behavior |
+
+### Reference Target Proposal
+
+The **Reference Target** proposal (WICG/webcomponents#1086) is the
+long-term solution for cross-root ARIA. It enables external elements to
+reference a shadow host by ID, with the shadow root designating which
+internal element receives the reference via `shadowRootReferenceTarget`.
+
+#### Status (June 2026)
+
+| Browser | Status |
+|---|---|
+| Chrome | Canary behind `--enable-experimental-web-platform-features` flag. Intent to Experiment filed. Not in stable. |
+| Firefox | Positive standards position. Igalia prototyping (NLNet funded). Bug 1981341. Not shipping. |
+| Safari/WebKit | Igalia prototype exists. No official standards position signal. |
+| Spec | WHATWG HTML #10707, Stage 3 ("Committed"). Pull requests DOM #1353, HTML #10995 in progress. Not yet merged into HTML Living Standard. |
+| Interop 2026 | Submitted as focus area proposal (web-platform-tests/interop#1011). |
+
+#### What Reference Target solves
+
+- **Outside → host → internal target** references (e.g., a label
+  element outside a shadow root referencing an input inside it via
+  the host)
+- Recursive resolution through nested shadow roots
+
+#### What Reference Target does NOT solve
+
+- Arbitrary sibling-to-sibling cross-root references
+- Direct parent-to-specific-child references bypassing the host
+- Attribute forwarding from host to internal elements
+- The tooltip case where the *trigger* is in light DOM and the
+  *content* is in the host's own shadow DOM (this is the reverse
+  direction)
+
+### Reviewing elements with cross-root ARIA
+
+When auditing an element with cross-root ARIA relationships:
+
+1. **Identify all ARIA relationships** the element establishes
+   (describedby, labelledby, controls, owns, etc.)
+2. **Map each relationship's direction**: which element sets the
+   property, which element is referenced, and which shadow roots are
+   involved
+3. **Check the ax tree in both browsers** to see if the relationship
+   actually resolves (don't trust DOM inspection)
+4. **Verify the fallback mechanism** works:
+   - If using an announcer, verify `role="status"` element exists,
+     content is announced on show, cleared on hide
+   - If using `aria-label`, verify the label text matches the
+     tooltip/popover content
+5. **Check for `silent` or equivalent opt-out** for cases where the
+   element's ARIA behavior conflicts with author-provided accessibility
+6. **Verify progressive enhancement code** is present:
+   - IDL property assignment (`ariaDescribedByElements = [el]`) should
+     be kept even though it silently fails today
+   - Comment explaining the cross-root limitation and linking to
+     relevant spec issues
+7. **Document the gap** in the review report under "Cross-Browser
+   Differences" or "Warnings"
+
+### Spec and issue references
+
+- WICG/aom#192 -- cross-root element reflection scope
+- whatwg/html#5401 -- element reflection and shadow roots
+- whatwg/html#10707 -- Reference Target spec integration (Stage 3)
+- WICG/webcomponents#1086 -- Reference Target tracking issue
+- WICG/webcomponents#974 -- ElementInternals pointing into own shadow
+- WPT `custom-elements/element-internals-aria-element-reflection.html`