chore(components): update language switch accessible names and roles

.changeset/real-women-decide.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': patch
+---
+
+Add accessibility note in the Language Switch page to highlight the requirement for clear accessible `names` on language selection options.

.changeset/stale-dogs-hope.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-components': patch
+---
+
+Enhanced accessibility of `post-language-switch` component by replacing `aria-labels` with `visually-hidden` spans and properly assigning semantic `role` attributes.

packages/components/cypress/e2e/language-option.cy.ts

@@ -19,7 +19,6 @@ describe('language-option', () => {
       cy.get('@button')
         .should('exist')
         .and('have.attr', 'aria-current', 'true')
-        .and('have.attr', 'aria-label', 'English')
         .and('have.attr', 'lang', 'en');
     });
 
@@ -50,7 +49,6 @@ describe('language-option', () => {
       cy.get('@anchor')
         .should('exist')
         .and('have.attr', 'aria-current', 'page')
-        .and('have.attr', 'aria-label', 'English')
         .and('have.attr', 'href', 'https://www.post.ch/en')
         .and('have.attr', 'hrefLang', 'en')
         .and('have.attr', 'lang', 'en');

packages/components/src/components/post-language-option/post-language-option.scss

@@ -8,6 +8,9 @@ post-language-option {
 
   button {
     @include post.reset-button;
+    .visually-hidden {
+      @include utilities-mx.visuallyhidden();
+    }
   }
 
   a {

packages/components/src/components/post-language-option/post-language-option.tsx

@@ -127,24 +127,24 @@ export class PostLanguageOption {
         {this.url ? (
           <a
             aria-current={this.active ? 'page' : undefined}
-            aria-label={this.name}
             href={this.url}
             hrefLang={lang}
             lang={lang}
             onClick={() => this.emitChange()}
             onKeyDown={emitOnKeyDown}
           >
             <slot />
+            <span class="visually-hidden">{this.name}</span>
           </a>
         ) : (
           <button
             aria-current={this.active ? 'true' : undefined}
-            aria-label={this.name}
             lang={lang}
             onClick={() => this.emitChange()}
             onKeyDown={emitOnKeyDown}
           >
             <slot />
+            <span class="visually-hidden">{this.name}</span>
           </button>
         )}
       </Host>

packages/components/src/components/post-language-switch/post-language-switch.scss

@@ -30,6 +30,9 @@ tokens.$default-map: components.$post-button;
   @include utilities-mx.not-disabled-hover() {
     @include button-mx.button-variant-def('hover', 'tertiary');
   }
+  .visually-hidden {
+    @include utilities-mx.visuallyhidden();
+  }
 
   post-icon {
     height: 24px;
@@ -61,3 +64,9 @@ tokens.$default-map: components.$post-button;
     }
   }
 }
+
+.post-language-switch-list {
+  .visually-hidden {
+    @include utilities-mx.visuallyhidden();
+  }
+}

packages/components/src/components/post-language-switch/post-language-switch.tsx

@@ -11,6 +11,7 @@ import { nanoid } from 'nanoid';
 })
 export class PostLanguageSwitch {
   private readonly menuId = `p${nanoid(11)}`;
+  private readonly listSpanId = `list-span-${nanoid(11)}`;
   private get languageOptions(): HTMLPostLanguageOptionElement[] {
     return Array.from(
       this.host.querySelectorAll<HTMLPostLanguageOptionElement>('post-language-option'),
@@ -108,13 +109,22 @@ export class PostLanguageSwitch {
   private updateChildrenVariant() {
     this.languageOptions.forEach(el => {
       el.setAttribute('variant', this.variant);
+      el.setAttribute('role', this.variant == 'menu' ? 'menuitem' : 'listitem');
     });
   }
 
   private renderList() {
     return (
-      <Host data-version={version} role="list" aria-label={this.caption}>
-        <div class="post-language-switch-list" role="group" aria-label={this.description}>
+      <Host data-version={version}>
+        <div
+          class="post-language-switch-list"
+          role="list"
+          aria-label={this.caption}
+          aria-describedby={this.listSpanId}
+        >
+          <span id={this.listSpanId} class="visually-hidden">
+            {this.description}
+          </span>
           <slot></slot>
         </div>
       </Host>
@@ -125,8 +135,10 @@ export class PostLanguageSwitch {
     return (
       <Host data-version={version}>
         <post-menu-trigger for={this.menuId}>
-          <button class="post-language-switch-trigger" aria-label={this.description}>
+          <button class="post-language-switch-trigger">
             {this.activeLang}
+            <span class="visually-hidden">{this.caption}</span>
+            <span class="visually-hidden">{this.description}</span>
             <post-icon aria-hidden="true" name="chevrondown"></post-icon>
           </button>
         </post-menu-trigger>

packages/documentation/src/stories/components/language-switch/language-switch.docs.mdx

@@ -1,21 +1,34 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as languageSwitchStories from './language-switch.stories';
+import { PostBanner } from '@swisspost/design-system-components-react';
 
 <Meta of={languageSwitchStories} />
 
 <div className="docs-title">
   # Language Switch
 
-  <link-design of={JSON.stringify(languageSwitchStories)}></link-design>
+<link-design of={JSON.stringify(languageSwitchStories)}></link-design>
+
 </div>
 
-<p className="lead">The language option switch is a web component which enables users to select their preferred
-  language.</p>
+<p className="lead">
+  The language option switch is a web component which enables users to select their preferred
+  language.
+</p>
 
 <Canvas sourceState="shown" of={languageSwitchStories.Default} />
 
 <Controls of={languageSwitchStories.Default} />
 
+<PostBanner type="info">
+  <p>
+    <b>Accessibility Note:</b> For each language option in the selection menu, the accessible name
+    is generated using the `name` property. It is essential that this property is set with the full,
+    readable name of the language (e.g., English) to serve as an accurate and clear accessible name
+    for assistive technologies.
+  </p>
+</PostBanner>
+
 ## Installation
 
 The `<post-language-switch>` element is part of the `@swisspost/design-system-components` package.