Improves Settings control accessibility and match highlighting

Announce the slider's unit via wa-slider's valueFormatter, surface the switch's disabled reason through wa-switch's hint (aria-describedby), replace the token menu's listbox/option misuse with a labeled group of buttons, and use the shared sr-only helper in the nav. Also highlight only the first visible variant of a paired control so duplicate-key descriptors don't double-highlight.

Author: d13

src/webviews/apps/settings/components/format-input.ts

@@ -430,16 +430,17 @@ export class GlFormatInput extends SignalWatcher(LitElement) {
 							>
 								<code-icon icon="chevron-down" aria-hidden="true"></code-icon>
 							</button>
-							<div slot="content" class="tokens" role="listbox" aria-label="Available tokens">
+							<div slot="content" class="tokens" role="group" aria-label="Available tokens">
 								<h3 class="tokens__title">Insert token</h3>
 								${tokens.map(t => {
 									// Commit tokens insert wrapped in `${…}`; date tokens insert bare
 									// eslint-disable-next-line prefer-template -- a template literal would need `\${` escaping, which is harder to read
 									const text = tokenMode === 'date' ? t.token : '${' + t.token + '}';
+									// Plain action buttons (insert on click) — not listbox options,
+									// which would imply arrow-key selection semantics
 									return html`<button
 										type="button"
 										class="token"
-										role="option"
 										@click=${() => this.insertToken(text)}
 									>
 										<code>${text}</code><span>${t.label}</span>

src/webviews/apps/settings/components/settings-detail.ts

@@ -231,7 +231,16 @@ export class GlSettingsDetail extends SignalWatcher(LitElement) {
 	 */
 	private isHighlighted(d: SettingDescriptor, highlighted: ReadonlySet<string>): boolean {
 		if (!('key' in d) || !highlighted.has(d.key)) return false;
-		if (this.isNaturallyVisible(d)) return true;
+
+		if (this.isNaturallyVisible(d)) {
+			// A key can have several visible variants (e.g. a checkbox + select pair
+			// differing only by `enabledWhen`) — highlight just the first so the pair
+			// doesn't double-highlight.
+			const firstVisible = this.category.controls.find(
+				c => 'key' in c && c.key === d.key && this.isNaturallyVisible(c),
+			);
+			return firstVisible === d;
+		}
 
 		// Hidden match: force-reveal only when no visible variant of the key exists
 		return !this.category.controls.some(
@@ -294,7 +303,7 @@ export class GlSettingsDetail extends SignalWatcher(LitElement) {
 									.checked=${masterOn && !masterDisabledByOrg}
 									?disabled=${masterDisabledByOrg}
 									label="Enable ${category.name}"
-									title=${ifDefined(
+									hint=${ifDefined(
 										masterDisabledByOrg
 											? 'AI features have been disabled by your GitKraken admin.'
 											: undefined,

src/webviews/apps/settings/components/settings-nav.ts

@@ -3,7 +3,7 @@ import { SignalWatcher } from '@lit-labs/signals';
 import { css, html, LitElement, nothing } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import type { AutolinkConfig } from '../../../../config.js';
-import { focusOutlineButton } from '../../shared/components/styles/lit/a11y.css.js';
+import { focusOutlineButton, srOnly } from '../../shared/components/styles/lit/a11y.css.js';
 import { boxSizingBase, linkBase } from '../../shared/components/styles/lit/base.css.js';
 import type { CheckDescriptor, SettingsCategory, SettingsGroup, SettingsSearchMatch } from '../model.js';
 import type { SettingsState } from '../state.js';
@@ -25,6 +25,7 @@ export class GlSettingsNav extends SignalWatcher(LitElement) {
 	static override styles = [
 		boxSizingBase,
 		linkBase,
+		srOnly,
 		css`
 			:host {
 				display: block;
@@ -129,18 +130,6 @@ export class GlSettingsNav extends SignalWatcher(LitElement) {
 			.empty p {
 				margin: 0 0 var(--gl-space-8);
 			}
-
-			.sr-only {
-				position: absolute;
-				width: 1px;
-				height: 1px;
-				padding: 0;
-				margin: -1px;
-				overflow: hidden;
-				white-space: nowrap;
-				border: 0;
-				clip: rect(0, 0, 0, 0);
-			}
 		`,
 	];
 

src/webviews/apps/shared/components/slider/slider.ts

@@ -77,7 +77,7 @@ export class GlSlider extends LitElement {
 				step=${this.step}
 				?disabled=${this.disabled}
 				label=${ifDefined(this.label)}
-				aria-valuetext=${ifDefined(this.unit ? `${this.value}${this.unit}` : undefined)}
+				.valueFormatter=${(value: number) => `${value}${this.unit}`}
 				@input=${this.handleInput}
 				@change=${this.handleChange}
 			></wa-slider>

src/webviews/apps/shared/components/switch/switch.ts

@@ -1,6 +1,7 @@
 import type WaSwitch from '@awesome.me/webawesome/dist/components/switch/switch.js';
 import { html, LitElement, nothing } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import { switchStyles } from './switch.css.js';
 import '@awesome.me/webawesome/dist/components/switch/switch.js';
 import '../shoelace-stub.js';
@@ -38,6 +39,14 @@ export class GlSwitch extends LitElement {
 	@property({ type: String })
 	label?: string;
 
+	/**
+	 * Optional description, surfaced to assistive tech via `wa-switch`'s `hint`
+	 * (which wires it to the inner control's `aria-describedby`) — host-level ARIA
+	 * never reaches the focused input. Renders visibly beneath the switch.
+	 */
+	@property({ type: String })
+	hint?: string;
+
 	@property({ type: String, reflect: true })
 	size: 'medium' | 'large' = 'medium';
 
@@ -59,6 +68,7 @@ export class GlSwitch extends LitElement {
 			exportparts="base, control, thumb, label"
 			.checked=${this.checked}
 			?disabled=${this.disabled}
+			hint=${ifDefined(this.hint)}
 			@change=${this.handleChange}
 			><slot>${this.label ? html`<span class="sr-only">${this.label}</span>` : nothing}</slot></wa-switch
 		>`;