From 65bb519f2fedc1735b793a26baec4c06890f914f Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Mon, 18 Aug 2025 10:44:34 +0200
Subject: [PATCH 01/29] add for-label story and demo target component

---
 packages/documentation/.storybook/preview.ts  |   2 +
 .../src/demo-components/demo-button.ts        |  43 +++++++
 .../src/demo-components/demo-target.ts        |  81 ++++++++++++
 .../src/demo-components/index.ts              |   2 +
 .../for/for.docs.mdx                          |  62 +++++++++
 .../for/for.stories.ts                        | 120 ++++++++++++++++++
 .../documentation/types/demo-components.ts    |   8 ++
 packages/documentation/types/index.ts         |   1 +
 8 files changed, 319 insertions(+)
 create mode 100644 packages/documentation/src/demo-components/demo-button.ts
 create mode 100644 packages/documentation/src/demo-components/demo-target.ts
 create mode 100644 packages/documentation/src/demo-components/index.ts
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
 create mode 100644 packages/documentation/types/demo-components.ts

diff --git a/packages/documentation/.storybook/preview.ts b/packages/documentation/.storybook/preview.ts
index 52d91c8f1d..1a1b29d779 100644
--- a/packages/documentation/.storybook/preview.ts
+++ b/packages/documentation/.storybook/preview.ts
@@ -19,6 +19,8 @@ import './styles/preview.scss';
 import { SyntaxHighlighter } from 'storybook/internal/components';
 import scss from 'react-syntax-highlighter/dist/esm/languages/prism/scss';
 
+import '../src/demo-components';
+
 SyntaxHighlighter.registerLanguage('scss', scss);
 
 export const SourceDarkScheme = true;
diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
new file mode 100644
index 0000000000..cf7bb9c731
--- /dev/null
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -0,0 +1,43 @@
+export class DemoButton extends HTMLElement {
+  static get observedAttributes() {
+    return ['aria-labelledby-id', 'aria-describedby-id'];
+  }
+
+  private ariaLabelledbyId?: string;
+  private ariaDescribedbyId?: string;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'aria-labelledby-id') this.ariaLabelledbyId = newValue;
+    if (name === 'aria-describedby-id') this.ariaDescribedbyId = newValue;
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    this.shadowRoot.innerHTML = `
+      <div 
+        class="btn btn-primary"
+        role="button"
+        tabindex="0"
+        ${this.ariaLabelledbyId ? `aria-labelledby="${this.ariaLabelledbyId}"` : ''}
+        ${this.ariaDescribedbyId ? `aria-describedby="${this.ariaDescribedbyId}"` : ''}
+      >
+        <slot name="label-slot"></slot>
+        <div>
+          <post-icon name="1022"></post-icon>
+        </div>
+      </div>
+    `;
+  }
+}
+
+customElements.define('demo-button', DemoButton);
diff --git a/packages/documentation/src/demo-components/demo-target.ts b/packages/documentation/src/demo-components/demo-target.ts
new file mode 100644
index 0000000000..cd89d7cdff
--- /dev/null
+++ b/packages/documentation/src/demo-components/demo-target.ts
@@ -0,0 +1,81 @@
+export class DemoTarget extends HTMLElement {
+  static get observedAttributes() {
+    return ['workaround', 'aria-labelledby-id', 'target-version'];
+  }
+
+  private workaround?: string;
+  private ariaLabelledbyId?: string;
+  private targetVersion?: '1' | '2' | '3';
+  private internalEl?: HTMLElement;
+  private slotEl?: HTMLSlotElement;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'workaround') this.workaround = newValue;
+    if (name === 'aria-labelledby-id') this.ariaLabelledbyId = newValue;
+    if (name === 'target-version') this.targetVersion = newValue as '1' | '2' | '3';
+
+    this.render();
+  }
+
+  private setupAriaLabelledBy() {
+    if (!this.internalEl) return;
+
+    if (this.targetVersion === '1') {
+      const labelEl = document.querySelector(`[for="${this.ariaLabelledbyId}"]`);
+      this.internalEl.ariaLabelledByElements =
+        this.workaround === 'ariaLabelledByElements' && labelEl ? [labelEl] : [];
+    } else if (this.targetVersion === '2') {
+      if (this.slotEl && this.workaround === 'ariaLabelledByElements') {
+        const assignedElements = this.slotEl.assignedElements({ flatten: true });
+        const labelElement = assignedElements.find(el => el.tagName === 'LABEL');
+        this.internalEl.ariaLabelledByElements = labelElement ? [labelElement] : [];
+      } else {
+        this.internalEl.ariaLabelledByElements = [];
+      }
+    } else if (this.targetVersion === '3') {
+      // Target3 doesn't have an input; just make div focusable
+      // this.setAttribute('tabindex', '0');
+      // this.setAttribute('role', 'textbox');
+    }
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+
+    if (this.targetVersion === '2') {
+      this.shadowRoot.innerHTML = `
+        <slot name="label-slot"></slot>
+        <input id="internal">
+      `;
+      this.slotEl = this.shadowRoot.querySelector('slot[name="label-slot"]') as HTMLSlotElement;
+      this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
+    } else if (this.targetVersion === '3') {
+      this.shadowRoot.innerHTML = `
+        <slot name="label-slot"></slot>
+        <input id="internal">
+        </input>
+      `;
+      this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
+    } else {
+      // default to target1
+      this.shadowRoot.innerHTML = `
+        <input id="internal">
+        <slot></slot>
+      `;
+      this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
+    }
+
+    this.setupAriaLabelledBy();
+  }
+}
+
+customElements.define('demo-target', DemoTarget);
diff --git a/packages/documentation/src/demo-components/index.ts b/packages/documentation/src/demo-components/index.ts
new file mode 100644
index 0000000000..b104b2ee97
--- /dev/null
+++ b/packages/documentation/src/demo-components/index.ts
@@ -0,0 +1,2 @@
+import './demo-button';
+import './demo-target';
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
new file mode 100644
index 0000000000..33be19dea3
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -0,0 +1,62 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import * as CCR from './for.stories';
+
+<Meta of={CCR} />
+
+# for
+
+##
+
+<div className="lead">The native HTML `for`/`id` relationship is a fundamental way to connect a `<label>` element to a form control (such as `<input>`, `<select>`, `<textarea>`, etc. or even to a custom form-associated control) within the same document structure (same DOM tree).</div>
+
+<div>This connection is established by setting the for attribute on the `<label>` to match the `id` attribute of the form control it describes. This relationship is crucial for accessibility, as it allows assistive technologies like screen readers to correctly associate and announce the label text when focus is placed on the associated input field, thereby making forms understandable and navigable.</div>
+
+### I. Referencing Within the Same DOM Tree ✔️
+
+<Canvas of={CCR.ExampleHTML} sourceState="shown" />
+
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
+
+<ul>
+  <li>Light DOM → Shadow DOM</li>
+  <li>Slotted Content → Shadow DOM</li>
+</ul>
+
+<p>When the referencing element (e.g. `<label for="...">`) is in the Light DOM and the target element is inside a Shadow DOM, the `for` attribute <b>cannot reference elements inside the Shadow DOM</b> using the standard id mechanism.</p>
+
+##### Possible Workarounds
+
+###### 1. `Element:ariaLabelledByElements`
+
+Defines programmatically the `ariaLabelledByElements` property of the element: `this.internalEl.ariaLabelledByElements = [labelEl]`. This solution creates the relationship without the use of an `id`.
+
+<b>Light DOM → Shadow DOM Example</b>
+<Canvas of={CCR.Example2} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example2} />
+</div>
+
+<b>Slotted Content → Shadow DOM Example</b>
+<Canvas of={CCR.Example3} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example3} />
+</div>
+
+###### 2. Set `aria-labelledby`on the host (for SSR Components) TO START EDIT THAT AND CHECK WITH FOCUS AND INPUT!!!
+
+This solution involves setting the `aria-labelledby` directly on the host. In order for this solution to work, the host must have a set `role=""` along with `tabindex="0"`.
+This defines the label text as the Accessible Name of the component, but NVDA does not announce it when an interactive element (e.g. an `<input>`) exists inside the component.
+
+Directly setting `aria-labelledby` on the host.
+
+<Canvas of={CCR.Example4} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example4} />
+</div>
+
+Setting `aria-labelledby` via `ElementInternals`.
+
+<Canvas of={CCR.Example5} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example5} />
+</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
new file mode 100644
index 0000000000..ac8d540883
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
@@ -0,0 +1,120 @@
+import { StoryObj, Args } from '@storybook/web-components-vite';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+  id: '76ade552-2c03-4d6d-9dce-28daa3401234',
+  title:
+    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/For',
+  parameters: {
+    badges: [],
+  },
+
+  decorators: [story => html`<div style="width:300px;height:60px;display:block">${story()}</div>`],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+export const ExampleHTML: Story = {
+  render: () => html`
+  
+    <label for="id_0">My Text</label>
+    <input id="id_0"></input>
+  `,
+};
+
+// 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`
+    <label for="id_1">My Text</label>
+    <demo-target
+      target-version="1"
+      workaround="${args.workaround}"
+      aria-labelledby-id="id_1"
+    ></demo-target>
+  `,
+};
+
+// 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`
+    <demo-target target-version="2" workaround="${args.workaround}">
+      <label slot="label-slot">My Text</label></demo-target
+    >
+  `,
+};
+
+// Case: Referencing from Shadow Dom to Light DOM workaround with aria-labelledby directly set on host
+export const Example4: Story = {
+  render: () => html`
+    <demo-target target-version="3" aria-labelledby="id_3">
+      <label id="id_3" slot="label-slot">My Text</label>
+    </demo-target>
+  `,
+};
+
+// Case: Referencing from Shadow Dom to Slotted Content (Light) DOM workaround with aria-labelledby directly set on host
+export const Example5: Story = {
+  render: () => html`
+    <post-test-target4 aria-labelledby="id_5">
+      <label id="id_5" slot="label-slot">My Text</label>
+    </post-test-target4>
+  `,
+};
+
+// Case: Standard Light DOM to Shadow DOM workaround
+export const Example6: Story = {
+  argTypes: {
+    workaround: {
+      name: 'Workaround',
+      control: {
+        type: 'radio',
+      },
+      options: ['none', 'ariaLabelledByElements (not working)'],
+    },
+  },
+  args: {
+    workaround: 'none',
+  },
+  render: (args: Args) => html`
+    <post-test-label workaround="${args.workaround}" id="id_6"> </post-test-label>
+    <input aria-labelledby="id_6"></input>
+  `,
+};
+
+// Case: Shadow DOM to other Shadow Dom workaround
+
+export const Example7: Story = {
+  render: () => html`
+    <post-test-label id="id_7"></post-test-label>
+    <post-test-target3 aria-labelledby="id_7"></post-test-target3>
+  `,
+};
diff --git a/packages/documentation/types/demo-components.ts b/packages/documentation/types/demo-components.ts
new file mode 100644
index 0000000000..630956c70f
--- /dev/null
+++ b/packages/documentation/types/demo-components.ts
@@ -0,0 +1,8 @@
+declare global {
+  interface Element {
+    ariaLabelledByElements: Element[];
+    ariaDescribedByElements: Element[];
+  }
+}
+
+export {};
diff --git a/packages/documentation/types/index.ts b/packages/documentation/types/index.ts
index da12ab5f30..1273eb6ad2 100644
--- a/packages/documentation/types/index.ts
+++ b/packages/documentation/types/index.ts
@@ -1,2 +1,3 @@
 export * from './package';
 export * from './storybook';
+export * from './demo-components';

From 49a5f6663c189e22d23fa0b33a3ccec2591260f4 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Fri, 29 Aug 2025 16:28:39 +0200
Subject: [PATCH 02/29] finish for -label stories and components

---
 .../src/demo-components/demo-label.ts         | 31 ++++++++++++++++
 .../src/demo-components/demo-target.ts        | 21 ++++++-----
 .../src/demo-components/index.ts              |  1 +
 .../for/for.docs.mdx                          | 37 +++++++++++++------
 .../for/for.stories.ts                        | 36 ++++++------------
 5 files changed, 81 insertions(+), 45 deletions(-)
 create mode 100644 packages/documentation/src/demo-components/demo-label.ts

diff --git a/packages/documentation/src/demo-components/demo-label.ts b/packages/documentation/src/demo-components/demo-label.ts
new file mode 100644
index 0000000000..1a03cc20f0
--- /dev/null
+++ b/packages/documentation/src/demo-components/demo-label.ts
@@ -0,0 +1,31 @@
+export class DemoLabel extends HTMLElement {
+  static get observedAttributes() {
+    return ['for'];
+  }
+
+  private for!: string;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'for') this.for = newValue;
+
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    this.shadowRoot.innerHTML = `
+      <label>My Text</label>
+    `;
+  }
+}
+
+customElements.define('demo-label', DemoLabel);
diff --git a/packages/documentation/src/demo-components/demo-target.ts b/packages/documentation/src/demo-components/demo-target.ts
index cd89d7cdff..c5b7ea667f 100644
--- a/packages/documentation/src/demo-components/demo-target.ts
+++ b/packages/documentation/src/demo-components/demo-target.ts
@@ -28,11 +28,13 @@ export class DemoTarget extends HTMLElement {
 
   private setupAriaLabelledBy() {
     if (!this.internalEl) return;
-
+    // Version #1
     if (this.targetVersion === '1') {
       const labelEl = document.querySelector(`[for="${this.ariaLabelledbyId}"]`);
       this.internalEl.ariaLabelledByElements =
         this.workaround === 'ariaLabelledByElements' && labelEl ? [labelEl] : [];
+
+      // Version #2
     } else if (this.targetVersion === '2') {
       if (this.slotEl && this.workaround === 'ariaLabelledByElements') {
         const assignedElements = this.slotEl.assignedElements({ flatten: true });
@@ -41,16 +43,18 @@ export class DemoTarget extends HTMLElement {
       } else {
         this.internalEl.ariaLabelledByElements = [];
       }
-    } else if (this.targetVersion === '3') {
-      // Target3 doesn't have an input; just make div focusable
-      // this.setAttribute('tabindex', '0');
-      // this.setAttribute('role', 'textbox');
+    } // Version #3
+    else if (this.targetVersion === '3') {
+      console.log(this.ariaLabelledbyId);
+      const labelEl = document.querySelector(`#${this.ariaLabelledbyId}`);
+      console.log(labelEl);
+      this.internalEl.ariaLabelledByElements = labelEl ? [labelEl] : [];
     }
   }
 
   private render() {
     if (!this.shadowRoot) return;
-
+    //Version #2
     if (this.targetVersion === '2') {
       this.shadowRoot.innerHTML = `
         <slot name="label-slot"></slot>
@@ -59,14 +63,13 @@ export class DemoTarget extends HTMLElement {
       this.slotEl = this.shadowRoot.querySelector('slot[name="label-slot"]') as HTMLSlotElement;
       this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
     } else if (this.targetVersion === '3') {
+      // Version #3
       this.shadowRoot.innerHTML = `
-        <slot name="label-slot"></slot>
         <input id="internal">
-        </input>
       `;
       this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
     } else {
-      // default to target1
+      // Version #1
       this.shadowRoot.innerHTML = `
         <input id="internal">
         <slot></slot>
diff --git a/packages/documentation/src/demo-components/index.ts b/packages/documentation/src/demo-components/index.ts
index b104b2ee97..500d1d5e93 100644
--- a/packages/documentation/src/demo-components/index.ts
+++ b/packages/documentation/src/demo-components/index.ts
@@ -1,2 +1,3 @@
 import './demo-button';
 import './demo-target';
+import './demo-label';
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
index 33be19dea3..3e83708ca6 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -7,9 +7,9 @@ import * as CCR from './for.stories';
 
 ##
 
-<div className="lead">The native HTML `for`/`id` relationship is a fundamental way to connect a `<label>` element to a form control (such as `<input>`, `<select>`, `<textarea>`, etc. or even to a custom form-associated control) within the same document structure (same DOM tree).</div>
+<div className="lead">The native HTML `for`/`id` relationship is a fundamental way to connect a `<label>` element to a form control, such as `<input>`, `<select>`, `<textarea>`, etc. or even to a custom form-associated control within the same DOM.</div>
 
-<div>This connection is established by setting the for attribute on the `<label>` to match the `id` attribute of the form control it describes. This relationship is crucial for accessibility, as it allows assistive technologies like screen readers to correctly associate and announce the label text when focus is placed on the associated input field, thereby making forms understandable and navigable.</div>
+<div>This connection is established by setting the for attribute on the `<label>` to match the `id` attribute of the form control it describes. This relationship is crucial for accessibility, as it allows assistive technologies like screen readers to correctly associate and announce the label text when focus is placed on the associated input field.</div>
 
 ### I. Referencing Within the Same DOM Tree ✔️
 
@@ -26,7 +26,7 @@ import * as CCR from './for.stories';
 
 ##### Possible Workarounds
 
-###### 1. `Element:ariaLabelledByElements`
+###### `Element:ariaLabelledByElements`
 
 Defines programmatically the `ariaLabelledByElements` property of the element: `this.internalEl.ariaLabelledByElements = [labelEl]`. This solution creates the relationship without the use of an `id`.
 
@@ -42,19 +42,34 @@ Defines programmatically the `ariaLabelledByElements` property of the element: `
   <Controls of={CCR.Example3} />
 </div>
 
-###### 2. Set `aria-labelledby`on the host (for SSR Components) TO START EDIT THAT AND CHECK WITH FOCUS AND INPUT!!!
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
 
-This solution involves setting the `aria-labelledby` directly on the host. In order for this solution to work, the host must have a set `role=""` along with `tabindex="0"`.
-This defines the label text as the Accessible Name of the component, but NVDA does not announce it when an interactive element (e.g. an `<input>`) exists inside the component.
+<ul>
+  <li>Shadow DOM → Light DOM</li>
+  <li>Shadow DOM → Slotted Content</li>
+</ul>
+<p>
+  A `for` attribute on an element inside a Shadow DOM{' '}
+  <b>cannot be used to reference the id of an element outside that Shadow DOM</b> (in the Light DOM
+  or an ancestor Shadow DOM). The way the HTML for attribute resolves an id is strictly limited to
+  the element's shadow-including tree.
+</p>
+
+##### Possible Workaround
 
-Directly setting `aria-labelledby` on the host.
+A possible workaround is to set directly an `id` on the host of the referencing element and an `aria-labelledby`on the target element.
 
 <Canvas of={CCR.Example4} sourceState="shown" />
-<div className="hide-col-default">
-  <Controls of={CCR.Example4} />
-</div>
 
-Setting `aria-labelledby` via `ElementInternals`.
+### IV.Referencing From a Shadow DOM Out to another Shadow DOM ❌
+
+<ul>
+  <li>Shadow DOM → Other Shadow DOM</li>
+</ul>
+
+##### Possible Workaround
+
+A workaround for this case combines approaches II and III: using `Element.ariaLabelledByElements` to set an `aria-labelledby` attribute on the Shadow DOM `input`, linking it to an ID defined on the host element of the `label` component.
 
 <Canvas of={CCR.Example5} sourceState="shown" />
 <div className="hide-col-default">
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
index ac8d540883..3120c90da6 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
@@ -72,26 +72,8 @@ export const Example3: Story = {
   `,
 };
 
-// Case: Referencing from Shadow Dom to Light DOM workaround with aria-labelledby directly set on host
-export const Example4: Story = {
-  render: () => html`
-    <demo-target target-version="3" aria-labelledby="id_3">
-      <label id="id_3" slot="label-slot">My Text</label>
-    </demo-target>
-  `,
-};
-
-// Case: Referencing from Shadow Dom to Slotted Content (Light) DOM workaround with aria-labelledby directly set on host
-export const Example5: Story = {
-  render: () => html`
-    <post-test-target4 aria-labelledby="id_5">
-      <label id="id_5" slot="label-slot">My Text</label>
-    </post-test-target4>
-  `,
-};
-
 // Case: Standard Light DOM to Shadow DOM workaround
-export const Example6: Story = {
+export const Example4: Story = {
   argTypes: {
     workaround: {
       name: 'Workaround',
@@ -104,17 +86,21 @@ export const Example6: Story = {
   args: {
     workaround: 'none',
   },
-  render: (args: Args) => html`
-    <post-test-label workaround="${args.workaround}" id="id_6"> </post-test-label>
-    <input aria-labelledby="id_6"></input>
+  render: () => html`
+    <demo-label id="id_2"> </demo-label>
+    <input aria-labelledby="id_2"></input>
   `,
 };
 
 // Case: Shadow DOM to other Shadow Dom workaround
 
-export const Example7: Story = {
+export const Example5: Story = {
   render: () => html`
-    <post-test-label id="id_7"></post-test-label>
-    <post-test-target3 aria-labelledby="id_7"></post-test-target3>
+    <demo-label id="id_3"></demo-label>
+    <demo-target
+      target-version="3"
+      aria-labelledby-id="id_3"
+      workaround="ariaLabelledByElements"
+    ></demo-target>
   `,
 };

From 42fc24bea231f4c7c97d5d59bfa812cba13a12d9 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Mon, 1 Sep 2025 11:28:20 +0200
Subject: [PATCH 03/29] add aria-labelledby story and web components

---
 .../src/demo-components/demo-button.ts        |  43 +++++--
 .../src/demo-components/demo-span.ts          |  31 +++++
 .../aria-labelledby/aria-labelledby.docs.mdx  |  56 +++++++++
 .../aria-labelledby.stories.ts                | 108 ++++++++++++++++++
 .../for/for.stories.ts                        |   2 +-
 5 files changed, 229 insertions(+), 11 deletions(-)
 create mode 100644 packages/documentation/src/demo-components/demo-span.ts
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts

diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index cf7bb9c731..d964587483 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -1,10 +1,13 @@
 export class DemoButton extends HTMLElement {
   static get observedAttributes() {
-    return ['aria-labelledby-id', 'aria-describedby-id'];
+    return ['button-version', 'workaround', 'aria-labelledby-id', 'aria-describedby-id'];
   }
-
+  private buttonVersion?: '1' | '2' | '3';
+  private workaround?: string;
+  private internalButton?: HTMLElement;
   private ariaLabelledbyId?: string;
   private ariaDescribedbyId?: string;
+  private slotEl?: HTMLSlotElement;
 
   constructor() {
     super();
@@ -16,27 +19,47 @@ export class DemoButton extends HTMLElement {
   }
 
   attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'workaround') this.workaround = newValue;
     if (name === 'aria-labelledby-id') this.ariaLabelledbyId = newValue;
     if (name === 'aria-describedby-id') this.ariaDescribedbyId = newValue;
+    if (name === 'button-version') this.buttonVersion = newValue as '1' | '2' | '3';
     this.render();
   }
 
+  private setupAria() {
+    if (this.buttonVersion == '1') {
+      if (this.workaround === 'ariaLabelledByElements') {
+        const labelEl = document.querySelector(`#${this.ariaLabelledbyId}`);
+        if (this.internalButton)
+          this.internalButton.ariaLabelledByElements = labelEl ? [labelEl] : [];
+      }
+    }
+
+    if (this.buttonVersion == '2') {
+      if (this.workaround === 'ariaLabelledByElements' && this.slotEl) {
+        const assignedElements = this.slotEl.assignedElements({ flatten: true });
+        const labelEl = assignedElements.find(el => el.tagName === 'SPAN');
+        if (this.internalButton)
+          this.internalButton.ariaLabelledByElements = labelEl ? [labelEl] : [];
+      }
+    }
+  }
+
   private render() {
     if (!this.shadowRoot) return;
     this.shadowRoot.innerHTML = `
-      <div 
+      <slot name="label-slot"></slot>
+      <div part="button"
         class="btn btn-primary"
         role="button"
         tabindex="0"
-        ${this.ariaLabelledbyId ? `aria-labelledby="${this.ariaLabelledbyId}"` : ''}
-        ${this.ariaDescribedbyId ? `aria-describedby="${this.ariaDescribedbyId}"` : ''}
-      >
-        <slot name="label-slot"></slot>
-        <div>
-          <post-icon name="1022"></post-icon>
-        </div>
+      > <post-icon name="1022"></post-icon>
       </div>
     `;
+
+    this.internalButton = this.shadowRoot.querySelector('div[role="button"]') as HTMLElement;
+    this.slotEl = this.shadowRoot.querySelector('slot[name="label-slot"]') as HTMLSlotElement;
+    this.setupAria();
   }
 }
 
diff --git a/packages/documentation/src/demo-components/demo-span.ts b/packages/documentation/src/demo-components/demo-span.ts
new file mode 100644
index 0000000000..b0a11f4651
--- /dev/null
+++ b/packages/documentation/src/demo-components/demo-span.ts
@@ -0,0 +1,31 @@
+export class DemoSpan extends HTMLElement {
+  static get observedAttributes() {
+    return ['spanId'];
+  }
+
+  private spanId!: string;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'id') this.spanId = newValue;
+
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    this.shadowRoot.innerHTML = `
+      <span>My Text</span>
+    `;
+  }
+}
+
+customElements.define('demo-span', DemoSpan);
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
new file mode 100644
index 0000000000..76a3a60ed6
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -0,0 +1,56 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import * as CCR from './aria-labelledby.stories';
+
+<Meta of={CCR} />
+
+# aria-labelledby
+
+<div className="lead">
+  In the Light DOM, the `aria-labelledby` attribute assigns an accessible name to an element by
+  referencing the ID of one or more elements that provide the descriptive text.
+</div>
+<div>
+  This is particularly useful when a simple text label isn’t directly linked to the element, or when
+  the accessible name needs to be composed from multiple pieces of text.
+</div>
+### I. Referencing Within the Same DOM Tree ✔️
+
+<Canvas of={CCR.ExampleHTML} sourceState="shown" />
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
+
+<ul>
+  <li>Light DOM → Shadow DOM</li>
+  <li>Slotted Content → Shadow DOM</li>
+</ul>
+
+Standard `aria-labelledby` cannot reference elements inside a Shadow DOM from outside it, because IDs within a Shadow DOM are encapsulated and inaccessible to the Light DOM or other Shadow DOMs.
+
+##### Possible Workarounds
+
+###### 1. `Element:ariaLabelledByElements`
+
+<b>Light DOM → Shadow DOM Example</b>
+<Canvas of={CCR.Example2} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example2} />
+</div>
+
+<b>Slotted Content → Shadow DOM Example</b>
+<Canvas of={CCR.Example3} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example3} />
+</div>
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+
+<ul>
+  <li>Shadow DOM → Light DOM</li>
+  <li>Shadow DOM → Slotted Content</li>
+</ul>
+
+Referencing an element in the light DOM from within the Shadow DOM using standard `aria-labelledby` is not possible.
+
+##### Possible Workaround
+
+An option is to set the `id` directly on the host of the labeling component. 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.
+
+<Canvas of={CCR.Example4} sourceState="shown" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
new file mode 100644
index 0000000000..f49a013b20
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
@@ -0,0 +1,108 @@
+import { StoryObj, Args } from '@storybook/web-components-vite';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+  id: '76ade552-2c03-4d6d-9dce-28daa3405678',
+  title:
+    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/aria-labelledby',
+  parameters: {
+    badges: [],
+  },
+
+  decorators: [story => html`<div style="width:300px;height:60px;display:block">${story()}</div>`],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+export const ExampleHTML: Story = {
+  render: () => html`
+    <span id="id_1">My Text</span>
+    <div class="btn btn-primary" aria-labelledby="id_1" role="button" tabindex="0">
+      <post-icon name="1022"></post-icon>
+    </div>
+  `,
+};
+
+// 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`
+    <span id="id_2">My Text</span>
+    <demo-button
+      button-version="1"
+      aria-labelledby-id="id_2"
+      workaround="${args.workaround}"
+    ></demo-button>
+  `,
+};
+
+// 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`
+    <demo-button button-version="2" workaround="${args.workaround}"
+      ><span slot="label-slot">My Text</span></demo-button
+    >
+  `,
+};
+
+// Case: Standard Light DOM to Shadow DOM workaround
+export const Example4: Story = {
+  render: () => html`
+    <demo-span id="id_6"></demo-span>
+    <div class="btn btn-primary" aria-labelledby="id_6" role="button" tabindex="0">
+      <post-icon name="1022"></post-icon>
+    </div>
+  `,
+};
+
+// Case: Referencing from Shadow Dom to the Light DOM workaround with aria-labelledby directly set on host
+export const Example6: Story = {
+  render: () => html`
+    <span id="id_4">My Text</span>
+    <post-test-button aria-labelledby-id="id_4"></post-test-button>
+  `,
+};
+
+// Case: Referencing from Shadow Dom to Slotted Content (Light) DOM workaround with aria-labelledby directly set on host
+export const Example5: Story = {
+  render: () => html`
+    <post-test-button aria-labelledby-id="id_5"
+      ><span slot="label-slot" id="id_5">My Text</span></post-test-button
+    >
+  `,
+};
+
+// Case: Shadow DOM to other Shadow Dom workaround
+export const Example7: Story = {
+  render: () => html`
+    <post-test-span id="id_7"></post-test-span>
+    <post-test-button aria-labelledby="id_7"></post-test-button>
+  `,
+};
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
index 3120c90da6..3ff53f63be 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
@@ -5,7 +5,7 @@ import { html } from 'lit';
 const meta: MetaExtended = {
   id: '76ade552-2c03-4d6d-9dce-28daa3401234',
   title:
-    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/For',
+    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/for',
   parameters: {
     badges: [],
   },

From 700a4dae945eb253c3dc5c1a0e94e5358eb939e9 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Mon, 8 Sep 2025 17:32:12 +0200
Subject: [PATCH 04/29] added aria-describedby and list-role stories

---
 .../src/demo-components/demo-button.ts        | 21 +++-
 .../demo-components/demo-list-item-group.ts   | 39 ++++++++
 .../src/demo-components/demo-list-item.ts     | 20 ++++
 .../src/demo-components/demo-list.ts          | 42 ++++++++
 .../src/demo-components/index.ts              |  1 +
 .../aria-describedby.docs.mdx                 | 71 ++++++++++++++
 .../aria-describedby.stories.ts               | 95 +++++++++++++++++++
 .../aria-labelledby/aria-labelledby.docs.mdx  | 14 ++-
 .../aria-labelledby.stories.ts                | 31 ++----
 .../aria-role-list/aria-role-list.docs.mdx    | 60 ++++++++++++
 .../aria-role-list/aria-role-list.stories.ts  | 85 +++++++++++++++++
 11 files changed, 455 insertions(+), 24 deletions(-)
 create mode 100644 packages/documentation/src/demo-components/demo-list-item-group.ts
 create mode 100644 packages/documentation/src/demo-components/demo-list-item.ts
 create mode 100644 packages/documentation/src/demo-components/demo-list.ts
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts

diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index d964587483..53fcd403e8 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -2,7 +2,7 @@ export class DemoButton extends HTMLElement {
   static get observedAttributes() {
     return ['button-version', 'workaround', 'aria-labelledby-id', 'aria-describedby-id'];
   }
-  private buttonVersion?: '1' | '2' | '3';
+  private buttonVersion?: '1' | '2' | '3' | '4';
   private workaround?: string;
   private internalButton?: HTMLElement;
   private ariaLabelledbyId?: string;
@@ -43,6 +43,25 @@ export class DemoButton extends HTMLElement {
           this.internalButton.ariaLabelledByElements = labelEl ? [labelEl] : [];
       }
     }
+
+    if (this.buttonVersion == '3') {
+      if (this.workaround === 'ariaDescribedByElements') {
+        const labelEl = document.querySelector(`#${this.ariaDescribedbyId}`);
+        console.log('version 3', labelEl);
+        if (this.internalButton)
+          this.internalButton.ariaDescribedByElements = labelEl ? [labelEl] : [];
+      }
+    }
+
+    if (this.buttonVersion == '4') {
+      if (this.workaround === 'ariaDescribedByElements' && this.slotEl) {
+        const assignedElements = this.slotEl.assignedElements({ flatten: true });
+
+        const labelEl = assignedElements.find(el => el.tagName === 'SPAN');
+        if (this.internalButton)
+          this.internalButton.ariaDescribedByElements = labelEl ? [labelEl] : [];
+      }
+    }
   }
 
   private render() {
diff --git a/packages/documentation/src/demo-components/demo-list-item-group.ts b/packages/documentation/src/demo-components/demo-list-item-group.ts
new file mode 100644
index 0000000000..ae03b010c0
--- /dev/null
+++ b/packages/documentation/src/demo-components/demo-list-item-group.ts
@@ -0,0 +1,39 @@
+export class DemoListItemGroup extends HTMLElement {
+  static get observedAttributes() {
+    return ['list-group-version'];
+  }
+
+  private listGroupVersion?: number;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  attributeChangedCallback(name: string, _oldValue: number, newValue: number) {
+    if (name === 'list-group-version') this.listGroupVersion = newValue;
+
+    this.render();
+  }
+
+  connectedCallback() {
+    console.log(this.listGroupVersion);
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    if (this.listGroupVersion == 1) {
+      this.shadowRoot.innerHTML = `
+        <slot name="demo-list-item"></slot>
+      `;
+    } else if (this.listGroupVersion == 2) {
+      this.shadowRoot.innerHTML = `<slot name="list-parent"></slot>
+        <div role="listitem">item 1</div>
+        <div role="listitem">item 2</div>
+        <div role="listitem">item 3</div>`;
+    }
+  }
+}
+
+customElements.define('demo-list-item-group', DemoListItemGroup);
diff --git a/packages/documentation/src/demo-components/demo-list-item.ts b/packages/documentation/src/demo-components/demo-list-item.ts
new file mode 100644
index 0000000000..ff976ce8c4
--- /dev/null
+++ b/packages/documentation/src/demo-components/demo-list-item.ts
@@ -0,0 +1,20 @@
+export class DemoListItem extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    this.shadowRoot.innerHTML = `
+    <div role="listitem">
+      <slot></slot>
+    </div>`;
+  }
+}
+
+customElements.define('demo-list-item', DemoListItem);
diff --git a/packages/documentation/src/demo-components/demo-list.ts b/packages/documentation/src/demo-components/demo-list.ts
new file mode 100644
index 0000000000..c141554f81
--- /dev/null
+++ b/packages/documentation/src/demo-components/demo-list.ts
@@ -0,0 +1,42 @@
+export class DemoList extends HTMLElement {
+  static get observedAttributes() {
+    return ['list-version'];
+  }
+
+  private listVersion?: number;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: number, newValue: number) {
+    if (name === 'list-version') this.listVersion = newValue;
+    this.render();
+  }
+
+  private render() {
+    console.log(this.listVersion);
+    if (!this.shadowRoot) return;
+
+    if (this.listVersion === 1) {
+      this.shadowRoot.innerHTML = `
+        <div>
+          <slot name="demo-list-item"></slot>
+        </div>
+    `;
+    } else if (this.listVersion === 2) {
+      this.shadowRoot.innerHTML = `<div role="list" tabindex="0">
+          <demo-list-item>item 1</demo-list-item>
+          <demo-list-item>item 2</demo-list-item>
+          <demo-list-item>item 3</demo-list-item>
+        </div>`;
+    }
+  }
+}
+
+customElements.define('demo-list', DemoList);
diff --git a/packages/documentation/src/demo-components/index.ts b/packages/documentation/src/demo-components/index.ts
index 500d1d5e93..ce0021e13c 100644
--- a/packages/documentation/src/demo-components/index.ts
+++ b/packages/documentation/src/demo-components/index.ts
@@ -1,3 +1,4 @@
 import './demo-button';
 import './demo-target';
 import './demo-label';
