From 589be40cb68c41bd981dcbc8c355f5a52414075b Mon Sep 17 00:00:00 2001
From: Jay Gindin <jgindin@google.com>
Date: Mon, 15 Jun 2026 11:59:45 -0400
Subject: [PATCH] Fix accessibility labels, interactive overlays, and
 decorative icons

- Add accessible aria-label attributes to matInput elements across
  the application to assist screen reader navigation.
- Attach structural role="button" and tabindex="0" attributes to the
  interactive pipeline dismiss overlay in the chat panel.
- Apply aria-hidden="true" to 10 purely decorative Material icons
  across the chat panel, debug errors, settings, composer shell, and
  workspace dashboard to prevent redundant voiceover announcements.
---
 .../app/chat/chat-panel/chat-panel.ng.html    | 20 ++++++---
 .../app/chat/chat-panel/chat-panel.spec.ts    | 41 ++++++++++++++++++-
 .../chat-panel/test/chat-panel.harness.ts     | 19 +++++++++
 .../app/debug/data-model/data-model.ng.html   |  1 +
 .../app/debug/data-model/data-model.spec.ts   |  8 ++++
 shell/src/app/debug/errors/errors.ng.html     |  2 +-
 shell/src/app/debug/errors/errors.spec.ts     | 18 ++++++++
 .../app/debug/errors/test/errors.harness.ts   |  5 +++
 shell/src/app/preview/raw/raw-frame.ng.html   |  1 +
 shell/src/app/preview/raw/raw-frame.spec.ts   |  9 ++++
 .../settings/settings-view/settings.ng.html   |  8 ++--
 .../settings/settings-view/settings.spec.ts   | 13 ++++++
 .../settings-view/test/settings.harness.ts    |  5 +++
 .../composer-shell/composer-shell.ng.html     |  4 +-
 .../composer-shell/composer-shell.spec.ts     |  8 ++++
 .../test/composer-shell.harness.ts            |  5 +++
 .../composer-workspace.ng.html                |  4 +-
 .../composer-workspace.spec.ts                |  8 ++++
 .../test/composer-workspace.harness.ts        |  5 +++
 19 files changed, 168 insertions(+), 16 deletions(-)

diff --git a/shell/src/app/chat/chat-panel/chat-panel.ng.html b/shell/src/app/chat/chat-panel/chat-panel.ng.html
index 8ee8275c..451bd705 100644
--- a/shell/src/app/chat/chat-panel/chat-panel.ng.html
+++ b/shell/src/app/chat/chat-panel/chat-panel.ng.html
@@ -16,12 +16,19 @@
 
 <div class="preview-frame-container">
   <!-- Loading/progress overlays status graphics panel -->
