From a8d98c7cf2ad8dc0581668674c991b99cb27b853 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Monda?= <laci@monda.hu>
Date: Sun, 16 Aug 2026 17:09:39 +0200
Subject: [PATCH 1/3] fix: make keymap SVG keys findable with VoiceOver

Name keys by physical QWERTY position plus current mapping, and hide off-screen layers and the remap overlay from the accessibility tree so icon-only and unmapped keys remain searchable.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../slider/keyboard-slider.component.html     |   4 +
 .../components/popover/popover.component.html |   2 +-
 .../svg/keyboard/svg-keyboard.component.html  |   1 +
 .../svg-icon-text-key.component.html          |   1 +
 .../svg-keyboard-key.component.html           |   4 +
 .../svg-keyboard-key.component.scss           |   8 +
 .../svg-keyboard-key.component.ts             |  85 +++------
 .../svg-keystroke-key.component.html          |   6 +-
 .../svg-mouse-click-key.html                  |   2 +-
 .../svg-mouse-move-key.html                   |   4 +-
 .../svg-mouse-scroll-key.html                 |   4 +-
 .../svg-mouse-speed-key.html                  |   2 +-
 .../svg-single-icon-key.component.html        |   1 +
 .../svg-switch-keymap-key.component.html      |   1 +
 .../svg-text-icon-key.component.html          |   1 +
 .../svg/module/svg-module.component.html      |   3 +
 .../svg/module/svg-module.component.ts        |  44 +++--
 .../svg/wrap/svg-keyboard-wrap.component.html |  12 +-
 .../util/build-key-accessible-label.test.ts   | 175 ++++++++++++++++++
 .../app/util/build-key-accessible-label.ts    | 112 +++++++++++
 20 files changed, 388 insertions(+), 84 deletions(-)
 create mode 100644 packages/uhk-web/src/app/util/build-key-accessible-label.test.ts
 create mode 100644 packages/uhk-web/src/app/util/build-key-accessible-label.ts

diff --git a/packages/uhk-web/src/app/components/keyboard/slider/keyboard-slider.component.html b/packages/uhk-web/src/app/components/keyboard/slider/keyboard-slider.component.html
index 58e0c1d6a49..039f9867cbd 100644
--- a/packages/uhk-web/src/app/components/keyboard/slider/keyboard-slider.component.html
+++ b/packages/uhk-web/src/app/components/keyboard/slider/keyboard-slider.component.html
@@ -1,5 +1,7 @@
 <svg-keyboard [ngClass]="aLayerCssClasses"
               id="svg-keyboard-a"
+              [attr.aria-hidden]="visibleLayerName === LayerNames.A ? null : true"
+              [attr.inert]="visibleLayerName === LayerNames.A ? null : ''"
               [attr.isKeyboardVisible]="visibleLayerName === LayerNames.A"
               [attr.layerId]="aLayer.id"
               [backlightingMode]="backlightingMode"
@@ -24,6 +26,8 @@
 
 <svg-keyboard *ngIf="bLayer"
               id="svg-keyboard-b"
+              [attr.aria-hidden]="visibleLayerName === LayerNames.B ? null : true"
+              [attr.inert]="visibleLayerName === LayerNames.B ? null : ''"
               [attr.isKeyboardVisible]="visibleLayerName === LayerNames.B"
               [attr.layerId]="bLayer.id"
               [backlightingMode]="backlightingMode"
diff --git a/packages/uhk-web/src/app/components/popover/popover.component.html b/packages/uhk-web/src/app/components/popover/popover.component.html
index af640462081..45cd2846294 100644
--- a/packages/uhk-web/src/app/components/popover/popover.component.html
+++ b/packages/uhk-web/src/app/components/popover/popover.component.html
@@ -139,7 +139,7 @@
                     (click)="toggleNote(noteTooltipRef)">
                 <fa-icon [icon]="faNoteSticky" aria-hidden="true"></fa-icon>
             </button>
-            <button class="btn btn-sm btn-default me-2" type="button" (click)="onCancelClick()"> Cancel</button>
+            <button class="btn btn-sm btn-default me-2" type="button" (click)="onCancelClick()">Cancel</button>
             <button class="btn btn-sm btn-primary" [class.disabled]="!keyActionValid" type="button"
                     (click)="onRemapKey()"> Remap key
             </button>
diff --git a/packages/uhk-web/src/app/components/svg/keyboard/svg-keyboard.component.html b/packages/uhk-web/src/app/components/svg/keyboard/svg-keyboard.component.html
index 7fc73c11797..92595740b32 100644
--- a/packages/uhk-web/src/app/components/svg/keyboard/svg-keyboard.component.html
+++ b/packages/uhk-web/src/app/components/svg/keyboard/svg-keyboard.component.html
@@ -14,6 +14,7 @@
            [capturingEnabled]="capturingEnabled"
            [attr.transform]="module.attributes.transform"
            [keyActions]="getKeyActions(module.id)"
