Copilot instructions

1---
2description: 'Use when implementing accessibility features, ARIA labels, screen reader support, accessible help dialogs, or keybinding scoping for accessibility. Covers AccessibleContentProvider, CONTEXT_ACCESSIBILITY_MODE_ENABLED, verbosity settings, and announcement patterns.'
3---
4 
5# Accessibility Guidelines
6 
7Accessibility is a high-priority area in VS Code. Follow these patterns to ensure features work correctly with screen readers and assistive technologies.
8 
9## Keybinding Scoping
10 
11Accessibility-specific keybindings MUST be scoped to prevent conflicts with standard shortcuts:
12 
13```typescript
14keybinding: {
15	primary: KeyCode.F7,
16	when: ContextKeyExpr.and(
17		EditorContextKeys.focus,
18		CONTEXT_ACCESSIBILITY_MODE_ENABLED
19	),
20	weight: KeybindingWeight.WorkbenchContrib,
21},
22```
23 
24**Why**: Without scoping, accessibility shortcuts steal commonly used keybindings (e.g., F7 for "Go to Next Symbol Highlight"). PR #293163 fixed this exact conflict.
25 
26## Accessible Help Dialogs (Alt+F1)
27 
28Use `AccessibleContentProvider` directly — do not create custom subclasses:
29 
30```typescript
31getProvider(): AccessibleContentProvider {
32	return new AccessibleContentProvider(
33		AccessibleViewProviderId.MyFeature,
34		{ type: AccessibleViewType.Help },
35		() => this.getHelpContent(),
36		() => this.onClose(),
37		'accessibility.verbosity.myFeature'
38	);
39}
40```
41 
42## Announcement Patterns
43 
44When announcing state changes to screen readers:
45 
461. **Only announce when conditions are met**: Check that a search string is present, widget is visible, and screen reader is active
472. **Prevent double-speak**: Track announcement state with a flag and use a timeout (~1 second)
483. **Use verbosity settings**: Check `accessibility.verbosity.[feature]` before verbose announcements
49 
50```typescript
51if (this.accessibilityService.isScreenReaderOptimized() &&
52    this.configService.getValue('accessibility.verbosity.hover') &&
53    !this._accessibilityHelpHintAnnounced) {
54	this._accessibilityHelpHintAnnounced = true;
55	// announce hint
56}
57```
58 
59## Multi-Modal Notifications
60 
61For important state changes, provide all three:
621. **Audio signal**: `this.accessibilitySignalService.playSignal(AccessibilitySignal.chatUserActionRequired)`
632. **ARIA alert**: `status(message)` for screen readers
643. **OS notification**: Respect `chat.notifyWindowOnConfirmation` setting. OS notifications are **conditional on window focus** — only fire when `targetWindow.document.hasFocus()` is `false` (see `ChatWindowNotifier`)
65 
66## Configuration
67 
68When adding a new accessible feature, register a verbosity setting:
69 
70```typescript
71// In accessibility configuration
72'accessibility.verbosity.myFeature': {
73	type: 'boolean',
74	default: true,
75	description: localize('accessibility.verbosity.myFeature', "...")
76}
77```
78 
79And extend `AccessibleViewProviderId` and `AccessibilityVerbositySettingId` enums for new help providers.
80