mirror of
https://github.com/microsoft/vscode.git
synced 2026-04-18 15:55:59 +01:00
80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
---
|
|
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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
// 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.
|