+ In the Light DOM, `aria-controls` is used to indicate that an element controls the visibility or
+ interaction of another element, by referencing its `id`.
+
+
+ This creates an accessibility relationship, helping assistive technologies understand the
+ interaction between the trigger and the controlled content.
+
+
+### I. Referencing Within the Same DOM Tree ✔️
+
+
+
Light DOM → Light DOM
+
+
+
+
+### II. Referencing From the LightDOM Into That Shadow DOM ❌
+
+
+
Light DOM → Shadow DOM
+
Slotted Content → Shadow DOM
+
+
+The `aria-controls` attribute cannot reference elements inside a Shadow DOM from the Light DOM. This is because IDs inside Shadow roots are encapsulated and inaccessible across boundaries, preventing valid accessibility relationships.
+
+##### Possible Workarounds
+
+###### 1. `Element:ariaControlsElements`
+
+Light DOM → Shadow DOM Example
+
+
+
+
+
+Slotted Content → Shadow DOM Example
+
+
+
+
+
+###### 2. Set `aria-labelledby`on the host (for SSR Components: to be tested)
+
+An option is to set the following attributes directly on the host of the target component:
+
+
+
the `aria-labelledby`
+
a semantic `role` (e.g. `textbox`, `button`)
+
`tabindex="0"`
+
+
+Light DOM → Shadow DOM Example
+
+
+Slotted Content → Shadow DOM Example
+
+
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+
+
+
Shadow DOM → Light DOM
+
Shadow DOM → Slotted Content
+
+
+Similarly to the previous case, referencing an element located outside a Shadow DOM from an element inside that Shadow DOM using standard `aria-labelledby` is not possible. The strong encapsulation of the Shadow DOM prevents elements within it from directly accessing and referencing the IDs of elements in the Light DOM.
+
+##### Possible Workaround
+
+An option is to set the `id` directly on the host of the referencing element. Please note that, in this case all the visible text inside the referencing component will be assigned as the Accessible Name of the target element.
+
+
+
+##### IV. Referencing From One Shadow DOM To Another Shadow DOM
+
+
+
Shadow DOM → Other Shadow DOM
+
+
+what happens
+
+##### Possible Workaround
+
+workaround text
+
+
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-controls/aria-controls.stories.ts b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-controls/aria-controls.stories.ts
new file mode 100644
index 0000000000..08c58c4dc7
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-controls/aria-controls.stories.ts
@@ -0,0 +1,144 @@
+import { StoryObj, Args } from '@storybook/web-components';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+ id: '76ade552-2c03-4d6d-9dce-28daa346f3g3',
+ title:
+ 'Accessibility Practices/Foundational Structure And Semantics/Reference Relationships/Crossing The Shadow Dom/Aria-Controls',
+ parameters: {
+ badges: [],
+ },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+function handleToggleClick(toggleId: string, textId: string): void {
+ const toggle = document.getElementById(toggleId);
+ const text = document.getElementById(textId);
+ if (toggle && text) {
+ const timestamp = Date.now(); // or use a counter
+ text.innerHTML = `
+
+ `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Slotted Text (Element)
+export const Example3: Story = {
+ argTypes: {
+ workaround: {
+ name: 'Workaround',
+ control: {
+ type: 'radio',
+ },
+ options: ['none', 'ariaControlsElements'],
+ },
+ },
+ args: {
+ workaround: 'none',
+ },
+ render: (args: Args) => html`
+
+ Toggle Text
+
+ `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Light DOM (Element) workaround with aria-controls directly set on host
+export const Example4: Story = {
+ render: () => html`
+ Control Element
+ Controlled Element 4
+ `,
+};
+
+// Case: Referencing from Shadow Dom to Slotted Text (Light DOM) workaround with aria-controls directly set on host
+export const Example5: Story = {
+ render: () => html`
+
+ Controlled Element 5 (Slotted)
+
+ `,
+};
+
+// Case: Standard Light DOM to Shadow DOM
+export const Example6: Story = {
+ render: () => html`
+
+
+ Control Element
+
+
+ `,
+};
+
+// Case: Shadow DOM to other Shadow Dom workaround
+export const Example7: Story = {
+ render: () => html`
+
+
+ `,
+};
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-describedby/aria-describedby.docs.mdx
new file mode 100644
index 0000000000..03cb87c88f
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-describedby/aria-describedby.docs.mdx
@@ -0,0 +1,93 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/blocks';
+import * as CCR from './aria-describedby.stories';
+
+
+
+# Aria-Describedby
+
+
+ In the Light DOM, `aria-describedby` is used to give an element its accessible name by referencing
+ the id of another element or multiple elements that contain the desired text.
+
+
+ This is useful when a simple text label isn't directly associated or when the name needs to be
+ combined from different pieces of text.
+
+
+### I. Referencing Within the Same DOM Tree ✔️
+
+
+
Light DOM → Light DOM
+
+
+
+
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
+
+
+
Light DOM → Shadow DOM
+
Slotted Content → Shadow DOM
+
+
+Standard `aria-describedby` cannot reference elements located inside a Shadow DOM from outside of it. This is because IDs inside a Shadow DOM are encapsulated and not accessible from the Light DOM or other Shadow DOMs.
+
+##### Possible Workarounds
+
+###### 1. `Element:ariaDescribedByElements` (Non SSR compatible: to be tested)
+
+Light DOM → Shadow DOM Example
+
+
+
+
+
+Slotted Content → Shadow DOM Example
+
+
+
+
+
+###### 2. Set `aria-describedby`on the host (for SSR Components: to be tested)
+
+An option is to set the following attributes directly on the host of the target component:
+
+
+
the `aria-describedby`
+
a semantic `role` (e.g. `textbox`, `button`)
+
`tabindex="0"`
+
+
+Light DOM → Shadow DOM Example
+
+
+Slotted Content → Shadow DOM Example
+
+
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+
+
+
Shadow DOM → Light DOM
+
Shadow DOM → Slotted Content
+
+
+Similarly to the previous case, referencing an element located outside a Shadow DOM from an element inside that Shadow DOM using standard `aria-describedby` is not possible. The strong encapsulation of the Shadow DOM prevents elements within it from directly accessing and referencing the IDs of elements in the Light DOM.
+
+##### Possible Workaround
+
+An option is to set the `id` directly on the host of the referencing element. Please note that, in this case all the visible text inside the referencing component will be assigned as the Accessible Name of the target element.
+
+
+
+##### IV. Referencing From One Shadow DOM To Another Shadow DOM
+
+
+
Shadow DOM → Other Shadow DOM
+
+
+Referencing an element located inside one Shadow DOM from an element located inside a different, separate Shadow DOM using standard `aria-describedby` is also not possible. Similar to the other cross-boundary scenarios, the IDs are scoped within their respective Shadow DOMs.
+
+##### Possible Workaround
+
+In this case, in order for the relationship to work, the referencing element must have the `id` directly set on its host (see workaround of case III) and the target element must have the `aria-describedby`, `role` and `tabindex="0"` set on its host (see workaround of case II).
+
+
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-describedby/aria-describedby.stories.ts b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-describedby/aria-describedby.stories.ts
new file mode 100644
index 0000000000..b7a3df5246
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-describedby/aria-describedby.stories.ts
@@ -0,0 +1,105 @@
+import { StoryObj, Args } from '@storybook/web-components';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+ id: '76ade552-2c03-4d6d-9dce-28daa340f3g6',
+ title:
+ 'Accessibility Practices/Foundational Structure And Semantics/Reference Relationships/Crossing The Shadow Dom/Aria-DescribedBy',
+ parameters: {
+ badges: [],
+ },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+export const ExampleHTML: Story = {
+ render: () => html`
+
+
+
+ My Description
+ `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Light DOM (Element) workaround setting programmatically the relevant Element property
+export const Example2: Story = {
+ argTypes: {
+ workaround: {
+ name: 'Workaround',
+ control: {
+ type: 'radio',
+ },
+ options: ['none', 'ariaDescribedByElements'],
+ },
+ },
+ args: {
+ workaround: 'none',
+ },
+ render: (args: Args) => html`
+
+ My Description
+ `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Slotted Content (Element) workaround setting programmatically the relevant Element property
+export const Example3: Story = {
+ argTypes: {
+ workaround: {
+ name: 'Workaround',
+ control: {
+ type: 'radio',
+ },
+ options: ['none', 'ariaDescribedByElements'],
+ },
+ },
+ args: {
+ workaround: 'none',
+ },
+ render: (args: Args) => html`
+ My Description
+ `,
+};
+
+// Case: Referencing from Shadow Dom to Light DOM workaround with aria-describedby directly set on host
+export const Example4: Story = {
+ render: () => html`
+
+ My Description
+ `,
+};
+
+// Case: Referencing from Shadow Dom to Slotted Content (Light DOM) workaround with aria-describedby directly set on host
+export const Example5: Story = {
+ render: () => html`
+ My Description
+
+ `,
+};
+
+// Case: Standard Light DOM to Shadow DOM workaround
+export const Example6: Story = {
+ render: () => html`
+
+
+
+
+ `,
+};
+
+// Case: Shadow DOM to other Shadow Dom workaround
+export const Example7: Story = {
+ render: () => html`
+
+
+ `,
+};
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-labelledby/aria-labelledby.docs.mdx
new file mode 100644
index 0000000000..b0635d1cfa
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-labelledby/aria-labelledby.docs.mdx
@@ -0,0 +1,91 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/blocks';
+import * as CCR from './aria-labelled-by.stories';
+
+
+
+# Aria-Labelledby
+
+
+ In the Light DOM, `aria-labelledby` is used to give an element its accessible name by referencing
+ the id of another element or multiple elements that contain the desired text.
+
+
+ This is useful when a simple text label isn't directly associated or when the name needs to be
+ combined from different pieces of text.
+
+### I. Referencing Within the Same DOM Tree ✔️
+
+
+
Light DOM → Light DOM
+
+
+
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
+
+
+
Light DOM → Shadow DOM
+
Slotted Content → Shadow DOM
+
+
+Standard `aria-labelledby` cannot reference elements located inside a Shadow DOM from outside of it. This is because IDs inside a Shadow DOM are encapsulated and not accessible from the Light DOM or other Shadow DOMs.
+
+##### Possible Workarounds
+
+###### 1. `Element:ariaLabelledByElements` (Non SSR compatible: to be tested)
+
+Light DOM → Shadow DOM Example
+
+
+
+
+
+Slotted Content → Shadow DOM Example
+
+
+
+
+
+###### 2. Set `aria-labelledby`on the host (for SSR Components: to be tested)
+
+An option is to set the following attributes directly on the host of the target component:
+
+
+
the `aria-labelledby`
+
a semantic `role` (e.g. `textbox`, `button`)
+
`tabindex="0"`
+
+
+Light DOM → Shadow DOM Example
+
+
+Slotted Content → Shadow DOM Example
+
+
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+
+
+
Shadow DOM → Light DOM
+
Shadow DOM → Slotted Content
+
+
+Similarly to the previous case, referencing an element located outside a Shadow DOM from an element inside that Shadow DOM using standard `aria-labelledby` is not possible. The strong encapsulation of the Shadow DOM prevents elements within it from directly accessing and referencing the IDs of elements in the Light DOM.
+
+##### Possible Workaround
+
+An option is to set the `id` directly on the host of the referencing element. Please note that, in this case all the visible text inside the referencing component will be assigned as the Accessible Name of the target element.
+
+
+
+##### IV. Referencing From One Shadow DOM To Another Shadow DOM
+
+
+
Shadow DOM → Other Shadow DOM
+
+
+Referencing an element located inside one Shadow DOM from an element located inside a different, separate Shadow DOM using standard `aria-labelledby` is also not possible. Similar to the other cross-boundary scenarios, the IDs are scoped within their respective Shadow DOMs.
+
+##### Possible Workaround
+
+In this case, in order for the relationship to work, the referencing element must have the `id` directly set on its host (see workaround of case III) and the target element must have the `aria-labelledby`, `role` and `tabindex="0"` set on its host (see workaround of case II).
+
+
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-labelledby/aria-labelledby.stories.ts b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-labelledby/aria-labelledby.stories.ts
new file mode 100644
index 0000000000..5af88a2f35
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-labelledby/aria-labelledby.stories.ts
@@ -0,0 +1,105 @@
+import { StoryObj, Args } from '@storybook/web-components';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+ id: '76ade552-2c03-4d6d-9dce-28daa340f7d5',
+ title:
+ 'Accessibility Practices/Foundational Structure And Semantics/Reference Relationships/Crossing The Shadow Dom/Aria-LabelledBy',
+ parameters: {
+ badges: [],
+ },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+export const ExampleHTML: Story = {
+ render: () => html`
+ My Text
+
+
+
+ `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Light DOM (Element) workaround setting programmatically the relevant Element property
+export const Example2: Story = {
+ argTypes: {
+ workaround: {
+ name: 'Workaround',
+ control: {
+ type: 'radio',
+ },
+ options: ['none', 'ariaLabelledByElements'],
+ },
+ },
+ args: {
+ workaround: 'none',
+ },
+ render: (args: Args) => html`
+ My Text
+
+ `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Slotted Content (Element) workaround setting programmatically the relevant Element property
+export const Example3: Story = {
+ argTypes: {
+ workaround: {
+ name: 'Workaround',
+ control: {
+ type: 'radio',
+ },
+ options: ['none', 'ariaLabelledByElements'],
+ },
+ },
+ args: {
+ workaround: 'none',
+ },
+ render: (args: Args) => html`
+ My Text
+ `,
+};
+
+// Case: Referencing from Shadow Dom to the Light DOM workaround with aria-labelledby directly set on host
+export const Example4: Story = {
+ render: () => html`
+ My Text
+
+ `,
+};
+
+// Case: Referencing from Shadow Dom to Slotted Content (Light) DOM workaround with aria-labelledby directly set on host
+export const Example5: Story = {
+ render: () => html`
+ My Text
+ `,
+};
+
+// Case: Standard Light DOM to Shadow DOM workaround
+export const Example6: Story = {
+ render: () => html`
+
+
+
+
+ `,
+};
+
+// Case: Shadow DOM to other Shadow Dom workaround
+export const Example7: Story = {
+ render: () => html`
+
+
+ `,
+};
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-roles/list-role/list-role.docs.mdx b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-roles/list-role/list-role.docs.mdx
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-roles/list-role/list-role.stories.ts b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-roles/list-role/list-role.stories.ts
new file mode 100644
index 0000000000..f3f60e905e
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/aria-roles/list-role/list-role.stories.ts
@@ -0,0 +1,81 @@
+import { StoryObj } from '@storybook/web-components';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+ id: '76ade552-2c03-4d6d-9dce-28daa346f456',
+ title:
+ 'Accessibility Practices/Foundational Structure And Semantics/Reference Relationships/Crossing The Shadow Dom/Aria-Roles/List Role',
+ parameters: {
+ badges: [],
+ },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+export const ExampleHTML: Story = {
+ render: () => html`
+
+
item 1
+
item 2
+
item 3
+
+ `,
+};
+
+// Case: Light Dom to child components with Slotted content
+export const Example1a: Story = {
+ render: () => html`
+
+
+
item 1
+
item 2
+
item 3
+
+
+ `,
+};
+
+// Case: Parent in the Light - children with Slotted content same component
+export const Example1b: Story = {
+ render: () => html`
+
+
item 1
+
item 2
+
item 3
+
+ `,
+};
+
+// Case: Parent in the Light (Component host) -> Children in the ShadowDOM
+export const Example2a: Story = {
+ render: () =>
+ html` `,
+};
+
+// Case: Parent in Light (slotted content) - Children in the ShadowDOM
+export const Example2b: Story = {
+ render: () =>
+ html`
+ `,
+};
+
+// Case: Parent in the Shadow - Children in the Light
+export const Example3: Story = {
+ render: () => html`
+
+
item 1
+
item 2
+
item 3
+
+ `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Slotted Content (Element)
+export const Example4: Story = {
+ render: () => html` `,
+};
diff --git a/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/for/for.docs.mdx
new file mode 100644
index 0000000000..ff70e5dd22
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/functional-structure-and-semantics/reference-relationships/crossing-the-shadow-dom/for/for.docs.mdx
@@ -0,0 +1,106 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/blocks';
+import * as CCR from './for.stories';
+
+
+
+# for
+
+##
+
+
The native HTML `for`/`id` relationship is a fundamental way to connect a `