-  @if (
-    pipelineStatus() !== 'idle' && pipelineStatus() !== 'ready' && pipelineStatus() !== 'failed'
-  ) {
-    <div class="pipeline-overlay" [class]="pipelineStatus()" (click)="dismissOverlay()">
+  @if (pipelineStatus() !== 'idle' && pipelineStatus() !== 'ready') {
+    <div
+      class="pipeline-overlay"
+      [class]="pipelineStatus()"
+      (click)="dismissOverlay()"
+      (keydown.enter)="dismissOverlay()"
+      (keydown.space)="$event.preventDefault(); dismissOverlay()"
+      role="button"
+      tabindex="0"
+      aria-label="Dismiss status overlay"
+    >
       @if (pipelineStatus() === 'failed') {
-        <mat-icon class="status-icon error-icon">error</mat-icon>
+        <mat-icon class="status-icon error-icon" aria-hidden="true">error</mat-icon>
       } @else {
         <mat-spinner [diameter]="40"></mat-spinner>
       }
@@ -71,7 +78,7 @@
                     [disabled]="isLocked()"
                     (click)="retryPrompt(turn.originalPrompt || '')"
                   >
-                    <mat-icon>refresh</mat-icon>
+                    <mat-icon aria-hidden="true">refresh</mat-icon>
                     Retry Request
                   </button>
                 </div>
@@ -88,6 +95,7 @@
     <mat-form-field appearance="outline" subscriptSizing="dynamic" class="prompt-form-field">
       <textarea
         matInput
+        aria-label="Chat prompt"
         [ngModel]="userPrompt()"
         (ngModelChange)="userPrompt.set($event)"
         [disabled]="isLocked()"
diff --git a/shell/src/app/chat/chat-panel/chat-panel.spec.ts b/shell/src/app/chat/chat-panel/chat-panel.spec.ts
index 276ba822..ed194993 100644
--- a/shell/src/app/chat/chat-panel/chat-panel.spec.ts
+++ b/shell/src/app/chat/chat-panel/chat-panel.spec.ts
@@ -29,6 +29,7 @@ import {PipelineStatus} from '../pipeline-status/pipeline-status';
 import {provideNoopAnimations} from '@angular/platform-browser/animations';
 import {CatalogManagement} from '../../storage/catalog-management/catalog-management';
 import {MatDialogHarness} from '@angular/material/dialog/testing';
+import {MatInputHarness} from '@angular/material/input/testing';
 import {Catalog} from '../../storage/models/catalog-storage.model';
 
 class MockChatState {
@@ -347,10 +348,10 @@ describe('ChatPanel Gemini Dialogue Panel Integration', () => {
       fixture.detectChanges();
       expect(await harness.hasLoadingOverlay()).toBe(false);
 
-      // Milestone 6: Aborted/Failed turns (overlay is NOT shown, allowing sidebar to be interactive)
+      // Milestone 6: Aborted/Failed turns (overlay is shown with error status)
       chatStateMock.pipelineStatus.set(PipelineStatus.FAILED);
       fixture.detectChanges();
-      expect(await harness.hasLoadingOverlay()).toBe(false);
+      expect(await harness.hasLoadingOverlay()).toBe(true);
     },
   );
 
@@ -384,4 +385,40 @@ describe('ChatPanel Gemini Dialogue Panel Integration', () => {
     // Send button must now be enabled
     expect(await harness.isSubmitDisabled()).toBe(false);
   });
+
+  it('applies the accessible name "Chat prompt" to the prompt textarea', async () => {
+    const loader = TestbedHarnessEnvironment.loader(fixture);
+    const input = await loader.getHarness(MatInputHarness);
+    const host = await input.host();
+    expect(await host.getAttribute('aria-label')).toBe('Chat prompt');
+  });
+
+  it('attaches structural accessibility attributes (role, tabindex, aria-label) to the pipeline dismiss overlay', async () => {
+    chatStateMock.pipelineStatus.set(PipelineStatus.RECEIVING_STREAM);
+    fixture.detectChanges();
+
+    const attrs = await harness.getPipelineOverlayAttributes();
+    expect(attrs.role).toBe('button');
+    expect(attrs.tabindex).toBe('0');
+    expect(attrs.ariaLabel).toBe('Dismiss status overlay');
+  });
+
+  it('applies aria-hidden attribute to purely decorative MatIcon elements across the chat panel', async () => {
+    const historyMocks: LlmMessage[] = [
+      {
+        role: MessageRole.ERROR,
+        content: 'error',
+        isRetryable: true,
+        originalPrompt: 'prompt',
+      },
+    ];
+    chatStateMock.chatHistory.set(historyMocks);
+    fixture.detectChanges();
+
+    const hiddenAttrs = await harness.getIconsAriaHidden();
+    expect(hiddenAttrs.length).toBeGreaterThan(0);
+    hiddenAttrs.forEach(attr => {
+      expect(attr).toBe('true');
+    });
+  });
 });
diff --git a/shell/src/app/chat/chat-panel/test/chat-panel.harness.ts b/shell/src/app/chat/chat-panel/test/chat-panel.harness.ts
index 208d29a5..db869aee 100644
--- a/shell/src/app/chat/chat-panel/test/chat-panel.harness.ts
+++ b/shell/src/app/chat/chat-panel/test/chat-panel.harness.ts
@@ -166,4 +166,23 @@ export class ChatPanelHarness extends ComponentHarness {
     }
     await buttons[index].click();
   }
