From cbab354c0eaecc461c33f6d616fcc212b519bca2 Mon Sep 17 00:00:00 2001
From: Bryan Cunningham <bcunningham@bitwarden.com>
Date: Fri, 18 Apr 2025 10:38:19 -0400
Subject: [PATCH] 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
---
 apps/browser/src/_locales/en/messages.json         |  3 +++
 .../extension-anon-layout-wrapper.component.html   |  7 ++++++-
 .../extension-anon-layout-wrapper.component.ts     |  2 ++
 .../accept-family-sponsorship.component.html       |  3 ++-
 apps/web/src/locales/en/messages.json              |  3 +++
 .../manage/accept-provider.component.html          |  6 +++++-
 .../providers/setup/setup-provider.component.html  |  6 +++++-
 .../setup/setup-business-unit.component.html       |  6 +++++-
 .../angular/anon-layout/anon-layout.component.html |  2 +-
 libs/components/src/icon/icon.component.ts         | 14 +++++++++-----
 libs/components/src/icon/icon.mdx                  | 10 ++++++++++
 libs/components/src/icon/icon.stories.ts           |  4 ++++
 12 files changed, 55 insertions(+), 11 deletions(-)

diff --git a/apps/browser/src/_locales/en/messages.json b/apps/browser/src/_locales/en/messages.json
index 87b94650b5..b0f3fb5d19 100644
--- 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)"
diff --git 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
index 54cb5203a8..bd2886dacf 100644
--- 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>
diff --git 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
index 51dbb6503d..d6cccf31bb 100644
--- 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,
diff --git 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
index fdbb6dbba9..ca1264829b 100644
--- 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"
diff --git a/apps/web/src/locales/en/messages.json b/apps/web/src/locales/en/messages.json
index 3d6cf0f23a..56a98a661e 100644
--- 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"
   },
diff --git 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
index 30cd7fec8f..3892892a9c 100644
--- 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"
diff --git 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
index 1fa2fd3415..cb8eaea80c 100644
--- 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"
diff --git 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
index e269aeb6d4..3d074906f2 100644
--- 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"
diff --git a/libs/auth/src/angular/anon-layout/anon-layout.component.html b/libs/auth/src/angular/anon-layout/anon-layout.component.html
index f31a5500b4..1e16dba82c 100644
--- 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
diff --git a/libs/components/src/icon/icon.component.ts b/libs/components/src/icon/icon.component.ts
index 2382d197be..08fa25956d 100644
--- 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) {}
 }
diff --git a/libs/components/src/icon/icon.mdx b/libs/components/src/icon/icon.mdx
index fc1c4cd3d5..6435fc2494 100644
--- 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.
diff --git a/libs/components/src/icon/icon.stories.ts b/libs/components/src/icon/icon.stories.ts
index 53454567b7..7892bdd3ec 100644
--- 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",
+    },
   },
 };