+           [moduleId]="module.id"
            [moduleNavCircle]="module.moduleNavCircle"
            [moduleNavPath]="module.moduleNavPath"
            [selectedKey]="selectedKey"
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-icon-text-key/svg-icon-text-key.component.html b/packages/uhk-web/src/app/components/svg/keys/svg-icon-text-key/svg-icon-text-key.component.html
index 59f52a96254..3927b1ac0db 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-icon-text-key/svg-icon-text-key.component.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-icon-text-key/svg-icon-text-key.component.html
@@ -3,6 +3,7 @@
         [attr.height]="useHeight"
         [attr.x]="useX"
         [attr.y]="useY"
+         aria-hidden="true"
          stroke-width="0"
 >
 </svg:use>
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.html b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.html
index 872cd701b4d..4607b90f315 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.html
@@ -1,3 +1,4 @@
+<svg:title>{{ accessibleLabel }}</svg:title>
 <svg:rect #svgRec
           *ngIf="svgKey.type === 'rec'"
           class="svg-rec"
@@ -39,6 +40,9 @@
 </svg:g>
 
 <svg:g [attr.transform]="calcTransform()">
+<svg:text class="svg-keyboard-key__accessible-name"
+          [attr.x]="(svgKey?.width || 0) / 2"
+          [attr.y]="(svgKey?.height || 0) / 2">{{ accessibleLabel }}</svg:text>
 <svg:path *ngIf="hasNote && svgKey.width"
           class="note-marker"
           [attr.d]="noteMarkerPath"
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss
index 767676f32a0..85f5555a230 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss
@@ -13,3 +13,11 @@
     fill: var(--color-keyboard-key-note-marker);
     pointer-events: none;
 }
+
+.svg-keyboard-key__accessible-name {
+    fill: currentColor;
+    font-size: 1px;
+    opacity: 0.01;
+    pointer-events: none;
+    stroke: none;
+}
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.ts b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.ts
index 325e44f2b92..ee7cb204d48 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.ts
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.ts
@@ -38,7 +38,8 @@ import {
     PlayMacroAction,
     SwitchKeymapAction,
     SwitchLayerAction,
-    SwitchLayerMode
+    SwitchLayerMode,
+    UserConfiguration,
 } from 'uhk-common';
 
 import { CaptureService } from '../../../../services/capture.service';
@@ -53,8 +54,10 @@ import { KeyModifierModel } from '../../../../models/key-modifier-model';
 import { LastEditedKey } from '../../../../models/last-edited-key';
 import { StartKeypressCapturingAction, StopKeypressCapturingAction } from '../../../../store/actions/app';
 import { KeyActionDragAndDropService } from '../../../../services/key-action-drag-and-drop.service';
+import { buildKeyAccessibleLabel } from '../../../../util/build-key-accessible-label';
 import { getColorsOf } from '../../../../util/get-colors-of';
 import { defaultUhkThemeColors } from '../../../../util/default-uhk-theme-colors';
+import { getDefaultQwertyKeyLabel } from '../../../../util/get-default-key-label';
 import { keyboardGreyRgbColor } from '../../../../util/rgb-color-contants';
 import { SvgKeyboardKey } from './svg-keyboard-key.model';
 