+
+  async getPipelineOverlayAttributes(): Promise<{
+    role: string | null;
+    tabindex: string | null;
+    ariaLabel: string | null;
+  }> {
+    const overlay = await this.locatorForOptional('.pipeline-overlay')();
+    if (!overlay) return {role: null, tabindex: null, ariaLabel: null};
+    return {
+      role: await overlay.getAttribute('role'),
+      tabindex: await overlay.getAttribute('tabindex'),
+      ariaLabel: await overlay.getAttribute('aria-label'),
+    };
+  }
+
+  async getIconsAriaHidden(): Promise<(string | null)[]> {
+    const icons = await this.locatorForAll('mat-icon')();
+    return Promise.all(icons.map(i => i.getAttribute('aria-hidden')));
+  }
 }
diff --git a/shell/src/app/debug/data-model/data-model.ng.html b/shell/src/app/debug/data-model/data-model.ng.html
index dbf8b37d..7a7a18e3 100644
--- a/shell/src/app/debug/data-model/data-model.ng.html
+++ b/shell/src/app/debug/data-model/data-model.ng.html
@@ -21,6 +21,7 @@
   <mat-form-field appearance="outline" subscriptSizing="dynamic" class="data-model-field">
     <textarea
       matInput
+      aria-label="Data model JSON"
       [ngModel]="dataModelJson()"
       (ngModelChange)="dataModelJson.set($event)"
       placeholder="Enter data model JSON here..."
diff --git a/shell/src/app/debug/data-model/data-model.spec.ts b/shell/src/app/debug/data-model/data-model.spec.ts
index 63822fc9..e94c980c 100644
--- a/shell/src/app/debug/data-model/data-model.spec.ts
+++ b/shell/src/app/debug/data-model/data-model.spec.ts
@@ -21,6 +21,7 @@ import {signal, WritableSignal} from '@angular/core';
 import {describe, it, expect, beforeEach, vi, afterEach} from 'vitest';
 import {DataModel} from './data-model';
 import {DataModelHarness} from './test/data-model.harness';
+import {MatInputHarness} from '@angular/material/input/testing';
 import {
   HostCommunication,
   MessageEnvelope,
@@ -173,4 +174,11 @@ describe('DataModel', () => {
 
     expect(await harness.getModelText()).toBe('');
   });
+
+  it('applies the accessible name "Data model JSON" to the data model textarea', async () => {
+    const loader = TestbedHarnessEnvironment.loader(fixture);
+    const input = await loader.getHarness(MatInputHarness);
+    const host = await input.host();
+    expect(await host.getAttribute('aria-label')).toBe('Data model JSON');
+  });
 });
diff --git a/shell/src/app/debug/errors/errors.ng.html b/shell/src/app/debug/errors/errors.ng.html
index c333c7cd..834ac9f2 100644
--- a/shell/src/app/debug/errors/errors.ng.html
+++ b/shell/src/app/debug/errors/errors.ng.html
@@ -51,7 +51,7 @@
                 (click)="toggleRow(element); $event.stopPropagation()"
                 aria-label="Toggle Stack Trace"
               >
-                <mat-icon>{{
+                <mat-icon aria-hidden="true">{{
                   isRowExpanded(element) ? 'keyboard_arrow_up' : 'keyboard_arrow_down'
                 }}</mat-icon>
               </button>
diff --git a/shell/src/app/debug/errors/errors.spec.ts b/shell/src/app/debug/errors/errors.spec.ts
index 5ed38015..a50cd642 100644
--- a/shell/src/app/debug/errors/errors.spec.ts
+++ b/shell/src/app/debug/errors/errors.spec.ts
@@ -277,4 +277,22 @@ describe('Errors', () => {
     expect(await harness.hasPlaceholder()).toBe(true);
     expect(fixture.componentInstance.expandedRows().size).toBe(0);
   });
+
+  it('applies aria-hidden attribute to the purely decorative MatIcon element inside stack toggle buttons', async () => {
+    mockMessageStream.set({
+      type: PreviewBridgeMessageType.CONSOLE_LOG,
+      payload: {
+        level: 'error',
+        message: 'Exception with stack',
+        stack: 'Stack trace details here\n  at file.ts:10',
+      },
+      origin: 'http://localhost',
+      timestamp: Date.now(),
+    });
+    fixture.detectChanges();
+
+    const hiddenAttrs = await harness.getIconsAriaHidden();
+    expect(hiddenAttrs.length).toBe(1);
+    expect(hiddenAttrs[0]).toBe('true');
+  });
 });
