vscode/.github/instructions/accessibility.instructions.md

description

description
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.

Accessibility Guidelines

Accessibility is a high-priority area in VS Code. Follow these patterns to ensure features work correctly with screen readers and assistive technologies.

Keybinding Scoping

Accessibility-specific keybindings MUST be scoped to prevent conflicts with standard shortcuts:

keybinding: {
	primary: KeyCode.F7,
	when: ContextKeyExpr.and(
		EditorContextKeys.focus,
		CONTEXT_ACCESSIBILITY_MODE_ENABLED
	),
	weight: KeybindingWeight.WorkbenchContrib,
},

Why: Without scoping, accessibility shortcuts steal commonly used keybindings (e.g., F7 for "Go to Next Symbol Highlight"). PR #293163 fixed this exact conflict.

Accessible Help Dialogs (Alt+F1)

Use AccessibleContentProvider directly — do not create custom subclasses:

getProvider(): AccessibleContentProvider {
	return new AccessibleContentProvider(
		AccessibleViewProviderId.MyFeature,
		{ type: AccessibleViewType.Help },
		() => this.getHelpContent(),
		() => this.onClose(),
		'accessibility.verbosity.myFeature'
	);
}

Announcement Patterns

When announcing state changes to screen readers:

1. Only announce when conditions are met: Check that a search string is present, widget is visible, and screen reader is active
2. Prevent double-speak: Track announcement state with a flag and use a timeout (~1 second)
3. Use verbosity settings: Check accessibility.verbosity.[feature] before verbose announcements

if (this.accessibilityService.isScreenReaderOptimized() &&
    this.configService.getValue('accessibility.verbosity.hover') &&
    !this._accessibilityHelpHintAnnounced) {
	this._accessibilityHelpHintAnnounced = true;
	// announce hint
}

Multi-Modal Notifications

For important state changes, provide all three:

1. Audio signal: this.accessibilitySignalService.playSignal(AccessibilitySignal.chatUserActionRequired)
2. ARIA alert: status(message) for screen readers
3. OS notification: Respect chat.notifyWindowOnConfirmation setting. OS notifications are conditional on window focus — only fire when targetWindow.document.hasFocus() is false (see ChatWindowNotifier)

Configuration

When adding a new accessible feature, register a verbosity setting:

// In accessibility configuration
'accessibility.verbosity.myFeature': {
	type: 'boolean',
	default: true,
	description: localize('accessibility.verbosity.myFeature', "...")
}

And extend AccessibleViewProviderId and AccessibilityVerbositySettingId enums for new help providers.