+import './demo-list-item-group';
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
new file mode 100644
index 0000000000..ab82dc045c
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -0,0 +1,71 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import * as CCR from './aria-describedby.stories';
+
+<Meta of={CCR} />
+
+# aria-describedby
+
+<div className="lead">
+  In the Light DOM, `aria-describedby` is used to give an element a description by referencing the
+  ID of another element or multiple elements that contain the desired text.
+</div>
+<div>
+  This is useful when a simple text label isn't enough or when the description needs to be combined
+  from different pieces of text.
+</div>
+### I. Referencing Within the Same DOM Tree ✔️
+
+<Canvas of={CCR.ExampleHTML} sourceState="shown" />
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
+
+<ul>
+  <li>Light DOM → Shadow DOM</li>
+  <li>Slotted Content → Shadow DOM</li>
+</ul>
+
+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`
+
+<b>Light DOM → Shadow DOM Example</b>
+<Canvas of={CCR.Example2} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example2} />
+</div>
+
+<b>Slotted Content → Shadow DOM Example</b>
+<Canvas of={CCR.Example3} sourceState="shown" />
+<div className="hide-col-default">
+  <Controls of={CCR.Example3} />
+</div>
+
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+
+<ul>
+  <li>Shadow DOM → Light DOM</li>
+  <li>Shadow DOM → Slotted Content</li>
+</ul>
+
+Referencing an element in the light DOM from within the Shadow DOM using standard `aria-describedeby` is not possible.
+
+##### Possible Workaround
+
+An option is to set the `id` directly on the host of the referencing element. In this case all the visible text inside the referencing component will be assigned as the Accessible Description of the target element.
+
+<Canvas of={CCR.Example4} sourceState="shown" />
+
+### IV. Referencing From One Shadow DOM To Another Shadow DOM ❌
+
+<ul>
+  <li>Shadow DOM → Other Shadow DOM</li>
+</ul>
+
+##### Possible Workaround
+
+A workaround for this case combines approaches II and III: using Element.ariaDescribedByElements to set an aria-describedby attribute on the Shadow DOM button, linking it to an ID defined on the host element of the labeling component.
+
+⚠️ In contrast to the respective `aria-labelledby` example, <b>NVDA does not announce</b> the accessible description in this scenario.
+
+<Canvas of={CCR.Example5} sourceState="shown" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
new file mode 100644
index 0000000000..95e79e9698
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
@@ -0,0 +1,95 @@
+import { StoryObj, Args } from '@storybook/web-components-vite';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+  id: '76ade552-2c03-4d6d-9dce-28daa3405910',
+  title:
+    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/aria-describedby',
+  parameters: {
+    badges: [],
+  },
+
+  decorators: [story => html`<div style="width:300px;height:60px;display:block">${story()}</div>`],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+export const ExampleHTML: Story = {
+  render: () => html`
+    <div class="btn btn-primary" aria-describedby="id_1" role="button" tabindex="0">
+      <post-icon name="1022"></post-icon>
+    </div>
+    <span id="id_1">My Description</span>
+  `,
+};
+
+// 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`
+    <demo-button
+      button-version="3"
+      aria-describedby-id="id_1"
+      workaround="${args.workaround}"
+    ></demo-button>
+    <span id="id_1">My Description</span>
+  `,
+};
+
+// 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`
+    <demo-button button-version="4" workaround="${args.workaround}"
+      ><span slot="label-slot">My Description</span></demo-button
+    >
+  `,
+};
+
+// Case: Standard Light DOM to Shadow DOM workaround
+export const Example4: Story = {
+  render: () => html`
+    <div class="btn btn-primary" aria-describedby="id_2" role="button" tabindex="0">
+      <post-icon name="1022"></post-icon>
+    </div>
+    <demo-span id="id_2">My description</demo-span>
+  `,
+};
+
+// Case: Shadow DOM to other Shadow Dom workaround
+export const Example5: Story = {
+  render: () => html`
+    <demo-button
+      button-version="3"
+      workaround="ariaDescribedByElements"
+      aria-describedby="id_3"
+    ></demo-button>
+    <demo-span id="id_3">My description</demo-span>
+  `,
+};
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index 76a3a60ed6..b93a0f0d8b 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -51,6 +51,18 @@ Referencing an element in the light DOM from within the Shadow DOM using standar
 
 ##### Possible Workaround
 
-An option is to set the `id` directly on the host of the labeling component. 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.
+An option is to set the `id` directly on the host of the labeling component. In this case all the visible text inside the referencing component will be assigned as the Accessible Name of the target element.
 
 <Canvas of={CCR.Example4} sourceState="shown" />
+
+##### IV. Referencing From One Shadow DOM To Another Shadow DOM
+
+<ul>
+  <li>Shadow DOM → Other Shadow DOM</li>
+</ul>
+
+##### Possible Workaround
+
+A workaround for this case combines approaches II and III: using `Element.ariaLabelledByElements` to set an `aria-labelledby` attribute on the Shadow DOM `button`, linking it to an ID defined on the host element of the labeling component.
+
+<Canvas of={CCR.Example5} sourceState="shown" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
index f49a013b20..c7b20422a0 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
@@ -75,34 +75,21 @@ export const Example3: Story = {
 // Case: Standard Light DOM to Shadow DOM workaround
 export const Example4: Story = {
   render: () => html`
-    <demo-span id="id_6"></demo-span>
-    <div class="btn btn-primary" aria-labelledby="id_6" role="button" tabindex="0">
+    <demo-span id="id_3">My Text</demo-span>
+    <div class="btn btn-primary" aria-labelledby="id_3" role="button" tabindex="0">
       <post-icon name="1022"></post-icon>
     </div>
   `,
 };
 
-// Case: Referencing from Shadow Dom to the Light DOM workaround with aria-labelledby directly set on host
-export const Example6: Story = {
-  render: () => html`
-    <span id="id_4">My Text</span>
-    <post-test-button aria-labelledby-id="id_4"></post-test-button>
-  `,
-};
-
-// Case: Referencing from Shadow Dom to Slotted Content (Light) DOM workaround with aria-labelledby directly set on host
-export const Example5: Story = {
-  render: () => html`
-    <post-test-button aria-labelledby-id="id_5"
-      ><span slot="label-slot" id="id_5">My Text</span></post-test-button
-    >
-  `,
-};
-
 // Case: Shadow DOM to other Shadow Dom workaround
-export const Example7: Story = {
+export const Example5: Story = {
   render: () => html`
-    <post-test-span id="id_7"></post-test-span>
-    <post-test-button aria-labelledby="id_7"></post-test-button>
+    <demo-span id="id_4">My Text</demo-span>
+    <demo-button
+      button-version="1"
+      aria-labelledby-id="id_4"
+      workaround="ariaLabelledByElements"
+    ></demo-button>
   `,
 };
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
new file mode 100644
index 0000000000..1ab2de46df
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -0,0 +1,60 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import * as CCR from './aria-role-list.stories';
+
+<Meta of={CCR} />
+
+# role="list"
+
+<div className="lead">
+  The `role="list"` attribute identifies an element as a list for assistive technologies, signaling
+  it contains related items marked with `role="listitem"`.
+</div>
+
+<div>
+While native elements like `<ul>` have this role implicitly, adding `role="list"` to non-semantic elements (e.g., `<div>`) ensures custom components are recognized as lists by screen readers.
+</div>
+
+### I. All Within the Same DOM Tree ✔️
+
+<ul>
+  <li>Basic HTML Example</li>
+</ul>
+<Canvas of={CCR.ExampleHTML} sourceState="shown" />
+<ul>
+  <li>Light DOM → Component with Slotted Children</li>
+</ul>
+<Canvas of={CCR.Example1a} sourceState="shown" />
+
+<ul>
+  <li> Component host → Same Component Slotted Children</li>
+</ul>
+<Canvas of={CCR.Example1b} sourceState="shown" />
+
+### II. Parent in the Light DOM - Children Into The Shadow DOM
+
+<ul>
+  <li>Light DOM → Shadow DOM ❓</li>
+  <Canvas of={CCR.Example2a} sourceState="shown" />
+</ul>
+<ul>
+  <li>Slotted Parent → Shadow DOM ❌</li>
+  <Canvas of={CCR.Example2b} sourceState="shown" />
+</ul>
+Light DOM elements with an ARIA parent role cannot be associated to children elements with the
+respective ARIA child roles across the Shadow DOM.
+
+### III. Parent in the Shadow DOM - Children Out to the Light DOM ✔️
+
+<ul>
+  <li>Shadow DOM → Light DOM </li>
+</ul>
+
+<Canvas of={CCR.Example3} sourceState="shown" />
+
+### IV. Referencing From One Shadow DOM To Another Shadow DOM ✔️
+
+<ul>
+  <li>Shadow DOM → Other nested Shadow DOM</li>
+</ul>
+
+<Canvas of={CCR.Example4} sourceState="shown" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
new file mode 100644
index 0000000000..16dbc0abf9
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
@@ -0,0 +1,85 @@
+import { StoryObj } from '@storybook/web-components-vite';
+import { MetaExtended } from '@root/types';
+import { html } from 'lit';
+
+const meta: MetaExtended = {
+  id: '76ade552-2c03-4d6d-9dce-28daa3405112',
+  title:
+    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/aria-role-list',
+  parameters: {
+    badges: [],
+  },
+
+  decorators: [story => html`<div style="width:300px;display:block">${story()}</div>`],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// Case: Standard Light DOM to Light DOM
+export const ExampleHTML: Story = {
+  render: () => html`
+    <div role="list" tabindex="0">
+      <div role="listitem">item 1</div>
+      <div role="listitem">item 2</div>
+      <div role="listitem">item 3</div>
+    </div>
+  `,
+};
+
+// Case: Light Dom to child components with Slotted content
+export const Example1a: Story = {
+  render: () => html`
+    <div role="list" tabindex="0">
+      <demo-list-item-group list-group-version="1">
+        <div slot="demo-list-item" role="listitem">item 1</div>
+        <div slot="demo-list-item" role="listitem">item 2</div>
+        <div slot="demo-list-item" role="listitem">item 3</div>
+      </demo-list-item-group>
+    </div>
+  `,
+};
+
+// Case: Parent in the Light - children with Slotted content same component
+export const Example1b: Story = {
+  render: () => html`
+    <demo-list-item-group list-group-version="1" role="list" tabindex="0">
+      <div slot="demo-list-item" role="listitem">item 1</div>
+      <div slot="demo-list-item" role="listitem">item 2</div>
+      <div slot="demo-list-item" role="listitem">item 3</div>
+    </demo-list-item-group>
+  `,
+};
+
+// Case: Parent in the Light (Component host) -> Children in the ShadowDOM
+export const Example2a: Story = {
+  render: () =>
+    html`
+      <demo-list-item-group list-group-version="2" role="list" tabindex="0"> </demo-list-item-group>
+    `,
+};
+
+// Case: Parent in Light (slotted content) - Children in the ShadowDOM
+export const Example2b: Story = {
+  render: () =>
+    html`<demo-list-item-group list-group-version="2" tabindex="0">
+      <div slot="list-parent" role="list"></div>
+    </demo-list-item-group>`,
+};
+
+// Case: Parent in the Shadow - Children in the Light
+export const Example3: Story = {
+  render: () => html`
+    <demo-list role="list" list-version="1" tabindex="0">
+      <div role="listitem" slot="demo-list-item">item 1</div>
+      <div role="listitem" slot="demo-list-item">item 2</div>
+      <div role="listitem" slot="demo-list-item">item 3</div>
+    </demo-list>
+  `,
+};
+
+// Case: Referencing from Shadow DOM (Host Attribute) to Slotted Content (Element)
+export const Example4: Story = {
+  render: () => html`<demo-list list-version="1"></demo-list>`,
+};

From 427be41f95e93716ac5eb88d247aea583e009faf Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 9 Sep 2025 10:59:56 +0200
Subject: [PATCH 05/29] updated stories

---
 .../src/demo-components/demo-button.ts        | 15 +++++++--------
 .../demo-components/demo-list-item-group.ts   |  1 -
 .../src/demo-components/demo-list.ts          | 19 +++++++++----------
 .../src/demo-components/demo-target.ts        | 12 +++++-------
 .../src/demo-components/index.ts              |  2 ++
 .../aria-describedby.stories.ts               |  2 +-
 .../aria-labelledby/aria-labelledby.docs.mdx  |  7 ++++++-
 .../aria-labelledby.stories.ts                |  4 ++--
 .../aria-role-list/aria-role-list.docs.mdx    | 11 ++++++-----
 .../aria-role-list/aria-role-list.stories.ts  | 16 ++++++++++------
 .../for/for.docs.mdx                          |  4 ++++
 .../for/for.stories.ts                        |  4 ++--
 12 files changed, 54 insertions(+), 43 deletions(-)

diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index 53fcd403e8..438a8b73e6 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -1,12 +1,12 @@
 export class DemoButton extends HTMLElement {
   static get observedAttributes() {
-    return ['button-version', 'workaround', 'aria-labelledby-id', 'aria-describedby-id'];
+    return ['button-version', 'workaround', 'arialabelledby-id', 'ariadescribedby-id'];
   }
   private buttonVersion?: '1' | '2' | '3' | '4';
   private workaround?: string;
   private internalButton?: HTMLElement;
-  private ariaLabelledbyId?: string;
-  private ariaDescribedbyId?: string;
+  private arialabelledbyId?: string;
+  private ariadescribedbyId?: string;
   private slotEl?: HTMLSlotElement;
 
   constructor() {
@@ -20,8 +20,8 @@ export class DemoButton extends HTMLElement {
 
   attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
     if (name === 'workaround') this.workaround = newValue;
-    if (name === 'aria-labelledby-id') this.ariaLabelledbyId = newValue;
-    if (name === 'aria-describedby-id') this.ariaDescribedbyId = newValue;
+    if (name === 'arialabelledby-id') this.arialabelledbyId = newValue;
+    if (name === 'ariadescribedby-id') this.ariadescribedbyId = newValue;
     if (name === 'button-version') this.buttonVersion = newValue as '1' | '2' | '3';
     this.render();
   }
@@ -29,7 +29,7 @@ export class DemoButton extends HTMLElement {
   private setupAria() {
     if (this.buttonVersion == '1') {
       if (this.workaround === 'ariaLabelledByElements') {
-        const labelEl = document.querySelector(`#${this.ariaLabelledbyId}`);
+        const labelEl = document.querySelector(`#${this.arialabelledbyId}`);
         if (this.internalButton)
           this.internalButton.ariaLabelledByElements = labelEl ? [labelEl] : [];
       }