diff --git a/shell/src/app/debug/errors/test/errors.harness.ts b/shell/src/app/debug/errors/test/errors.harness.ts
index 2d74449d..a1d8b80b 100644
--- a/shell/src/app/debug/errors/test/errors.harness.ts
+++ b/shell/src/app/debug/errors/test/errors.harness.ts
@@ -83,4 +83,9 @@ export class ErrorsHarness extends ComponentHarness {
     }
     return list[index].text();
   }
+
+  async getIconsAriaHidden(): Promise<(string | null)[]> {
+    const icons = await this.locatorForAll('mat-icon')();
+    return Promise.all(icons.map(i => i.getAttribute('aria-hidden')));
+  }
 }
diff --git a/shell/src/app/preview/raw/raw-frame.ng.html b/shell/src/app/preview/raw/raw-frame.ng.html
index 5edbbdc1..def1d33f 100644
--- a/shell/src/app/preview/raw/raw-frame.ng.html
+++ b/shell/src/app/preview/raw/raw-frame.ng.html
@@ -24,6 +24,7 @@
   <mat-form-field appearance="outline" subscriptSizing="dynamic" class="raw-json-field">
     <textarea
       matInput
+      aria-label="Raw layout JSON"
       [ngModel]="layoutJson()"
       (ngModelChange)="onLayoutChange($event)"
       [readOnly]="isLocked()"
diff --git a/shell/src/app/preview/raw/raw-frame.spec.ts b/shell/src/app/preview/raw/raw-frame.spec.ts
index d7c47ca5..f2f5410e 100644
--- a/shell/src/app/preview/raw/raw-frame.spec.ts
+++ b/shell/src/app/preview/raw/raw-frame.spec.ts
@@ -18,6 +18,7 @@ import {TestBed} from '@angular/core/testing';
 import {RawFrame} from './raw-frame';
 import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
 import {RawFrameHarness} from './test/raw-frame.harness';
+import {MatInputHarness} from '@angular/material/input/testing';
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {provideNoopAnimations} from '@angular/platform-browser/animations';
 import {IS_EXTENSION_MODE} from '../../shell/environment-tokens/environment-tokens';
@@ -303,4 +304,12 @@ describe('RawFrame JSON Source Editor View', () => {
     fixture.detectChanges();
     expect(await harness.isReadOnly()).toBe(false);
   });
+
+  it('applies the accessible name "Raw layout JSON" to the raw layout textarea', async () => {
+    const {fixture} = await setup(false);
+    const loader = TestbedHarnessEnvironment.loader(fixture);
+    const input = await loader.getHarness(MatInputHarness);
+    const host = await input.host();
+    expect(await host.getAttribute('aria-label')).toBe('Raw layout JSON');
+  });
 });