@@ -108,9 +111,12 @@ export class SvgKeyboardKeyComponent implements OnChanges, OnDestroy {
     @Input() isActive = false;
     @Input() hostConnections: HostConnection[] = [];
     @Input() keyAction: KeyAction;
+    @Input() keyId = 0;
     @Input() svgKey: SvgKeyboardKey;
     @Input() capturingEnabled: boolean;
+    @Input() defaultUserConfiguration = new UserConfiguration();
     @Input() macroMap = new Map<number, Macro>();
+    @Input() moduleId = 0;
     @Input() lastEdited: boolean;
     @Input() lastEditedKey: LastEditedKey;
 
@@ -364,7 +370,11 @@ export class SvgKeyboardKeyComponent implements OnChanges, OnDestroy {
     }
 
     ngOnChanges(changes: SimpleChanges) {
-        if (changes['keyAction']) {
+        if (changes['keyAction']
+            || changes['defaultUserConfiguration']
+            || changes['keyId']
+            || changes['macroMap']
+            || changes['moduleId']) {
             this.setLabels();
         }
 
@@ -472,9 +482,9 @@ export class SvgKeyboardKeyComponent implements OnChanges, OnDestroy {
         this.labelType = LabelTypes.OneLineText;
         this.labelSource = undefined;
         this.secondaryText = undefined;
-        this.accessibleLabel = 'Unassigned key';
 
         if (!this.keyAction) {
+            this.updateAccessibleLabel();
             return;
         }
 
@@ -630,7 +640,7 @@ export class SvgKeyboardKeyComponent implements OnChanges, OnDestroy {
             this.labelSource = undefined;
         }
 
-        this.accessibleLabel = this.buildAccessibleLabel();
+        this.updateAccessibleLabel();
     }
 
     private blinkSvgRec(): void {
@@ -685,59 +695,20 @@ export class SvgKeyboardKeyComponent implements OnChanges, OnDestroy {
         }
     }
 
-    private buildAccessibleLabel(): string {
-        if (!this.keyAction) {
-            return 'Unassigned key';
-        }
-
-        if (this.keyAction instanceof KeystrokeAction) {
-            const parts: string[] = [];
-
-            if (this.keyAction.hasActiveModifier()) {
-                parts.push(this.keyAction.getModifierList().join(' + '));
-            }
-
-            if (this.keyAction.hasScancode()) {
-                parts.push(this.mapper.scanCodeToText(this.keyAction.scancode, this.keyAction.type).join(' '));
-            }
-
-            if (parts.length === 0) {
-                parts.push('Keystroke');
-            }
-
-            if (this.keyAction.hasSecondaryRoleAction()) {
-                parts.push(`secondary role ${this.mapper.getSecondaryRoleText(this.keyAction.secondaryRoleAction)}`);
-            }
-
-            return parts.join(', ');
-        }
-
-        if (this.keyAction instanceof SwitchLayerAction) {
-            const layerName = this.layerOptionMap.get(this.keyAction.layer)?.name || 'unknown';
-            return `Switch to ${layerName} layer`;
-        }
-
-        if (this.keyAction instanceof SwitchKeymapAction) {
-            return `Switch to keymap ${this.keyAction.keymapAbbreviation}`;
-        }
-
-        if (this.keyAction instanceof PlayMacroAction) {
-            const macroName = this.macroMap.get(this.keyAction.macroId)?.name;
-            return macroName ? `Play macro ${macroName}` : 'Play macro';
-        }
-
-        if (this.keyAction instanceof MouseAction) {
-            return 'Mouse action';
-        }
-
-        if (this.keyAction instanceof ConnectionsAction) {
-            return 'Host connection action';
-        }
-
-        if (this.keyAction instanceof OtherAction) {
-            return 'Other action';
-        }
+    private updateAccessibleLabel(): void {
+        const physicalKeyLabel = getDefaultQwertyKeyLabel({
+            defaultUserConfiguration: this.defaultUserConfiguration,
+            keyId: this.keyId,
+            mapper: this.mapper,
+            moduleId: this.moduleId,
+        });
 
-        return 'Assigned key action';
+        this.accessibleLabel = buildKeyAccessibleLabel({
+            keyAction: this.keyAction,
+            layerOptionMap: this.layerOptionMap,
+            macroMap: this.macroMap,
+            mapper: this.mapper,
+            physicalKeyLabel,
+        });
     }
 }
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-keystroke-key/svg-keystroke-key.component.html b/packages/uhk-web/src/app/components/svg/keys/svg-keystroke-key/svg-keystroke-key.component.html
index 5000ce125ea..deb8bd1eba2 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-keystroke-key/svg-keystroke-key.component.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-keystroke-key/svg-keystroke-key.component.html
@@ -41,7 +41,7 @@
     [attr.y]="modifierContainer.y" preserveAspectRatio="none">
     <svg viewBox="0 0 100 100" [attr.width]="shift.width" [attr.height]="shift.height" [attr.x]="shift.x" [attr.y]="shift.y"
         preserveAspectRatio="none" [class.disabled]="shift.disabled">
-        <svg:use [attr.xlink:href]="modifierIconNames.shift" stroke="none"/>
+        <svg:use [attr.xlink:href]="modifierIconNames.shift" aria-hidden="true" stroke="none"/>
     </svg>
     <svg viewBox="0 0 100 100" [attr.width]="control.width" [attr.height]="control.height" [attr.x]="control.x" [attr.y]="control.y"
         preserveAspectRatio="none" [class.disabled]="control.disabled">
@@ -49,12 +49,12 @@
     </svg>
     <svg viewBox="0 0 100 100" [attr.width]="option.width" [attr.height]="option.height" [attr.x]="option.x" [attr.y]="option.y"
         preserveAspectRatio="none" [class.disabled]="option.disabled">
-        <svg:use *ngIf="modifierIconNames.option" [attr.xlink:href]="modifierIconNames.option" stroke="none"/>
+        <svg:use *ngIf="modifierIconNames.option" [attr.xlink:href]="modifierIconNames.option" aria-hidden="true" stroke="none"/>
         <svg:text *ngIf="!modifierIconNames.option" text-anchor="middle" alignment-baseline="middle" x="50" y="55" stroke="none">A</svg:text>
     </svg>
     <svg viewBox="0 0 100 100" [attr.width]="command.width" [attr.height]="command.height" [attr.x]="command.x" [attr.y]="command.y"
         preserveAspectRatio="none" [class.disabled]="command.disabled">
-        <svg:use *ngIf="modifierIconNames.command" [attr.xlink:href]="modifierIconNames.command" stroke="none"/>
+        <svg:use *ngIf="modifierIconNames.command" [attr.xlink:href]="modifierIconNames.command" aria-hidden="true" stroke="none"/>
         <svg:text *ngIf="!modifierIconNames.command" text-anchor="middle" alignment-baseline="middle" x="50" y="55" stroke="none">S</svg:text>
     </svg>
 </svg>
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-click-key/svg-mouse-click-key.html b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-click-key/svg-mouse-click-key.html
index 27dcab28b08..e98281ff59e 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-click-key/svg-mouse-click-key.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-click-key/svg-mouse-click-key.html
@@ -1,4 +1,4 @@
-<svg:use [attr.xlink:href]="icon" width="20" height="20" x="10" y="25">
+<svg:use [attr.xlink:href]="icon" width="20" height="20" x="10" y="25" aria-hidden="true">
 </svg:use>
 <svg:text
     [attr.x]="60"
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-move-key/svg-mouse-move-key.html b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-move-key/svg-mouse-move-key.html
index f626a040dc2..3d0f2ff0a75 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-move-key/svg-mouse-move-key.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-move-key/svg-mouse-move-key.html
@@ -1,4 +1,4 @@
-<svg:use [attr.xlink:href]="mouseIcon" width="20" height="20" x="8" y="25"></svg:use>
+<svg:use [attr.xlink:href]="mouseIcon" width="20" height="20" x="8" y="25" aria-hidden="true"></svg:use>
 <svg:text
     [attr.x]="60"
     [attr.y]="0"
@@ -7,4 +7,4 @@
     stroke="none">
         <tspan dy="45"> Move </tspan>
 </svg:text>
-<svg:use [attr.xlink:href]="directionIcon" width="30" height="30" x="35" y="55"></svg:use>
+<svg:use [attr.xlink:href]="directionIcon" width="30" height="30" x="35" y="55" aria-hidden="true"></svg:use>
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-scroll-key/svg-mouse-scroll-key.html b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-scroll-key/svg-mouse-scroll-key.html
index db0896bd698..56b22985c5b 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-scroll-key/svg-mouse-scroll-key.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-scroll-key/svg-mouse-scroll-key.html
@@ -1,4 +1,4 @@
-<svg:use [attr.xlink:href]="mouseIcon" width="20" height="20" x="8" y="25"></svg:use>
+<svg:use [attr.xlink:href]="mouseIcon" width="20" height="20" x="8" y="25" aria-hidden="true"></svg:use>
 <svg:text
     [attr.x]="60"
     [attr.y]="0"
@@ -7,4 +7,4 @@
     stroke="none">
         <tspan dy="45"> Scroll </tspan>
 </svg:text>
-<svg:use [attr.xlink:href]="directionIcon" width="30" height="30" x="35" y="55"></svg:use>
+<svg:use [attr.xlink:href]="directionIcon" width="30" height="30" x="35" y="55" aria-hidden="true"></svg:use>
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-speed-key/svg-mouse-speed-key.html b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-speed-key/svg-mouse-speed-key.html
index bb8542641cd..651a0db1ac5 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-mouse-speed-key/svg-mouse-speed-key.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-mouse-speed-key/svg-mouse-speed-key.html
@@ -1,4 +1,4 @@
-<svg:use [attr.xlink:href]="icon" width="20" height="20" x="4" y="25">
+<svg:use [attr.xlink:href]="icon" width="20" height="20" x="4" y="25" aria-hidden="true">
 </svg:use>
 <svg:text
     [attr.x]="60"
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-single-icon-key/svg-single-icon-key.component.html b/packages/uhk-web/src/app/components/svg/keys/svg-single-icon-key/svg-single-icon-key.component.html
index e0ebab521b2..f4bfb61d4f3 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-single-icon-key/svg-single-icon-key.component.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-single-icon-key/svg-single-icon-key.component.html
@@ -3,6 +3,7 @@
          [attr.height]="svgHeight"
          [attr.x]="svgX"
          [attr.y]="svgHeight"
+         aria-hidden="true"
          stroke="none">
 </svg:use>
 <svg:g svg-secondary-role
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-switch-keymap-key/svg-switch-keymap-key.component.html b/packages/uhk-web/src/app/components/svg/keys/svg-switch-keymap-key/svg-switch-keymap-key.component.html
index 9b8d4f8ec57..f5a82040d72 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-switch-keymap-key/svg-switch-keymap-key.component.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-switch-keymap-key/svg-switch-keymap-key.component.html
@@ -3,6 +3,7 @@
         [attr.height]="useHeight"
         [attr.x]="useX"
         [attr.y]="useY"
+         aria-hidden="true"
          stroke="none">
 </svg:use>
 <svg:text
diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-text-icon-key/svg-text-icon-key.component.html b/packages/uhk-web/src/app/components/svg/keys/svg-text-icon-key/svg-text-icon-key.component.html
index 6cf2f38d583..6572c95902d 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-text-icon-key/svg-text-icon-key.component.html
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-text-icon-key/svg-text-icon-key.component.html
@@ -12,6 +12,7 @@
         [attr.height]="useHeight"
         [attr.x]="useX"
         [attr.y]="useY"
+         aria-hidden="true"
          stroke-width="0"
 >
 </svg:use>
diff --git a/packages/uhk-web/src/app/components/svg/module/svg-module.component.html b/packages/uhk-web/src/app/components/svg/module/svg-module.component.html
index e4458480139..6084d808a62 100644
--- a/packages/uhk-web/src/app/components/svg/module/svg-module.component.html
+++ b/packages/uhk-web/src/app/components/svg/module/svg-module.component.html
@@ -26,11 +26,14 @@
             [id]="key.id"
             [svgKey]="key"
             [backlightingMode]="backlightingMode"
+            [defaultUserConfiguration]="defaultUserConfiguration"
             [isActive]="selected && i === selectedKey.keyId"
             [keyAction]="keyActions && keyActions[i]"
+            [keyId]="i"
             [capturingEnabled]="capturingEnabled"
             [hostConnections]="hostConnections"
             [macroMap]="macroMap"
+            [moduleId]="moduleId"
             [lastEdited]="lastEdited"
             [lastEditedKey]="lastEditedKey"
             (keyClick)="onKeyClick(i, $event)"
diff --git a/packages/uhk-web/src/app/components/svg/module/svg-module.component.ts b/packages/uhk-web/src/app/components/svg/module/svg-module.component.ts
index 2f28103c708..0eb24bcf007 100644
--- a/packages/uhk-web/src/app/components/svg/module/svg-module.component.ts
+++ b/packages/uhk-web/src/app/components/svg/module/svg-module.component.ts
@@ -1,14 +1,15 @@
 import {
+    ChangeDetectionStrategy,
+    ChangeDetectorRef,
     Component,
     EventEmitter,
     Input,
     OnDestroy,
     Output,
-    ChangeDetectionStrategy,
     inject,
 } from '@angular/core';
 import { Store } from '@ngrx/store';
-import { BacklightingMode, HostConnection, KeyAction, Macro, UhkThemeColors } from 'uhk-common';
+import { BacklightingMode, HostConnection, KeyAction, Macro, UhkThemeColors, UserConfiguration } from 'uhk-common';
 import { Subscription } from 'rxjs';
 
 import { LastEditedKey } from '../../../models/last-edited-key';
@@ -19,7 +20,7 @@ import {
     SvgModuleCaptureEvent,
     SvgModuleKeyClickEvent
 } from '../../../models/svg-key-events';
-import { AppState, getHostConnections, getMacroMap } from '../../../store';
+import { AppState, getDefaultUserConfiguration, getHostConnections, getMacroMap } from '../../../store';
 
 @Component({
     selector: 'g[svg-module]',
@@ -42,6 +43,7 @@ export class SvgModuleComponent implements OnDestroy {
     @Input() capturingEnabled: boolean;
     @Input() lastEdited: boolean;
     @Input() lastEditedKey: LastEditedKey;
+    @Input() moduleId = 0;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     @Input() moduleNavCircle: any;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -51,27 +53,37 @@ export class SvgModuleComponent implements OnDestroy {
     @Output() capture = new EventEmitter<SvgModuleCaptureEvent>();
     @Output() navigateToModuleSettings = new EventEmitter<void>();
 
-    hostConnections: HostConnection[] = []
-    macroMap: Map<number, Macro>;
-    private macroMapSubscription: Subscription;
-    private hostConnectionsSubscription: Subscription;
+    defaultUserConfiguration = new UserConfiguration();
+    hostConnections: HostConnection[] = [];
+    macroMap = new Map<number, Macro>();
+    private readonly subscriptions = new Subscription();
     private readonly store = inject<Store<AppState>>(Store);
+    private readonly cdRef = inject(ChangeDetectorRef);
 
     constructor() {
-        const store = this.store;
-
         this.keyboardKeys = [];
-        this.macroMapSubscription = store.select(getMacroMap)
-            .subscribe(map => this.macroMap = map);
-        this.hostConnectionsSubscription = this.store.select(getHostConnections)
-            .subscribe((connections: HostConnection[]) => {
+        this.subscriptions.add(
+            this.store.select(getMacroMap).subscribe(macroMap => {
+                this.macroMap = macroMap;
+                this.cdRef.markForCheck();
+            })
+        );
+        this.subscriptions.add(
+            this.store.select(getHostConnections).subscribe((connections: HostConnection[]) => {
                 this.hostConnections = connections;
-            });
+                this.cdRef.markForCheck();
+            })
+        );
+        this.subscriptions.add(
+            this.store.select(getDefaultUserConfiguration).subscribe(defaultUserConfiguration => {
+                this.defaultUserConfiguration = defaultUserConfiguration;
+                this.cdRef.markForCheck();
+            })
+        );
     }
 
     ngOnDestroy(): void {
-        this.macroMapSubscription.unsubscribe();
-        this.hostConnectionsSubscription?.unsubscribe();
+        this.subscriptions.unsubscribe();
     }
 
     onKeyClick(keyId: number, event: SvgKeyClickEvent): void {
diff --git a/packages/uhk-web/src/app/components/svg/wrap/svg-keyboard-wrap.component.html b/packages/uhk-web/src/app/components/svg/wrap/svg-keyboard-wrap.component.html
index 741d0851c51..b4aed534e2e 100644
--- a/packages/uhk-web/src/app/components/svg/wrap/svg-keyboard-wrap.component.html
+++ b/packages/uhk-web/src/app/components/svg/wrap/svg-keyboard-wrap.component.html
@@ -1,5 +1,7 @@
 <ng-template [ngIf]="layers">
     <layers [class.disabled]="animationState === 'opened'"
+            [attr.aria-hidden]="animationState === 'opened' ? true : null"
+            [attr.inert]="animationState === 'opened' ? '' : null"
             [allowLayerCopy]="allowLayerCopy"
             [allowNewLayers]="allowNewLayers"
             [canPasteLayer]="canPasteLayer"
@@ -20,6 +22,8 @@
             (toggleColorFromPalette)="toggleColorFromPalette.emit($event)"
     ></layers>
     <keyboard-slider id="keyboard-slider"
+                     [attr.aria-hidden]="animationState === 'opened' ? true : null"
+                     [attr.inert]="animationState === 'opened' ? '' : null"
                      [animationEnabled]="animationEnabled"
                      [backlightingMode]="backlightingMode"
                      [layers]="layers"
@@ -39,6 +43,9 @@
 
     <popover tabindex="0"
              autofocus
+             role="dialog"
+             aria-modal="true"
+             aria-label="Remap key"
              [@popover]="{ value:'', params: { animationTime: animationTime } }"
              *ngIf="animationState === 'opened'"
              [visible]="true"
@@ -70,5 +77,8 @@
             </p>
         </div>
     </div>
-    <div class="popover-overlay" [class.display]="animationState === 'opened'" (click)="cancelPopover()"></div>
+    <div class="popover-overlay"
+         aria-hidden="true"
+         [class.display]="animationState === 'opened'"
+         (click)="cancelPopover()"></div>
 </ng-template>
diff --git a/packages/uhk-web/src/app/util/build-key-accessible-label.test.ts b/packages/uhk-web/src/app/util/build-key-accessible-label.test.ts
new file mode 100644
index 00000000000..13fd12e20d6
--- /dev/null
+++ b/packages/uhk-web/src/app/util/build-key-accessible-label.test.ts
@@ -0,0 +1,175 @@
+import { describe, it } from 'node:test';
+
+import {
+    KeystrokeAction,
+    LayerName,
+    Macro,
+    NoneAction,
+    PlayMacroAction,
+    SecondaryRoleAction,
+    SwitchLayerAction,
+} from 'uhk-common';
+
+import {
+    buildKeyAccessibleLabel,
+    combinePhysicalAndActionLabel,
+    KeyAccessibleLabelMapper,
+} from './build-key-accessible-label.js';
+
+function createMapper(): KeyAccessibleLabelMapper {
+    return {
+        scanCodeToText(scanCode: number): string[] {
+            if (scanCode === 4) {
+                return ['A'];
+            }
+
+            if (scanCode === 82) {
+                return ['Up Arrow'];
+            }
+
+            if (scanCode === 90) {
+                return ['Np 2', 'icon-kbd__mod--arrow-down'];
+            }
+
+            return [`B${scanCode}`];
+        },
+        getSecondaryRoleText(secondaryRoleAction: SecondaryRoleAction): string {
+            if (secondaryRoleAction === SecondaryRoleAction.mod) {
+                return 'Mod';
+            }
+
+            return 'unknown';
+        },
+    };
+}
+
+describe('combinePhysicalAndActionLabel', () => {
+    it('appends unassigned when the key has no action', ({ assert }) => {
+        assert.equal(combinePhysicalAndActionLabel('Up Arrow', 'unassigned'), 'Up Arrow, unassigned');
+    });
+
+    it('returns only the physical name when it matches the action', ({ assert }) => {
+        assert.equal(combinePhysicalAndActionLabel('Up Arrow', 'Up Arrow'), 'Up Arrow');
+    });
+
+    it('includes both names when the mapping differs from the physical key', ({ assert }) => {
+        assert.equal(combinePhysicalAndActionLabel('I', 'Up Arrow'), 'I, Up Arrow');
+    });
+});
+
+describe('buildKeyAccessibleLabel', () => {
+    const mapper = createMapper();
+    const layerOptionMap = new Map([
+        [LayerName.mod, { name: 'Mod' }],
+    ]);
+
+    it('labels an unmapped physical arrow so VoiceOver can search for it', ({ assert }) => {
+        const label = buildKeyAccessibleLabel({
+            keyAction: new NoneAction(),
+            layerOptionMap,
+            mapper,
+            physicalKeyLabel: 'Up Arrow',
+        });
+
+        assert.equal(label, 'Up Arrow, unassigned');
+    });
+
+    it('labels a missing key action as unassigned', ({ assert }) => {
+        const label = buildKeyAccessibleLabel({
+            layerOptionMap,
+            mapper,
+            physicalKeyLabel: 'Home',
+        });
+
+        assert.equal(label, 'Home, unassigned');
+    });
+
+    it('keeps a single name when the key still performs its physical action', ({ assert }) => {
+        const keyAction = new KeystrokeAction();
+        keyAction.scancode = 82;
+
+        const label = buildKeyAccessibleLabel({
+            keyAction,
+            layerOptionMap,
+            mapper,
+            physicalKeyLabel: 'Up Arrow',
+        });
+
+        assert.equal(label, 'Up Arrow');
+    });
+
+    it('includes the physical key when it is remapped to an arrow', ({ assert }) => {
+        const keyAction = new KeystrokeAction();
+        keyAction.scancode = 82;
+
+        const label = buildKeyAccessibleLabel({
+            keyAction,
+            layerOptionMap,
+            mapper,
+            physicalKeyLabel: 'I',
+        });
+
+        assert.equal(label, 'I, Up Arrow');
+    });
+
+    it('omits icon filenames from scancode labels', ({ assert }) => {
+        const keyAction = new KeystrokeAction();
+        keyAction.scancode = 90;
+
+        const label = buildKeyAccessibleLabel({
+            keyAction,
+            layerOptionMap,
+            mapper,
+            physicalKeyLabel: 'Np 2',
+        });
+
+        assert.equal(label, 'Np 2');
+    });
+
+    it('includes modifiers and secondary role', ({ assert }) => {
+        const keyAction = new KeystrokeAction();
+        keyAction.scancode = 4;
+        keyAction.modifierMask = 2;
+        keyAction.secondaryRoleAction = SecondaryRoleAction.mod;
+
+        const label = buildKeyAccessibleLabel({
+            keyAction,
+            layerOptionMap,
+            mapper,
+            physicalKeyLabel: 'A',
+        });
+
+        assert.equal(label, 'A, LShift, A, secondary role Mod');
+    });
+
+    it('describes layer switch actions', ({ assert }) => {
+        const keyAction = new SwitchLayerAction();
+        keyAction.layer = LayerName.mod;
+
+        const label = buildKeyAccessibleLabel({
+            keyAction,
+            layerOptionMap,
+            mapper,
+            physicalKeyLabel: 'Space',
+        });
+
+        assert.equal(label, 'Space, Switch to Mod layer');
+    });
+
+    it('describes macro playback', ({ assert }) => {
+        const keyAction = new PlayMacroAction();
+        keyAction.macroId = 3;
+        const macro = new Macro();
+        macro.name = 'Previous heading';
+
+        const label = buildKeyAccessibleLabel({
+            keyAction,
+            layerOptionMap,
+            macroMap: new Map([[3, macro]]),
+            mapper,
+            physicalKeyLabel: 'Up Arrow',
+        });
+
+        assert.equal(label, 'Up Arrow, Play macro Previous heading');
+    });
+});
diff --git a/packages/uhk-web/src/app/util/build-key-accessible-label.ts b/packages/uhk-web/src/app/util/build-key-accessible-label.ts
new file mode 100644
index 00000000000..8e1e7fa968d
--- /dev/null
+++ b/packages/uhk-web/src/app/util/build-key-accessible-label.ts
@@ -0,0 +1,112 @@
+import {
+    ConnectionsAction,
+    KeyAction,
+    KeystrokeAction,
+    KeystrokeType,
+    Macro,
+    MouseAction,
+    NoneAction,
+    OtherAction,
+    PlayMacroAction,
+    SecondaryRoleAction,
+    SwitchKeymapAction,
+    SwitchLayerAction,
+} from 'uhk-common';
+
+export const UNASSIGNED_KEY_ACTION_LABEL = 'unassigned';
+
+export interface KeyAccessibleLabelMapper {
+    scanCodeToText(scanCode: number, type?: KeystrokeType): string[];
+    getSecondaryRoleText(secondaryRoleAction: SecondaryRoleAction): string;
+}
+
+export interface BuildKeyAccessibleLabelOptions {
+    keyAction?: KeyAction;
+    layerOptionMap: Map<number, { name: string }>;
+    macroMap?: Map<number, Macro>;
+    mapper: KeyAccessibleLabelMapper;
+    physicalKeyLabel: string;
+}
+
+export function buildKeyAccessibleLabel(options: BuildKeyAccessibleLabelOptions): string {
+    const actionLabel = buildKeyActionAccessibleLabel(options);
+
+    return combinePhysicalAndActionLabel(options.physicalKeyLabel, actionLabel);
+}
+
+export function combinePhysicalAndActionLabel(physicalKeyLabel: string, actionLabel: string): string {
+    if (actionLabel === UNASSIGNED_KEY_ACTION_LABEL) {
+        return `${physicalKeyLabel}, ${UNASSIGNED_KEY_ACTION_LABEL}`;
+    }
+
+    if (actionLabel === physicalKeyLabel) {
+        return physicalKeyLabel;
+    }
+
+    return `${physicalKeyLabel}, ${actionLabel}`;
+}
+
+function buildKeyActionAccessibleLabel(options: BuildKeyAccessibleLabelOptions): string {
+    const keyAction = options.keyAction;
+
+    if (!keyAction || keyAction instanceof NoneAction) {
+        return UNASSIGNED_KEY_ACTION_LABEL;
+    }
+
+    if (keyAction instanceof KeystrokeAction) {
+        const parts: string[] = [];
+
+        if (keyAction.hasActiveModifier()) {
+            parts.push(keyAction.getModifierList().join(' + '));
+        }
+
+        if (keyAction.hasScancode()) {
+            const scancodeText = options.mapper.scanCodeToText(keyAction.scancode, keyAction.type)
+                .filter(part => !part.startsWith('icon'))
+                .join(' ');
+
+            if (scancodeText) {
+                parts.push(scancodeText);
+            }
+        }
+
+        if (parts.length === 0) {
+            parts.push('Keystroke');
+        }
+
+        if (keyAction.hasSecondaryRoleAction()) {
+            const secondaryRoleText = options.mapper.getSecondaryRoleText(keyAction.secondaryRoleAction);
+            parts.push(`secondary role ${secondaryRoleText || 'unknown'}`);
+        }
+
+        return parts.join(', ');
+    }
+
+    if (keyAction instanceof SwitchLayerAction) {
+        const layerName = options.layerOptionMap.get(keyAction.layer)?.name || 'unknown';
+        return `Switch to ${layerName} layer`;
+    }
+
+    if (keyAction instanceof SwitchKeymapAction) {
+        return `Switch to keymap ${keyAction.keymapAbbreviation}`;
+    }
+
+    if (keyAction instanceof PlayMacroAction) {
+        const macroName = options.macroMap?.get(keyAction.macroId)?.name;
+        return macroName ? `Play macro ${macroName}` : 'Play macro';
+    }
+
+    if (keyAction instanceof MouseAction) {
+        return 'Mouse action';
+    }
+
+    if (keyAction instanceof ConnectionsAction) {
+        return 'Host connection action';
+    }
+
+    if (keyAction instanceof OtherAction) {
+        return 'Sleep';
+    }
+
+    return 'Assigned key action';
+}

From 17a3e9da7d3201ca8b76af01f655893e0ee58e7c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Monda?= <laci@monda.hu>
Date: Sun, 16 Aug 2026 17:13:06 +0200
Subject: [PATCH 2/3] fix: use lowercase currentcolor in key accessible-name
 styles

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss
index 85f5555a230..6c69cfd5bd8 100644
--- a/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss
+++ b/packages/uhk-web/src/app/components/svg/keys/svg-keyboard-key/svg-keyboard-key.component.scss
@@ -15,7 +15,7 @@
 }
 
 .svg-keyboard-key__accessible-name {
-    fill: currentColor;
+    fill: currentcolor;
     font-size: 1px;
     opacity: 0.01;
     pointer-events: none;

From ac840441b9e173c0d251c2b603b7bc41abb9c091 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Monda?= <laci@monda.hu>
Date: Tue, 18 Aug 2026 11:24:20 +0200
Subject: [PATCH 3/3] chore: bump firmware version to 18.0.1

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 4c8aaa23c2c..48aa39e1dc9 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
   "author": "Ultimate Gadget Laboratories",
   "main": "electron/dist/electron-main.js",
   "version": "10.1.0",
-  "firmwareVersion": "17.2.0",
+  "firmwareVersion": "18.0.1",
   "deviceProtocolVersion": "4.19.0",
   "userConfigVersion": "15.0.0",
   "hardwareConfigVersion": "1.0.0",