@@ -46,8 +46,7 @@ export class DemoButton extends HTMLElement {
 
     if (this.buttonVersion == '3') {
       if (this.workaround === 'ariaDescribedByElements') {
-        const labelEl = document.querySelector(`#${this.ariaDescribedbyId}`);
-        console.log('version 3', labelEl);
+        const labelEl = document.querySelector(`#${this.ariadescribedbyId}`);
         if (this.internalButton)
           this.internalButton.ariaDescribedByElements = labelEl ? [labelEl] : [];
       }
diff --git a/packages/documentation/src/demo-components/demo-list-item-group.ts b/packages/documentation/src/demo-components/demo-list-item-group.ts
index ae03b010c0..3ff0edb26a 100644
--- a/packages/documentation/src/demo-components/demo-list-item-group.ts
+++ b/packages/documentation/src/demo-components/demo-list-item-group.ts
@@ -17,7 +17,6 @@ export class DemoListItemGroup extends HTMLElement {
   }
 
   connectedCallback() {
-    console.log(this.listGroupVersion);
     this.render();
   }
 
diff --git a/packages/documentation/src/demo-components/demo-list.ts b/packages/documentation/src/demo-components/demo-list.ts
index c141554f81..0e85c7238b 100644
--- a/packages/documentation/src/demo-components/demo-list.ts
+++ b/packages/documentation/src/demo-components/demo-list.ts
@@ -16,25 +16,24 @@ export class DemoList extends HTMLElement {
 
   attributeChangedCallback(name: string, _oldValue: number, newValue: number) {
     if (name === 'list-version') this.listVersion = newValue;
+
     this.render();
   }
 
   private render() {
-    console.log(this.listVersion);
     if (!this.shadowRoot) return;
-
-    if (this.listVersion === 1) {
+    if (this.listVersion == 1) {
       this.shadowRoot.innerHTML = `
         <div>
-          <slot name="demo-list-item"></slot>
+          <slot></slot>
+        </div>
+    `;
+    } else if (this.listVersion == 2) {
+      this.shadowRoot.innerHTML = `
+        <div role="list" tabindex="0">
+          <slot></slot>
         </div>
     `;
-    } else if (this.listVersion === 2) {
-      this.shadowRoot.innerHTML = `<div role="list" tabindex="0">
-          <demo-list-item>item 1</demo-list-item>
-          <demo-list-item>item 2</demo-list-item>
-          <demo-list-item>item 3</demo-list-item>
-        </div>`;
     }
   }
 }
diff --git a/packages/documentation/src/demo-components/demo-target.ts b/packages/documentation/src/demo-components/demo-target.ts
index c5b7ea667f..3297b0fbbc 100644
--- a/packages/documentation/src/demo-components/demo-target.ts
+++ b/packages/documentation/src/demo-components/demo-target.ts
@@ -1,10 +1,10 @@
 export class DemoTarget extends HTMLElement {
   static get observedAttributes() {
-    return ['workaround', 'aria-labelledby-id', 'target-version'];
+    return ['workaround', 'arialabelledby-id', 'target-version'];
   }
 
   private workaround?: string;
-  private ariaLabelledbyId?: string;
+  private arialabelledbyId?: string;
   private targetVersion?: '1' | '2' | '3';
   private internalEl?: HTMLElement;
   private slotEl?: HTMLSlotElement;
@@ -20,7 +20,7 @@ export class DemoTarget extends HTMLElement {
 
   attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
     if (name === 'workaround') this.workaround = newValue;
-    if (name === 'aria-labelledby-id') this.ariaLabelledbyId = newValue;
+    if (name === 'arialabelledby-id') this.arialabelledbyId = newValue;
     if (name === 'target-version') this.targetVersion = newValue as '1' | '2' | '3';
 
     this.render();
@@ -30,7 +30,7 @@ export class DemoTarget extends HTMLElement {
     if (!this.internalEl) return;
     // Version #1
     if (this.targetVersion === '1') {
-      const labelEl = document.querySelector(`[for="${this.ariaLabelledbyId}"]`);
+      const labelEl = document.querySelector(`[for="${this.arialabelledbyId}"]`);
       this.internalEl.ariaLabelledByElements =
         this.workaround === 'ariaLabelledByElements' && labelEl ? [labelEl] : [];
 
@@ -45,9 +45,7 @@ export class DemoTarget extends HTMLElement {
       }
     } // Version #3
     else if (this.targetVersion === '3') {
-      console.log(this.ariaLabelledbyId);
-      const labelEl = document.querySelector(`#${this.ariaLabelledbyId}`);
-      console.log(labelEl);
+      const labelEl = document.querySelector(`#${this.arialabelledbyId}`);
       this.internalEl.ariaLabelledByElements = labelEl ? [labelEl] : [];
     }
   }
diff --git a/packages/documentation/src/demo-components/index.ts b/packages/documentation/src/demo-components/index.ts
index ce0021e13c..85f6bf2202 100644
--- a/packages/documentation/src/demo-components/index.ts
+++ b/packages/documentation/src/demo-components/index.ts
@@ -1,4 +1,6 @@
 import './demo-button';
 import './demo-target';
 import './demo-label';
+import './demo-list';
+import './demo-list-item';
 import './demo-list-item-group';
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
index 95e79e9698..897dffaf28 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
@@ -44,7 +44,7 @@ export const Example2: Story = {
   render: (args: Args) => html`
     <demo-button
       button-version="3"
-      aria-describedby-id="id_1"
+      ariadescribedby-id="id_1"
       workaround="${args.workaround}"
     ></demo-button>
     <span id="id_1">My Description</span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index b93a0f0d8b..2b0268c983 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -40,6 +40,9 @@ Standard `aria-labelledby` cannot reference elements inside a Shadow DOM from ou
 <div className="hide-col-default">
   <Controls of={CCR.Example3} />
 </div>
+
+⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
+
 ### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
 
 <ul>
@@ -55,7 +58,7 @@ An option is to set the `id` directly on the host of the labeling component. In
 
 <Canvas of={CCR.Example4} sourceState="shown" />
 
-##### IV. Referencing From One Shadow DOM To Another Shadow DOM
+### IV. Referencing From One Shadow DOM To Another Shadow DOM
 
 <ul>
   <li>Shadow DOM → Other Shadow DOM</li>
@@ -66,3 +69,5 @@ An option is to set the `id` directly on the host of the labeling component. In
 A workaround for this case combines approaches II and III: using `Element.ariaLabelledByElements` to set an `aria-labelledby` attribute on the Shadow DOM `button`, linking it to an ID defined on the host element of the labeling component.
 
 <Canvas of={CCR.Example5} sourceState="shown" />
+
+⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
index c7b20422a0..422eb9fdff 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
@@ -45,7 +45,7 @@ export const Example2: Story = {
     <span id="id_2">My Text</span>
     <demo-button
       button-version="1"
-      aria-labelledby-id="id_2"
+      arialabelledby-id="id_2"
       workaround="${args.workaround}"
     ></demo-button>
   `,
@@ -88,7 +88,7 @@ export const Example5: Story = {
     <demo-span id="id_4">My Text</demo-span>
     <demo-button
       button-version="1"
-      aria-labelledby-id="id_4"
+      arialabelledby-id="id_4"
       workaround="ariaLabelledByElements"
     ></demo-button>
   `,
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
index 1ab2de46df..e2eb9a8219 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -33,15 +33,16 @@ While native elements like `<ul>` have this role implicitly, adding `role="list"
 ### II. Parent in the Light DOM - Children Into The Shadow DOM
 
 <ul>
-  <li>Light DOM → Shadow DOM ❓</li>
-  <Canvas of={CCR.Example2a} sourceState="shown" />
+  <li>Light DOM → Shadow DOM ✔️</li>
+
 </ul>
+  <Canvas of={CCR.Example2a} sourceState="shown" />
+
 <ul>
   <li>Slotted Parent → Shadow DOM ❌</li>
-  <Canvas of={CCR.Example2b} sourceState="shown" />
+
 </ul>
-Light DOM elements with an ARIA parent role cannot be associated to children elements with the
-respective ARIA child roles across the Shadow DOM.
+  <Canvas of={CCR.Example2b} sourceState="shown" />
 
 ### III. Parent in the Shadow DOM - Children Out to the Light DOM ✔️
 
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
index 16dbc0abf9..ef3ef2871f 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
@@ -64,22 +64,26 @@ export const Example2a: Story = {
 export const Example2b: Story = {
   render: () =>
     html`<demo-list-item-group list-group-version="2" tabindex="0">
-      <div slot="list-parent" role="list"></div>
+      <div role="list" tabindex="0" slot="list-parent"></div>
     </demo-list-item-group>`,
 };
 
 // Case: Parent in the Shadow - Children in the Light
 export const Example3: Story = {
   render: () => html`
-    <demo-list role="list" list-version="1" tabindex="0">
-      <div role="listitem" slot="demo-list-item">item 1</div>
-      <div role="listitem" slot="demo-list-item">item 2</div>
-      <div role="listitem" slot="demo-list-item">item 3</div>
+    <demo-list role="list" tabindex="0" list-version="1">
+      <div role="listitem">item 1</div>
+      <div role="listitem">item 2</div>
+      <div role="listitem">item 3</div>
     </demo-list>
   `,
 };
 
 // Case: Referencing from Shadow DOM (Host Attribute) to Slotted Content (Element)
 export const Example4: Story = {
-  render: () => html`<demo-list list-version="1"></demo-list>`,
+  render: () => html`<demo-list list-version="2">
+    <demo-list-item>item 1</demo-list-item>
+    <demo-list-item>item 2</demo-list-item>
+    <demo-list-item>item 3</demo-list-item>
+  </demo-list>`,
 };
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
index 3e83708ca6..0c485e38d5 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -42,6 +42,8 @@ Defines programmatically the `ariaLabelledByElements` property of the element: `
   <Controls of={CCR.Example3} />
 </div>
 
+⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
+
 ### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
 
 <ul>
@@ -75,3 +77,5 @@ A workaround for this case combines approaches II and III: using `Element.ariaLa
 <div className="hide-col-default">
   <Controls of={CCR.Example5} />
 </div>
+
+⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
index 3ff53f63be..4c0a389b08 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
@@ -45,7 +45,7 @@ export const Example2: Story = {
     <demo-target
       target-version="1"
       workaround="${args.workaround}"
-      aria-labelledby-id="id_1"
+      arialabelledby-id="id_1"
     ></demo-target>
   `,
 };
@@ -99,7 +99,7 @@ export const Example5: Story = {
     <demo-label id="id_3"></demo-label>
     <demo-target
       target-version="3"
-      aria-labelledby-id="id_3"
+      arialabelledby-id="id_3"
       workaround="ariaLabelledByElements"
     ></demo-target>
   `,

From 9699f89ea73104691adc4842a699ccff29ccba09 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 9 Sep 2025 11:10:56 +0200
Subject: [PATCH 06/29] fix lint error

---
 .../aria-describedby/aria-describedby.docs.mdx                  | 2 +-
 .../aria-labelledby/aria-labelledby.docs.mdx                    | 2 +-
 .../aria-role-list/aria-role-list.docs.mdx                      | 2 +-
 .../reference-crossing-the-shadowdom/for/for.docs.mdx           | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
index ab82dc045c..2db62572f8 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-describedby.stories';
 
 <Meta of={CCR} />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index 2b0268c983..045e3ace83 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-labelledby.stories';
 
 <Meta of={CCR} />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
index e2eb9a8219..0af07419cd 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-role-list.stories';
 
 <Meta of={CCR} />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
index 0c485e38d5..c18c64781e 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as CCR from './for.stories';
 
 <Meta of={CCR} />

From 0c78e0d0fde08bfbe41270dd9043b5bc06bcdced Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 9 Sep 2025 11:19:22 +0200
Subject: [PATCH 07/29] fix code smells

---
 .../src/demo-components/demo-button.ts        | 43 +++++++------------
 .../src/demo-components/demo-target.ts        | 34 ++++++++-------
 2 files changed, 34 insertions(+), 43 deletions(-)

diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index 438a8b73e6..1397a703a1 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -27,40 +27,29 @@ export class DemoButton extends HTMLElement {
   }
 
   private setupAria() {
-    if (this.buttonVersion == '1') {
-      if (this.workaround === 'ariaLabelledByElements') {
-        const labelEl = document.querySelector(`#${this.arialabelledbyId}`);
-        if (this.internalButton)
-          this.internalButton.ariaLabelledByElements = labelEl ? [labelEl] : [];
-      }
-    }
+    const isLabelled = this.workaround === 'ariaLabelledByElements';
+    const isDescribed = this.workaround === 'ariaDescribedByElements';
 
-    if (this.buttonVersion == '2') {
-      if (this.workaround === 'ariaLabelledByElements' && this.slotEl) {
-        const assignedElements = this.slotEl.assignedElements({ flatten: true });
-        const labelEl = assignedElements.find(el => el.tagName === 'SPAN');
-        if (this.internalButton)
-          this.internalButton.ariaLabelledByElements = labelEl ? [labelEl] : [];
-      }
+    if (!this.internalButton || (!isLabelled && !isDescribed)) {
+      return;
     }
 
-    if (this.buttonVersion == '3') {
-      if (this.workaround === 'ariaDescribedByElements') {
-        const labelEl = document.querySelector(`#${this.ariadescribedbyId}`);
-        if (this.internalButton)
-          this.internalButton.ariaDescribedByElements = labelEl ? [labelEl] : [];
-      }
-    }
+    let elementToLink: Element | null = null;
 
-    if (this.buttonVersion == '4') {
-      if (this.workaround === 'ariaDescribedByElements' && this.slotEl) {
+    if (this.buttonVersion === '1' || this.buttonVersion === '3') {
+      const id = isLabelled ? this.arialabelledbyId : this.ariadescribedbyId;
+      if (id) {
+        elementToLink = document.querySelector(`#${id}`);
+      }
+    } else if (this.buttonVersion === '2' || this.buttonVersion === '4') {
+      if (this.slotEl) {
         const assignedElements = this.slotEl.assignedElements({ flatten: true });
-
-        const labelEl = assignedElements.find(el => el.tagName === 'SPAN');
-        if (this.internalButton)
-          this.internalButton.ariaDescribedByElements = labelEl ? [labelEl] : [];
+        elementToLink = assignedElements.find(el => el.tagName === 'SPAN') || null;
       }
     }
+
+    const ariaPropertyName = isLabelled ? 'ariaLabelledByElements' : 'ariaDescribedByElements';
+    this.internalButton[ariaPropertyName] = elementToLink ? [elementToLink] : [];
   }
 
   private render() {
diff --git a/packages/documentation/src/demo-components/demo-target.ts b/packages/documentation/src/demo-components/demo-target.ts
index 3297b0fbbc..3742dcb9ce 100644
--- a/packages/documentation/src/demo-components/demo-target.ts
+++ b/packages/documentation/src/demo-components/demo-target.ts
@@ -27,27 +27,29 @@ export class DemoTarget extends HTMLElement {
   }
 
   private setupAriaLabelledBy() {
-    if (!this.internalEl) return;
-    // Version #1
-    if (this.targetVersion === '1') {
-      const labelEl = document.querySelector(`[for="${this.arialabelledbyId}"]`);
-      this.internalEl.ariaLabelledByElements =
-        this.workaround === 'ariaLabelledByElements' && labelEl ? [labelEl] : [];
+    if (!this.internalEl) {
+      return;
+    }
 
-      // Version #2
+    let elementToLink: Element | null = null;
+    const isLabelledByWorkaround = this.workaround === 'ariaLabelledByElements';
+
+    if (this.targetVersion === '1') {
+      if (isLabelledByWorkaround && this.arialabelledbyId) {
+        elementToLink = document.querySelector(`[for="${this.arialabelledbyId}"]`);
+      }
     } else if (this.targetVersion === '2') {
-      if (this.slotEl && this.workaround === 'ariaLabelledByElements') {
+      if (isLabelledByWorkaround && this.slotEl) {
         const assignedElements = this.slotEl.assignedElements({ flatten: true });
-        const labelElement = assignedElements.find(el => el.tagName === 'LABEL');
-        this.internalEl.ariaLabelledByElements = labelElement ? [labelElement] : [];
-      } else {
-        this.internalEl.ariaLabelledByElements = [];
+        elementToLink = assignedElements.find(el => el.tagName === 'LABEL') || null;
+      }
+    } else if (this.targetVersion === '3') {
+      if (this.arialabelledbyId) {
+        elementToLink = document.querySelector(`#${this.arialabelledbyId}`);
       }
-    } // Version #3
-    else if (this.targetVersion === '3') {
-      const labelEl = document.querySelector(`#${this.arialabelledbyId}`);
-      this.internalEl.ariaLabelledByElements = labelEl ? [labelEl] : [];
     }
+
+    this.internalEl.ariaLabelledByElements = elementToLink ? [elementToLink] : [];
   }
 
   private render() {

From 03bef8d93eab7b2f9987f257c091d394ba4d1dc0 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 9 Sep 2025 11:28:54 +0200
Subject: [PATCH 08/29] fix lint error

---
 .../aria-role-list/aria-role-list.docs.mdx                      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
index 0af07419cd..e1453d9d5d 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-role-list.stories';
 
 <Meta of={CCR} />

From a4fee212001728557c1ed87afb019adceb210d1b Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Fri, 12 Sep 2025 15:24:17 +0200
Subject: [PATCH 09/29] updatesd aria-labelledby stories with more information
 and examples

---
 .../components/post-popover-trigger/readme.md |  78 ++++++++
 .../src/demo-components/index.ts              |   1 +
 .../aria-labelledby/aria-labelledby.docs.mdx  | 167 +++++++++++++-----
 .../aria-labelledby.stories.ts                |   1 +
 ...arialabelledbyElementsProperty.sample.html |   5 +
 .../arialabelledbyElementsProperty.sample.js  |   8 +
 .../examples/defaultExample.sample.html       |   7 +
 .../examples/defaultExample2.sample.html      |  11 ++
 .../nonWorkingExample-III.sample.html         |  10 ++
 .../nonWorkingExample-IIa.sample.html         |  10 ++
 .../nonWorkingExample-IIb.sample.html         |  11 ++
 .../examples/nonWorkingExample-IV.sample.html |  13 ++
 .../examples/workaround-IIa.sample.html       |  10 ++
 .../examples/workaround-IIb.sample.html       |  10 ++
 .../examples/workingExample-III.sample.html   |  10 ++
 .../examples/workingExample-IIa.sample.html   |  23 +++
 .../examples/workingExample-IIb.sample.html   |  29 +++
 .../examples/workingExample-IV.sample.html    |  22 +++
 18 files changed, 386 insertions(+), 40 deletions(-)
 create mode 100644 packages/components/src/components/post-popover-trigger/readme.md
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.js
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html

diff --git a/packages/components/src/components/post-popover-trigger/readme.md b/packages/components/src/components/post-popover-trigger/readme.md
new file mode 100644
index 0000000000..38b8977829
--- /dev/null
+++ b/packages/components/src/components/post-popover-trigger/readme.md
@@ -0,0 +1,78 @@
+# post-popover
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property                          | Attribute              | Description                                                                                                                                                                                                                                                                                                                                                                               | Type                                                                                                                                                                 | Default     |
+| --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `arrow`                           | `arrow`                | Show a little indicator arrow                                                                                                                                                                                                                                                                                                                                                             | `boolean`                                                                                                                                                            | `true`      |
+| `closeButtonCaption` _(required)_ | `close-button-caption` | Define the caption of the close button for assistive technology                                                                                                                                                                                                                                                                                                                           | `string`                                                                                                                                                             | `undefined` |
+| `placement`                       | `placement`            | Defines the position of the popover relative to its trigger. Popovers are automatically flipped to the opposite side if there is not enough available space and are shifted towards the viewport if they would overlap edge boundaries. For supported values and behavior details, see the [Floating UI placement documentation](https://floating-ui.com/docs/computePosition#placement). | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'top'`     |
+
+
+## Methods
+
+### `hide() => Promise<void>`
+
+Programmatically hide this popover
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `show(target: HTMLElement) => Promise<void>`
+
+Programmatically display the popover
+
+#### Parameters
+
+| Name     | Type          | Description                                                                  |
+| -------- | ------------- | ---------------------------------------------------------------------------- |
+| `target` | `HTMLElement` | An element with [data-popover-target="id"] where the popover should be shown |
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `toggle(target: HTMLElement, force?: boolean) => Promise<void>`
+
+Toggle popover display
+
+#### Parameters
+
+| Name     | Type          | Description                                                                        |
+| -------- | ------------- | ---------------------------------------------------------------------------------- |
+| `target` | `HTMLElement` | An element with [data-popover-target="id"] where the popover should be anchored to |
+| `force`  | `boolean`     | Pass true to always show or false to always hide                                   |
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+
+## Dependencies
+
+### Depends on
+
+- [post-popovercontainer](../post-popovercontainer)
+
+### Graph
+```mermaid
+graph TD;
+  post-popover --> post-popovercontainer
+  style post-popover fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*
diff --git a/packages/documentation/src/demo-components/index.ts b/packages/documentation/src/demo-components/index.ts
index 85f6bf2202..a48dc8d22b 100644
--- a/packages/documentation/src/demo-components/index.ts
+++ b/packages/documentation/src/demo-components/index.ts
@@ -4,3 +4,4 @@ import './demo-label';
 import './demo-list';
 import './demo-list-item';
 import './demo-list-item-group';
+import './demo-span';
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index 045e3ace83..a202178616 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -1,5 +1,17 @@
-import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-labelledby.stories';
+import DefaultExample from './examples/defaultExample.sample.html?raw';
+import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
+import ArialabelledbyElementsPropertyHTML from './examples/arialabelledbyElementsProperty.sample.html?raw';
+import ArialabelledbyElementsProperty from './examples/arialabelledbyElementsProperty.sample.js?raw';
+import NonWorkingExampleIIa from './examples/nonWorkingExample-IIa.sample.html?raw';
+import NonWorkingExampleIIb from './examples/nonWorkingExample-IIb.sample.html?raw';
+import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
+import NonWorkingExampleIII from './examples/nonWorkingExample-III.sample.html?raw';
+import WorkingExampleIII from './examples/workingExample-III.sample.html?raw';
+import NonWorkingExampleIV from './examples/nonWorkingExample-IV.sample.html?raw';
+import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <Meta of={CCR} />
 
@@ -9,65 +21,140 @@ import * as CCR from './aria-labelledby.stories';
   In the Light DOM, the `aria-labelledby` attribute assigns an accessible name to an element by
   referencing the ID of one or more elements that provide the descriptive text.
 </div>
-<div>
+<p>
   This is particularly useful when a simple text label isn’t directly linked to the element, or when
   the accessible name needs to be composed from multiple pieces of text.
-</div>
-### I. Referencing Within the Same DOM Tree ✔️
-
-<Canvas of={CCR.ExampleHTML} sourceState="shown" />
-### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
-
-<ul>
-  <li>Light DOM → Shadow DOM</li>
-  <li>Slotted Content → Shadow DOM</li>
-</ul>
-
-Standard `aria-labelledby` cannot reference elements inside a Shadow DOM from outside it, because IDs within a Shadow DOM are encapsulated and inaccessible to the Light DOM or other Shadow DOMs.
-
-##### Possible Workarounds
-
-###### 1. `Element:ariaLabelledByElements`
-
-<b>Light DOM → Shadow DOM Example</b>
-<Canvas of={CCR.Example2} sourceState="shown" />
+</p>
+### I. Referencing Within the Same DOM Tree
+
+<Canvas of={CCR.ExampleHTML} sourceState="hide" />
+
+• <b>Same Light DOM</b> ✔️
+
+<Source language="html" dark code={DefaultExample}></Source>
+
+• <b>Same Shadow DOM</b> ✔️
+
+<Source language="html" dark code={DefaultExample2}></Source>
+<p>
+  <b>
+    The above relationships are valid because in both cases the label and its associated target
+    element are part of the same tree.
+  </b>
+</p>
+
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM{' '}
+
+• <b>Light DOM → Shadow DOM</b> ❌
+
+<Source language="html" dark code={NonWorkingExampleIIa}></Source>
+
+• <b>Slotted Content → Shadow DOM</b> ❌
+
+<Source language="html" dark code={NonWorkingExampleIIb}></Source>
+
+<p>
+  The above examples do not work across shadow DOM boundaries when setting the aria-labelledby
+  attribute directly.
+</p>
+<p>
+  <b>
+    Attribute element references can only point to elements in the same DOM or shadow DOM, because
+    IDs are only valid within their own scope.
+  </b>
+</p>
+
+#### Workaround: `Element:ariaLabelledByElements`
+
+<p>
+  `ariaLabelledByElements` is a property of the Element interface that returns an array of elements
+  labeling the element. It provides direct references to these elements rather than just their ID
+  strings.{' '}
+  <a
+    target="blank"
+    href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements"
+  >
+    🔗ariaLabelledByElements
+  </a>
+</p>
+
+<div className="lead">Basic usage of `ariaLabelledByElements` </div>
+<Source language="html" dark code={ArialabelledbyElementsPropertyHTML}></Source>
+<p>
+  Instead of adding the `aria-labelledby` attribute on the element, we can set it using the
+  `ariaLabelledByElements` property.
+</p>
+<Source language="js" dark code={ArialabelledbyElementsProperty}></Source>
+<p>
+  The following examples demonstrate how the `ariaLabelledByElements` property can be used to
+  establish relationships <b>across the shadow DOM</b>.
+</p>
+
+<p>
+  <b>• Light DOM → Shadow DOM Example</b> ✔️
+</p>
+<p>
+  In this case a label element in the light DOM is directly assigned to a target element inside a custom
+  component’s shadow DOM using `ariaLabelledByElements`.
+</p>
+
+<Source language="html" dark code={WorkingExampleIIa}></Source>
+<p>Use the control below to toggle the `ariaLabelledByElements` workaround implementation.</p>
+<Canvas of={CCR.Example2} sourceState="hide" />
 <div className="hide-col-default">
   <Controls of={CCR.Example2} />
 </div>
 
-<b>Slotted Content → Shadow DOM Example</b>
-<Canvas of={CCR.Example3} sourceState="shown" />
+<p>
+  <b>• Slotted Content → Shadow DOM Example</b> ✔️
+</p>
+<p>
+  In this case a label element provided via a light DOM slot is automatically assigned to a target
+  element inside a custom component’s shadow DOM using `ariaLabelledByElements`.
+</p>
+<Source language="html" dark code={WorkingExampleIIb}></Source>
+<p>Use the control below to toggle the `ariaLabelledByElements` workaround implementation.</p>
+<Canvas of={CCR.Example3} sourceState="hide<p>" />
 <div className="hide-col-default">
   <Controls of={CCR.Example3} />
 </div>
 
-⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
-
-### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
 
-<ul>
-  <li>Shadow DOM → Light DOM</li>
-  <li>Shadow DOM → Slotted Content</li>
-</ul>
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM
 
-Referencing an element in the light DOM from within the Shadow DOM using standard `aria-labelledby` is not possible.
+<p>
+  <b>• Shadow DOM → Light DOM (or Shadow DOM → Slotted Content)</b>❌
+</p>
 
-##### Possible Workaround
+<p>
+  Referencing an element in the light DOM from within a shadow DOM using the standard{' '}
+  <code>aria-labelledby</code> is not possible. The `ariaLabelledByElements` property neither works
+  in this case because, for it to work, the label element must be in the same DOM or in a parent DOM
+  of the target element.
+</p>
+<Source language="html" dark code={NonWorkingExampleIII}></Source>
 
-An option is to set the `id` directly on the host of the labeling component. In this case all the visible text inside the referencing component will be assigned as the Accessible Name of the target element.
+##### Working Solution: Set the `id`on the label component host
 
-<Canvas of={CCR.Example4} sourceState="shown" />
+<p>
+  The only option here is to <b>set the `id` directly on the host</b> of the labeling component. In
+  this case <b>all the visible text inside the referencing component will be assigned as the Accessible Name</b> of the target element.
+</p>
+<Source language="html" dark code={WorkingExampleIII}></Source>
+<Canvas of={CCR.Example4} sourceState="hide" />
 
 ### IV. Referencing From One Shadow DOM To Another Shadow DOM
 
-<ul>
-  <li>Shadow DOM → Other Shadow DOM</li>
-</ul>
+Shadow DOM → Other Shadow DOM ❌
 
-##### Possible Workaround
+<Source language="html" dark code={NonWorkingExampleIV}></Source>
+<p> This relationship is not valid because both `id` and `aria-labelledby` attributes are scoped only within their individual shadowDoms.</p>
+##### Working Solution
 
-A workaround for this case combines approaches II and III: using `Element.ariaLabelledByElements` to set an `aria-labelledby` attribute on the Shadow DOM `button`, linking it to an ID defined on the host element of the labeling component.
+A working solution for this case combines approaches II and III: setting the label component’s `id` directly on the host element (III), and using `Element.ariaLabelledByElements` to assign the label to the target component.
 
+<Source language="html" dark code={WorkingExampleIV}></Source>
 <Canvas of={CCR.Example5} sourceState="shown" />
 
-⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
+⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
index 422eb9fdff..d5eb065567 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
@@ -32,6 +32,7 @@ export const Example2: Story = {
   argTypes: {
     workaround: {
       name: 'Workaround',
+      description: 'Toggles the workaround solution',
       control: {
         type: 'radio',
       },
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html
new file mode 100644
index 0000000000..91058c0f53
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html
@@ -0,0 +1,5 @@
+<!-- A simple label element that can provide an accessible name -->
+<span id="labelId"></span>
+
+<!-- A target element to label -->
+<element id="elementId"></element>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.js b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.js
new file mode 100644
index 0000000000..38a1bf7836
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.js
@@ -0,0 +1,8 @@
+// Get the element that will serve as the label
+const label = document.getElementById('labelId');
+
+// Get the element that needs an accessible name
+const element = document.getElementById('elementId');
+
+// Assign one or more label elements directly to the target element `ariaLabelledByElements` property
+element.ariaLabelledByElements = [label];
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
new file mode 100644
index 0000000000..7f171e39b7
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
@@ -0,0 +1,7 @@
+<!-- This is a label element in the "light DOM" -->
+<span id="labelId">My Text</span>
+
+<!-- This is a div element in the same "light DOM" -->
+<div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+  <icon></icon>
+</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
new file mode 100644
index 0000000000..914e362a0b
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
@@ -0,0 +1,11 @@
+<custom-component>
+  <!-- #shadow-root -->
+   
+    <!-- This is a label element in the "shadow DOM" -->
+    <span id="labelId">My Text</span>
+
+    <!-- This is a div element in the same "shadow DOM" -->
+    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+      <icon></icon>
+    </div>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
new file mode 100644
index 0000000000..8d3ab118a7
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
@@ -0,0 +1,10 @@
+<!-- This is a custom component with a label  -->
+<custom-component>
+  <!-- #shadow-root -->
+  <span id="labelId">My Text</span>
+</custom-component>
+
+<!-- This is a button element in the "light DOM" -->
+<div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+  <icon></icon>
+</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
new file mode 100644
index 0000000000..e4028a5deb
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
@@ -0,0 +1,10 @@
+<!-- This is a label element in the "light DOM" -->
+<span id="labelId">My Text</span>
+
+<!-- This is a custom component -->
+<custom-component>
+  <!-- #shadow-root -->
+  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <icon></icon>
+  </div>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
new file mode 100644
index 0000000000..d4be1c8371
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
@@ -0,0 +1,11 @@
+<!-- This is a custom component -->
+<custom-component>
+  <!-- #shadow-root -->
+  <slot name="label-slot"> </slot>
+  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <icon></icon>
+  </div>
+
+  <!-- This is the sloted label element -->
+  <span slot="label-slot" id="labelId">My Text</span>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
new file mode 100644
index 0000000000..7b0b04a372
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
@@ -0,0 +1,13 @@
+<!-- This is a custom label component  -->
+<custom-label>
+  <!-- #shadow-root -->
+  <span id="labelId">My Text</span>
+</custom-label>
+
+<!-- This is a custom button component -->
+<custom-button>
+  <!-- #shadow-root -->
+  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <icon></icon>
+  </div>
+</custom-button>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
new file mode 100644
index 0000000000..e4028a5deb
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
@@ -0,0 +1,10 @@
+<!-- This is a label element in the "light DOM" -->
+<span id="labelId">My Text</span>
+
+<!-- This is a custom component -->
+<custom-component>
+  <!-- #shadow-root -->
+  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <icon></icon>
+  </div>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
new file mode 100644
index 0000000000..e4028a5deb
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
@@ -0,0 +1,10 @@
+<!-- This is a label element in the "light DOM" -->
+<span id="labelId">My Text</span>
+
+<!-- This is a custom component -->
+<custom-component>
+  <!-- #shadow-root -->
+  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <icon></icon>
+  </div>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
new file mode 100644
index 0000000000..57e2bc9832
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
@@ -0,0 +1,10 @@
+<!-- This is a custom component with a label  -->
+<custom-component id="labelId">
+  <!-- #shadow-root -->
+  <span>My Text</span>
+</custom-component>
+
+<!-- This is a button element in the "light DOM" -->
+<div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+  <icon></icon>
+</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
new file mode 100644
index 0000000000..19bd7f26a7
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
@@ -0,0 +1,23 @@
+<!-- This is a label element in the light DOM -->
+<span id="labelId">My Text</span>
+
+<!-- 
+  This is a custom web component. 
+  We pass the labelId as a prop to associate the label with an element inside its shadow DOM.
+-->
+<custom-component labelId="labelId">
+  <!-- #shadow-root -->
+  <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
+    <!--The aria-labelledby attribute is set automatically by the browser -->
+    <icon></icon>
+  </div>
+</custom-component>
+
+<script>
+  // Get the label element from the light DOM
+  const label = document.getElementById('labelId');
+
+  // Assign the label element directly to the component's internal target element
+  // using ariaLabelledByElements to establish the accessible name
+  this.targetRef.ariaLabelledByElements = [label];
+</script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
new file mode 100644
index 0000000000..d808fc98a0
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
@@ -0,0 +1,29 @@
+<!-- This is a custom web component -->
+<custom-component>
+  <!-- #shadow-root -->
+
+  <!-- Slot for passing in a label from the light DOM -->
+  <slot name="label-slot"></slot>
+
+  <!-- Target element inside shadow DOM -->
+  <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
+    <!--The aria-labelledby attribute is set automatically by the browser -->
+    <icon></icon>
+  </div>
+
+  <!-- This is the slotted label element provided from the light DOM -->
+  <span slot="label-slot" id="labelId">My Text</span>
+</custom-component>
+
+<script>
+  // Get the slot element inside shadow DOM
+  const slotContent = this.shadowRoot
+    .querySelector('slot[name="label-slot"]')
+    .assignedElements({ flatten: true });
+
+  // Identify the element that contains text
+  const label = slotContent.find(el => el.textContent.trim().length > 0);
+
+  // Assign the slotted element(s) as labels for the target using ariaLabelledByElements
+  this.targetRef.ariaLabelledByElements = [label];
+</script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
new file mode 100644
index 0000000000..7b922cead4
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
@@ -0,0 +1,22 @@
+<!-- This is a custom label component  -->
+<custom-label id="labelId">
+  <!-- #shadow-root -->
+  <span>My Text</span>
+</custom-label>
+
+<!-- This is a custom button component -->
+<custom-button>
+  <!-- #shadow-root -->
+  <div part="button" role="button" tabindex="0" aria-labelledby>
+    <icon></icon>
+  </div>
+</custom-button>
+
+<script>
+  // Get the label element from the light DOM
+  const label = document.getElementById('labelId');
+
+  // Assign the label element directly to the component's internal target element
+  // using ariaLabelledByElements to establish the accessible name
+  this.targetRef.ariaLabelledByElements = [label];
+</script>

From c57fa88960c8a8753716640f531bb9c5af1ae742 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Fri, 12 Sep 2025 15:30:41 +0200
Subject: [PATCH 10/29] lint error

---
 .../aria-labelledby/aria-labelledby.docs.mdx              | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index a202178616..b4b24973c5 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -43,7 +43,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
   </b>
 </p>
 
-### II. Referencing From Outside a Shadow DOM Into That Shadow DOM{' '}
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM
 
 • <b>Light DOM → Shadow DOM</b> ❌
 
@@ -69,7 +69,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 <p>
   `ariaLabelledByElements` is a property of the Element interface that returns an array of elements
   labeling the element. It provides direct references to these elements rather than just their ID
-  strings.{' '}
+  strings.
   <a
     target="blank"
     href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements"
@@ -128,8 +128,8 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </p>
 
 <p>
-  Referencing an element in the light DOM from within a shadow DOM using the standard{' '}
-  <code>aria-labelledby</code> is not possible. The `ariaLabelledByElements` property neither works
+  Referencing an element in the light DOM from within a shadow DOM using the standard
+  `aria-labelledby` is not possible. The `ariaLabelledByElements` property neither works
   in this case because, for it to work, the label element must be in the same DOM or in a parent DOM
   of the target element.
 </p>

From 82b04def4cb98b6b3e04cf8926f81499e876ce24 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 16 Sep 2025 15:39:07 +0200
Subject: [PATCH 11/29] update examples as per review comments

---
 ...arialabelledbyElementsProperty.sample.html |  2 --
 .../examples/defaultExample.sample.html       |  4 +--
 .../examples/defaultExample2.sample.html      |  8 ++----
 .../nonWorkingExample-III.sample.html         |  6 ++---
 .../nonWorkingExample-IIa.sample.html         |  6 ++---
 .../nonWorkingExample-IIb.sample.html         | 15 +++++------
 .../examples/nonWorkingExample-IV.sample.html | 12 ++++-----
 .../examples/workaround-IIa.sample.html       | 10 +++----
 .../examples/workaround-IIb.sample.html       | 10 +++----
 .../examples/workingExample-III.sample.html   |  8 +++---
 .../examples/workingExample-IIa.sample.html   | 17 ++++--------
 .../examples/workingExample-IIb.sample.html   | 26 ++++++-------------
 .../examples/workingExample-IV.sample.html    | 18 +++++--------
 13 files changed, 49 insertions(+), 93 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html
index 91058c0f53..7160a12432 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html
@@ -1,5 +1,3 @@
-<!-- A simple label element that can provide an accessible name -->
 <span id="labelId"></span>
 
-<!-- A target element to label -->
 <element id="elementId"></element>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
index 7f171e39b7..e0b2f1addf 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
@@ -1,7 +1,5 @@
-<!-- This is a label element in the "light DOM" -->
 <span id="labelId">My Text</span>
 
-<!-- This is a div element in the same "light DOM" -->
 <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-  <icon></icon>
+  <custom-icon />
 </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
index 914e362a0b..b4a33a6bf0 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
@@ -1,11 +1,7 @@
 <custom-component>
-  <!-- #shadow-root -->
-   
-    <!-- This is a label element in the "shadow DOM" -->
+  ⏷ #shadow-root (open)
     <span id="labelId">My Text</span>
-
-    <!-- This is a div element in the same "shadow DOM" -->
     <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-      <icon></icon>
+      <custom-icon />
     </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
index 8d3ab118a7..13c94fd9f4 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
@@ -1,10 +1,8 @@
-<!-- This is a custom component with a label  -->
 <custom-component>
-  <!-- #shadow-root -->
-  <span id="labelId">My Text</span>
+  ⏷ #shadow-root (open)
+    <span id="labelId">My Text</span>
 </custom-component>
 
-<!-- This is a button element in the "light DOM" -->
 <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
   <icon></icon>
 </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
index e4028a5deb..ed7fd11a25 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
@@ -1,10 +1,8 @@
-<!-- This is a label element in the "light DOM" -->
 <span id="labelId">My Text</span>
 
-<!-- This is a custom component -->
 <custom-component>
-  <!-- #shadow-root -->
+  ⏷ #shadow-root (open)
   <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-    <icon></icon>
+    <custom-icon />
   </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
index d4be1c8371..d3d88cbc00 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
@@ -1,11 +1,8 @@
-<!-- This is a custom component -->
 <custom-component>
-  <!-- #shadow-root -->
-  <slot name="label-slot"> </slot>
-  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-    <icon></icon>
-  </div>
-
-  <!-- This is the sloted label element -->
-  <span slot="label-slot" id="labelId">My Text</span>
+  ⏷ #shadow-root (open)
+    <slot name="label-slot"> </slot>
+    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+      <custom-icon />
+    </div>
+    <span slot="label-slot" id="labelId">My Text</span>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
index 7b0b04a372..d208f22d56 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
@@ -1,13 +1,11 @@
-<!-- This is a custom label component  -->
 <custom-label>
-  <!-- #shadow-root -->
+  ⏷ #shadow-root (open)
   <span id="labelId">My Text</span>
 </custom-label>
 
-<!-- This is a custom button component -->
 <custom-button>
-  <!-- #shadow-root -->
-  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-    <icon></icon>
-  </div>
+  ⏷ #shadow-root (open)
+    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+      <custom-icon />
+    </div>
 </custom-button>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
index e4028a5deb..ef1292dff4 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
@@ -1,10 +1,8 @@
-<!-- This is a label element in the "light DOM" -->
 <span id="labelId">My Text</span>
 
-<!-- This is a custom component -->
 <custom-component>
-  <!-- #shadow-root -->
-  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-    <icon></icon>
-  </div>
+  ⏷ #shadow-root (open)
+    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+      <custom-icon />
+    </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
index e4028a5deb..ef1292dff4 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
@@ -1,10 +1,8 @@
-<!-- This is a label element in the "light DOM" -->
 <span id="labelId">My Text</span>
 
-<!-- This is a custom component -->
 <custom-component>
-  <!-- #shadow-root -->
-  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-    <icon></icon>
-  </div>
+  ⏷ #shadow-root (open)
+    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+      <custom-icon />
+    </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
index 57e2bc9832..a69d3a4738 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
@@ -1,10 +1,8 @@
-<!-- This is a custom component with a label  -->
 <custom-component id="labelId">
-  <!-- #shadow-root -->
-  <span>My Text</span>
+  ⏷ #shadow-root (open)
+    <span>My Text</span>
 </custom-component>
 
-<!-- This is a button element in the "light DOM" -->
 <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-  <icon></icon>
+  <custom-icon />
 </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
index 19bd7f26a7..0315bef19f 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
@@ -1,22 +1,15 @@
-<!-- This is a label element in the light DOM -->
 <span id="labelId">My Text</span>
 
-<!-- 
-  This is a custom web component. 
-  We pass the labelId as a prop to associate the label with an element inside its shadow DOM.
--->
 <custom-component labelId="labelId">
-  <!-- #shadow-root -->
-  <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
-    <!--The aria-labelledby attribute is set automatically by the browser -->
-    <icon></icon>
-  </div>
+  ⏷ #shadow-root (open)
+    <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
+      <!--The aria-labelledby attribute is set automatically by the browser -->
+        <custom-icon />
+    </div>
 </custom-component>
 
 <script>
-  // Get the label element from the light DOM
   const label = document.getElementById('labelId');
-
   // Assign the label element directly to the component's internal target element
   // using ariaLabelledByElements to establish the accessible name
   this.targetRef.ariaLabelledByElements = [label];
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
index d808fc98a0..350f21637d 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
@@ -1,29 +1,19 @@
-<!-- This is a custom web component -->
 <custom-component>
-  <!-- #shadow-root -->
-
-  <!-- Slot for passing in a label from the light DOM -->
-  <slot name="label-slot"></slot>
-
-  <!-- Target element inside shadow DOM -->
-  <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
-    <!--The aria-labelledby attribute is set automatically by the browser -->
-    <icon></icon>
-  </div>
-
-  <!-- This is the slotted label element provided from the light DOM -->
+  ⏷ #shadow-root (open)
+    <slot name="label-slot"></slot>
+    <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
+      <!--The aria-labelledby attribute is set automatically by the browser -->
+      <custom-icon />
+    </div>
+  <!-- slotted label elemen -->
   <span slot="label-slot" id="labelId">My Text</span>
 </custom-component>
 
 <script>
-  // Get the slot element inside shadow DOM
+  // Assign the slotted element(s) as labels for the target using ariaLabelledByElements
   const slotContent = this.shadowRoot
     .querySelector('slot[name="label-slot"]')
     .assignedElements({ flatten: true });
-
-  // Identify the element that contains text
   const label = slotContent.find(el => el.textContent.trim().length > 0);
-
-  // Assign the slotted element(s) as labels for the target using ariaLabelledByElements
   this.targetRef.ariaLabelledByElements = [label];
 </script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
index 7b922cead4..94df4df2b6 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
@@ -1,22 +1,18 @@
-<!-- This is a custom label component  -->
 <custom-label id="labelId">
-  <!-- #shadow-root -->
-  <span>My Text</span>
+  ⏷ #shadow-root (open)
+    <span>My Text</span>
 </custom-label>
 
-<!-- This is a custom button component -->
 <custom-button>
-  <!-- #shadow-root -->
-  <div part="button" role="button" tabindex="0" aria-labelledby>
-    <icon></icon>
-  </div>
+  ⏷ #shadow-root (open)
+    <div part="button" role="button" tabindex="0" aria-labelledby>
+      <custom-icon />
+    </div>
 </custom-button>
 
 <script>
-  // Get the label element from the light DOM
-  const label = document.getElementById('labelId');
-
   // Assign the label element directly to the component's internal target element
   // using ariaLabelledByElements to establish the accessible name
+  const label = document.getElementById('labelId');
   this.targetRef.ariaLabelledByElements = [label];
 </script>

From 1ed58d51bdcf93e52a635fe28a9c5f77f8907331 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 16 Sep 2025 15:41:15 +0200
Subject: [PATCH 12/29] update wording

---
 .../aria-labelledby/aria-labelledby.docs.mdx                  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index b4b24973c5..da6064d310 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -29,11 +29,11 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <Canvas of={CCR.ExampleHTML} sourceState="hide" />
 
-• <b>Same Light DOM</b> ✔️
+• <b>Both elements in Light DOM</b> ✔️
 
 <Source language="html" dark code={DefaultExample}></Source>
 
-• <b>Same Shadow DOM</b> ✔️
+• <b>Both elements in same Shadow DOM</b> ✔️
 
 <Source language="html" dark code={DefaultExample2}></Source>
 <p>

From 4e0a1a0781427ac27911a5779f4e3b50cc4e0a51 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 16 Sep 2025 15:50:16 +0200
Subject: [PATCH 13/29] minor example updates

---
 .../examples/nonWorkingExample-III.sample.html              | 2 +-
 .../examples/nonWorkingExample-IIa.sample.html              | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
index 13c94fd9f4..68673bbf03 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
@@ -4,5 +4,5 @@
 </custom-component>
 
 <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-  <icon></icon>
+  <custom-icon />
 </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
index ed7fd11a25..ef1292dff4 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
@@ -2,7 +2,7 @@
 
 <custom-component>
   ⏷ #shadow-root (open)
-  <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-    <custom-icon />
-  </div>
+    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+      <custom-icon />
+    </div>
 </custom-component>

From c5853a2ff6d4318043fcf1a5d46c333ac170ebef Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Mon, 22 Sep 2025 08:11:45 +0200
Subject: [PATCH 14/29] updated examples as per review comments

---
 .../src/demo-components/demo-button.ts        |  18 +-
 .../{demo-target.ts => demo-input.ts}         |  16 +-
 .../src/demo-components/demo-span.ts          |   7 +-
 .../src/demo-components/index.ts              |   2 +-
 .../aria-describedby.docs.mdx                 | 178 ++++++++++++++----
 .../aria-describedby.stories.ts               |   9 +-
 .../aria-describedby.styles.scss              |  22 +++
 ...riadescribedbyElementsProperty.sample.html |   3 +
 .../ariadescribedbyElementsProperty.sample.js |   8 +
 .../examples/defaultExample.sample.html       |   5 +
 .../examples/defaultExample2.sample.html      |   7 +
 .../nonWorkingExample-III.sample.html         |   8 +
 .../nonWorkingExample-IIa.sample.html         |   8 +
 .../nonWorkingExample-IIb.sample.html         |   8 +
 .../examples/nonWorkingExample-IV.sample.html |  12 ++
 .../examples/workaround-IIa.sample.html       |   9 +
 .../examples/workaround-IIb.sample.html       |   8 +
 .../examples/workingExample-III.sample.html   |   8 +
 .../examples/workingExample-IIa.sample.html   |  16 ++
 .../examples/workingExample-IIb.sample.html   |  19 ++
 .../examples/workingExample-IV.sample.html    |  19 ++
 .../aria-labelledby/aria-labelledby.docs.mdx  |  36 ++--
 .../aria-labelledby.stories.ts                |  10 +-
 .../aria-labelledby.styles.scss               |  22 +++
 .../examples/defaultExample.sample.html       |   2 +-
 .../examples/defaultExample2.sample.html      |   2 +-
 .../nonWorkingExample-III.sample.html         |   2 +-
 .../nonWorkingExample-IIa.sample.html         |   2 +-
 .../nonWorkingExample-IIb.sample.html         |  10 +-
 .../examples/nonWorkingExample-IV.sample.html |   2 +-
 .../examples/workaround-IIa.sample.html       |   2 +-
 .../examples/workaround-IIb.sample.html       |   2 +-
 .../examples/workingExample-III.sample.html   |   2 +-
 .../examples/workingExample-IIa.sample.html   |   2 +-
 .../examples/workingExample-IIb.sample.html   |  18 +-
 .../examples/workingExample-IV.sample.html    |   2 +-
 ...arialabelledbyElementsProperty.sample.html |   3 +
 .../arialabelledbyElementsProperty.sample.js  |   8 +
 .../for/examples/defaultExample.sample.html   |   3 +
 .../for/examples/defaultExample2.sample.html  |   5 +
 .../nonWorkingExample-III.sample.html         |   6 +
 .../nonWorkingExample-IIa.sample.html         |   6 +
 .../nonWorkingExample-IIb.sample.html         |   6 +
 .../examples/nonWorkingExample-IV.sample.html |   9 +
 .../for/examples/workaround-IIa.sample.html   |   6 +
 .../for/examples/workaround-IIb.sample.html   |   6 +
 .../examples/workingExample-III.sample.html   |   6 +
 .../examples/workingExample-IIa.sample.html   |  16 ++
 .../examples/workingExample-IIb.sample.html   |  17 ++
 .../examples/workingExample-IV.sample.html    |  16 ++
 .../for/for.docs.mdx                          | 118 ++++++++++--
 .../for/for.stories.ts                        |  18 +-
 52 files changed, 629 insertions(+), 126 deletions(-)
 rename packages/documentation/src/demo-components/{demo-target.ts => demo-input.ts} (85%)
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.js
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample2.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-III.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IV.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-III.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IV.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.js
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-III.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html

diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index 1397a703a1..49c0c0f133 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -54,18 +54,28 @@ export class DemoButton extends HTMLElement {
 
   private render() {
     if (!this.shadowRoot) return;
-    this.shadowRoot.innerHTML = `
-      <slot name="label-slot"></slot>
+
+    if (this.buttonVersion) {
+      this.shadowRoot.innerHTML = `
+      <slot name="aria-slot"></slot>
       <div part="button"
-        class="btn btn-primary"
         role="button"
         tabindex="0"
       > <post-icon name="1022"></post-icon>
       </div>
     `;
+    } else {
+      this.shadowRoot.innerHTML = `
+      <span id="example">My Text</span>
+      <div part="button"
+      role="button" tabindex="0" aria-labelledby="example">
+        <post-icon name="1022"></post-icon>
+      </div>
+   `;
+    }
 
     this.internalButton = this.shadowRoot.querySelector('div[role="button"]') as HTMLElement;
-    this.slotEl = this.shadowRoot.querySelector('slot[name="label-slot"]') as HTMLSlotElement;
+    this.slotEl = this.shadowRoot.querySelector('slot[name="aria-slot"]') as HTMLSlotElement;
     this.setupAria();
   }
 }
diff --git a/packages/documentation/src/demo-components/demo-target.ts b/packages/documentation/src/demo-components/demo-input.ts
similarity index 85%
rename from packages/documentation/src/demo-components/demo-target.ts
rename to packages/documentation/src/demo-components/demo-input.ts
index 3742dcb9ce..149681dbeb 100644
--- a/packages/documentation/src/demo-components/demo-target.ts
+++ b/packages/documentation/src/demo-components/demo-input.ts
@@ -1,4 +1,4 @@
-export class DemoTarget extends HTMLElement {
+export class DemoInput extends HTMLElement {
   static get observedAttributes() {
     return ['workaround', 'arialabelledby-id', 'target-version'];
   }
@@ -57,10 +57,10 @@ export class DemoTarget extends HTMLElement {
     //Version #2
     if (this.targetVersion === '2') {
       this.shadowRoot.innerHTML = `
-        <slot name="label-slot"></slot>
+        <slot name="aria-slot"></slot>
         <input id="internal">
       `;
-      this.slotEl = this.shadowRoot.querySelector('slot[name="label-slot"]') as HTMLSlotElement;
+      this.slotEl = this.shadowRoot.querySelector('slot[name="aria-slot"]') as HTMLSlotElement;
       this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
     } else if (this.targetVersion === '3') {
       // Version #3
@@ -68,17 +68,23 @@ export class DemoTarget extends HTMLElement {
         <input id="internal">
       `;
       this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
-    } else {
+    } else if (this.targetVersion === '1') {
       // Version #1
       this.shadowRoot.innerHTML = `
         <input id="internal">
         <slot></slot>
       `;
       this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
+    } else {
+      // Version default
+      this.shadowRoot.innerHTML = `
+        <label for="example">My Text</label>
+        <input id="example">
+      `;
     }
 
     this.setupAriaLabelledBy();
   }
 }
 
-customElements.define('demo-target', DemoTarget);
+customElements.define('demo-input', DemoInput);
diff --git a/packages/documentation/src/demo-components/demo-span.ts b/packages/documentation/src/demo-components/demo-span.ts
index b0a11f4651..9629a62455 100644
--- a/packages/documentation/src/demo-components/demo-span.ts
+++ b/packages/documentation/src/demo-components/demo-span.ts
@@ -1,9 +1,10 @@
 export class DemoSpan extends HTMLElement {
   static get observedAttributes() {
-    return ['spanId'];
+    return ['spanId', 'content'];
   }
 
   private spanId!: string;
+  private content: string = 'My text';
 
   constructor() {
     super();
@@ -16,14 +17,16 @@ export class DemoSpan extends HTMLElement {
 
   attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
     if (name === 'id') this.spanId = newValue;
+    if (name === 'content') this.content = newValue;
 
     this.render();
   }
 
   private render() {
     if (!this.shadowRoot) return;
+
     this.shadowRoot.innerHTML = `
-      <span>My Text</span>
+      <span>${this.content}</span>
     `;
   }
 }
diff --git a/packages/documentation/src/demo-components/index.ts b/packages/documentation/src/demo-components/index.ts
index a48dc8d22b..18a3ef5194 100644
--- a/packages/documentation/src/demo-components/index.ts
+++ b/packages/documentation/src/demo-components/index.ts
@@ -1,5 +1,5 @@
 import './demo-button';
-import './demo-target';
+import './demo-input';
 import './demo-label';
 import './demo-list';
 import './demo-list-item';
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
index 2db62572f8..3eab51ad8b 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -1,5 +1,17 @@
-import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-describedby.stories';
+import DefaultExample from './examples/defaultExample.sample.html?raw';
+import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
+import AriaDescribedbyElementsPropertyHTML from './examples/ariadescribedbyElementsProperty.sample.html?raw';
+import AriaDescribedbyElementsProperty from './examples/ariadescribedbyElementsProperty.sample.js?raw';
+import NonWorkingExampleIIa from './examples/nonWorkingExample-IIa.sample.html?raw';
+import NonWorkingExampleIIb from './examples/nonWorkingExample-IIb.sample.html?raw';
+import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
+import NonWorkingExampleIII from './examples/nonWorkingExample-III.sample.html?raw';
+import WorkingExampleIII from './examples/workingExample-III.sample.html?raw';
+import NonWorkingExampleIV from './examples/nonWorkingExample-IV.sample.html?raw';
+import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <Meta of={CCR} />
 
@@ -9,63 +21,151 @@ import * as CCR from './aria-describedby.stories';
   In the Light DOM, `aria-describedby` is used to give an element a description by referencing the
   ID of another element or multiple elements that contain the desired text.
 </div>
-<div>
+<p>
   This is useful when a simple text label isn't enough or when the description needs to be combined
   from different pieces of text.
-</div>
-### I. Referencing Within the Same DOM Tree ✔️
-
-<Canvas of={CCR.ExampleHTML} sourceState="shown" />
-### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
-
-<ul>
-  <li>Light DOM → Shadow DOM</li>
-  <li>Slotted Content → Shadow DOM</li>
-</ul>
-
-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`
-
-<b>Light DOM → Shadow DOM Example</b>
-<Canvas of={CCR.Example2} sourceState="shown" />
+</p>
+
+### I. Referencing Within the Same DOM Tree
+
+• <b>Both elements in Light DOM</b> ✔️
+
+<Source language="html" dark code={DefaultExample}></Source>
+
+• <b>Both elements in same Shadow DOM</b> ✔️
+
+<Source language="html" dark code={DefaultExample2}></Source>
+<p>
+  <b>
+    The above relationships are valid because in both cases the target element and its description
+    are part of the same tree.
+  </b>
+</p>
+
+<p>
+  Below is a working example of an `aria-describedby`/`id` relationship within the shadowDom of a
+  custom button component. You can <b>test it with NVDA</b> to confirm the correct description
+  announcement.
+</p>
+<Canvas of={CCR.ExampleHTML} sourceState="hide" />
+
+
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM
+
+• <b>Light DOM → Shadow DOM</b> ❌
+
+<Source language="html" dark code={NonWorkingExampleIIa}></Source>
+
+• <b>Slotted Content → Shadow DOM</b> ❌
+
+<Source language="html" dark code={NonWorkingExampleIIb}></Source>
+
+<p>
+  The above examples do not work across shadow DOM boundaries when setting the aria-describedby
+  attribute directly.
+</p>
+<p>
+  <b>
+    Attribute element references can only point to elements in the same DOM or shadow DOM, because
+    IDs are only valid within their own scope.
+  </b>
+</p>
+
+#### Workaround: `Element:ariaDescribedByElements`
+
+<p>
+  `ariaDescribedByElements` is a property of the Element interface that returns an array of elements
+  describing the element. It provides direct references to these elements rather than just their ID
+  strings.
+  <a
+    target="blank"
+    href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaDescribedByElements"
+  >
+    🔗ariaDescribedByElements
+  </a>
+</p>
+
+<div className="lead">Basic usage of `ariaDescribedByElements` </div>
+<Source language="html" dark code={AriaDescribedbyElementsPropertyHTML}></Source>
+<p>
+  Instead of adding the `aria-describedby` attribute on the element, we can set it using the
+  `ariaDescribedByElements` property.
+</p>
+<Source language="js" dark code={AriaDescribedbyElementsProperty}></Source>
+<p>
+  The following examples demonstrate how the `ariaDescribedByElements` property can be used to
+  establish relationships <b>across the shadow DOM</b>.
+</p>
+
+<p>
+  <b>• Light DOM → Shadow DOM Example</b> ✔️
+</p>
+<p>
+  In this case a description element in the light DOM is directly assigned to a target element inside a
+  custom component’s shadow DOM using `ariaDescribedByElements`.
+</p>
+
+<Source language="html" dark code={WorkingExampleIIa}></Source>
+<p>Use the control below to toggle the `ariaDescribedByElements` workaround implementation.</p>
+<Canvas of={CCR.Example2} sourceState="hide" />
 <div className="hide-col-default">
   <Controls of={CCR.Example2} />
 </div>
 
-<b>Slotted Content → Shadow DOM Example</b>
-<Canvas of={CCR.Example3} sourceState="shown" />
+<p>
+  <b>• Slotted Content → Shadow DOM Example</b> ✔️
+</p>
+<p>
+  In this case a description element provided via a light DOM slot is automatically assigned to a target
+  element inside a custom component’s shadow DOM using `ariaDescribedByElements`.
+</p>
+<Source language="html" dark code={WorkingExampleIIb}></Source>
+<p>Use the control below to toggle the `ariaDescribedByElements` workaround implementation.</p>
+<Canvas of={CCR.Example3} sourceState="hide<p>" />
 <div className="hide-col-default">
   <Controls of={CCR.Example3} />
 </div>
 
-### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
 
-<ul>
-  <li>Shadow DOM → Light DOM</li>
-  <li>Shadow DOM → Slotted Content</li>
-</ul>
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM
 
-Referencing an element in the light DOM from within the Shadow DOM using standard `aria-describedeby` is not possible.
+<p>
+  <b>• Shadow DOM → Light DOM (or Shadow DOM → Slotted Content)</b>❌
+</p>
 
-##### Possible Workaround
+<p>
+  Referencing an element in the light DOM from within a shadow DOM using the standard
+  `aria-describedby` is not possible. The `ariaDescribedByElements` property neither works in this
+  case because, for it to work, the description element must be in the same DOM or in a parent DOM of the
+  target element.
+</p>
+<Source language="html" dark code={NonWorkingExampleIII}></Source>
 
-An option is to set the `id` directly on the host of the referencing element. In this case all the visible text inside the referencing component will be assigned as the Accessible Description of the target element.
+##### Working Solution: Set the `id`on the description component host
 
-<Canvas of={CCR.Example4} sourceState="shown" />
+<p>
+  The only option here is to <b>set the `id` directly on the host</b> of the description component. In
+  this case <b>all the visible text inside this component will be assigned as the Accessible Description</b>  of the target element.
+</p>
+<Source language="html" dark code={WorkingExampleIII}></Source>
+<Canvas of={CCR.Example4} sourceState="hide" />
 
-### IV. Referencing From One Shadow DOM To Another Shadow DOM ❌
+### IV. Referencing From One Shadow DOM To Another Shadow DOM
 
-<ul>
-  <li>Shadow DOM → Other Shadow DOM</li>
-</ul>
+Shadow DOM → Other Shadow DOM ❌
 
-##### Possible Workaround
+<Source language="html" dark code={NonWorkingExampleIV}></Source>
+<p>
+  This relationship is not valid because both `id` and `aria-describedby` attributes are scoped only within
+  their individual shadowDoms.
+</p>
 
-A workaround for this case combines approaches II and III: using Element.ariaDescribedByElements to set an aria-describedby attribute on the Shadow DOM button, linking it to an ID defined on the host element of the labeling component.
+##### Working Solution
 
-⚠️ In contrast to the respective `aria-labelledby` example, <b>NVDA does not announce</b> the accessible description in this scenario.
+A working solution for this case combines approaches II and III: setting the description component’s `id` directly on the host element (III), and using `Element.ariaDescribedByElements` to assign the description to the target component.
 
+<Source language="html" dark code={WorkingExampleIV}></Source>
 <Canvas of={CCR.Example5} sourceState="shown" />
+
+⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
index 897dffaf28..b2b2f2664b 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
@@ -1,6 +1,7 @@
 import { StoryObj, Args } from '@storybook/web-components-vite';
 import { MetaExtended } from '@root/types';
 import { html } from 'lit';
+import './aria-describedby.styles.scss';
 
 const meta: MetaExtended = {
   id: '76ade552-2c03-4d6d-9dce-28daa3405910',
@@ -67,7 +68,7 @@ export const Example3: Story = {
   },
   render: (args: Args) => html`
     <demo-button button-version="4" workaround="${args.workaround}"
-      ><span slot="label-slot">My Description</span></demo-button
+      ><span slot="aria-slot">My Description</span></demo-button
     >
   `,
 };
@@ -78,7 +79,7 @@ export const Example4: Story = {
     <div class="btn btn-primary" aria-describedby="id_2" role="button" tabindex="0">
       <post-icon name="1022"></post-icon>
     </div>
-    <demo-span id="id_2">My description</demo-span>
+    <demo-span content="My Description" id="id_2"></demo-span>
   `,
 };
 
@@ -88,8 +89,8 @@ export const Example5: Story = {
     <demo-button
       button-version="3"
       workaround="ariaDescribedByElements"
-      aria-describedby="id_3"
+      ariadescribedby-id="id_3"
     ></demo-button>
-    <demo-span id="id_3">My description</demo-span>
+    <demo-span content="My Description" id="id_3"></demo-span>
   `,
 };
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss
new file mode 100644
index 0000000000..bf859e8590
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss
@@ -0,0 +1,22 @@
+::part(button) {
+  display: inline-flex;
+  position: relative;
+  align-items: center;
+  justify-content: center;
+  max-width: 100%;
+  overflow: hidden;
+  transition: opacity 250ms, border-color 250ms, background-color 250ms, color 250ms;
+  border-width: 2px;
+  border-style: solid;
+  border-radius: 100px;
+  font-weight: bold;
+  width: 48px;
+  min-height: 40px;
+  color: white;
+  background: black;
+
+  &:hover {
+    background-color: #504f4b;
+    border-color: #504f4b;
+  }
+}
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html
new file mode 100644
index 0000000000..64a1f8f77e
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html
@@ -0,0 +1,3 @@
+<element id="elementId"></element>
+
+<span id="descriptionId"></span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.js b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.js
new file mode 100644
index 0000000000..ca1650819a
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.js
@@ -0,0 +1,8 @@
+// Get the element that will serve as the description
+const description = document.getElementById('descriptionId');
+
+// Get the element that needs an accessible description
+const element = document.getElementById('elementId');
+
+// Assign one or more description elements directly to the target element `ariaDescribedByElements` property
+element.ariaDescribedByElements = [description];
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample.sample.html
new file mode 100644
index 0000000000..8c6f22e30b
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample.sample.html
@@ -0,0 +1,5 @@
+<div role="button" tabindex="0" aria-describedby="descriptionId">
+  <custom-icon />
+</div>
+
+<span id="descriptionId">My Description</span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample2.sample.html
new file mode 100644
index 0000000000..0ce4ef870d
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample2.sample.html
@@ -0,0 +1,7 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <div role="button" tabindex="0" aria-describedby="descriptionId">
+      <custom-icon />
+    </div>
+    <span id="descriptionId">My Description</span>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-III.sample.html
new file mode 100644
index 0000000000..8518f0469a
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-III.sample.html
@@ -0,0 +1,8 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <span id="descriptionId">My Description</span>
+</custom-component>
+
+<div role="button" tabindex="0" aria-describedby="descriptionId">
+  <custom-icon />
+</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIa.sample.html
new file mode 100644
index 0000000000..d5d65462ca
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIa.sample.html
@@ -0,0 +1,8 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <div role="button" tabindex="0" aria-describedby="descriptionId">
+      <custom-icon />
+    </div>
+</custom-component>
+
+<span id="descriptionId">My Description</span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIb.sample.html
new file mode 100644
index 0000000000..7cb30ae36a
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIb.sample.html
@@ -0,0 +1,8 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <div role="button" tabindex="0" aria-describedby="descriptionId">
+      <custom-icon />
+    </div>
+    <slot name="description-slot"> </slot>
+  <span slot="description-slot" id="descriptionId">My Description</span>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IV.sample.html
new file mode 100644
index 0000000000..107d099356
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IV.sample.html
@@ -0,0 +1,12 @@
+<custom-button>
+  ⏷ #shadow-root (open)
+    <div role="button" tabindex="0" aria-describedby="descriptionId">
+      <custom-icon />
+    </div>
+</custom-button>
+
+<custom-description>
+  ⏷ #shadow-root (open)
+  <span id="descriptionId">My Description</span>
+</custom-description>
+
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html
new file mode 100644
index 0000000000..e5c60ad61e
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html
@@ -0,0 +1,9 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <div role="button" tabindex="0" aria-describedby="descriptionId">
+      <custom-icon />
+    </div>
+</custom-component>
+
+<span id="descriptionId">My Description</span>
+
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html
new file mode 100644
index 0000000000..d5d65462ca
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html
@@ -0,0 +1,8 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <div role="button" tabindex="0" aria-describedby="descriptionId">
+      <custom-icon />
+    </div>
+</custom-component>
+
+<span id="descriptionId">My Description</span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-III.sample.html
new file mode 100644
index 0000000000..14d2527003
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-III.sample.html
@@ -0,0 +1,8 @@
+<div role="button" tabindex="0" aria-describedby="descriptionId">
+  <custom-icon />
+</div>
+
+<custom-component id="descriptionId">
+  ⏷ #shadow-root (open)
+    <span>My Description</span>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIa.sample.html
new file mode 100644
index 0000000000..aefe9337c5
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIa.sample.html
@@ -0,0 +1,16 @@
+<span id="descriptionId">My Description</span>
+
+<custom-component descriptionId="descriptionId">
+  ⏷ #shadow-root (open)
+    <div ref="targetRef" role="button" tabindex="0" aria-describedby>
+      <!--The aria-describedby attribute is set automatically by the browser -->
+        <custom-icon />
+    </div>
+</custom-component>
+
+<script>
+  const description = document.getElementById('descriptionId');
+  // Assign the description element directly to the component's internal target element
+  // using ariaDescribedByElements to establish the accessible description
+  this.targetRef.ariaDescribedByElements = [description];
+</script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIb.sample.html
new file mode 100644
index 0000000000..a3caff1abb
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIb.sample.html
@@ -0,0 +1,19 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+  <slot name="description-slot"></slot>
+  <div ref="targetRef" role="button" tabindex="0" aria-describedby>
+    <!--The aria-describedby attribute is set automatically by the browser -->
+    <custom-icon />
+  </div>
+  <!-- slotted description -->
+  <span slot="description-slot">My Description</span>
+</custom-component>
+
+<script>
+  // Assign the slotted element(s) as description for the target using ariaDescribedbyByElements
+  const slotContent = this.shadowRoot
+    .querySelector('slot[name="description-slot"]')
+    .assignedElements({ flatten: true });
+  const description = slotContent.find(el => el.textContent.trim().length > 0);
+  this.targetRef.ariaDescribedbyByElements = [description];
+</script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IV.sample.html
new file mode 100644
index 0000000000..80c0a1b3e6
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IV.sample.html
@@ -0,0 +1,19 @@
+<custom-button>
+  ⏷ #shadow-root (open)
+    <div role="button" tabindex="0" aria-describedby>
+      <custom-icon />
+    </div>
+</custom-button>
+
+<custom-description id="descriptionId">
+  ⏷ #shadow-root (open)
+    <span>My Description</span>
+</custom-description>
+
+<script>
+  // Assign the description element directly to the component's internal target element
+  // using ariaDescribedByElements to establish the accessible description
+  const description = document.getElementById('descriptionId');
+  this.targetRef.ariaDescribedByElements = [description];
+</script>
+
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index da6064d310..c68513af2a 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -19,7 +19,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <div className="lead">
   In the Light DOM, the `aria-labelledby` attribute assigns an accessible name to an element by
-  referencing the ID of one or more elements that provide the descriptive text.
+  referencing the ID of one or more elements that provide the labeling text.
 </div>
 <p>
   This is particularly useful when a simple text label isn’t directly linked to the element, or when
@@ -27,8 +27,6 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </p>
 ### I. Referencing Within the Same DOM Tree
 
-<Canvas of={CCR.ExampleHTML} sourceState="hide" />
-
 • <b>Both elements in Light DOM</b> ✔️
 
 <Source language="html" dark code={DefaultExample}></Source>
@@ -43,6 +41,14 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
   </b>
 </p>
 
+<p>
+  Below is a working example of an `aria-labelledby`/`id` relationship within the shadowDom of a
+  custom button component. You can <b>test it with NVDA</b> to confirm the correct label
+  announcement.
+</p>
+
+<Canvas of={CCR.ExampleHTML} sourceState="hide" />
+
 ### II. Referencing From Outside a Shadow DOM Into That Shadow DOM
 
 • <b>Light DOM → Shadow DOM</b> ❌
@@ -94,8 +100,8 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
   <b>• Light DOM → Shadow DOM Example</b> ✔️
 </p>
 <p>
-  In this case a label element in the light DOM is directly assigned to a target element inside a custom
-  component’s shadow DOM using `ariaLabelledByElements`.
+  In this case a label element in the light DOM is directly assigned to a target element inside a
+  custom component’s shadow DOM using `ariaLabelledByElements`.
 </p>
 
 <Source language="html" dark code={WorkingExampleIIa}></Source>
@@ -129,9 +135,9 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <p>
   Referencing an element in the light DOM from within a shadow DOM using the standard
-  `aria-labelledby` is not possible. The `ariaLabelledByElements` property neither works
-  in this case because, for it to work, the label element must be in the same DOM or in a parent DOM
-  of the target element.
+  `aria-labelledby` is not possible. The `ariaLabelledByElements` property neither works in this
+  case because, for it to work, the label element must be in the same DOM or in a parent DOM of the
+  target element.
 </p>
 <Source language="html" dark code={NonWorkingExampleIII}></Source>
 
@@ -139,7 +145,11 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <p>
   The only option here is to <b>set the `id` directly on the host</b> of the labeling component. In
-  this case <b>all the visible text inside the referencing component will be assigned as the Accessible Name</b> of the target element.
+  this case{' '}
+  <b>
+    all the visible text inside the referencing component will be assigned as the Accessible Name
+  </b>{' '}
+  of the target element.
 </p>
 <Source language="html" dark code={WorkingExampleIII}></Source>
 <Canvas of={CCR.Example4} sourceState="hide" />
@@ -149,12 +159,16 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 Shadow DOM → Other Shadow DOM ❌
 
 <Source language="html" dark code={NonWorkingExampleIV}></Source>
-<p> This relationship is not valid because both `id` and `aria-labelledby` attributes are scoped only within their individual shadowDoms.</p>
+<p>
+  {' '}
+  This relationship is not valid because both `id` and `aria-labelledby` attributes are scoped only within
+  their individual shadowDoms.
+</p>
 ##### Working Solution
 
 A working solution for this case combines approaches II and III: setting the label component’s `id` directly on the host element (III), and using `Element.ariaLabelledByElements` to assign the label to the target component.
 
 <Source language="html" dark code={WorkingExampleIV}></Source>
-<Canvas of={CCR.Example5} sourceState="shown" />
+<Canvas of={CCR.Example5} sourceState="hide" />
 
 ⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
index d5eb065567..0cace5fc4d 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
@@ -1,6 +1,7 @@
 import { StoryObj, Args } from '@storybook/web-components-vite';
 import { MetaExtended } from '@root/types';
 import { html } from 'lit';
+import './aria-labelledby.styles.scss';
 
 const meta: MetaExtended = {
   id: '76ade552-2c03-4d6d-9dce-28daa3405678',
@@ -19,12 +20,7 @@ type Story = StoryObj;
 
 // Case: Standard Light DOM to Light DOM
 export const ExampleHTML: Story = {
-  render: () => html`
-    <span id="id_1">My Text</span>
-    <div class="btn btn-primary" aria-labelledby="id_1" role="button" tabindex="0">
-      <post-icon name="1022"></post-icon>
-    </div>
-  `,
+  render: () => html` <demo-button> </demo-button> `,
 };
 
 // Case: Referencing from Shadow DOM (Host Attribute) to Light DOM (Element) workaround setting programmatically the relevant Element property
@@ -68,7 +64,7 @@ export const Example3: Story = {
   },
   render: (args: Args) => html`
     <demo-button button-version="2" workaround="${args.workaround}"
-      ><span slot="label-slot">My Text</span></demo-button
+      ><span slot="aria-slot">My Text</span></demo-button
     >
   `,
 };
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss
new file mode 100644
index 0000000000..bf859e8590
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss
@@ -0,0 +1,22 @@
+::part(button) {
+  display: inline-flex;
+  position: relative;
+  align-items: center;
+  justify-content: center;
+  max-width: 100%;
+  overflow: hidden;
+  transition: opacity 250ms, border-color 250ms, background-color 250ms, color 250ms;
+  border-width: 2px;
+  border-style: solid;
+  border-radius: 100px;
+  font-weight: bold;
+  width: 48px;
+  min-height: 40px;
+  color: white;
+  background: black;
+
+  &:hover {
+    background-color: #504f4b;
+    border-color: #504f4b;
+  }
+}
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
index e0b2f1addf..0a309addfa 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
@@ -1,5 +1,5 @@
 <span id="labelId">My Text</span>
 
-<div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+<div role="button" tabindex="0" aria-labelledby="labelId">
   <custom-icon />
 </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
index b4a33a6bf0..b465534e19 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
@@ -1,7 +1,7 @@
 <custom-component>
   ⏷ #shadow-root (open)
     <span id="labelId">My Text</span>
-    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <div role="button" tabindex="0" aria-labelledby="labelId">
       <custom-icon />
     </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
index 68673bbf03..0ad5d47931 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
@@ -3,6 +3,6 @@
     <span id="labelId">My Text</span>
 </custom-component>
 
-<div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+<div role="button" tabindex="0" aria-labelledby="labelId">
   <custom-icon />
 </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
index ef1292dff4..388de8933f 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
@@ -2,7 +2,7 @@
 
 <custom-component>
   ⏷ #shadow-root (open)
-    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <div role="button" tabindex="0" aria-labelledby="labelId">
       <custom-icon />
     </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
index d3d88cbc00..997d9faf11 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
@@ -1,8 +1,8 @@
 <custom-component>
   ⏷ #shadow-root (open)
-    <slot name="label-slot"> </slot>
-    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
-      <custom-icon />
-    </div>
-    <span slot="label-slot" id="labelId">My Text</span>
+  <slot name="aria-slot"> </slot>
+  <div role="button" tabindex="0" aria-labelledby="labelId">
+    <custom-icon />
+  </div>
+  <span slot="aria-slot" id="labelId">My Text</span>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
index d208f22d56..05b27ce5bf 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
@@ -5,7 +5,7 @@
 
 <custom-button>
   ⏷ #shadow-root (open)
-    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <div role="button" tabindex="0" aria-labelledby="labelId">
       <custom-icon />
     </div>
 </custom-button>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
index ef1292dff4..388de8933f 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
@@ -2,7 +2,7 @@
 
 <custom-component>
   ⏷ #shadow-root (open)
-    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <div role="button" tabindex="0" aria-labelledby="labelId">
       <custom-icon />
     </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
index ef1292dff4..388de8933f 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
@@ -2,7 +2,7 @@
 
 <custom-component>
   ⏷ #shadow-root (open)
-    <div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+    <div role="button" tabindex="0" aria-labelledby="labelId">
       <custom-icon />
     </div>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
index a69d3a4738..429fdc2626 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
@@ -3,6 +3,6 @@
     <span>My Text</span>
 </custom-component>
 
-<div part="button" role="button" tabindex="0" aria-labelledby="labelId">
+<div role="button" tabindex="0" aria-labelledby="labelId">
   <custom-icon />
 </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
index 0315bef19f..9f2d63843c 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
@@ -2,7 +2,7 @@
 
 <custom-component labelId="labelId">
   ⏷ #shadow-root (open)
-    <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
+    <div ref="targetRef" role="button" tabindex="0" aria-labelledby>
       <!--The aria-labelledby attribute is set automatically by the browser -->
         <custom-icon />
     </div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
index 350f21637d..2ae81bd671 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
@@ -1,18 +1,18 @@
 <custom-component>
   ⏷ #shadow-root (open)
-    <slot name="label-slot"></slot>
-    <div ref="targetRef" part="button" role="button" tabindex="0" aria-labelledby>
-      <!--The aria-labelledby attribute is set automatically by the browser -->
-      <custom-icon />
-    </div>
-  <!-- slotted label elemen -->
-  <span slot="label-slot" id="labelId">My Text</span>
+  <slot name="aria-slot"></slot>
+  <div ref="targetRef" role="button" tabindex="0" aria-labelledby>
+    <!--The aria-labelledby attribute is set automatically by the browser -->
+    <custom-icon />
+  </div>
+  <!-- slotted label element -->
+  <span slot="aria-slot">My Text</span>
 </custom-component>
 
 <script>
-  // Assign the slotted element(s) as labels for the target using ariaLabelledByElements
+  // Assign the slotted element(s) as label for the target using ariaLabelledByElements
   const slotContent = this.shadowRoot
-    .querySelector('slot[name="label-slot"]')
+    .querySelector('slot[name="aria-slot"]')
     .assignedElements({ flatten: true });
   const label = slotContent.find(el => el.textContent.trim().length > 0);
   this.targetRef.ariaLabelledByElements = [label];
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
index 94df4df2b6..e2c1013216 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
@@ -5,7 +5,7 @@
 
 <custom-button>
   ⏷ #shadow-root (open)
-    <div part="button" role="button" tabindex="0" aria-labelledby>
+    <div role="button" tabindex="0" aria-labelledby>
       <custom-icon />
     </div>
 </custom-button>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html
new file mode 100644
index 0000000000..a3fa48a27b
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html
@@ -0,0 +1,3 @@
+<label id="labelId"></span>
+
+<input id="inputId">
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.js b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.js
new file mode 100644
index 0000000000..bb66e1f7a4
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.js
@@ -0,0 +1,8 @@
+// Get the element that will serve as the label
+const label = document.getElementById('labelId');
+
+// Get the input that needs a label
+const input = document.getElementById('inputId');
+
+// Assign one or more label elements directly to the target element `ariaLabelledByElements` property
+input.ariaLabelledByElements = [label];
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample.sample.html
new file mode 100644
index 0000000000..d73fcbd078
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample.sample.html
@@ -0,0 +1,3 @@
+<label for="inputId">My Text</span>
+
+<input id="inputId">
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html
new file mode 100644
index 0000000000..28476e3df6
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html
@@ -0,0 +1,5 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+  <label for="inputId">My Text</label>
+  <input id="inputId" />
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html
new file mode 100644
index 0000000000..152a5691b6
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html
@@ -0,0 +1,6 @@
+<custom-label>
+  ⏷ #shadow-root (open)
+    <label for="inputId">My Text</label>
+</custom-label>
+
+ <input id="inputId" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIa.sample.html
new file mode 100644
index 0000000000..2105fe5f23
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIa.sample.html
@@ -0,0 +1,6 @@
+<label for="inputId">My Text</label>
+
+<custom-input>
+  ⏷ #shadow-root (open)
+    <input id="inputId" />
+</custom-input>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIb.sample.html
new file mode 100644
index 0000000000..43a8dc6c44
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIb.sample.html
@@ -0,0 +1,6 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <slot name="label-slot"></slot>
+    <input id="inputId">
+  <label for="inputId" slot="label-slot">My Text</label>
+</custom-component>
\ No newline at end of file
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html
new file mode 100644
index 0000000000..3a60815e66
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html
@@ -0,0 +1,9 @@
+<custom-label>
+  ⏷ #shadow-root (open)
+  <label for="inputId">My Text</label>
+</custom-label>
+
+<custom-input>
+  ⏷ #shadow-root (open)
+    <input id="inputId" />
+</custom-input>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html
new file mode 100644
index 0000000000..6087c6cc11
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html
@@ -0,0 +1,6 @@
+<label id="labelId" for="inputId">My Text</label>
+
+<custom-input>
+  ⏷ #shadow-root (open)
+    <input id="inputId" aria-labelledby="labelId"/> 
+</custom-input>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html
new file mode 100644
index 0000000000..ca69b62a6d
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html
@@ -0,0 +1,6 @@
+<custom-input>
+  ⏷ #shadow-root (open)
+  <input id="inputId" aria-labelledby="labelId" />
+
+  <label id="labelId" for="labelId">My Text</label>
+</custom-input>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-III.sample.html
new file mode 100644
index 0000000000..efc44a6eb0
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-III.sample.html
@@ -0,0 +1,6 @@
+<custom-label id="labelId">
+  ⏷ #shadow-root (open)
+    <label for="inputId">My Text</label>
+</custom-label>
+
+<input id="inputId" aria-labelledby="labelId" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIa.sample.html
new file mode 100644
index 0000000000..45295664f1
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIa.sample.html
@@ -0,0 +1,16 @@
+<label for="inputId">My Text</label>
+
+<custom-input labelId="labelId">
+  ⏷ #shadow-root (open)
+    <input ref="targetRef" id="inputId" aria-labelledby>
+      <!--The aria-labelledby attribute is set automatically by the browser -->
+        <custom-icon />
+    </div>
+</custom-input>
+
+<script>
+  const label = document.getElementById('for[inputId]');
+  // Assign the label element directly to the component's internal target element
+  // using ariaLabelledByElements to establish the accessible name
+  this.targetRef.ariaLabelledByElements = [label];
+</script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html
new file mode 100644
index 0000000000..2513c7c2b1
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html
@@ -0,0 +1,17 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+  <slot name="label-slot"></slot>
+  <input ref="targetRef" aria-labelledby>
+    <!--The aria-labelledby attribute is set automatically by the browser -->
+  <!-- slotted label element -->
+  <label slot="label-slot">My Text</label>
+</custom-component>
+
+<script>
+  // Assign the slotted element(s) as label for the target using ariaLabelledByElements
+  const slotContent = this.shadowRoot
+    .querySelector('slot[name="label-slot"]')
+    .assignedElements({ flatten: true });
+  const label = slotContent.find(el => el.textContent.trim().length > 0);
+  this.targetRef.ariaLabelledByElements = [label];
+</script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html
new file mode 100644
index 0000000000..fb6607b85a
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html
@@ -0,0 +1,16 @@
+<custom-label id="labelId">
+  ⏷ #shadow-root (open)
+    <label for="inputId">My Text</label>
+</custom-label>
+
+<custom-button>
+  ⏷ #shadow-root (open)
+  <input id="inputId" aria-labelledby="labelId" />
+</custom-button>
+
+<script>
+  // Assign the label element directly to the component's internal target element
+  // using ariaLabelledByElements to establish the accessible name
+  const label = document.getElementById('labelId');
+  this.targetRef.ariaLabelledByElements = [label];
+</script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
index c18c64781e..ae3d31760c 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -1,5 +1,17 @@
-import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './for.stories';
+import DefaultExample from './examples/defaultExample.sample.html?raw';
+import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
+import ArialabelledbyElementsPropertyHTML from './examples/arialabelledbyElementsProperty.sample.html?raw';
+import ArialabelledbyElementsProperty from './examples/arialabelledbyElementsProperty.sample.js?raw';
+import NonWorkingExampleIIa from './examples/nonWorkingExample-IIa.sample.html?raw';
+import NonWorkingExampleIIb from './examples/nonWorkingExample-IIb.sample.html?raw';
+import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
+import NonWorkingExampleIII from './examples/nonWorkingExample-III.sample.html?raw';
+import WorkingExampleIII from './examples/workingExample-III.sample.html?raw';
+import NonWorkingExampleIV from './examples/nonWorkingExample-IV.sample.html?raw';
+import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <Meta of={CCR} />
 
@@ -9,40 +21,110 @@ import * as CCR from './for.stories';
 
 <div className="lead">The native HTML `for`/`id` relationship is a fundamental way to connect a `<label>` element to a form control, such as `<input>`, `<select>`, `<textarea>`, etc. or even to a custom form-associated control within the same DOM.</div>
 
-<div>This connection is established by setting the for attribute on the `<label>` to match the `id` attribute of the form control it describes. This relationship is crucial for accessibility, as it allows assistive technologies like screen readers to correctly associate and announce the label text when focus is placed on the associated input field.</div>
+<p>
+  This relationship is important for accessibility, as it allows assistive technologies to correctly
+  associate and announce the label text when focus is placed on the respective input field.
+</p>
 
-### I. Referencing Within the Same DOM Tree ✔️
+### I. Referencing Within the Same DOM Tree
 
-<Canvas of={CCR.ExampleHTML} sourceState="shown" />
+• <b>Both elements in Light DOM</b> ✔️
 
-### II. Referencing From Outside a Shadow DOM Into That Shadow DOM ❌
+<Source language="html" dark code={DefaultExample}></Source>
 
-<ul>
-  <li>Light DOM → Shadow DOM</li>
-  <li>Slotted Content → Shadow DOM</li>
-</ul>
+• <b>Both elements in same Shadow DOM</b> ✔️
+
+<Source language="html" dark code={DefaultExample2}></Source>
+<p>
+  <b>
+    The above relationships are valid because in both cases the label and its associated input
+    element are part of the same tree.
+  </b>
+</p>
+
+<p>
+  Below is a working example of a `for`/`id` relationship within the shadowDom of a custom
+  component. You can <b>test it with NVDA</b> to confirm the correct label announcement.
+</p>
+
+<Canvas of={CCR.ExampleHTML} sourceState="hide" />
+### II. Referencing From Outside a Shadow DOM Into That Shadow DOM
+
+• <b>Light DOM → Shadow DOM</b> ❌
+
+<Source language="html" dark code={NonWorkingExampleIIa}></Source>
+
+• <b>Slotted Content → Shadow DOM</b> ❌
+
+<Source language="html" dark code={NonWorkingExampleIIb}></Source>
+
+<p>
+  The above examples do not work across shadow DOM boundaries when setting the `for` / `id`
+  attributes directly.
+</p>
+<p>
+  <b>
+    Attribute element references can only point to elements in the same DOM or shadow DOM, because
+    IDs are only valid within their own scope.
+  </b>
+</p>
 
-<p>When the referencing element (e.g. `<label for="...">`) is in the Light DOM and the target element is inside a Shadow DOM, the `for` attribute <b>cannot reference elements inside the Shadow DOM</b> using the standard id mechanism.</p>
+#### Workaround: `Element:ariaLabelledByElements`
 
-##### Possible Workarounds
+<p>
+  `ariaLabelledByElements` is a property of the Element interface that returns an array of elements
+  labeling the element. It provides direct references to these elements rather than just their ID
+  strings.
+  <a
+    target="blank"
+    href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements"
+  >
+    🔗ariaLabelledByElements
+  </a>
+</p>
 
-###### `Element:ariaLabelledByElements`
+<div className="lead">Basic usage of `ariaLabelledByElements` </div>
+<Source language="html" dark code={ArialabelledbyElementsPropertyHTML}></Source>
+<p>
+  Instead of adding the `aria-labelledby` attribute on the element, we can set it using the
+  `ariaLabelledByElements` property.
+</p>
+<Source language="js" dark code={ArialabelledbyElementsProperty}></Source>
+<p>
+  The following examples demonstrate how the `ariaLabelledByElements` property can be used to
+  establish relationships <b>across the shadow DOM</b>.
+</p>
 
-Defines programmatically the `ariaLabelledByElements` property of the element: `this.internalEl.ariaLabelledByElements = [labelEl]`. This solution creates the relationship without the use of an `id`.
+<p>
+  <b>• Light DOM → Shadow DOM Example</b> ✔️
+</p>
+<p>
+  In this case a label element in the light DOM is directly assigned to a target element inside a
+  custom component’s shadow DOM using `ariaLabelledByElements`.
+</p>
 
-<b>Light DOM → Shadow DOM Example</b>
-<Canvas of={CCR.Example2} sourceState="shown" />
+<Source language="html" dark code={WorkingExampleIIa}></Source>
+<p>Use the control below to toggle the `ariaLabelledByElements` workaround implementation.</p>
+<Canvas of={CCR.Example2} sourceState="hide" />
 <div className="hide-col-default">
   <Controls of={CCR.Example2} />
 </div>
 
-<b>Slotted Content → Shadow DOM Example</b>
-<Canvas of={CCR.Example3} sourceState="shown" />
+<p>
+  <b>• Slotted Content → Shadow DOM Example</b> ✔️
+</p>
+<p>
+  In this case a label element provided via a light DOM slot is automatically assigned to a target
+  element inside a custom component’s shadow DOM using `ariaLabelledByElements`.
+</p>
+<Source language="html" dark code={WorkingExampleIIb}></Source>
+<p>Use the control below to toggle the `ariaLabelledByElements` workaround implementation.</p>
+<Canvas of={CCR.Example3} sourceState="hide<p>" />
 <div className="hide-col-default">
   <Controls of={CCR.Example3} />
 </div>
 
-⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
+⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
 
 ### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
 
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
index 4c0a389b08..11061989ca 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.stories.ts
@@ -19,11 +19,7 @@ type Story = StoryObj;
 
 // Case: Standard Light DOM to Light DOM
 export const ExampleHTML: Story = {
-  render: () => html`
-  
-    <label for="id_0">My Text</label>
-    <input id="id_0"></input>
-  `,
+  render: () => html` <demo-input></demo-input> `,
 };
 
 // Case: Referencing from Shadow DOM (Host Attribute) to Light DOM (Element) workaround setting programmatically the relevant Element property
@@ -42,11 +38,11 @@ export const Example2: Story = {
   },
   render: (args: Args) => html`
     <label for="id_1">My Text</label>
-    <demo-target
+    <demo-input
       target-version="1"
       workaround="${args.workaround}"
       arialabelledby-id="id_1"
-    ></demo-target>
+    ></demo-input>
   `,
 };
 
@@ -66,8 +62,8 @@ export const Example3: Story = {
     workaround: 'none',
   },
   render: (args: Args) => html`
-    <demo-target target-version="2" workaround="${args.workaround}">
-      <label slot="label-slot">My Text</label></demo-target
+    <demo-input target-version="2" workaround="${args.workaround}">
+      <label slot="aria-slot">My Text</label></demo-input
     >
   `,
 };
@@ -97,10 +93,10 @@ export const Example4: Story = {
 export const Example5: Story = {
   render: () => html`
     <demo-label id="id_3"></demo-label>
-    <demo-target
+    <demo-input
       target-version="3"
       arialabelledby-id="id_3"
       workaround="ariaLabelledByElements"
-    ></demo-target>
+    ></demo-input>
   `,
 };

From 4c93d040da6a6531c3bd60e894d5bb3c217fe093 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Wed, 24 Sep 2025 08:58:17 +0200
Subject: [PATCH 15/29] update role="list" examples and text

---
 .../demo-components/demo-list-item-group.ts   |  11 +-
 .../src/demo-components/demo-list.ts          |  21 ++-
 .../aria-labelledby/aria-labelledby.docs.mdx  |   3 +-
 .../aria-role-list/aria-role-list.docs.mdx    | 152 +++++++++++++-----
 .../aria-role-list/aria-role-list.stories.ts  |  60 ++++---
 .../examples/defaultExample.sample.html       |   5 +
 .../examples/defaultExample2.sample.html      |   8 +
 .../examples/defaultExample3.sample.html      |   7 +
 .../examples/workingExample-IIIa.sample.html  |   7 +
 .../examples/workingExample-IIIb.sample.html  |  13 ++
 .../examples/workingExample-IIa.sample.html   |   6 +
 .../examples/workingExample-IIb.sample.html   |  10 ++
 .../examples/workingExample-IVa.sample.html   |  11 ++
 .../examples/workingExample-IVb.sample.html   |  20 +++
 .../examples/workingExample-IVc.sample.html   |  20 +++
 ...arialabelledbyElementsProperty.sample.html |   4 +-
 .../for/examples/defaultExample2.sample.html  |   4 +-
 .../nonWorkingExample-III.sample.html         |   2 +-
 .../examples/nonWorkingExample-IV.sample.html |   2 +-
 .../examples/workingExample-IIb.sample.html   |   7 +-
 .../examples/workingExample-IV.sample.html    |   2 +-
 .../for/for.docs.mdx                          |  53 +++---
 turbo.json                                    |   3 -
 23 files changed, 331 insertions(+), 100 deletions(-)
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample2.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample3.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVa.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVb.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVc.sample.html
 delete mode 100644 turbo.json

diff --git a/packages/documentation/src/demo-components/demo-list-item-group.ts b/packages/documentation/src/demo-components/demo-list-item-group.ts
index 3ff0edb26a..14718735c7 100644
--- a/packages/documentation/src/demo-components/demo-list-item-group.ts
+++ b/packages/documentation/src/demo-components/demo-list-item-group.ts
@@ -24,13 +24,22 @@ export class DemoListItemGroup extends HTMLElement {
     if (!this.shadowRoot) return;
     if (this.listGroupVersion == 1) {
       this.shadowRoot.innerHTML = `
-        <slot name="demo-list-item"></slot>
+        <slot name="list-item"></slot>
       `;
     } else if (this.listGroupVersion == 2) {
       this.shadowRoot.innerHTML = `<slot name="list-parent"></slot>
         <div role="listitem">item 1</div>
         <div role="listitem">item 2</div>
         <div role="listitem">item 3</div>`;
+    } else if (this.listGroupVersion == 3) {
+      this.shadowRoot.innerHTML = `
+        <div role="listitem">item 1</div>
+        <div role="listitem">item 2</div>
+        <div role="listitem">item 3</div>`;
+    } else if (this.listGroupVersion == 4) {
+      this.shadowRoot.innerHTML = `
+        <slot></slot>
+      `;
     }
   }
 }
diff --git a/packages/documentation/src/demo-components/demo-list.ts b/packages/documentation/src/demo-components/demo-list.ts
index 0e85c7238b..503d71aa99 100644
--- a/packages/documentation/src/demo-components/demo-list.ts
+++ b/packages/documentation/src/demo-components/demo-list.ts
@@ -22,18 +22,31 @@ export class DemoList extends HTMLElement {
 
   private render() {
     if (!this.shadowRoot) return;
-    if (this.listVersion == 1) {
+    if (this.listVersion == 0) {
       this.shadowRoot.innerHTML = `
-        <div>
-          <slot></slot>
+        <div role="list" tabindex="0">
         </div>
     `;
+    } else if (this.listVersion == 1) {
+      this.shadowRoot.innerHTML = `
+          <slot></slot>
+    `;
     } else if (this.listVersion == 2) {
       this.shadowRoot.innerHTML = `
         <div role="list" tabindex="0">
-          <slot></slot>
+          <div role="listitem">item 1</div>
+          <div role="listitem">item 2</div>
+          <div role="listitem">item 3</div>
+        </div>
+    `;
+    } else if (this.listVersion == 3) {
+      this.shadowRoot.innerHTML = `
+        <div role="list" tabindex="0">
+            <slot></slot>
         </div>
     `;
+    } else if (this.listVersion == 4) {
+      this.shadowRoot.innerHTML = `<demo-list-item-group list-group-version="3"></demo-list-item-group>`;
     }
   }
 }
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index c68513af2a..d4eaaead45 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -19,7 +19,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <div className="lead">
   In the Light DOM, the `aria-labelledby` attribute assigns an accessible name to an element by
-  referencing the ID of one or more elements that provide the labeling text.
+  referencing the ID of one or more elements that provide the descriptive text.
 </div>
 <p>
   This is particularly useful when a simple text label isn’t directly linked to the element, or when
@@ -160,7 +160,6 @@ Shadow DOM → Other Shadow DOM ❌
 
 <Source language="html" dark code={NonWorkingExampleIV}></Source>
 <p>
-  {' '}
   This relationship is not valid because both `id` and `aria-labelledby` attributes are scoped only within
   their individual shadowDoms.
 </p>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
index e1453d9d5d..a746187144 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -1,61 +1,137 @@
-import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-role-list.stories';
 
+import DefaultExample from './examples/defaultExample.sample.html?raw';
+import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
+import DefaultExample3 from './examples/defaultExample3.sample.html?raw';
+import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
+import WorkingExampleIIIa from './examples/workingExample-IIIa.sample.html?raw';
+import WorkingExampleIIIb from './examples/workingExample-IIIb.sample.html?raw';
+import WorkingExampleIVa from './examples/workingExample-IVa.sample.html?raw';
+import WorkingExampleIVb from './examples/workingExample-IVb.sample.html?raw';
+import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
+
 <Meta of={CCR} />
 
 # role="list"
 
 <div className="lead">
-  The `role="list"` attribute identifies an element as a list for assistive technologies, signaling
-  it contains related items marked with `role="listitem"`.
+  The `role="list"` tells assistive technologies that an element represents a list, which is
+  expected to contain related items identified with `role="listitem"`.
 </div>
 
-<div>
-While native elements like `<ul>` have this role implicitly, adding `role="list"` to non-semantic elements (e.g., `<div>`) ensures custom components are recognized as lists by screen readers.
-</div>
+### I. Referencing Within the Same DOM Tree
+
+• <b>Both `list` parent and `listitem` children in Light DOM</b> ✔️
+
+<Source language="html" dark code={DefaultExample}></Source>
+
+<Canvas of={CCR.ExampleHTML} sourceState="hide" />
+
+<p>
+  This represents the default structure, where a `role="list"` element contains direct children with
+  `role="listitem"`.
+</p>
+
+• <b>Both `list` parent and `listitem` children in the same Shadow DOM</b> ✔️
+
+<Source language="html" dark code={DefaultExample2}></Source>
+
+<Canvas of={CCR.Example1a} sourceState="hide" />
+
+<p>
+  Same as above, but contained within a custom component’s Shadow DOM. The `role="list"` still has
+  direct `role="listitem"` children, so the structure remains valid.
+</p>
+
+• <b>`list` role on the host and slotted `listitem` children</b> ✔️
+
+<Source language="html" dark code={DefaultExample3}></Source>
+
+<Canvas of={CCR.Example1b} sourceState="hide" />
+
+<p>
+  Similarly, in the case of a component with `role="list"` set on the host and slotted `listitems`, the
+  relationship is preserved correctly.
+</p>
+
+### II. Parent in the Light DOM-children Into The Shadow DOM
+
+• <b>Light DOM → Shadow DOM</b> ✔️
+
+<Source language="html" dark code={WorkingExampleIIa}></Source>
+
+<Canvas of={CCR.Example2a} sourceState="hide" />
+
+<p>
+  In the case a component with `role="list"` in the host with `listitem` elements within its Shadow
+  DOM, the relationship is valid.
+</p>
+
+• <b>Slotted Parent → Shadow DOM</b> ❌
+
+<Source language="html" dark code={WorkingExampleIIb}></Source>
+
+<p>
+  ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
+  children of an element with `role="list"`. The relationship fails not because of the Shadow DOM
+  boundary, but due to the incorrect structure itself.
+</p>
+
+### III. Parent in the Shadow DOM - Children Out to the Light DOM
+
+• <b>Parent in the Shadow DOM → Children in the Light DOM</b> ❌
+
+<Source language="html" dark code={WorkingExampleIIIa}></Source>
+
+<p>
+  ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
+  children of an element with `role="list"`. The relationship fails not because of the Shadow DOM
+  boundary, but due to the incorrect structure itself.
+</p>
+
+• <b>Parent in the Shadow DOM → Slotted Children </b> ✔️
+
+<Source language="html" dark code={WorkingExampleIIIb}></Source>
+
+<Canvas of={CCR.Example3b} sourceState="hide" />
+
+<p>
+  When a component applies `role="list"` to an internal element and its children with `role="listitem"` are slotted into that element, the structure still works correctly and preserves a valid `list/listitem` relationship.
+</p>
 
-### I. All Within the Same DOM Tree ✔️
+### IV. Referencing From One Shadow DOM To Another Shadow shadowDOM
 
-<ul>
-  <li>Basic HTML Example</li>
-</ul>
-<Canvas of={CCR.ExampleHTML} sourceState="shown" />
-<ul>
-  <li>Light DOM → Component with Slotted Children</li>
-</ul>
-<Canvas of={CCR.Example1a} sourceState="shown" />
+• <b>Parent in the Shadow DOM → Children grouped in a nested Component</b> ✔️
 
-<ul>
-  <li> Component host → Same Component Slotted Children</li>
-</ul>
-<Canvas of={CCR.Example1b} sourceState="shown" />
+<Source language="html" dark code={WorkingExampleIVa}></Source>
 
-### II. Parent in the Light DOM - Children Into The Shadow DOM
+<Canvas of={CCR.Example4a} sourceState="shown" />
 
-<ul>
-  <li>Light DOM → Shadow DOM ✔️</li>
+<p>
+  This structure works correctly: the parent `role="list"` maintains a valid relationship with its children, even when the `listitem` elements are grouped inside a nested component.
+</p>
 
-</ul>
-  <Canvas of={CCR.Example2a} sourceState="shown" />
+• <b>Parent in the Shadow DOM → slotted Children as individual Components</b> ✔️
 
-<ul>
-  <li>Slotted Parent → Shadow DOM ❌</li>
+<Source language="html" dark code={WorkingExampleIVb}></Source>
 
-</ul>
-  <Canvas of={CCR.Example2b} sourceState="shown" />
+<Canvas of={CCR.Example4b} sourceState="hide" />
+<p>
+ In this case the `listitem` elements are slotted and encapsulated within individual custom components. This structure also forms a valid `list-listitem` relationship.
+</p>
 
-### III. Parent in the Shadow DOM - Children Out to the Light DOM ✔️
+• <b>Parent in the Shadow DOM → nested Grouping Component -> nested Children individual components</b> ✔️
 
-<ul>
-  <li>Shadow DOM → Light DOM </li>
-</ul>
+<Source language="html" dark code={WorkingExampleIVc}></Source>
 
-<Canvas of={CCR.Example3} sourceState="shown" />
+<Canvas of={CCR.Example4c} sourceState="hide" />
 
-### IV. Referencing From One Shadow DOM To Another Shadow DOM ✔️
+<p>
+  In the case of a `role="list"` parent containing a grouping component, with individual `listitem` children nested inside their own components, the relationship is still correctly preserved across two Shadow DOM boundaries.
+</p>
 
-<ul>
-  <li>Shadow DOM → Other nested Shadow DOM</li>
-</ul>
 
-<Canvas of={CCR.Example4} sourceState="shown" />
+## Conclusion: Shadow DOM and List Semantics 
+<p>When the markup is properly structured such that elements with `role="listitem"` exist within a parent element having `role="list"`, the presence of Shadow DOM does not break the semantic `list/listitem` relationship—even across multiple component boundaries. The `listitems` do not necessarily have to be direct children of the `role="list"` element for the relationship to be preserved, as the accessibility tree will bridge through the encapsulation when the markup is correct.</p>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
index ef3ef2871f..7fd94c044c 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
@@ -30,25 +30,21 @@ export const ExampleHTML: Story = {
 
 // Case: Light Dom to child components with Slotted content
 export const Example1a: Story = {
-  render: () => html`
-    <div role="list" tabindex="0">
-      <demo-list-item-group list-group-version="1">
-        <div slot="demo-list-item" role="listitem">item 1</div>
-        <div slot="demo-list-item" role="listitem">item 2</div>
-        <div slot="demo-list-item" role="listitem">item 3</div>
-      </demo-list-item-group>
-    </div>
-  `,
+  render: () => html` <demo-list list-version="2">
+    <div role="listitem">item 1</div>
+    <div role="listitem">item 2</div>
+    <div role="listitem">item 3</div>
+  </demo-list>`,
 };
 
 // Case: Parent in the Light - children with Slotted content same component
 export const Example1b: Story = {
   render: () => html`
-    <demo-list-item-group list-group-version="1" role="list" tabindex="0">
-      <div slot="demo-list-item" role="listitem">item 1</div>
-      <div slot="demo-list-item" role="listitem">item 2</div>
-      <div slot="demo-list-item" role="listitem">item 3</div>
-    </demo-list-item-group>
+    <demo-list role="list" tabindex="0" list-version="1">
+      <div role="listitem">item 1</div>
+      <div role="listitem">item 2</div>
+      <div role="listitem">item 3</div>
+    </demo-list>
   `,
 };
 
@@ -69,9 +65,19 @@ export const Example2b: Story = {
 };
 
 // Case: Parent in the Shadow - Children in the Light
-export const Example3: Story = {
+export const Example3a: Story = {
   render: () => html`
-    <demo-list role="list" tabindex="0" list-version="1">
+    <demo-list list-version="0"></demo-list>
+    <div role="listitem">item 1</div>
+    <div role="listitem">item 2</div>
+    <div role="listitem">item 3</div>
+  `,
+};
+
+// Case: Parent in the Shadow - Children Slotted
+export const Example3b: Story = {
+  render: () => html`
+    <demo-list list-version="3">
       <div role="listitem">item 1</div>
       <div role="listitem">item 2</div>
       <div role="listitem">item 3</div>
@@ -79,11 +85,27 @@ export const Example3: Story = {
   `,
 };
 
-// Case: Referencing from Shadow DOM (Host Attribute) to Slotted Content (Element)
-export const Example4: Story = {
-  render: () => html`<demo-list list-version="2">
+// Case: Referencing from Shadow DOM to embedded Shadow DOM
+export const Example4a: Story = {
+  render: () => html` <demo-list list-version="4" role="list" tabindex="0"> </demo-list>`,
+};
+
+// Case: Referencing from Shadow DOM with slotted children in different embedded shadow DOMs
+export const Example4b: Story = {
+  render: () => html`<demo-list list-version="3">
     <demo-list-item>item 1</demo-list-item>
     <demo-list-item>item 2</demo-list-item>
     <demo-list-item>item 3</demo-list-item>
   </demo-list>`,
 };
+
+// Case: Parent in the Shadow > custom-component > childrent components
+export const Example4c: Story = {
+  render: () => html`<demo-list list-version="3">
+    <demo-list-item-group list-group-version="4" role="presentation">
+      <demo-list-item>item 1</demo-list-item>
+      <demo-list-item>item 2</demo-list-item>
+      <demo-list-item>item 3</demo-list-item>
+    </demo-list-item-group>
+  </demo-list>`,
+};
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample.sample.html
new file mode 100644
index 0000000000..3d98ef8e29
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample.sample.html
@@ -0,0 +1,5 @@
+<div role="list">
+  <div role="listitem">item 1</div>
+  <div role="listitem">item 2</div>
+  <div role="listitem">item 3</div>
+</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample2.sample.html
new file mode 100644
index 0000000000..4ab8ba42ec
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample2.sample.html
@@ -0,0 +1,8 @@
+<custom-component>
+  ⏷ #shadow-root (open)
+    <div role="list">
+      <div role="listitem">item 1</div>
+      <div role="listitem">item 2</div>
+      <div role="listitem">item 3</div>
+    </div>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample3.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample3.sample.html
new file mode 100644
index 0000000000..a0ae2e60b8
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample3.sample.html
@@ -0,0 +1,7 @@
+<custom-component role="list">
+  ⏷ #shadow-root (open)
+    <slot></slot>
+  <div role="listitem">item 1</div>
+  <div role="listitem">item 2</div>
+  <div role="listitem">item 3</div>
+</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIa.sample.html
new file mode 100644
index 0000000000..670820c5bf
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIa.sample.html
@@ -0,0 +1,7 @@
+<custom-list>
+  ⏷ #shadow-root (open)
+    <div role="list">test</div>
+</custom-list>
+<div role="listitem">item 1</div>
+<div role="listitem">item 2</div>
+<div role="listitem">item 3</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIb.sample.html
new file mode 100644
index 0000000000..be5ccd5d35
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIb.sample.html
@@ -0,0 +1,13 @@
+<custom-list>
+  ⏷ #shadow-root (open)
+    <div role="list">
+      <slot></slot>
+    </div>
+    
+  <!-- Slotted list items -->
+  <div role="listitem">item 1</div>
+  <div role="listitem">item 2</div>
+  <div role="listitem">item 3</div>
+</custom-list>
+
+
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIa.sample.html
new file mode 100644
index 0000000000..8e9e8883d5
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIa.sample.html
@@ -0,0 +1,6 @@
+<custom-list role="list">
+  ⏷ #shadow-root (open)
+    <div role="listitem">item 1</div>
+    <div role="listitem">item 2</div>
+    <div role="listitem">item 3</div>
+</custom-list>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIb.sample.html
new file mode 100644
index 0000000000..9e95d4a2ac
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIb.sample.html
@@ -0,0 +1,10 @@
+<custom-list>
+  ⏷ #shadow-root (open)
+    <slot name="parent-slot"></slot>
+    <div role="listitem">item 1</div>
+    <div role="listitem">item 2</div>
+    <div role="listitem">item 3</div>
+
+ <!-- Slotted parent with role="list"-->   
+ <div role="list" slot="parent-slot"></div>
+</custom-list>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVa.sample.html
new file mode 100644
index 0000000000..937da1cef0
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVa.sample.html
@@ -0,0 +1,11 @@
+<custom-list>
+  ⏷ #shadow-root (open)
+    <div role="list">
+      <custom-list-item-group>
+        ⏷ #shadow-root (open)
+        <div role="listitem">item 1</div>
+        <div role="listitem">item 2</div>
+        <div role="listitem">item 3</div>
+      </custom-list-item-group>
+    </div>
+</custom-list>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVb.sample.html
new file mode 100644
index 0000000000..a565b687b5
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVb.sample.html
@@ -0,0 +1,20 @@
+<custom-list>
+  ⏷ #shadow-root (open)
+    <div role="list">
+      <slot></slot>
+    </div>
+
+  <!-- Slotted custom list components -->
+  <custom-list-item>
+    ⏷ #shadow-root (open)
+      <div role="listitem">item 1</div>
+  </custom-list-item>
+  <custom-list-item>
+    ⏷ #shadow-root (open)
+      <div role="listitem">item 2</div>
+  </custom-list-item>
+  <custom-list-item>
+    ⏷ #shadow-root (open)
+    <div role="listitem">item 3</div>
+  </custom-list-item>
+</custom-list>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVc.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVc.sample.html
new file mode 100644
index 0000000000..d2950b875f
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVc.sample.html
@@ -0,0 +1,20 @@
+<custom-list>
+  ⏷ #shadow-root (open)
+      <div role="list">
+        <custom-list-item-group>
+          ⏷ #shadow-root (open)
+            <custom-list-item>
+              ⏷ #shadow-root (open)
+                <div role="listitem">item 1</div>
+            </custom-list-item>
+            <custom-list-item>
+              ⏷ #shadow-root (open)
+                <div role="listitem">item 2</div>
+            </custom-list-item>
+            <custom-list-item>
+              ⏷ #shadow-root (open)
+                <div role="listitem">item 3</div>
+            </custom-list-item>
+        </custom-list-item-group>
+      </div>
+</custom-list>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html
index a3fa48a27b..b061f1763b 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html
@@ -1,3 +1,3 @@
-<label id="labelId"></span>
+<label id="labelId">My Text</label>
 
-<input id="inputId">
+<input id="inputId" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html
index 28476e3df6..1757b65f4e 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html
@@ -1,5 +1,5 @@
 <custom-component>
   ⏷ #shadow-root (open)
-  <label for="inputId">My Text</label>
-  <input id="inputId" />
+    <label for="inputId">My Text</label>
+    <input id="inputId" />
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html
index 152a5691b6..453cefe722 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html
@@ -3,4 +3,4 @@
     <label for="inputId">My Text</label>
 </custom-label>
 
- <input id="inputId" />
+<input id="inputId" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html
index 3a60815e66..1b51c7fc71 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html
@@ -1,6 +1,6 @@
 <custom-label>
   ⏷ #shadow-root (open)
-  <label for="inputId">My Text</label>
+    <label for="inputId">My Text</label>
 </custom-label>
 
 <custom-input>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html
index 2513c7c2b1..558477d758 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html
@@ -1,10 +1,11 @@
 <custom-component>
   ⏷ #shadow-root (open)
-  <slot name="label-slot"></slot>
-  <input ref="targetRef" aria-labelledby>
+    <slot name="label-slot"></slot>
     <!--The aria-labelledby attribute is set automatically by the browser -->
+    <div ref="targetRef" role="button" tabindex="0" aria-labelledby>
+
   <!-- slotted label element -->
-  <label slot="label-slot">My Text</label>
+  <span slot="label-slot">My Text</span>
 </custom-component>
 
 <script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html
index fb6607b85a..aa7f6b29c3 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html
@@ -5,7 +5,7 @@
 
 <custom-button>
   ⏷ #shadow-root (open)
-  <input id="inputId" aria-labelledby="labelId" />
+  <input ref="targetRef" id="inputId" aria-labelledby />
 </custom-button>
 
 <script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
index ae3d31760c..6251f699f1 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -126,38 +126,45 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 ⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
 
-### III. Referencing From Inside a Shadow DOM Out to the Light DOM ❌
+### III. Referencing From Inside a Shadow DOM Out to the Light DOM
 
-<ul>
-  <li>Shadow DOM → Light DOM</li>
-  <li>Shadow DOM → Slotted Content</li>
-</ul>
 <p>
-  A `for` attribute on an element inside a Shadow DOM{' '}
-  <b>cannot be used to reference the id of an element outside that Shadow DOM</b> (in the Light DOM
-  or an ancestor Shadow DOM). The way the HTML for attribute resolves an id is strictly limited to
-  the element's shadow-including tree.
+  <b>• Shadow DOM → Light DOM (or Shadow DOM → Slotted Content)</b>❌
 </p>
 
-##### Possible Workaround
+<p>
+ A `for` attribute on an element inside a Shadow DOM <b>cannot reference the id of an element outside that Shadow DOM</b>. The `ariaLabelledByElements` property neither works in this case because, for it to work, the label element must be in the same DOM or in a parent DOM of the target element.
+</p>
+
+<Source language="html" dark code={NonWorkingExampleIII}></Source>
 
-A possible workaround is to set directly an `id` on the host of the referencing element and an `aria-labelledby`on the target element.
+##### Working Solution: Set the `id`on the label component host
 
-<Canvas of={CCR.Example4} sourceState="shown" />
+<p>
+  The only option here is to <b>set the `id` directly on the host</b> of the labeling component. In
+  this case{' '}
+  <b>
+    all the visible text inside the referencing component will be assigned as the Accessible Name
+  </b>{' '}
+  of the target element.
+</p>
+<Source language="html" dark code={WorkingExampleIII}></Source>
+<Canvas of={CCR.Example4} sourceState="hide" />
 
-### IV.Referencing From a Shadow DOM Out to another Shadow DOM ❌
+### IV. Referencing From One Shadow DOM To Another Shadow DOM
 
-<ul>
-  <li>Shadow DOM → Other Shadow DOM</li>
-</ul>
+Shadow DOM → Other Shadow DOM ❌
 
-##### Possible Workaround
+<Source language="html" dark code={NonWorkingExampleIV}></Source>
+<p>
+  This relationship is not valid because both `for` and `id` attributes are scoped only within
+  their individual shadowDoms.
+</p>
+##### Working Solution
 
-A workaround for this case combines approaches II and III: using `Element.ariaLabelledByElements` to set an `aria-labelledby` attribute on the Shadow DOM `input`, linking it to an ID defined on the host element of the `label` component.
+A working solution for this case combines approaches II and III: setting the label component’s `id` directly on the host element (III), and using `Element.ariaLabelledByElements` to assign the label to the target component (II).
 
-<Canvas of={CCR.Example5} sourceState="shown" />
-<div className="hide-col-default">
-  <Controls of={CCR.Example5} />
-</div>
+<Source language="html" dark code={WorkingExampleIV}></Source>
+<Canvas of={CCR.Example5} sourceState="hide" />
 
-⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but fails on Siteimprove and Accessibility Insights tools.
+⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
\ No newline at end of file
diff --git a/turbo.json b/turbo.json
deleted file mode 100644
index 90faa728a1..0000000000
--- a/turbo.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
-  "tasks": {}
-}

From f7fd9a9c191ffcd82694edc3c57b73ac1d9a15b6 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Wed, 24 Sep 2025 09:48:10 +0200
Subject: [PATCH 16/29] revert file

---
 turbo.json | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 turbo.json

diff --git a/turbo.json b/turbo.json
new file mode 100644
index 0000000000..90faa728a1
--- /dev/null
+++ b/turbo.json
@@ -0,0 +1,3 @@
+{
+  "tasks": {}
+}

From c8a88030b10d8236b21d1941f45bbc2443b125ed Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Wed, 24 Sep 2025 11:05:58 +0200
Subject: [PATCH 17/29] added intro cross reference table

---
 .../reference-table/reference-table.docs.mdx  |  66 +++++++++++
 .../reference-table.stories.ts                | 110 ++++++++++++++++++
 2 files changed, 176 insertions(+)
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
new file mode 100644
index 0000000000..41ebb1d79d
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
@@ -0,0 +1,66 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import * as CCR from './reference-table.stories';
+
+<Meta of={CCR} />
+
+# Attribute Referencing Table
+
+<div
+  className="table-responsive"
+  style={{ '--post-docs-tile-size': '100px', '--post-docs-tile-rg-size': '100px' }}
+>
+  <table className="table table-bordered ">
+    <caption className="visually-hidden">Cross-component referencing table</caption>
+    <colgroup>
+      <col style={{ width: '15%' }} />
+      <col style={{ width: '28%' }} />
+      <col style={{ width: '25%' }} />
+      <col style={{ width: '15%' }} />
+      <col style={{ width: '10%' }} />
+    </colgroup>
+    <thead>
+      <tr>
+        <th style={{ textAlign: 'left' }} scope="col">Attribute</th>
+        <th scope="col">Cross-Boundary Case</th>
+        <th scope="col" style={{ fontSize: '1.2rem' }}>Works Across ShadowDOM</th>
+        <th scope="col" style={{ fontSize: '1.2rem' }}>✔️Workaround/⬇️Trade-off</th>
+        <th scope="col">Documentation Link</th>
+      </tr>
+    </thead>
+   <tbody>
+ {CCR.referencingData.map(({ attribute, cases }, attrIndex) =>
+  cases.map((row, index) => (
+    <tr
+      key={`${attribute}-${index}`}
+      style={{
+        backgroundColor: attrIndex % 2 === 1 ? '#f2f2f2' : 'transparent', 
+      }}
+    >
+      {/* Span the attribute cell only for the first case row */}
+      {index === 0 && (
+        <td rowSpan={cases.length} style={{ verticalAlign: 'middle' }}>
+          {attribute}
+        </td>
+      )}
+      <td style={{ fontSize: '1.1rem', textAlign: 'center', verticalAlign: 'middle' }}>{row.case}</td>
+      <td style={{ textAlign: 'center', verticalAlign: 'middle' }}>{row.worksAcrossShadow}</td>
+      <td style={{ textAlign: 'center', verticalAlign: 'middle' }}>{row.workaround}</td>
+      <td style={{ textAlign: 'center', verticalAlign: 'middle' }}>
+        {row.docPage ? (
+          <a
+            href={row.docPage}
+            style={{ textDecoration: 'none' }}
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            🔗
+          </a>
+        ) : null}
+      </td>
+    </tr>
+  ))
+)}
+
+</tbody>
+  </table>
+</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
new file mode 100644
index 0000000000..db4066c502
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
@@ -0,0 +1,110 @@
+import { StoryObj } from '@storybook/web-components-vite';
+import { MetaExtended } from '@root/types';
+
+const meta: MetaExtended = {
+  id: '76ade552-2c03-4d6d-9dce-28daa560f755',
+  title:
+    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/🔀Cross-Shadow DOM: Attibute Referencing Table',
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {};
+
+export const referencingData = [
+  {
+    attribute: 'For',
+    cases: [
+      {
+        case: 'Light DOM/Slot ➔ ShadowDOM',
+        worksAcrossShadow: '❌',
+        workaround: '✔️ Elements API - ariaLabelledByElements',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa340f7d3--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom-',
+      },
+      {
+        case: 'ShadowDOM ➔ Light DOM/Slot',
+        worksAcrossShadow: '❌',
+        workaround: '⬇️ Set the "id" on the component host',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3401234--docs#iii-referencing-from-inside-a-shadow-dom-out-to-the-light-dom',
+      },
+      {
+        case: 'ShadowDOM ➔ Other ShadowDOM',
+        worksAcrossShadow: '❌',
+        workaround:
+          'Combine above solutions: ✔️ Elements API - ariaLabelledByElements ⬇️ Set the "id" on the component host',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3401234--docs#iv-referencing-from-one-shadow-dom-to-another-shadow-dom',
+      },
+    ],
+  },
+  {
+    attribute: 'Aria-Labelledby',
+    cases: [
+      {
+        case: 'Light DOM/Slot ➔ ShadowDOM',
+        worksAcrossShadow: '❌',
+        workaround: '✔️ Elements API - ariaLabelledByElements',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
+      },
+      {
+        case: 'ShadowDOM ➔ Light DOM/Slot',
+        worksAcrossShadow: '❌',
+        workaround: '⬇️ Set the "id" on the component host',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#iii-referencing-from-inside-a-shadow-dom-out-to-the-light-dom',
+      },
+      {
+        case: 'ShadowDOM ➔ Other ShadowDOM',
+        worksAcrossShadow: '❌',
+        workaround:
+          'Combine above solutions: ✔️ Elements API - ariaLabelledByElements ⬇️ Set the "id" on the component host',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#iv-referencing-from-one-shadow-dom-to-another-shadow-dom',
+      },
+    ],
+  },
+  {
+    attribute: 'Aria-Describedby',
+    cases: [
+      {
+        case: 'Light DOM/Slot ➔ ShadowDOM',
+        worksAcrossShadow: '❌',
+        workaround: '✔️ Elements API - ariaDescribedByElements',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
+      },
+      {
+        case: 'ShadowDOM ➔ Light DOM/Slot',
+        worksAcrossShadow: '❌',
+        workaround: '⬇️ Set the "id" on the component host',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
+      },
+      {
+        case: 'ShadowDOM ➔ Other ShadowDOM',
+        worksAcrossShadow: '❌',
+        workaround:
+          'Combine above solutions: ✔️ Elements API - ariaDescribedByElements ⬇️ Set the "id" on the component host',
+        docPage:
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#iv-referencing-from-one-shadow-dom-to-another-shadow-dom',
+      },
+    ],
+  },
+  {
+    attribute: 'Aria-Role: List ',
+    cases: [
+      {
+        case: 'Light DOM/Slot ➔ ShadowDOM',
+        worksAcrossShadow:
+          '✔️ The relationship is not affected by the ShadowDOM. It will be valid for all cases where the structure is accessible in such way that the "list" element contains its "listitems".',
+        workaround: '',
+        docPage: '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405112--docs',
+      },
+    ],
+  },
+];

From b64f4e1dd108be3ac0103faa8facf31273ae8ab7 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Wed, 24 Sep 2025 11:13:33 +0200
Subject: [PATCH 18/29] lint error

---
 .../reference-table/reference-table.docs.mdx                    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
index 41ebb1d79d..0ed69a0549 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta, Canvas, Source, Controls } from '@storybook/addon-docs/blocks';
+import { Meta } from '@storybook/addon-docs/blocks';
 import * as CCR from './reference-table.stories';
 
 <Meta of={CCR} />

From 23913ca935a6cdd8a96e135288f74aacc5a5ef5f Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 18 Nov 2025 16:16:47 +0100
Subject: [PATCH 19/29] review comments update

---
 .../components/post-popover-trigger/readme.md | 67 +---------------
 .../src/demo-components/demo-button.ts        | 33 +++++---
 .../aria-describedby.docs.mdx                 | 72 +++++++++--------
 .../aria-describedby.stories.ts               |  7 +-
 .../aria-describedby.styles.scss              |  1 +
 ...riadescribedbyElementsProperty.sample.html |  3 -
 ...iadescribedbyelements-property.sample.html |  3 +
 ...riadescribedbyelements-property.sample.js} |  0
 ...ple.html => default-example-2.sample.html} |  0
 ...ample.html => default-example.sample.html} |  0
 ...ml => non-working-example-III.sample.html} |  0
 ...ml => non-working-example-IIa.sample.html} |  0
 ...ml => non-working-example-IIb.sample.html} |  1 +
 ...tml => non-working-example-IV.sample.html} |  2 +-
 .../examples/workaround-IIa.sample.html       |  9 ---
 .../examples/workaround-IIb.sample.html       |  8 --
 ...e.html => working-example-III.sample.html} |  0
 ...e.html => working-example-IIa.sample.html} |  4 +-
 ...e.html => working-example-IIb.sample.html} | 13 ++--
 ...le.html => working-example-IV.sample.html} |  0
 .../aria-labelledby/aria-labelledby.docs.mdx  | 71 ++++++++---------
 .../aria-labelledby.stories.ts                |  4 +-
 .../aria-labelledby.styles.scss               |  1 +
 ...ialabelledbyelements-property.sample.html} |  0
 ...arialabelledbyelements-property.sample.js} |  0
 ...ple.html => default-example-2.sample.html} |  0
 ...ample.html => default-example.sample.html} |  0
 ...ml => non-working-example-III.sample.html} |  0
 ...ml => non-working-example-IIa.sample.html} |  0
 ...ml => non-working-example-IIb.sample.html} |  0
 ...tml => non-working-example-IV.sample.html} |  0
 .../examples/workaround-IIa.sample.html       |  8 --
 .../examples/workaround-IIb.sample.html       |  8 --
 ...e.html => working-example-III.sample.html} |  0
 ...e.html => working-example-IIa.sample.html} |  0
 ...e.html => working-example-IIb.sample.html} |  0
 ...le.html => working-example-IV.sample.html} |  0
 .../aria-role-list/aria-role-list.docs.mdx    | 77 +++++++++++--------
 ...ple.html => default-example-2.sample.html} |  0
 ...ple.html => default-example-3.sample.html} |  1 +
 ...ample.html => default-example.sample.html} |  0
 ....html => working-example-IIIa.sample.html} |  1 +
 ....html => working-example-IIIb.sample.html} |  0
 ...e.html => working-example-IIa.sample.html} |  0
 ...e.html => working-example-IIb.sample.html} |  0
 ...e.html => working-example-IVa.sample.html} |  0
 ...e.html => working-example-IVb.sample.html} |  0
 ...e.html => working-example-IVc.sample.html} |  0
 ...ialabelledbyelements-property.sample.html} |  0
 ...arialabelledbyelements-property.sample.js} |  0
 ...ple.html => default-example-2.sample.html} |  0
 ...ample.html => default-example.sample.html} |  0
 ...ml => non-working-example-III.sample.html} |  0
 ...ml => non-working-example-IIa.sample.html} |  0
 ...ml => non-working-example-IIb.sample.html} |  0
 ...tml => non-working-example-IV.sample.html} |  0
 .../for/examples/workaround-IIa.sample.html   |  6 --
 .../for/examples/workaround-IIb.sample.html   |  6 --
 ...e.html => working-example-III.sample.html} |  0
 ...e.html => working-example-IIa.sample.html} |  0
 ...e.html => working-example-IIb.sample.html} |  0
 ...le.html => working-example-IV.sample.html} |  0
 .../for/for.docs.mdx                          | 45 ++++++-----
 .../reference-table.stories.ts                | 12 +--
 64 files changed, 193 insertions(+), 270 deletions(-)
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html
 create mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyelements-property.sample.html
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{ariadescribedbyElementsProperty.sample.js => ariadescribedbyelements-property.sample.js} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{defaultExample2.sample.html => default-example-2.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{defaultExample.sample.html => default-example.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{nonWorkingExample-III.sample.html => non-working-example-III.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{nonWorkingExample-IIa.sample.html => non-working-example-IIa.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{nonWorkingExample-IIb.sample.html => non-working-example-IIb.sample.html} (98%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{nonWorkingExample-IV.sample.html => non-working-example-IV.sample.html} (82%)
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{workingExample-III.sample.html => working-example-III.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{workingExample-IIa.sample.html => working-example-IIa.sample.html} (99%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{workingExample-IIb.sample.html => working-example-IIb.sample.html} (60%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/{workingExample-IV.sample.html => working-example-IV.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{arialabelledbyElementsProperty.sample.html => arialabelledbyelements-property.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{arialabelledbyElementsProperty.sample.js => arialabelledbyelements-property.sample.js} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{defaultExample2.sample.html => default-example-2.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{defaultExample.sample.html => default-example.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{nonWorkingExample-III.sample.html => non-working-example-III.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{nonWorkingExample-IIa.sample.html => non-working-example-IIa.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{nonWorkingExample-IIb.sample.html => non-working-example-IIb.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{nonWorkingExample-IV.sample.html => non-working-example-IV.sample.html} (100%)
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{workingExample-III.sample.html => working-example-III.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{workingExample-IIa.sample.html => working-example-IIa.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{workingExample-IIb.sample.html => working-example-IIb.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/{workingExample-IV.sample.html => working-example-IV.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{defaultExample2.sample.html => default-example-2.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{defaultExample3.sample.html => default-example-3.sample.html} (97%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{defaultExample.sample.html => default-example.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{workingExample-IIIa.sample.html => working-example-IIIa.sample.html} (99%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{workingExample-IIIb.sample.html => working-example-IIIb.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{workingExample-IIb.sample.html => working-example-IIa.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{workingExample-IIa.sample.html => working-example-IIb.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{workingExample-IVa.sample.html => working-example-IVa.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{workingExample-IVb.sample.html => working-example-IVb.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{workingExample-IVc.sample.html => working-example-IVc.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{arialabelledbyElementsProperty.sample.html => arialabelledbyelements-property.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{arialabelledbyElementsProperty.sample.js => arialabelledbyelements-property.sample.js} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{defaultExample2.sample.html => default-example-2.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{defaultExample.sample.html => default-example.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{nonWorkingExample-III.sample.html => non-working-example-III.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{nonWorkingExample-IIa.sample.html => non-working-example-IIa.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{nonWorkingExample-IIb.sample.html => non-working-example-IIb.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{nonWorkingExample-IV.sample.html => non-working-example-IV.sample.html} (100%)
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{workingExample-III.sample.html => working-example-III.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{workingExample-IIa.sample.html => working-example-IIa.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{workingExample-IIb.sample.html => working-example-IIb.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/{workingExample-IV.sample.html => working-example-IV.sample.html} (100%)

diff --git a/packages/components/src/components/post-popover-trigger/readme.md b/packages/components/src/components/post-popover-trigger/readme.md
index 9ee7b43b64..82ea44e984 100644
--- a/packages/components/src/components/post-popover-trigger/readme.md
+++ b/packages/components/src/components/post-popover-trigger/readme.md
@@ -5,73 +5,8 @@
 
 <!-- Auto Generated Below -->
 
-## Properties
-
-| Property                          | Attribute              | Description                                                                                                                                                                                                                                                                                                                                                                               | Type                                                                                                                                                                 | Default     |
-| --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
-| `arrow`                           | `arrow`                | Show a little indicator arrow                                                                                                                                                                                                                                                                                                                                                             | `boolean`                                                                                                                                                            | `true`      |
-| `closeButtonCaption` _(required)_ | `close-button-caption` | Define the caption of the close button for assistive technology                                                                                                                                                                                                                                                                                                                           | `string`                                                                                                                                                             | `undefined` |
-| `placement`                       | `placement`            | Defines the position of the popover relative to its trigger. Popovers are automatically flipped to the opposite side if there is not enough available space and are shifted towards the viewport if they would overlap edge boundaries. For supported values and behavior details, see the [Floating UI placement documentation](https://floating-ui.com/docs/computePosition#placement). | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'top'`     |
-
-
-## Methods
-
-### `hide() => Promise<void>`
-
-Programmatically hide this popover
-
-#### Returns
-
-Type: `Promise<void>`
-
-
-
-### `show(target: HTMLElement) => Promise<void>`
-
-Programmatically display the popover
-
-#### Parameters
-
-| Name     | Type          | Description                                                                  |
-| -------- | ------------- | ---------------------------------------------------------------------------- |
-| `target` | `HTMLElement` | An element with [data-popover-target="id"] where the popover should be shown |
-
-#### Returns
-
-Type: `Promise<void>`
 
-
-
-### `toggle(target: HTMLElement, force?: boolean) => Promise<void>`
-
-Toggle popover display
-
-#### Parameters
-
-| Name     | Type          | Description                                                                        |
-| -------- | ------------- | ---------------------------------------------------------------------------------- |
-| `target` | `HTMLElement` | An element with [data-popover-target="id"] where the popover should be anchored to |
-| `force`  | `boolean`     | Pass true to always show or false to always hide                                   |
-
-#### Returns
-
-Type: `Promise<void>`
-
-
-
-
-## Dependencies
-
-### Depends on
-
-- [post-popovercontainer](../post-popovercontainer)
-
-### Graph
-```mermaid
-graph TD;
-  post-popover --> post-popovercontainer
-  style post-popover fill:#f9f,stroke:#333,stroke-width:4px
-```
+## Properties
 
 | Property           | Attribute | Description                                                                                   | Type     | Default     |
 | ------------------ | --------- | --------------------------------------------------------------------------------------------- | -------- | ----------- |
diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index 49c0c0f133..b2215acf6b 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -19,23 +19,29 @@ export class DemoButton extends HTMLElement {
   }
 
   attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
-    if (name === 'workaround') this.workaround = newValue;
-    if (name === 'arialabelledby-id') this.arialabelledbyId = newValue;
-    if (name === 'ariadescribedby-id') this.ariadescribedbyId = newValue;
-    if (name === 'button-version') this.buttonVersion = newValue as '1' | '2' | '3';
+    const member = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+    if (member === 'buttonVersion') {
+      this.buttonVersion = newValue as '1' | '2' | '3' | '4';
+    } else {
+      this[member as keyof this] = newValue as this[keyof this];
+    }
+
     this.render();
   }
 
   private setupAria() {
+    let elementToLink: Element | null = null;
+
     const isLabelled = this.workaround === 'ariaLabelledByElements';
     const isDescribed = this.workaround === 'ariaDescribedByElements';
 
+    const ariaPropertyName = isLabelled ? 'ariaLabelledByElements' : 'ariaDescribedByElements';
+
     if (!this.internalButton || (!isLabelled && !isDescribed)) {
       return;
     }
 
-    let elementToLink: Element | null = null;
-
     if (this.buttonVersion === '1' || this.buttonVersion === '3') {
       const id = isLabelled ? this.arialabelledbyId : this.ariadescribedbyId;
       if (id) {
@@ -48,7 +54,6 @@ export class DemoButton extends HTMLElement {
       }
     }
 
-    const ariaPropertyName = isLabelled ? 'ariaLabelledByElements' : 'ariaDescribedByElements';
     this.internalButton[ariaPropertyName] = elementToLink ? [elementToLink] : [];
   }
 
@@ -64,13 +69,21 @@ export class DemoButton extends HTMLElement {
       > <post-icon name="1022"></post-icon>
       </div>
     `;
-    } else {
+    } else if (this.arialabelledbyId) {
+      this.shadowRoot.innerHTML = `
+      <span id="${this.arialabelledbyId}">My Text</span>
+      <div part="button"
+      role="button" tabindex="0" aria-labelledby="${this.arialabelledbyId}">
+        <post-icon name="1022"></post-icon>
+      </div>
+   `;
+    } else if (this.ariadescribedbyId) {
       this.shadowRoot.innerHTML = `
-      <span id="example">My Text</span>
       <div part="button"
-      role="button" tabindex="0" aria-labelledby="example">
+      role="button" tabindex="0" aria-describedby="${this.ariadescribedbyId}">
         <post-icon name="1022"></post-icon>
       </div>
+        <span id="${this.ariadescribedbyId}">My Description</span>
    `;
     }
 
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
index 3eab51ad8b..1968a59439 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -1,17 +1,17 @@
 import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-describedby.stories';
-import DefaultExample from './examples/defaultExample.sample.html?raw';
-import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
-import AriaDescribedbyElementsPropertyHTML from './examples/ariadescribedbyElementsProperty.sample.html?raw';
-import AriaDescribedbyElementsProperty from './examples/ariadescribedbyElementsProperty.sample.js?raw';
-import NonWorkingExampleIIa from './examples/nonWorkingExample-IIa.sample.html?raw';
-import NonWorkingExampleIIb from './examples/nonWorkingExample-IIb.sample.html?raw';
-import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
-import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
-import NonWorkingExampleIII from './examples/nonWorkingExample-III.sample.html?raw';
-import WorkingExampleIII from './examples/workingExample-III.sample.html?raw';
-import NonWorkingExampleIV from './examples/nonWorkingExample-IV.sample.html?raw';
-import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
+import DefaultExample from './examples/default-example.sample.html?raw';
+import DefaultExample2 from './examples/default-example-2.sample.html?raw';
+import AriaDescribedbyElementsPropertyHTML from './examples/ariadescribedbyelements-property.sample.html?raw';
+import AriaDescribedbyElementsProperty from './examples/ariadescribedbyelements-property.sample.js?raw';
+import NonWorkingExampleIIa from './examples/non-working-example-IIa.sample.html?raw';
+import NonWorkingExampleIIb from './examples/non-working-example-IIb.sample.html?raw';
+import WorkingExampleIIa from './examples/working-example-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/working-example-IIb.sample.html?raw';
+import NonWorkingExampleIII from './examples/non-working-example-III.sample.html?raw';
+import WorkingExampleIII from './examples/working-example-III.sample.html?raw';
+import NonWorkingExampleIV from './examples/non-working-example-IV.sample.html?raw';
+import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 <Meta of={CCR} />
 
@@ -25,6 +25,11 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
   This is useful when a simple text label isn't enough or when the description needs to be combined
   from different pieces of text.
 </p>
+<p>
+  ⚠️ The `aria-describedby` attribute is not intended to reference content from external sources.
+  Its value must consist of one or more element IDs (space-separated if multiple), and each ID must
+  correspond to an element within the same DOM document.
+</p>
 
 ### I. Referencing Within the Same DOM Tree
 
@@ -47,21 +52,21 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
   custom button component. You can <b>test it with NVDA</b> to confirm the correct description
   announcement.
 </p>
-<Canvas of={CCR.ExampleHTML} sourceState="hide" />
 
+<Canvas of={CCR.ExampleHTML} sourceState="hide" />
 
-### II. Referencing From Outside a Shadow DOM Into That Shadow DOM
+### II. Referencing From the ShadowDOM out to the Light DOM
 
-• <b>Light DOM → Shadow DOM</b> ❌
+• <b>Shadow DOM → Light DOM</b> ❌
 
 <Source language="html" dark code={NonWorkingExampleIIa}></Source>
 
-• <b>Slotted Content → Shadow DOM</b> ❌
+• <b>Shadow DOM → Slotted Content </b> ❌
 
 <Source language="html" dark code={NonWorkingExampleIIb}></Source>
 
 <p>
-  The above examples do not work across shadow DOM boundaries when setting the aria-describedby
+  The above examples do not work across shadow DOM boundaries when setting the `aria-describedby`
   attribute directly.
 </p>
 <p>
@@ -74,7 +79,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 #### Workaround: `Element:ariaDescribedByElements`
 
 <p>
-  `ariaDescribedByElements` is a property of the Element interface that returns an array of elements
+  `ariaDescribedByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="_blank">Element API</a> that returns an array of elements
   describing the element. It provides direct references to these elements rather than just their ID
   strings.
   <a
@@ -98,11 +103,11 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </p>
 
 <p>
-  <b>• Light DOM → Shadow DOM Example</b> ✔️
+  <b>• Shadow DOM → Light DOM Example</b> ✔️
 </p>
 <p>
-  In this case a description element in the light DOM is directly assigned to a target element inside a
-  custom component’s shadow DOM using `ariaDescribedByElements`.
+  In this case a description element in the light DOM is referenced by an element inside a custom
+  component’s shadow DOM using `ariaDescribedByElements`.
 </p>
 
 <Source language="html" dark code={WorkingExampleIIa}></Source>
@@ -113,10 +118,10 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </div>
 
 <p>
-  <b>• Slotted Content → Shadow DOM Example</b> ✔️
+  <b>• Shadow DOM → Slotted Content Example</b> ✔️
 </p>
 <p>
-  In this case a description element provided via a light DOM slot is automatically assigned to a target
+  In this case a description element provided via a light DOM slot is automatically referenced by an
   element inside a custom component’s shadow DOM using `ariaDescribedByElements`.
 </p>
 <Source language="html" dark code={WorkingExampleIIb}></Source>
@@ -128,25 +133,26 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 ⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
 
-### III. Referencing From Inside a Shadow DOM Out to the Light DOM
+### III. Referencing From the Light DOM into the ShadowDOM
 
 <p>
-  <b>• Shadow DOM → Light DOM (or Shadow DOM → Slotted Content)</b>❌
+  <b>• Light DOM→ Shadow DOM (or Slotted Content→Shadow DOM )</b>❌
 </p>
 
 <p>
-  Referencing an element in the light DOM from within a shadow DOM using the standard
+  Referencing an element from the light DOM into the shadow DOM using the standard
   `aria-describedby` is not possible. The `ariaDescribedByElements` property neither works in this
-  case because, for it to work, the description element must be in the same DOM or in a parent DOM of the
-  target element.
+  case because, for it to work, the description element must be in the same DOM or in a parent DOM
+  of the referencing element.
 </p>
 <Source language="html" dark code={NonWorkingExampleIII}></Source>
 
 ##### Working Solution: Set the `id`on the description component host
 
 <p>
-  The only option here is to <b>set the `id` directly on the host</b> of the description component. In
-  this case <b>all the visible text inside this component will be assigned as the Accessible Description</b>  of the target element.
+  The only option here is to <b>set the `id` directly on the host</b> of the description component.
+  In this case <b>all the visible text inside this component will be assigned as the Accessible Description</b>
+  of the referencing element.
 </p>
 <Source language="html" dark code={WorkingExampleIII}></Source>
 <Canvas of={CCR.Example4} sourceState="hide" />
@@ -157,13 +163,13 @@ Shadow DOM → Other Shadow DOM ❌
 
 <Source language="html" dark code={NonWorkingExampleIV}></Source>
 <p>
-  This relationship is not valid because both `id` and `aria-describedby` attributes are scoped only within
-  their individual shadowDoms.
+  This relationship is not valid because both `id` and `aria-describedby` attributes are scoped only
+  within their individual shadowDoms.
 </p>
 
 ##### Working Solution
 
-A working solution for this case combines approaches II and III: setting the description component’s `id` directly on the host element (III), and using `Element.ariaDescribedByElements` to assign the description to the target component.
+A working solution for this case combines approaches II and III: setting the description component’s `id` directly on the host element (III), and using `Element.ariaDescribedByElements` to assign the description to the referencing component.
 
 <Source language="html" dark code={WorkingExampleIV}></Source>
 <Canvas of={CCR.Example5} sourceState="shown" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
index b2b2f2664b..84da604b4c 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.stories.ts
@@ -20,12 +20,7 @@ type Story = StoryObj;
 
 // Case: Standard Light DOM to Light DOM
 export const ExampleHTML: Story = {
-  render: () => html`
-    <div class="btn btn-primary" aria-describedby="id_1" role="button" tabindex="0">
-      <post-icon name="1022"></post-icon>
-    </div>
-    <span id="id_1">My Description</span>
-  `,
+  render: () => html` <demo-button ariadescribedby-id="example-description"></demo-button> `,
 };
 
 // Case: Referencing from Shadow DOM (Host Attribute) to Light DOM (Element) workaround setting programmatically the relevant Element property
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss
index bf859e8590..258028b073 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.styles.scss
@@ -1,3 +1,4 @@
+// Styles used for the <demo-button> component
 ::part(button) {
   display: inline-flex;
   position: relative;
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html
deleted file mode 100644
index 64a1f8f77e..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.html
+++ /dev/null
@@ -1,3 +0,0 @@
-<element id="elementId"></element>
-
-<span id="descriptionId"></span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyelements-property.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyelements-property.sample.html
new file mode 100644
index 0000000000..89432ef6f5
--- /dev/null
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyelements-property.sample.html
@@ -0,0 +1,3 @@
+<custom-element id="elementId">A custom element</custom-element>
+
+<span id="descriptionId">A description for the custom-element</span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.js b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyelements-property.sample.js
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyElementsProperty.sample.js
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/ariadescribedbyelements-property.sample.js
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/default-example-2.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample2.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/default-example-2.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/default-example.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/defaultExample.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/default-example.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-III.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-III.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-III.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IIa.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IIa.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IIb.sample.html
similarity index 98%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IIb.sample.html
index 7cb30ae36a..0301739c10 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IIb.sample.html
@@ -4,5 +4,6 @@
       <custom-icon />
     </div>
     <slot name="description-slot"> </slot>
+    
   <span slot="description-slot" id="descriptionId">My Description</span>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IV.sample.html
similarity index 82%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IV.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IV.sample.html
index 107d099356..c723bf9b37 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/nonWorkingExample-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/non-working-example-IV.sample.html
@@ -7,6 +7,6 @@
 
 <custom-description>
   ⏷ #shadow-root (open)
-  <span id="descriptionId">My Description</span>
+    <span id="descriptionId">My Description</span>
 </custom-description>
 
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html
deleted file mode 100644
index e5c60ad61e..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIa.sample.html
+++ /dev/null
@@ -1,9 +0,0 @@
-<custom-component>
-  ⏷ #shadow-root (open)
-    <div role="button" tabindex="0" aria-describedby="descriptionId">
-      <custom-icon />
-    </div>
-</custom-component>
-
-<span id="descriptionId">My Description</span>
-
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html
deleted file mode 100644
index d5d65462ca..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workaround-IIb.sample.html
+++ /dev/null
@@ -1,8 +0,0 @@
-<custom-component>
-  ⏷ #shadow-root (open)
-    <div role="button" tabindex="0" aria-describedby="descriptionId">
-      <custom-icon />
-    </div>
-</custom-component>
-
-<span id="descriptionId">My Description</span>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-III.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-III.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-III.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIa.sample.html
similarity index 99%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIa.sample.html
index aefe9337c5..da556380dd 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIa.sample.html
@@ -1,4 +1,4 @@
-<span id="descriptionId">My Description</span>
+
 
 <custom-component descriptionId="descriptionId">
   ⏷ #shadow-root (open)
@@ -8,6 +8,8 @@
     </div>
 </custom-component>
 
+<span id="descriptionId">My Description</span>
+
 <script>
   const description = document.getElementById('descriptionId');
   // Assign the description element directly to the component's internal target element
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIb.sample.html
similarity index 60%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIb.sample.html
index a3caff1abb..5e3b16bd85 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIb.sample.html
@@ -1,12 +1,11 @@
 <custom-component>
   ⏷ #shadow-root (open)
-  <slot name="description-slot"></slot>
-  <div ref="targetRef" role="button" tabindex="0" aria-describedby>
-    <!--The aria-describedby attribute is set automatically by the browser -->
-    <custom-icon />
-  </div>
-  <!-- slotted description -->
-  <span slot="description-slot">My Description</span>
+    <slot name="description-slot"></slot>
+    <div ref="targetRef" role="button" tabindex="0" aria-describedby>
+      <!--The aria-describedby attribute is set automatically by the browser -->
+      <custom-icon />
+    </div>
+    <span slot="description-slot">My Description</span>
 </custom-component>
 
 <script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IV.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/workingExample-IV.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IV.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index d4eaaead45..05223acca7 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -1,17 +1,17 @@
 import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-labelledby.stories';
-import DefaultExample from './examples/defaultExample.sample.html?raw';
-import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
-import ArialabelledbyElementsPropertyHTML from './examples/arialabelledbyElementsProperty.sample.html?raw';
-import ArialabelledbyElementsProperty from './examples/arialabelledbyElementsProperty.sample.js?raw';
-import NonWorkingExampleIIa from './examples/nonWorkingExample-IIa.sample.html?raw';
-import NonWorkingExampleIIb from './examples/nonWorkingExample-IIb.sample.html?raw';
-import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
-import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
-import NonWorkingExampleIII from './examples/nonWorkingExample-III.sample.html?raw';
-import WorkingExampleIII from './examples/workingExample-III.sample.html?raw';
-import NonWorkingExampleIV from './examples/nonWorkingExample-IV.sample.html?raw';
-import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
+import DefaultExample from './examples/default-example.sample.html?raw';
+import DefaultExample2 from './examples/default-example-2.sample.html?raw';
+import ArialabelledbyElementsPropertyHTML from './examples/arialabelledbyelements-property.sample.html?raw';
+import ArialabelledbyElementsProperty from './examples/arialabelledbyelements-property.sample.js?raw';
+import NonWorkingExampleIIa from './examples/non-working-example-IIa.sample.html?raw';
+import NonWorkingExampleIIb from './examples/non-working-example-IIb.sample.html?raw';
+import WorkingExampleIIa from './examples/working-example-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/working-example-IIb.sample.html?raw';
+import NonWorkingExampleIII from './examples/non-working-example-III.sample.html?raw';
+import WorkingExampleIII from './examples/working-example-III.sample.html?raw';
+import NonWorkingExampleIV from './examples/non-working-example-IV.sample.html?raw';
+import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 <Meta of={CCR} />
 
@@ -49,13 +49,13 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <Canvas of={CCR.ExampleHTML} sourceState="hide" />
 
-### II. Referencing From Outside a Shadow DOM Into That Shadow DOM
+### II. Referencing From the ShadowDOM out to the Light DOM
 
-• <b>Light DOM → Shadow DOM</b> ❌
+• <b>Shadow DOM → Light DOM</b> ❌
 
 <Source language="html" dark code={NonWorkingExampleIIa}></Source>
 
-• <b>Slotted Content → Shadow DOM</b> ❌
+• <b>Shadow DOM → Slotted Content</b> ❌
 
 <Source language="html" dark code={NonWorkingExampleIIb}></Source>
 
@@ -73,7 +73,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 #### Workaround: `Element:ariaLabelledByElements`
 
 <p>
-  `ariaLabelledByElements` is a property of the Element interface that returns an array of elements
+  `ariaLabelledByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="_blank">Element API</a> that returns an array of elements
   labeling the element. It provides direct references to these elements rather than just their ID
   strings.
   <a
@@ -85,11 +85,12 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </p>
 
 <div className="lead">Basic usage of `ariaLabelledByElements` </div>
-<Source language="html" dark code={ArialabelledbyElementsPropertyHTML}></Source>
 <p>
   Instead of adding the `aria-labelledby` attribute on the element, we can set it using the
   `ariaLabelledByElements` property.
 </p>
+<Source language="html" dark code={ArialabelledbyElementsPropertyHTML}></Source>
+
 <Source language="js" dark code={ArialabelledbyElementsProperty}></Source>
 <p>
   The following examples demonstrate how the `ariaLabelledByElements` property can be used to
@@ -97,11 +98,11 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </p>
 
 <p>
-  <b>• Light DOM → Shadow DOM Example</b> ✔️
+  <b>• Shadow DOM → Light DOM Example</b> ✔️
 </p>
 <p>
-  In this case a label element in the light DOM is directly assigned to a target element inside a
-  custom component’s shadow DOM using `ariaLabelledByElements`.
+  In this case a label element in the light DOM is referenced by an element inside a custom
+  component’s shadow DOM using `ariaLabelledByElements`.
 </p>
 
 <Source language="html" dark code={WorkingExampleIIa}></Source>
@@ -112,11 +113,11 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </div>
 
 <p>
-  <b>• Slotted Content → Shadow DOM Example</b> ✔️
+  <b>• Shadow DOM → Slotted Content Example</b> ✔️
 </p>
 <p>
-  In this case a label element provided via a light DOM slot is automatically assigned to a target
-  element inside a custom component’s shadow DOM using `ariaLabelledByElements`.
+  In this case a label element provided via a slot is referenced by an element inside a custom
+  component’s shadow DOM using `ariaLabelledByElements`.
 </p>
 <Source language="html" dark code={WorkingExampleIIb}></Source>
 <p>Use the control below to toggle the `ariaLabelledByElements` workaround implementation.</p>
@@ -127,17 +128,16 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 ⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
 
-### III. Referencing From Inside a Shadow DOM Out to the Light DOM
+### III. Referencing From the Light DOM into the ShadowDOM
 
 <p>
-  <b>• Shadow DOM → Light DOM (or Shadow DOM → Slotted Content)</b>❌
+  <b>• Light DOM → Shadow DOM (or Slotted Content → Shadow DOM)</b> ❌
 </p>
 
 <p>
-  Referencing an element in the light DOM from within a shadow DOM using the standard
-  `aria-labelledby` is not possible. The `ariaLabelledByElements` property neither works in this
-  case because, for it to work, the label element must be in the same DOM or in a parent DOM of the
-  target element.
+  Referencing an element in the shadow DOM from the light DOM using the standard `aria-labelledby`
+  is not possible. The `ariaLabelledByElements` property neither works in this case because, for it
+  to work, the label element shoul be in the same DOM or in a parent DOM of the target element.
 </p>
 <Source language="html" dark code={NonWorkingExampleIII}></Source>
 
@@ -145,13 +145,8 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 <p>
   The only option here is to <b>set the `id` directly on the host</b> of the labeling component. In
-  this case{' '}
-  <b>
-    all the visible text inside the referencing component will be assigned as the Accessible Name
-  </b>{' '}
-  of the target element.
+  this case <b>all the visible text inside the component that contains the reference will be assigned as the Accessible Name</b> of the target element.
 </p>
-<Source language="html" dark code={WorkingExampleIII}></Source>
 <Canvas of={CCR.Example4} sourceState="hide" />
 
 ### IV. Referencing From One Shadow DOM To Another Shadow DOM
@@ -160,12 +155,12 @@ Shadow DOM → Other Shadow DOM ❌
 
 <Source language="html" dark code={NonWorkingExampleIV}></Source>
 <p>
-  This relationship is not valid because both `id` and `aria-labelledby` attributes are scoped only within
-  their individual shadowDoms.
+  This relationship is not valid because both `id` and `aria-labelledby` attributes are scoped only
+  within their individual shadowDoms.
 </p>
 ##### Working Solution
 
-A working solution for this case combines approaches II and III: setting the label component’s `id` directly on the host element (III), and using `Element.ariaLabelledByElements` to assign the label to the target component.
+A working solution for this case combines approaches II and III: setting the label component’s `id` directly on the host element (III), and using `Element.ariaLabelledByElements` to assign the label to the referencing component.
 
 <Source language="html" dark code={WorkingExampleIV}></Source>
 <Canvas of={CCR.Example5} sourceState="hide" />
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
index 0cace5fc4d..67079ecf12 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.stories.ts
@@ -18,9 +18,9 @@ export default meta;
 
 type Story = StoryObj;
 
-// Case: Standard Light DOM to Light DOM
+// Case: Shadow Dom EXAMPLE
 export const ExampleHTML: Story = {
-  render: () => html` <demo-button> </demo-button> `,
+  render: () => html` <demo-button arialabelledby-id="example-label"> </demo-button> `,
 };
 
 // Case: Referencing from Shadow DOM (Host Attribute) to Light DOM (Element) workaround setting programmatically the relevant Element property
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss
index bf859e8590..258028b073 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.styles.scss
@@ -1,3 +1,4 @@
+// Styles used for the <demo-button> component
 ::part(button) {
   display: inline-flex;
   position: relative;
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyelements-property.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyelements-property.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.js b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyelements-property.sample.js
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyElementsProperty.sample.js
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/arialabelledbyelements-property.sample.js
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/default-example-2.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample2.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/default-example-2.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/default-example.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/defaultExample.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/default-example.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-III.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-III.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-III.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIa.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIa.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIb.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIb.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IV.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/nonWorkingExample-IV.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IV.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
deleted file mode 100644
index 388de8933f..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIa.sample.html
+++ /dev/null
@@ -1,8 +0,0 @@
-<span id="labelId">My Text</span>
-
-<custom-component>
-  ⏷ #shadow-root (open)
-    <div role="button" tabindex="0" aria-labelledby="labelId">
-      <custom-icon />
-    </div>
-</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
deleted file mode 100644
index 388de8933f..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workaround-IIb.sample.html
+++ /dev/null
@@ -1,8 +0,0 @@
-<span id="labelId">My Text</span>
-
-<custom-component>
-  ⏷ #shadow-root (open)
-    <div role="button" tabindex="0" aria-labelledby="labelId">
-      <custom-icon />
-    </div>
-</custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-III.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-III.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-III.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIa.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIa.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIb.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIb.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IV.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/workingExample-IV.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IV.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
index a746187144..41b832f161 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -1,16 +1,16 @@
 import { Meta, Canvas, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './aria-role-list.stories';
 
-import DefaultExample from './examples/defaultExample.sample.html?raw';
-import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
-import DefaultExample3 from './examples/defaultExample3.sample.html?raw';
-import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
-import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
-import WorkingExampleIIIa from './examples/workingExample-IIIa.sample.html?raw';
-import WorkingExampleIIIb from './examples/workingExample-IIIb.sample.html?raw';
-import WorkingExampleIVa from './examples/workingExample-IVa.sample.html?raw';
-import WorkingExampleIVb from './examples/workingExample-IVb.sample.html?raw';
-import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
+import DefaultExample from './examples/default-example.sample.html?raw';
+import DefaultExample2 from './examples/default-example-2.sample.html?raw';
+import DefaultExample3 from './examples/default-example-3.sample.html?raw';
+import WorkingExampleIIa from './examples/working-example-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/working-example-IIb.sample.html?raw';
+import WorkingExampleIIIa from './examples/working-example-IIIa.sample.html?raw';
+import WorkingExampleIIIb from './examples/working-example-IIIb.sample.html?raw';
+import WorkingExampleIVa from './examples/working-example-IVa.sample.html?raw';
+import WorkingExampleIVb from './examples/working-example-IVb.sample.html?raw';
+import WorkingExampleIVc from './examples/working-example-IVc.sample.html?raw';
 
 <Meta of={CCR} />
 
@@ -21,9 +21,9 @@ import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
   expected to contain related items identified with `role="listitem"`.
 </div>
 
-### I. Referencing Within the Same DOM Tree
+### I. Parent and Children Within the Same DOM Tree
 
-• <b>Both `list` parent and `listitem` children in Light DOM</b> ✔️
+• <b>Both parent and children in Light DOM</b> ✔️
 
 <Source language="html" dark code={DefaultExample}></Source>
 
@@ -34,7 +34,7 @@ import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
   `role="listitem"`.
 </p>
 
-• <b>Both `list` parent and `listitem` children in the same Shadow DOM</b> ✔️
+• <b>Parent and children in the same Shadow DOM</b> ✔️
 
 <Source language="html" dark code={DefaultExample2}></Source>
 
@@ -45,20 +45,20 @@ import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
   direct `role="listitem"` children, so the structure remains valid.
 </p>
 
-• <b>`list` role on the host and slotted `listitem` children</b> ✔️
+• <b>Parent on the host with slotted children</b> ✔️
 
 <Source language="html" dark code={DefaultExample3}></Source>
 
 <Canvas of={CCR.Example1b} sourceState="hide" />
 
 <p>
-  Similarly, in the case of a component with `role="list"` set on the host and slotted `listitems`, the
-  relationship is preserved correctly.
+  Similarly, in the case of a component with `role="list"` set on the host and slotted `listitems`,
+  the relationship is preserved correctly.
 </p>
 
 ### II. Parent in the Light DOM-children Into The Shadow DOM
 
-• <b>Light DOM → Shadow DOM</b> ✔️
+• <b>Parent in the light DOM and children in the ShadowDOM</b> ✔️
 
 <Source language="html" dark code={WorkingExampleIIa}></Source>
 
@@ -69,9 +69,9 @@ import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
   DOM, the relationship is valid.
 </p>
 
-• <b>Slotted Parent → Shadow DOM</b> ❌
+• <b>Slotted parent and children in the ShadowDOM</b> ❌
 
-<Source language="html" dark code={WorkingExampleIIb}></Source>
+<Source language="html" dark code={WorkingExampleIIa}></Source>
 
 <p>
   ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
@@ -81,9 +81,9 @@ import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
 
 ### III. Parent in the Shadow DOM - Children Out to the Light DOM
 
-• <b>Parent in the Shadow DOM → Children in the Light DOM</b> ❌
+• <b>Parent in the Shadow DOM and children in the Light DOM</b> ❌
 
-<Source language="html" dark code={WorkingExampleIIIa}></Source>
+<Source language="html" dark code={WorkingExampleIIIb}></Source>
 
 <p>
   ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
@@ -91,47 +91,60 @@ import WorkingExampleIVc from './examples/workingExample-IVc.sample.html?raw';
   boundary, but due to the incorrect structure itself.
 </p>
 
-• <b>Parent in the Shadow DOM → Slotted Children </b> ✔️
+• <b>Parent in the Shadow DOM with slotted children </b> ✔️
 
 <Source language="html" dark code={WorkingExampleIIIb}></Source>
 
 <Canvas of={CCR.Example3b} sourceState="hide" />
 
 <p>
-  When a component applies `role="list"` to an internal element and its children with `role="listitem"` are slotted into that element, the structure still works correctly and preserves a valid `list/listitem` relationship.
+  When a component applies `role="list"` to an internal element and its children with
+  `role="listitem"` are slotted into that element, the structure still works correctly and preserves
+  a valid `list/listitem` relationship.
 </p>
 
-### IV. Referencing From One Shadow DOM To Another Shadow shadowDOM
+### IV. Referencing From One ShadowDOM To Another ShadowDOM
 
-• <b>Parent in the Shadow DOM → Children grouped in a nested Component</b> ✔️
+• <b>Parent in the Shadow DOM - Children grouped in a nested Component</b> ✔️
 
 <Source language="html" dark code={WorkingExampleIVa}></Source>
 
 <Canvas of={CCR.Example4a} sourceState="shown" />
 
 <p>
-  This structure works correctly: the parent `role="list"` maintains a valid relationship with its children, even when the `listitem` elements are grouped inside a nested component.
+  This structure works correctly: the parent `role="list"` maintains a valid relationship with its
+  children, even when the `listitem` elements are grouped inside a nested component.
 </p>
 
-• <b>Parent in the Shadow DOM → slotted Children as individual Components</b> ✔️
+• <b>Parent in the Shadow DOM - Slotted Children as individual Components</b> ✔️
 
 <Source language="html" dark code={WorkingExampleIVb}></Source>
 
 <Canvas of={CCR.Example4b} sourceState="hide" />
 <p>
- In this case the `listitem` elements are slotted and encapsulated within individual custom components. This structure also forms a valid `list-listitem` relationship.
+  In this case the `listitem` elements are slotted and encapsulated within individual custom
+  components. This structure also forms a valid `list-listitem` relationship.
 </p>
 
-• <b>Parent in the Shadow DOM → nested Grouping Component -> nested Children individual components</b> ✔️
+• <b>Parent in the Shadow DOM - nested Grouping Component -> nested Children individual components</b> ✔️
 
 <Source language="html" dark code={WorkingExampleIVc}></Source>
 
 <Canvas of={CCR.Example4c} sourceState="hide" />
 
 <p>
-  In the case of a `role="list"` parent containing a grouping component, with individual `listitem` children nested inside their own components, the relationship is still correctly preserved across two Shadow DOM boundaries.
+  In the case of a `role="list"` parent containing a grouping component, with individual `listitem`
+  children nested inside their own components, the relationship is still correctly preserved across
+  two Shadow DOM boundaries.
 </p>
 
+## Conclusion: Shadow DOM and List Semantics
 
-## Conclusion: Shadow DOM and List Semantics 
-<p>When the markup is properly structured such that elements with `role="listitem"` exist within a parent element having `role="list"`, the presence of Shadow DOM does not break the semantic `list/listitem` relationship—even across multiple component boundaries. The `listitems` do not necessarily have to be direct children of the `role="list"` element for the relationship to be preserved, as the accessibility tree will bridge through the encapsulation when the markup is correct.</p>
+<p>
+  When the markup is properly structured such that elements with `role="listitem"` exist within a
+  parent element having `role="list"`, the presence of Shadow DOM does not break the semantic
+  `list/listitem` relationship—even across multiple component boundaries. The `listitems` do not
+  necessarily have to be direct children of the `role="list"` element for the relationship to be
+  preserved, as the accessibility tree will bridge through the encapsulation when the markup is
+  correct.
+</p>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/default-example-2.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample2.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/default-example-2.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample3.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/default-example-3.sample.html
similarity index 97%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample3.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/default-example-3.sample.html
index a0ae2e60b8..a91d173410 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample3.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/default-example-3.sample.html
@@ -1,6 +1,7 @@
 <custom-component role="list">
   ⏷ #shadow-root (open)
     <slot></slot>
+    
   <div role="listitem">item 1</div>
   <div role="listitem">item 2</div>
   <div role="listitem">item 3</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/default-example.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/defaultExample.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/default-example.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIa.sample.html
similarity index 99%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIa.sample.html
index 670820c5bf..d42e710e66 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIa.sample.html
@@ -2,6 +2,7 @@
   ⏷ #shadow-root (open)
     <div role="list">test</div>
 </custom-list>
+
 <div role="listitem">item 1</div>
 <div role="listitem">item 2</div>
 <div role="listitem">item 3</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIb.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIb.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIa.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIa.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIb.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIb.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVa.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVa.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVb.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVb.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVc.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVc.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/workingExample-IVc.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVc.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyelements-property.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyelements-property.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.js b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyelements-property.sample.js
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyElementsProperty.sample.js
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/arialabelledbyelements-property.sample.js
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/default-example-2.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample2.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/default-example-2.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/default-example.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/defaultExample.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/default-example.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-III.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-III.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-III.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIa.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIa.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IV.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/nonWorkingExample-IV.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IV.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html
deleted file mode 100644
index 6087c6cc11..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIa.sample.html
+++ /dev/null
@@ -1,6 +0,0 @@
-<label id="labelId" for="inputId">My Text</label>
-
-<custom-input>
-  ⏷ #shadow-root (open)
-    <input id="inputId" aria-labelledby="labelId"/> 
-</custom-input>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html
deleted file mode 100644
index ca69b62a6d..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workaround-IIb.sample.html
+++ /dev/null
@@ -1,6 +0,0 @@
-<custom-input>
-  ⏷ #shadow-root (open)
-  <input id="inputId" aria-labelledby="labelId" />
-
-  <label id="labelId" for="labelId">My Text</label>
-</custom-input>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-III.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-III.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-III.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-III.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIa.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIa.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIb.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIb.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IV.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/workingExample-IV.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IV.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
index 6251f699f1..09c4bf7900 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -1,17 +1,17 @@
 import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
 import * as CCR from './for.stories';
-import DefaultExample from './examples/defaultExample.sample.html?raw';
-import DefaultExample2 from './examples/defaultExample2.sample.html?raw';
-import ArialabelledbyElementsPropertyHTML from './examples/arialabelledbyElementsProperty.sample.html?raw';
-import ArialabelledbyElementsProperty from './examples/arialabelledbyElementsProperty.sample.js?raw';
-import NonWorkingExampleIIa from './examples/nonWorkingExample-IIa.sample.html?raw';
-import NonWorkingExampleIIb from './examples/nonWorkingExample-IIb.sample.html?raw';
-import WorkingExampleIIa from './examples/workingExample-IIa.sample.html?raw';
-import WorkingExampleIIb from './examples/workingExample-IIb.sample.html?raw';
-import NonWorkingExampleIII from './examples/nonWorkingExample-III.sample.html?raw';
-import WorkingExampleIII from './examples/workingExample-III.sample.html?raw';
-import NonWorkingExampleIV from './examples/nonWorkingExample-IV.sample.html?raw';
-import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
+import DefaultExample from './examples/default-example.sample.html?raw';
+import DefaultExample2 from './examples/default-example-2.sample.html?raw';
+import ArialabelledbyElementsPropertyHTML from './examples/arialabelledbyelements-property.sample.html?raw';
+import ArialabelledbyElementsProperty from './examples/arialabelledbyelements-property.sample.js?raw';
+import NonWorkingExampleIIa from './examples/non-working-example-IIa.sample.html?raw';
+import NonWorkingExampleIIb from './examples/non-working-example-IIb.sample.html?raw';
+import WorkingExampleIIa from './examples/working-example-IIa.sample.html?raw';
+import WorkingExampleIIb from './examples/working-example-IIb.sample.html?raw';
+import NonWorkingExampleIII from './examples/non-working-example-III.sample.html?raw';
+import WorkingExampleIII from './examples/working-example-III.sample.html?raw';
+import NonWorkingExampleIV from './examples/non-working-example-IV.sample.html?raw';
+import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 <Meta of={CCR} />
 
@@ -48,7 +48,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </p>
 
 <Canvas of={CCR.ExampleHTML} sourceState="hide" />
-### II. Referencing From Outside a Shadow DOM Into That Shadow DOM
+### II. Referencing From the Light DOM into the ShadowDOM
 
 • <b>Light DOM → Shadow DOM</b> ❌
 
@@ -72,7 +72,7 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 #### Workaround: `Element:ariaLabelledByElements`
 
 <p>
-  `ariaLabelledByElements` is a property of the Element interface that returns an array of elements
+  `ariaLabelledByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="_blank">Element API</a> that returns an array of elements
   labeling the element. It provides direct references to these elements rather than just their ID
   strings.
   <a
@@ -84,11 +84,13 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 </p>
 
 <div className="lead">Basic usage of `ariaLabelledByElements` </div>
-<Source language="html" dark code={ArialabelledbyElementsPropertyHTML}></Source>
+
 <p>
   Instead of adding the `aria-labelledby` attribute on the element, we can set it using the
   `ariaLabelledByElements` property.
 </p>
+<Source language="html" dark code={ArialabelledbyElementsPropertyHTML}></Source>
+
 <Source language="js" dark code={ArialabelledbyElementsProperty}></Source>
 <p>
   The following examples demonstrate how the `ariaLabelledByElements` property can be used to
@@ -126,14 +128,17 @@ import WorkingExampleIV from './examples/workingExample-IV.sample.html?raw';
 
 ⚠️ In the above scenarios, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
 
-### III. Referencing From Inside a Shadow DOM Out to the Light DOM
+### III. Referencing From the ShadowDOM into the Light DOM
 
 <p>
   <b>• Shadow DOM → Light DOM (or Shadow DOM → Slotted Content)</b>❌
 </p>
 
 <p>
- A `for` attribute on an element inside a Shadow DOM <b>cannot reference the id of an element outside that Shadow DOM</b>. The `ariaLabelledByElements` property neither works in this case because, for it to work, the label element must be in the same DOM or in a parent DOM of the target element.
+  A `for` attribute on an element inside a Shadow DOM{' '}
+  <b>cannot reference the id of an element outside that Shadow DOM</b>. The `ariaLabelledByElements`
+  property neither works in this case because, for it to work, the label element must be in the same
+  DOM or in a parent DOM of the target element.
 </p>
 
 <Source language="html" dark code={NonWorkingExampleIII}></Source>
@@ -157,8 +162,8 @@ Shadow DOM → Other Shadow DOM ❌
 
 <Source language="html" dark code={NonWorkingExampleIV}></Source>
 <p>
-  This relationship is not valid because both `for` and `id` attributes are scoped only within
-  their individual shadowDoms.
+  This relationship is not valid because both `for` and `id` attributes are scoped only within their
+  individual shadowDoms.
 </p>
 ##### Working Solution
 
@@ -167,4 +172,4 @@ A working solution for this case combines approaches II and III: setting the lab
 <Source language="html" dark code={WorkingExampleIV}></Source>
 <Canvas of={CCR.Example5} sourceState="hide" />
 
-⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
\ No newline at end of file
+⚠️ In the above scenario, the relationship is correctly announced by NVDA, passes accessibility checks on Axe, WAVE and NVDA but partially fails on Siteimprove and Accessibility Insights tools.
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
index db4066c502..30d23a97de 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
@@ -45,14 +45,14 @@ export const referencingData = [
     attribute: 'Aria-Labelledby',
     cases: [
       {
-        case: 'Light DOM/Slot ➔ ShadowDOM',
+        case: 'ShadowDOM ➔ Light DOM/Slot',
         worksAcrossShadow: '❌',
         workaround: '✔️ Elements API - ariaLabelledByElements',
         docPage:
           '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
       },
       {
-        case: 'ShadowDOM ➔ Light DOM/Slot',
+        case: 'Light DOM/Slot ➔ ShadowDOM',
         worksAcrossShadow: '❌',
         workaround: '⬇️ Set the "id" on the component host',
         docPage:
@@ -72,14 +72,14 @@ export const referencingData = [
     attribute: 'Aria-Describedby',
     cases: [
       {
-        case: 'Light DOM/Slot ➔ ShadowDOM',
+        case: 'ShadowDOM ➔ Light DOM/Slot',
         worksAcrossShadow: '❌',
         workaround: '✔️ Elements API - ariaDescribedByElements',
         docPage:
           '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
       },
       {
-        case: 'ShadowDOM ➔ Light DOM/Slot',
+        case: 'Light DOM/Slot ➔ ShadowDOM',
         worksAcrossShadow: '❌',
         workaround: '⬇️ Set the "id" on the component host',
         docPage:
@@ -99,9 +99,9 @@ export const referencingData = [
     attribute: 'Aria-Role: List ',
     cases: [
       {
-        case: 'Light DOM/Slot ➔ ShadowDOM',
+        case: 'All cases',
         worksAcrossShadow:
-          '✔️ The relationship is not affected by the ShadowDOM. It will be valid for all cases where the structure is accessible in such way that the "list" element contains its "listitems".',
+          '✔️ The relationship is not affected by the ShadowDOM. It will always be valid if the structure is accessible and the "list" element contains its "listitems".',
         workaround: '',
         docPage: '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405112--docs',
       },

From e563f4419910d50ebf76678e5d12485c912744f2 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 18 Nov 2025 16:44:09 +0100
Subject: [PATCH 20/29] review comments update

---
 .../for/examples/non-working-example-IIb.sample.html |  3 ++-
 .../for/examples/working-example-IIa.sample.html     |  4 +---
 .../for/examples/working-example-IIb.sample.html     |  1 -
 .../for/examples/working-example-IV.sample.html      |  2 +-
 .../reference-table/reference-table.stories.ts       | 12 ++++++------
 5 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
index 43a8dc6c44..9f0be04c70 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
@@ -2,5 +2,6 @@
   ⏷ #shadow-root (open)
     <slot name="label-slot"></slot>
     <input id="inputId">
-  <label for="inputId" slot="label-slot">My Text</label>
+    
+    <label for="inputId" slot="label-slot">My Text</label>
 </custom-component>
\ No newline at end of file
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIa.sample.html
index 45295664f1..5800d8b804 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIa.sample.html
@@ -3,9 +3,7 @@
 <custom-input labelId="labelId">
   ⏷ #shadow-root (open)
     <input ref="targetRef" id="inputId" aria-labelledby>
-      <!--The aria-labelledby attribute is set automatically by the browser -->
-        <custom-icon />
-    </div>
+    <!--The aria-labelledby attribute is set automatically by the browser -->
 </custom-input>
 
 <script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIb.sample.html
index 558477d758..b641384851 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IIb.sample.html
@@ -4,7 +4,6 @@
     <!--The aria-labelledby attribute is set automatically by the browser -->
     <div ref="targetRef" role="button" tabindex="0" aria-labelledby>
 
-  <!-- slotted label element -->
   <span slot="label-slot">My Text</span>
 </custom-component>
 
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IV.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IV.sample.html
index aa7f6b29c3..dfce0d8e2e 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IV.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/working-example-IV.sample.html
@@ -5,7 +5,7 @@
 
 <custom-button>
   ⏷ #shadow-root (open)
-  <input ref="targetRef" id="inputId" aria-labelledby />
+    <input ref="targetRef" id="inputId" aria-labelledby />
 </custom-button>
 
 <script>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
index 30d23a97de..e927748910 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
@@ -22,14 +22,14 @@ export const referencingData = [
         worksAcrossShadow: '❌',
         workaround: '✔️ Elements API - ariaLabelledByElements',
         docPage:
-          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa340f7d3--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom-',
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3401234--docs#ii-referencing-from-the-light-dom-into-the-shadowdom',
       },
       {
         case: 'ShadowDOM ➔ Light DOM/Slot',
         worksAcrossShadow: '❌',
         workaround: '⬇️ Set the "id" on the component host',
         docPage:
-          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3401234--docs#iii-referencing-from-inside-a-shadow-dom-out-to-the-light-dom',
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3401234--docs#iii-referencing-from-the-shadowdom-into-the-light-dom',
       },
       {
         case: 'ShadowDOM ➔ Other ShadowDOM',
@@ -49,14 +49,14 @@ export const referencingData = [
         worksAcrossShadow: '❌',
         workaround: '✔️ Elements API - ariaLabelledByElements',
         docPage:
-          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#ii-referencing-from-the-shadowdom-out-to-the-light-dom',
       },
       {
         case: 'Light DOM/Slot ➔ ShadowDOM',
         worksAcrossShadow: '❌',
         workaround: '⬇️ Set the "id" on the component host',
         docPage:
-          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#iii-referencing-from-inside-a-shadow-dom-out-to-the-light-dom',
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405678--docs#iii-referencing-from-the-light-dom-into-the-shadowdom',
       },
       {
         case: 'ShadowDOM ➔ Other ShadowDOM',
@@ -76,14 +76,14 @@ export const referencingData = [
         worksAcrossShadow: '❌',
         workaround: '✔️ Elements API - ariaDescribedByElements',
         docPage:
-          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#ii-referencing-from-the-shadowdom-out-to-the-light-dom',
       },
       {
         case: 'Light DOM/Slot ➔ ShadowDOM',
         worksAcrossShadow: '❌',
         workaround: '⬇️ Set the "id" on the component host',
         docPage:
-          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#ii-referencing-from-outside-a-shadow-dom-into-that-shadow-dom',
+          '/?path=/docs/76ade552-2c03-4d6d-9dce-28daa3405910--docs#iii-referencing-from-the-light-dom-into-the-shadowdom',
       },
       {
         case: 'ShadowDOM ➔ Other ShadowDOM',

From d481cb166d313090fea61cf4f9addf6a29de9e8b Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 18 Nov 2025 16:50:43 +0100
Subject: [PATCH 21/29] lint errors

---
 .../aria-describedby/aria-describedby.docs.mdx     |  2 +-
 .../aria-labelledby/aria-labelledby.docs.mdx       | 14 +++++++++-----
 .../for/for.docs.mdx                               |  9 ++++++---
 3 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
index 1968a59439..34e76ad9c3 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -79,7 +79,7 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 #### Workaround: `Element:ariaDescribedByElements`
 
 <p>
-  `ariaDescribedByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="_blank">Element API</a> that returns an array of elements
+  `ariaDescribedByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">Element API</a> that returns an array of elements
   describing the element. It provides direct references to these elements rather than just their ID
   strings.
   <a
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index 05223acca7..71b2d4d916 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -73,9 +73,12 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 #### Workaround: `Element:ariaLabelledByElements`
 
 <p>
-  `ariaLabelledByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="_blank">Element API</a> that returns an array of elements
-  labeling the element. It provides direct references to these elements rather than just their ID
-  strings.
+  `ariaLabelledByElements` is a property of the{' '}
+  <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">
+    Element API
+  </a>{' '}
+  that returns an array of elements labeling the element. It provides direct references to these
+  elements rather than just their ID strings.
   <a
     target="blank"
     href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements"
@@ -145,9 +148,10 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 <p>
   The only option here is to <b>set the `id` directly on the host</b> of the labeling component. In
-  this case <b>all the visible text inside the component that contains the reference will be assigned as the Accessible Name</b> of the target element.
+  this case <b>all the visible text inside the component that contains the reference will be assigned as the
+    Accessible Name</b> of the target element.
 </p>
-<Canvas of={CCR.Example4} sourceState="hide" />
+<Source language="html" dark code={WorkingExampleIII}></Source>
 
 ### IV. Referencing From One Shadow DOM To Another Shadow DOM
 
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
index 09c4bf7900..ec62e95c7d 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/for.docs.mdx
@@ -72,9 +72,12 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 #### Workaround: `Element:ariaLabelledByElements`
 
 <p>
-  `ariaLabelledByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="_blank">Element API</a> that returns an array of elements
-  labeling the element. It provides direct references to these elements rather than just their ID
-  strings.
+  `ariaLabelledByElements` is a property of the{' '}
+  <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">
+    Element API
+  </a>{' '}
+  that returns an array of elements labeling the element. It provides direct references to these
+  elements rather than just their ID strings.
   <a
     target="blank"
     href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements"

From aa845c68453115f78c02a502b2ad03444092e205 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Tue, 18 Nov 2025 17:10:02 +0100
Subject: [PATCH 22/29] fix lint errors

---
 .../aria-role-list/aria-role-list.docs.mdx                  | 5 +++--
 .../aria-role-list/aria-role-list.stories.ts                | 6 +-----
 .../reference-table/reference-table.docs.mdx                | 2 +-
 .../reference-table/reference-table.stories.ts              | 2 +-
 4 files changed, 6 insertions(+), 9 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
index 41b832f161..41321987a3 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -71,7 +71,8 @@ import WorkingExampleIVc from './examples/working-example-IVc.sample.html?raw';
 
 • <b>Slotted parent and children in the ShadowDOM</b> ❌
 
-<Source language="html" dark code={WorkingExampleIIa}></Source>
+<Source language="html" dark code={WorkingExampleIIb}></Source>
+<Canvas of={CCR.Example2b} sourceState="hide" />
 
 <p>
   ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
@@ -83,7 +84,7 @@ import WorkingExampleIVc from './examples/working-example-IVc.sample.html?raw';
 
 • <b>Parent in the Shadow DOM and children in the Light DOM</b> ❌
 
-<Source language="html" dark code={WorkingExampleIIIb}></Source>
+<Source language="html" dark code={WorkingExampleIIIa}></Source>
 
 <p>
   ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
index 7fd94c044c..b5db9a4de4 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
@@ -30,11 +30,7 @@ export const ExampleHTML: Story = {
 
 // Case: Light Dom to child components with Slotted content
 export const Example1a: Story = {
-  render: () => html` <demo-list list-version="2">
-    <div role="listitem">item 1</div>
-    <div role="listitem">item 2</div>
-    <div role="listitem">item 3</div>
-  </demo-list>`,
+  render: () => html` <demo-list list-version="2"> </demo-list>`,
 };
 
 // Case: Parent in the Light - children with Slotted content same component
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
index 0ed69a0549..d68ffbadee 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.docs.mdx
@@ -28,7 +28,7 @@ import * as CCR from './reference-table.stories';
       </tr>
     </thead>
    <tbody>
- {CCR.referencingData.map(({ attribute, cases }, attrIndex) =>
+ {CCR.ReferencingData.map(({ attribute, cases }, attrIndex) =>
   cases.map((row, index) => (
     <tr
       key={`${attribute}-${index}`}
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
index e927748910..d24d84d16f 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
@@ -13,7 +13,7 @@ type Story = StoryObj;
 
 export const Default: Story = {};
 
-export const referencingData = [
+export const ReferencingData = [
   {
     attribute: 'For',
     cases: [

From 711d3777d7a2217b60f887136b96993518a9b88a Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Thu, 27 Nov 2025 10:36:00 +0100
Subject: [PATCH 23/29] remove obsolete file and fix indentation

---
 .../components/src/components/post-popover-trigger/readme.md   | 3 +--
 packages/documentation/src/demo-components/demo-button.ts      | 2 +-
 .../aria-describedby/examples/working-example-IIa.sample.html  | 2 +-
 3 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/packages/components/src/components/post-popover-trigger/readme.md b/packages/components/src/components/post-popover-trigger/readme.md
index 82ea44e984..c3dc54d5da 100644
--- a/packages/components/src/components/post-popover-trigger/readme.md
+++ b/packages/components/src/components/post-popover-trigger/readme.md
@@ -1,7 +1,6 @@
+# post-popover-trigger
 
-# post-popover
 
-# post-popover-trigger
 
 <!-- Auto Generated Below -->
 
diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index b2215acf6b..c8b77ab0ff 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -19,7 +19,7 @@ export class DemoButton extends HTMLElement {
   }
 
   attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
-    const member = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const member = name.replace(/-([a-z])/g, (_, p) => p.toUpperCase());
 
     if (member === 'buttonVersion') {
       this.buttonVersion = newValue as '1' | '2' | '3' | '4';
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIa.sample.html
index da556380dd..1fe6001d25 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/examples/working-example-IIa.sample.html
@@ -4,7 +4,7 @@
   ⏷ #shadow-root (open)
     <div ref="targetRef" role="button" tabindex="0" aria-describedby>
       <!--The aria-describedby attribute is set automatically by the browser -->
-        <custom-icon />
+      <custom-icon />
     </div>
 </custom-component>
 

From ebe278b0150351f55e74f18ddb4320db245a476e Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Thu, 27 Nov 2025 11:06:20 +0100
Subject: [PATCH 24/29] removed invalid html role="list" examples and fixed
 identation

---
 .../src/demo-components/demo-button.ts        |  7 ++--
 .../aria-role-list/aria-role-list.docs.mdx    | 35 ++++---------------
 .../aria-role-list/aria-role-list.stories.ts  | 24 ++-----------
 ...le.html => working-example-II.sample.html} |  0
 ...e.html => working-example-III.sample.html} |  0
 .../examples/working-example-IIIa.sample.html |  8 -----
 .../examples/working-example-IIb.sample.html  |  6 ----
 .../examples/working-example-IVa.sample.html  |  6 ++--
 .../non-working-example-IIb.sample.html       |  2 +-
 .../reference-table.stories.ts                |  2 +-
 10 files changed, 19 insertions(+), 71 deletions(-)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{working-example-IIa.sample.html => working-example-II.sample.html} (100%)
 rename packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/{working-example-IIIb.sample.html => working-example-III.sample.html} (100%)
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIa.sample.html
 delete mode 100644 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIb.sample.html

diff --git a/packages/documentation/src/demo-components/demo-button.ts b/packages/documentation/src/demo-components/demo-button.ts
index c8b77ab0ff..693ea81673 100644
--- a/packages/documentation/src/demo-components/demo-button.ts
+++ b/packages/documentation/src/demo-components/demo-button.ts
@@ -1,8 +1,11 @@
+type ButtonVersion = '1' | '2' | '3' | '4';
+
 export class DemoButton extends HTMLElement {
   static get observedAttributes() {
     return ['button-version', 'workaround', 'arialabelledby-id', 'ariadescribedby-id'];
   }
-  private buttonVersion?: '1' | '2' | '3' | '4';
+
+  private buttonVersion?: ButtonVersion;
   private workaround?: string;
   private internalButton?: HTMLElement;
   private arialabelledbyId?: string;
@@ -22,7 +25,7 @@ export class DemoButton extends HTMLElement {
     const member = name.replace(/-([a-z])/g, (_, p) => p.toUpperCase());
 
     if (member === 'buttonVersion') {
-      this.buttonVersion = newValue as '1' | '2' | '3' | '4';
+      this.buttonVersion = newValue as ButtonVersion;
     } else {
       this[member as keyof this] = newValue as this[keyof this];
     }
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
index 41321987a3..2e68803a88 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.docs.mdx
@@ -4,10 +4,8 @@ import * as CCR from './aria-role-list.stories';
 import DefaultExample from './examples/default-example.sample.html?raw';
 import DefaultExample2 from './examples/default-example-2.sample.html?raw';
 import DefaultExample3 from './examples/default-example-3.sample.html?raw';
-import WorkingExampleIIa from './examples/working-example-IIa.sample.html?raw';
-import WorkingExampleIIb from './examples/working-example-IIb.sample.html?raw';
-import WorkingExampleIIIa from './examples/working-example-IIIa.sample.html?raw';
-import WorkingExampleIIIb from './examples/working-example-IIIb.sample.html?raw';
+import WorkingExampleII from './examples/working-example-II.sample.html?raw';
+import WorkingExampleIII from './examples/working-example-III.sample.html?raw';
 import WorkingExampleIVa from './examples/working-example-IVa.sample.html?raw';
 import WorkingExampleIVb from './examples/working-example-IVb.sample.html?raw';
 import WorkingExampleIVc from './examples/working-example-IVc.sample.html?raw';
@@ -60,43 +58,22 @@ import WorkingExampleIVc from './examples/working-example-IVc.sample.html?raw';
 
 • <b>Parent in the light DOM and children in the ShadowDOM</b> ✔️
 
-<Source language="html" dark code={WorkingExampleIIa}></Source>
+<Source language="html" dark code={WorkingExampleII}></Source>
 
-<Canvas of={CCR.Example2a} sourceState="hide" />
+<Canvas of={CCR.Example2} sourceState="hide" />
 
 <p>
   In the case a component with `role="list"` in the host with `listitem` elements within its Shadow
   DOM, the relationship is valid.
 </p>
 
-• <b>Slotted parent and children in the ShadowDOM</b> ❌
-
-<Source language="html" dark code={WorkingExampleIIb}></Source>
-<Canvas of={CCR.Example2b} sourceState="hide" />
-
-<p>
-  ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
-  children of an element with `role="list"`. The relationship fails not because of the Shadow DOM
-  boundary, but due to the incorrect structure itself.
-</p>
-
 ### III. Parent in the Shadow DOM - Children Out to the Light DOM
 
-• <b>Parent in the Shadow DOM and children in the Light DOM</b> ❌
-
-<Source language="html" dark code={WorkingExampleIIIa}></Source>
-
-<p>
-  ⚠️ The above structure does not comply with accessibility standards, as `listitems` must be
-  children of an element with `role="list"`. The relationship fails not because of the Shadow DOM
-  boundary, but due to the incorrect structure itself.
-</p>
-
 • <b>Parent in the Shadow DOM with slotted children </b> ✔️
 
-<Source language="html" dark code={WorkingExampleIIIb}></Source>
+<Source language="html" dark code={WorkingExampleIII}></Source>
 
-<Canvas of={CCR.Example3b} sourceState="hide" />
+<Canvas of={CCR.Example3} sourceState="hide" />
 
 <p>
   When a component applies `role="list"` to an internal element and its children with
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
index b5db9a4de4..de6263a17f 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/aria-role-list.stories.ts
@@ -5,7 +5,7 @@ import { html } from 'lit';
 const meta: MetaExtended = {
   id: '76ade552-2c03-4d6d-9dce-28daa3405112',
   title:
-    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/aria-role-list',
+    'Accessibility Practices/Foundational Structure And Semantics/Reference Crossing The Shadowdom/role-list',
   parameters: {
     badges: [],
   },
@@ -45,33 +45,15 @@ export const Example1b: Story = {
 };
 
 // Case: Parent in the Light (Component host) -> Children in the ShadowDOM
-export const Example2a: Story = {
+export const Example2: Story = {
   render: () =>
     html`
       <demo-list-item-group list-group-version="2" role="list" tabindex="0"> </demo-list-item-group>
     `,
 };
 
-// Case: Parent in Light (slotted content) - Children in the ShadowDOM
-export const Example2b: Story = {
-  render: () =>
-    html`<demo-list-item-group list-group-version="2" tabindex="0">
-      <div role="list" tabindex="0" slot="list-parent"></div>
-    </demo-list-item-group>`,
-};
-
-// Case: Parent in the Shadow - Children in the Light
-export const Example3a: Story = {
-  render: () => html`
-    <demo-list list-version="0"></demo-list>
-    <div role="listitem">item 1</div>
-    <div role="listitem">item 2</div>
-    <div role="listitem">item 3</div>
-  `,
-};
-
 // Case: Parent in the Shadow - Children Slotted
-export const Example3b: Story = {
+export const Example3: Story = {
   render: () => html`
     <demo-list list-version="3">
       <div role="listitem">item 1</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIa.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-III.sample.html
similarity index 100%
rename from packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIb.sample.html
rename to packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-III.sample.html
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIa.sample.html
deleted file mode 100644
index d42e710e66..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIIa.sample.html
+++ /dev/null
@@ -1,8 +0,0 @@
-<custom-list>
-  ⏷ #shadow-root (open)
-    <div role="list">test</div>
-</custom-list>
-
-<div role="listitem">item 1</div>
-<div role="listitem">item 2</div>
-<div role="listitem">item 3</div>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIb.sample.html
deleted file mode 100644
index 8e9e8883d5..0000000000
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IIb.sample.html
+++ /dev/null
@@ -1,6 +0,0 @@
-<custom-list role="list">
-  ⏷ #shadow-root (open)
-    <div role="listitem">item 1</div>
-    <div role="listitem">item 2</div>
-    <div role="listitem">item 3</div>
-</custom-list>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVa.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVa.sample.html
index 937da1cef0..0c161a72b5 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVa.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-IVa.sample.html
@@ -3,9 +3,9 @@
     <div role="list">
       <custom-list-item-group>
         ⏷ #shadow-root (open)
-        <div role="listitem">item 1</div>
-        <div role="listitem">item 2</div>
-        <div role="listitem">item 3</div>
+          <div role="listitem">item 1</div>
+          <div role="listitem">item 2</div>
+          <div role="listitem">item 3</div> 
       </custom-list-item-group>
     </div>
 </custom-list>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
index 9f0be04c70..c838123411 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/for/examples/non-working-example-IIb.sample.html
@@ -3,5 +3,5 @@
     <slot name="label-slot"></slot>
     <input id="inputId">
     
-    <label for="inputId" slot="label-slot">My Text</label>
+  <label for="inputId" slot="label-slot">My Text</label>
 </custom-component>
\ No newline at end of file
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
index d24d84d16f..2ededf2987 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/reference-table/reference-table.stories.ts
@@ -96,7 +96,7 @@ export const ReferencingData = [
     ],
   },
   {
-    attribute: 'Aria-Role: List ',
+    attribute: 'Role: List ',
     cases: [
       {
         case: 'All cases',

From 7554cf804a725838f01f7bd34213cdc09bae19ed Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Thu, 27 Nov 2025 11:14:41 +0100
Subject: [PATCH 25/29] fix identation

---
 .../examples/non-working-example-IIb.sample.html     |  9 +++++----
 .../examples/working-example-IIb.sample.html         | 12 ++++++------
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIb.sample.html
index 997d9faf11..49c8858f80 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/non-working-example-IIb.sample.html
@@ -1,8 +1,9 @@
 <custom-component>
   ⏷ #shadow-root (open)
-  <slot name="aria-slot"> </slot>
-  <div role="button" tabindex="0" aria-labelledby="labelId">
-    <custom-icon />
-  </div>
+    <slot name="aria-slot"> </slot>
+    <div role="button" tabindex="0" aria-labelledby="labelId">
+      <custom-icon />
+    </div>
+    
   <span slot="aria-slot" id="labelId">My Text</span>
 </custom-component>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIb.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIb.sample.html
index 2ae81bd671..e17c03d593 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIb.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/examples/working-example-IIb.sample.html
@@ -1,11 +1,11 @@
 <custom-component>
   ⏷ #shadow-root (open)
-  <slot name="aria-slot"></slot>
-  <div ref="targetRef" role="button" tabindex="0" aria-labelledby>
-    <!--The aria-labelledby attribute is set automatically by the browser -->
-    <custom-icon />
-  </div>
-  <!-- slotted label element -->
+    <slot name="aria-slot"></slot>
+    <div ref="targetRef" role="button" tabindex="0" aria-labelledby>
+      <!--The aria-labelledby attribute is set automatically by the browser -->
+      <custom-icon />
+    </div>
+
   <span slot="aria-slot">My Text</span>
 </custom-component>
 

From 3ab600853afa49c314c094e132bbbfc24865b0d5 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <66249294+myrta2302@users.noreply.github.com>
Date: Wed, 3 Dec 2025 07:10:33 +0100
Subject: [PATCH 26/29] Update
 packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Oliver Schürch <oliver.schuerch@post.ch>
---
 .../aria-role-list/examples/working-example-II.sample.html    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html
index 9e95d4a2ac..b60959a434 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html
@@ -5,6 +5,6 @@
     <div role="listitem">item 2</div>
     <div role="listitem">item 3</div>
 
- <!-- Slotted parent with role="list"-->   
- <div role="list" slot="parent-slot"></div>
+  <!-- Slotted parent with role="list"-->   
+  <div role="list" slot="parent-slot"></div>
 </custom-list>

From bc4e88c8b2c928a161fb04b9ce98517d4f0ffd62 Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Wed, 3 Dec 2025 07:25:51 +0100
Subject: [PATCH 27/29] review comments update

---
 .../aria-describedby/aria-describedby.docs.mdx    |  2 +-
 .../aria-labelledby/aria-labelledby.docs.mdx      | 15 ++++++++++-----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
index 34e76ad9c3..c27c910271 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -26,7 +26,7 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
   from different pieces of text.
 </p>
 <p>
-  ⚠️ The `aria-describedby` attribute is not intended to reference content from external sources.
+  ℹ️ The `aria-describedby` attribute is not intended to reference content from external sources.
   Its value must consist of one or more element IDs (space-separated if multiple), and each ID must
   correspond to an element within the same DOM document.
 </p>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index 71b2d4d916..d15ae32f11 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -25,6 +25,13 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
   This is particularly useful when a simple text label isn’t directly linked to the element, or when
   the accessible name needs to be composed from multiple pieces of text.
 </p>
+
+<p>
+  ℹ️ The `aria-labelledby` attribute is not intended to reference content from external sources.
+  Its value must consist of one or more element IDs (space-separated if multiple), and each ID must
+  correspond to an element within the same DOM document.
+</p>
+
 ### I. Referencing Within the Same DOM Tree
 
 • <b>Both elements in Light DOM</b> ✔️
@@ -72,12 +79,10 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 #### Workaround: `Element:ariaLabelledByElements`
 
-<p>
-  `ariaLabelledByElements` is a property of the{' '}
+<p>`ariaLabelledByElements` is a property of the
   <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">
     Element API
-  </a>{' '}
-  that returns an array of elements labeling the element. It provides direct references to these
+  </a> that returns an array of elements labeling the element. It provides direct references to these
   elements rather than just their ID strings.
   <a
     target="blank"
@@ -140,7 +145,7 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 <p>
   Referencing an element in the shadow DOM from the light DOM using the standard `aria-labelledby`
   is not possible. The `ariaLabelledByElements` property neither works in this case because, for it
-  to work, the label element shoul be in the same DOM or in a parent DOM of the target element.
+  to work, the label element should be in the same DOM or in a parent DOM of the target element.
 </p>
 <Source language="html" dark code={NonWorkingExampleIII}></Source>
 

From 3b4fdc3b3b46b3399ae6039fa668f8fc2db74b2e Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Wed, 3 Dec 2025 07:32:57 +0100
Subject: [PATCH 28/29] lint error

---
 .../aria-describedby/aria-describedby.docs.mdx       | 10 +++-------
 .../aria-labelledby/aria-labelledby.docs.mdx         | 12 ++++--------
 2 files changed, 7 insertions(+), 15 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
index c27c910271..d8da6a842c 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -78,17 +78,13 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 #### Workaround: `Element:ariaDescribedByElements`
 
-<p>
-  `ariaDescribedByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">Element API</a> that returns an array of elements
+<p>`ariaDescribedByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">Element API</a> that returns an array of elements
   describing the element. It provides direct references to these elements rather than just their ID
-  strings.
-  <a
+  strings. <a
     target="blank"
     href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaDescribedByElements"
   >
-    🔗ariaDescribedByElements
-  </a>
-</p>
+    🔗ariaDescribedByElements</a></p>
 
 <div className="lead">Basic usage of `ariaDescribedByElements` </div>
 <Source language="html" dark code={AriaDescribedbyElementsPropertyHTML}></Source>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index d15ae32f11..df909878a1 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -79,18 +79,14 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 #### Workaround: `Element:ariaLabelledByElements`
 
-<p>`ariaLabelledByElements` is a property of the
-  <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">
-    Element API
-  </a> that returns an array of elements labeling the element. It provides direct references to these
-  elements rather than just their ID strings.
-  <a
+<p>`ariaLabelledByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">
+    Element API</a> that returns an array of elements labeling the element. It provides direct references to these
+  elements rather than just their ID strings.<a
     target="blank"
     href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements"
   >
     🔗ariaLabelledByElements
-  </a>
-</p>
+  </a></p>
 
 <div className="lead">Basic usage of `ariaLabelledByElements` </div>
 <p>

From 4ad0d57c9b68ab0b9898e00c4de28c03db7c025f Mon Sep 17 00:00:00 2001
From: Myrta Sakellariou <myrta.sakellariou@gmail.com>
Date: Wed, 3 Dec 2025 08:21:46 +0100
Subject: [PATCH 29/29] fix lint error

---
 .../aria-describedby.docs.mdx                 | 17 +++++-----
 .../aria-labelledby/aria-labelledby.docs.mdx  | 31 +++++--------------
 2 files changed, 16 insertions(+), 32 deletions(-)

diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
index d8da6a842c..3dff76042c 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-describedby/aria-describedby.docs.mdx
@@ -25,11 +25,8 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
   This is useful when a simple text label isn't enough or when the description needs to be combined
   from different pieces of text.
 </p>
-<p>
-  ℹ️ The `aria-describedby` attribute is not intended to reference content from external sources.
-  Its value must consist of one or more element IDs (space-separated if multiple), and each ID must
-  correspond to an element within the same DOM document.
-</p>
+<p>ⓘ The `aria-describedby` attribute is not intended to reference content from external sources. Its value must consist of one or more element IDs (space-separated if multiple), and each ID must
+  correspond to an element within the same DOM document.</p>
 
 ### I. Referencing Within the Same DOM Tree
 
@@ -78,13 +75,17 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 #### Workaround: `Element:ariaDescribedByElements`
 
-<p>`ariaDescribedByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">Element API</a> that returns an array of elements
+<p>
+  `ariaDescribedByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">Element API</a> that returns an array of elements
   describing the element. It provides direct references to these elements rather than just their ID
-  strings. <a
+  strings.
+  <a
     target="blank"
     href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaDescribedByElements"
   >
-    🔗ariaDescribedByElements</a></p>
+    🔗ariaDescribedByElements
+  </a>
+</p>
 
 <div className="lead">Basic usage of `ariaDescribedByElements` </div>
 <Source language="html" dark code={AriaDescribedbyElementsPropertyHTML}></Source>
diff --git a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
index df909878a1..5c7c797490 100644
--- a/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
+++ b/packages/documentation/src/stories/accessibility-practices/foundational-structure-and-semantics/reference-crossing-the-shadowdom/aria-labelledby/aria-labelledby.docs.mdx
@@ -21,16 +21,11 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
   In the Light DOM, the `aria-labelledby` attribute assigns an accessible name to an element by
   referencing the ID of one or more elements that provide the descriptive text.
 </div>
-<p>
-  This is particularly useful when a simple text label isn’t directly linked to the element, or when
-  the accessible name needs to be composed from multiple pieces of text.
-</p>
+<p>This is particularly useful when a simple text label isn’t directly linked to the element, or when
+  the accessible name needs to be composed from multiple pieces of text.</p>
 
-<p>
-  ℹ️ The `aria-labelledby` attribute is not intended to reference content from external sources.
-  Its value must consist of one or more element IDs (space-separated if multiple), and each ID must
-  correspond to an element within the same DOM document.
-</p>
+<p>ⓘ The `aria-labelledby` attribute is not intended to reference content from external sources.
+  Its value must consist of one or more element IDs (space-separated if multiple), and each ID must correspond to an element within the same DOM document.</p>
 
 ### I. Referencing Within the Same DOM Tree
 
@@ -41,12 +36,7 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 • <b>Both elements in same Shadow DOM</b> ✔️
 
 <Source language="html" dark code={DefaultExample2}></Source>
-<p>
-  <b>
-    The above relationships are valid because in both cases the label and its associated target
-    element are part of the same tree.
-  </b>
-</p>
+<p><b>The above relationships are valid because in both cases the label and its associated target element are part of the same tree.</b></p>
 
 <p>
   Below is a working example of an `aria-labelledby`/`id` relationship within the shadowDom of a
@@ -79,15 +69,8 @@ import WorkingExampleIV from './examples/working-example-IV.sample.html?raw';
 
 #### Workaround: `Element:ariaLabelledByElements`
 
-<p>`ariaLabelledByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">
-    Element API</a> that returns an array of elements labeling the element. It provides direct references to these
-  elements rather than just their ID strings.<a
-    target="blank"
-    href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements"
-  >
-    🔗ariaLabelledByElements
-  </a></p>
-
+<p>`ariaLabelledByElements` is a property of the <a href="https://developer.mozilla.org/fr/docs/Web/API/Element" target="blank">Element API</a> that returns an array of elements labeling the element. It provides direct references to these
+  elements rather than just their ID strings. <a target="blank" href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements">🔗ariaLabelledByElements</a></p>
 <div className="lead">Basic usage of `ariaLabelledByElements` </div>
 <p>
   Instead of adding the `aria-labelledby` attribute on the element, we can set it using the