diff --git a/shell/src/app/settings/settings-view/settings.ng.html b/shell/src/app/settings/settings-view/settings.ng.html
index b3777040..2c0b6362 100644
--- a/shell/src/app/settings/settings-view/settings.ng.html
+++ b/shell/src/app/settings/settings-view/settings.ng.html
@@ -25,7 +25,7 @@
           <h3>Renderer Application URL</h3>
           @if (isLocked()) {
             <div class="locked-notice">
-              <mat-icon color="warn">lock</mat-icon>
+              <mat-icon color="warn" aria-hidden="true">lock</mat-icon>
               <span
                 >Active URL configuration is locked by enterprise policy (allowOverrides:
                 false).</span
@@ -73,7 +73,9 @@ <h3>Gemini API Provisioning</h3>
                 (click)="hideApiKey.set(!hideApiKey())"
                 [attr.aria-label]="hideApiKey() ? 'Show API key' : 'Hide API key'"
               >
-                <mat-icon>{{ hideApiKey() ? 'visibility' : 'visibility_off' }}</mat-icon>
+                <mat-icon aria-hidden="true">{{
+                  hideApiKey() ? 'visibility' : 'visibility_off'
+                }}</mat-icon>
               </button>
               @if (settingsForm.controls.apiKey.hasError('required')) {
                 <mat-error>Gemini API key is required in external environments.</mat-error>
@@ -92,7 +94,7 @@ <h3>Developer Authentication Overrides</h3>
           </p>
           @if (isLocked()) {
             <div class="locked-notice auth-locked-notice">
-              <mat-icon color="warn">lock</mat-icon>
+              <mat-icon color="warn" aria-hidden="true">lock</mat-icon>
               <span>Authentication mode overrides are locked by enterprise policy.</span>
             </div>
           }
diff --git a/shell/src/app/settings/settings-view/settings.spec.ts b/shell/src/app/settings/settings-view/settings.spec.ts
index 935a0c40..d46d8850 100644
--- a/shell/src/app/settings/settings-view/settings.spec.ts
+++ b/shell/src/app/settings/settings-view/settings.spec.ts
@@ -434,4 +434,17 @@ describe('Settings', () => {
 
     expect(locationAssign).toHaveBeenCalledWith(expect.anything(), '/');
   });
+
+  it('applies aria-hidden attribute to purely decorative MatIcon elements across settings', async () => {
+    mockStartupResolution.isContextLocked.mockReturnValue(true);
+    mockStartupResolution.isThirdPartyEnvironment.mockReturnValue(true);
+    const {fixture, harness} = await setupComponent();
+    fixture.detectChanges();
+
+    const hiddenAttrs = await harness.getIconsAriaHidden();
+    expect(hiddenAttrs.length).toBe(3);
+    hiddenAttrs.forEach(attr => {
+      expect(attr).toBe('true');
+    });
+  });
 });
diff --git a/shell/src/app/settings/settings-view/test/settings.harness.ts b/shell/src/app/settings/settings-view/test/settings.harness.ts
index 1f82199a..4d8c7047 100644
--- a/shell/src/app/settings/settings-view/test/settings.harness.ts
+++ b/shell/src/app/settings/settings-view/test/settings.harness.ts
@@ -168,4 +168,9 @@ export class SettingsHarness extends ComponentHarness {
     const chip = await this.getCatalogBadge();
     return chip.text();
   }
+
+  async getIconsAriaHidden(): Promise<(string | null)[]> {
+    const icons = await this.locatorForAll('mat-icon')();
+    return Promise.all(icons.map(i => i.getAttribute('aria-hidden')));
+  }
 }
diff --git a/shell/src/app/shell/composer-shell/composer-shell.ng.html b/shell/src/app/shell/composer-shell/composer-shell.ng.html
index 7e34482a..ad9c59ef 100644
--- a/shell/src/app/shell/composer-shell/composer-shell.ng.html
+++ b/shell/src/app/shell/composer-shell/composer-shell.ng.html
@@ -21,7 +21,7 @@
     (click)="sidenav.toggle()"
     aria-label="Toggle sidenav"
   >
-    <mat-icon>menu</mat-icon>
+    <mat-icon aria-hidden="true">menu</mat-icon>
   </button>
   <span class="header-title" [matTooltip]="activeCatalogDescription() || ''"
     >A2UI Composer{{ activeCatalogTitle() ? ' - ' + activeCatalogTitle() : '' }}</span
@@ -37,7 +37,7 @@
     (click)="toggleTheme()"
     [attr.aria-label]="isDarkTheme() ? 'Switch to light theme' : 'Switch to dark theme'"
   >
-    <mat-icon>{{ isDarkTheme() ? 'light_mode' : 'dark_mode' }}</mat-icon>
+    <mat-icon aria-hidden="true">{{ isDarkTheme() ? 'light_mode' : 'dark_mode' }}</mat-icon>
   </button>
 </mat-toolbar>
 
diff --git a/shell/src/app/shell/composer-shell/composer-shell.spec.ts b/shell/src/app/shell/composer-shell/composer-shell.spec.ts
index e0402f7a..2dc3df35 100644
--- a/shell/src/app/shell/composer-shell/composer-shell.spec.ts
+++ b/shell/src/app/shell/composer-shell/composer-shell.spec.ts
@@ -190,4 +190,12 @@ describe('ComposerShell Layout', () => {
     await harness.clickThemeToggleButton();
     expect(configProviderMock.setThemePreference).toHaveBeenCalledWith('light');
   });
