Hide bit-icon component from screen readers by default (#14295)

* adds aria-hidden to bit-icon when no aria-label provided * add ariaLabel to logo svg usages * add ariaLabel documentation * default ariaLable value to undefined * add logo label to translations * adds i18n pipe to component * Add binding to example docs
2025-12-06 00:13:28 +00:00 · 2025-04-18 10:38:19 -04:00
parent e026799071
commit cbab354c0e
12 changed files with 55 additions and 11 deletions
--- a/apps/browser/src/_locales/en/messages.json
+++ b/apps/browser/src/_locales/en/messages.json
@@ -2,6 +2,9 @@
  "appName": {
    "message": "Bitwarden"
  },
+  "appLogoLabel": {
+    "message": "Bitwarden logo"
+  },
  "extName": {
    "message": "Bitwarden Password Manager",
    "description": "Extension name, MUST be less than 40 characters (Safari restriction)"
--- a/apps/browser/src/auth/popup/extension-anon-layout-wrapper/extension-anon-layout-wrapper.component.html
+++ b/apps/browser/src/auth/popup/extension-anon-layout-wrapper/extension-anon-layout-wrapper.component.html
@@ -5,7 +5,12 @@
    [showBackButton]="showBackButton"
    [pageTitle]="''"
  >
-    <bit-icon *ngIf="showLogo" class="tw-inline-flex" [icon]="logo"></bit-icon>
+    <bit-icon
+      *ngIf="showLogo"
+      class="tw-inline-flex"
+      [icon]="logo"
+      [ariaLabel]="'appLogoLabel' | i18n"
+    ></bit-icon>

    <ng-container slot="end">
      <app-pop-out></app-pop-out>
--- a/apps/browser/src/auth/popup/extension-anon-layout-wrapper/extension-anon-layout-wrapper.component.ts
+++ b/apps/browser/src/auth/popup/extension-anon-layout-wrapper/extension-anon-layout-wrapper.component.ts
@@ -12,6 +12,7 @@ import {
 } from "@bitwarden/auth/angular";
 import { I18nService } from "@bitwarden/common/platform/abstractions/i18n.service";
 import { Icon, IconModule, Translation } from "@bitwarden/components";
+import { I18nPipe } from "@bitwarden/ui-common";

 import { PopOutComponent } from "../../../platform/popup/components/pop-out.component";
 import { PopupHeaderComponent } from "../../../platform/popup/layout/popup-header.component";
@@ -36,6 +37,7 @@ export interface ExtensionAnonLayoutWrapperData extends AnonLayoutWrapperData {
    AnonLayoutComponent,
    CommonModule,
    CurrentAccountComponent,
+    I18nPipe,
    IconModule,
    PopOutComponent,
    PopupPageComponent,
--- a/apps/web/src/app/admin-console/organizations/sponsorships/accept-family-sponsorship.component.html
+++ b/apps/web/src/app/admin-console/organizations/sponsorships/accept-family-sponsorship.component.html
@@ -1,6 +1,7 @@
 <div class="tw-mt-10 tw-flex tw-justify-center" *ngIf="loading">
  <div>
-    <bit-icon class="tw-w-72 tw-block tw-mb-4" [icon]="logo"></bit-icon>
+    <bit-icon class="tw-w-72 tw-block tw-mb-4" [icon]="logo" [ariaLabel]="'appLogoLabel' | i18n">
+    </bit-icon>
    <div class="tw-flex tw-justify-center">
      <i
        class="bwi bwi-spinner bwi-spin bwi-2x tw-text-muted"
--- a/apps/web/src/locales/en/messages.json
+++ b/apps/web/src/locales/en/messages.json
@@ -2,6 +2,9 @@
  "allApplications": {
    "message": "All applications"
  },
+  "appLogoLabel": {
+    "message": "Bitwarden logo"
+  },
  "criticalApplications": {
    "message": "Critical applications"
  },
--- a/bitwarden_license/bit-web/src/app/admin-console/providers/manage/accept-provider.component.html
+++ b/bitwarden_license/bit-web/src/app/admin-console/providers/manage/accept-provider.component.html
@@ -1,6 +1,10 @@
 <div class="tw-mt-5 tw-flex tw-justify-center" *ngIf="loading">
  <div>
-    <bit-icon class="tw-w-72 tw-block tw-mb-4" [icon]="logo"></bit-icon>
+    <bit-icon
+      class="tw-w-72 tw-block tw-mb-4"
+      [icon]="logo"
+      [ariaLabel]="'appLogoLabel' | i18n"
+    ></bit-icon>
    <p class="tw-text-center">
      <i
        class="bwi bwi-spinner bwi-spin bwi-2x tw-text-muted"
--- a/bitwarden_license/bit-web/src/app/admin-console/providers/setup/setup-provider.component.html
+++ b/bitwarden_license/bit-web/src/app/admin-console/providers/setup/setup-provider.component.html
@@ -1,6 +1,10 @@
 <div class="tw-mt-12 tw-flex tw-justify-center" *ngIf="loading">
  <div>
-    <bit-icon class="tw-w-72 tw-block tw-mb-4" [icon]="logo"></bit-icon>
+    <bit-icon
+      class="tw-w-72 tw-block tw-mb-4"
+      [icon]="logo"
+      [ariaLabel]="'appLogoLabel' | i18n"
+    ></bit-icon>
    <p class="tw-text-center">
      <i
        class="bwi bwi-spinner bwi-spin bwi-2x tw-text-muted"
--- a/bitwarden_license/bit-web/src/app/billing/providers/setup/setup-business-unit.component.html
+++ b/bitwarden_license/bit-web/src/app/billing/providers/setup/setup-business-unit.component.html
@@ -1,6 +1,10 @@
 <div class="tw-mt-12 tw-flex tw-justify-center" *ngIf="loading">
  <div>
-    <bit-icon class="tw-w-72 tw-block tw-mb-4" [icon]="bitwardenLogo"></bit-icon>
+    <bit-icon
+      class="tw-w-72 tw-block tw-mb-4"
+      [icon]="bitwardenLogo"
+      [ariaLabel]="'appLogoLabel' | i18n"
+    ></bit-icon>
    <p class="tw-text-center">
      <i
        class="bwi bwi-spinner bwi-spin bwi-2x tw-text-muted"
--- a/libs/auth/src/angular/anon-layout/anon-layout.component.html
+++ b/libs/auth/src/angular/anon-layout/anon-layout.component.html
@@ -10,7 +10,7 @@
    [routerLink]="['/']"
    class="tw-w-[128px] tw-block tw-mb-12 [&>*]:tw-align-top"
  >
-    <bit-icon [icon]="logo"></bit-icon>
+    <bit-icon [icon]="logo" [ariaLabel]="'appLogoLabel' | i18n"></bit-icon>
  </a>

  <div
--- a/libs/components/src/icon/icon.component.ts
+++ b/libs/components/src/icon/icon.component.ts
@@ -1,19 +1,23 @@
-// FIXME: Update this file to be type safe and remove this and next line
-// @ts-strict-ignore
-import { Component, HostBinding, Input } from "@angular/core";
+import { Component, Input } from "@angular/core";
 import { DomSanitizer, SafeHtml } from "@angular/platform-browser";

 import { Icon, isIcon } from "./icon";

@Component({
  selector: "bit-icon",
+  host: {
+    "[attr.aria-hidden]": "!ariaLabel",
+    "[attr.aria-label]": "ariaLabel",
+    "[innerHtml]": "innerHtml",
+  },
  template: ``,
  standalone: true,
 })
 export class BitIconComponent {
+  innerHtml: SafeHtml | null = null;
+
  @Input() set icon(icon: Icon) {
    if (!isIcon(icon)) {
-      this.innerHtml = "";
      return;
    }

@@ -21,7 +25,7 @@ export class BitIconComponent {
    this.innerHtml = this.domSanitizer.bypassSecurityTrustHtml(svg);
  }

-  @HostBinding() innerHtml: SafeHtml;
+  @Input() ariaLabel: string | undefined = undefined;

  constructor(private domSanitizer: DomSanitizer) {}
 }
--- a/libs/components/src/icon/icon.mdx
+++ b/libs/components/src/icon/icon.mdx
@@ -98,9 +98,19 @@ import * as stories from "./icon.stories";
       ```

     - **HTML:**
+
+       > NOTE: SVG icons are treated as decorative by default and will be `aria-hidden` unless an
+       > `ariaLabel` is explicitly provided to the `<bit-icon>` component
+
       ```html
       <bit-icon [icon]="Icons.ExampleIcon"></bit-icon>
       ```

+       With `ariaLabel`
+
+       ```html
+       <bit-icon [icon]="Icons.ExampleIcon" [ariaLabel]="Your custom label text here"></bit-icon>
+       ```
+
 8. **Ensure your SVG renders properly** according to Figma in both light and dark modes on a client
   which supports multiple style modes.
--- a/libs/components/src/icon/icon.stories.ts
+++ b/libs/components/src/icon/icon.stories.ts
@@ -26,5 +26,9 @@ export const Default: Story = {
      mapping: GenericIcons,
      control: { type: "select" },
    },
+    ariaLabel: {
+      control: "text",
+      description: "the text used by a screen reader to describe the icon",
+    },
  },
 };