+
+  it('applies aria-hidden attribute to purely decorative MatIcon elements across the composer shell', async () => {
+    const hiddenAttrs = await harness.getIconsAriaHidden();
+    expect(hiddenAttrs.length).toBe(2);
+    hiddenAttrs.forEach(attr => {
+      expect(attr).toBe('true');
+    });
+  });
 });
diff --git a/shell/src/app/shell/composer-shell/test/composer-shell.harness.ts b/shell/src/app/shell/composer-shell/test/composer-shell.harness.ts
index b415eaef..587cc38e 100644
--- a/shell/src/app/shell/composer-shell/test/composer-shell.harness.ts
+++ b/shell/src/app/shell/composer-shell/test/composer-shell.harness.ts
@@ -58,4 +58,9 @@ export class ComposerShellHarness extends ComponentHarness {
     const sidenav = await this.getSidenav();
     return sidenav.isOpen();
   }
+
+  async getIconsAriaHidden(): Promise<(string | null)[]> {
+    const icons = await this.locatorForAll('mat-icon')();
+    return Promise.all(icons.map(i => i.getAttribute('aria-hidden')));
+  }
 }
diff --git a/shell/src/app/shell/composer-workspace/composer-workspace.ng.html b/shell/src/app/shell/composer-workspace/composer-workspace.ng.html
index 6b35a7d7..c1426108 100644
--- a/shell/src/app/shell/composer-workspace/composer-workspace.ng.html
+++ b/shell/src/app/shell/composer-workspace/composer-workspace.ng.html
@@ -46,7 +46,7 @@
           matTooltip="Clear all log tabs"
           matTooltipPosition="left"
         >
-          <mat-icon>delete</mat-icon>
+          <mat-icon aria-hidden="true">delete</mat-icon>
         </button>
         <button
           mat-icon-button
@@ -55,7 +55,7 @@
           [matTooltip]="isDebugCollapsed() ? 'Expand Debug Panel' : 'Collapse Debug Panel'"
           matTooltipPosition="left"
         >
-          <mat-icon>{{
+          <mat-icon aria-hidden="true">{{
             isDebugCollapsed() ? 'keyboard_arrow_up' : 'keyboard_arrow_down'
           }}</mat-icon>
         </button>
diff --git a/shell/src/app/shell/composer-workspace/composer-workspace.spec.ts b/shell/src/app/shell/composer-workspace/composer-workspace.spec.ts
index d487a540..7717ae9d 100644
--- a/shell/src/app/shell/composer-workspace/composer-workspace.spec.ts
+++ b/shell/src/app/shell/composer-workspace/composer-workspace.spec.ts
@@ -353,4 +353,12 @@ describe('ComposerWorkspace Dashboard', () => {
       expect(await newHarness.isDebugSectionCollapsed()).toBe(true);
     },
   );
+
+  it('applies aria-hidden attribute to purely decorative MatIcon elements across the workspace header controls', async () => {
+    const hiddenAttrs = await harness.getIconsAriaHidden();
+    expect(hiddenAttrs.length).toBe(2);
+    hiddenAttrs.forEach(attr => {
+      expect(attr).toBe('true');
+    });
+  });
 });
diff --git a/shell/src/app/shell/composer-workspace/test/composer-workspace.harness.ts b/shell/src/app/shell/composer-workspace/test/composer-workspace.harness.ts
index b44622c0..9ea15e58 100644
--- a/shell/src/app/shell/composer-workspace/test/composer-workspace.harness.ts
+++ b/shell/src/app/shell/composer-workspace/test/composer-workspace.harness.ts
@@ -51,4 +51,9 @@ export class ComposerWorkspaceHarness extends ComponentHarness {
     const section = await this.locatorFor('.debug-section')();
     return section.hasClass('collapsed');
   }
+
+  async getIconsAriaHidden(): Promise<(string | null)[]> {
+    const icons = await this.locatorForAll('.debug-header-controls mat-icon')();
+    return Promise.all(icons.map(i => i.getAttribute('aria-hidden')));
+  }
 }