[Accessibility] Content: Accessibility Help Providers for Find and Filter Experiences by accesswatch · Pull Request #292220 · microsoft/vscode

accesswatch · 2026-02-02T02:10:40Z

[Accessibility] Content: Accessibility Help Providers for Find and Filter Experiences

Executive Summary

This PR delivers the concrete accessibility help content that screen reader users will see when pressing Alt+F1 in any find or filter experience. Each provider generates localized, context-aware help text that explains keyboard shortcuts, navigation patterns, focus behavior, and available options specific to that component.

Key user benefit: Screen reader users can now press Alt+F1 in any find dialog to receive comprehensive, accurate guidance on how to use that specific find experience effectively.

Implementation insight: All help content has been validated against actual VS Code behavior. Critical focus behavior corrections were made during implementation—for example, documenting that Enter in Terminal find jumps to the previous match (opposite of Editor find).

Checklist

Code follows VS Code contribution guidelines
All user-visible strings use nls.localize() for localization
TypeScript compilation passes
Existing tests pass
New provider smoke tests added
Screen reader testing completed with NVDA/JAWS

What This PR Includes

7 New Accessibility Help Provider Files

Each file implements IAccessibleViewImplementation and IAccessibleViewContentProvider to deliver rich, contextual help content.

1. Editor Find/Replace Help

File: src/vs/workbench/contrib/codeEditor/browser/editorFindAccessibilityHelp.ts

Activation: CONTEXT_FIND_INPUT_FOCUSED or CONTEXT_REPLACE_INPUT_FOCUSED

Content sections:

Current search status (term, match count, position)
Whether Replace mode is active
Focus behavior explanation (focus stays in input on Enter)
Keyboard shortcuts for Find context:
- Enter / Shift+Enter - Next/previous match
- Escape - Close and return to editor
- Ctrl+Shift+1 - Replace current match
- Ctrl+Alt+Enter - Replace all
Find options: Regex, Case sensitive, Whole word, In selection
Relevant settings: editor.find.seedSearchStringFromSelection

Code architecture:

export class EditorFindAccessibilityHelp implements IAccessibleViewImplementation {
    readonly priority = 105;
    readonly name = 'editor-find';
    readonly when = ContextKeyExpr.or(CONTEXT_FIND_INPUT_FOCUSED, CONTEXT_REPLACE_INPUT_FOCUSED);
    readonly type = AccessibleViewType.Help;

    getProvider(accessor: ServicesAccessor) {
        // Returns EditorFindAccessibilityHelpProvider with current find state
    }
}

2. Terminal Find Help

File: src/vs/workbench/contrib/terminalContrib/find/browser/terminalFindAccessibilityHelp.ts

Activation: Terminal find input focused

Content sections:

Terminal-specific search behavior (searches visible buffer + scrollback)
Critical: Enter navigates to previous match (opposite of editor)
Focus behavior (stays in find input)
Buffer navigation and selection modes
Keyboard shortcuts:
- Enter - Previous match (scrolls up)
- Shift+Enter - Next match (scrolls down)
- Escape - Close find, focus terminal
Terminal-specific limitations (no regex in some shells)

Key implementation detail:

// Terminal uses opposite navigation direction
const enterBehavior = nls.localize('terminalFindEnter',
    "Press Enter to navigate to the previous match (scrolling up through buffer)");

3. Webview Find Help

File: src/vs/workbench/contrib/webview/browser/webviewFindAccessibilityHelp.ts

Activation: Webview find input focused

Content sections:

Extension webview search capabilities
Markdown preview find behavior
Focus behavior (stays in find input)
Limitations: Some extension webviews may not support find
Keyboard shortcuts (same as editor find)

4. Output Panel Filter Help

File: src/vs/workbench/contrib/output/browser/outputAccessibilityHelp.ts

Activation: Output panel filter input focused

Content sections:

Filter vs. Find distinction (filters visible content, doesn't highlight)
Channel selection (dropdown behavior)
Filter syntax (plain text, case-insensitive by default)
Log level considerations
Keyboard navigation for filtered results
Common troubleshooting patterns

5. Problems Panel Filter Help

File: src/vs/workbench/contrib/markers/browser/markersAccessibilityHelp.ts

Activation: Problems panel filter input focused

Content sections:

Filter by severity (errors, warnings, info)
Filter by source (ESLint, TypeScript, etc.)
Filter by text content
Quick fix navigation (Ctrl+. on focused problem)
Focus behavior in tree view
Keyboard shortcuts:
- F4 / Shift+F4 - Navigate between problems
- Enter - Open file at problem location

6. Debug Console Filter Help

File: src/vs/workbench/contrib/debug/browser/replAccessibilityHelp.ts

Activation: Debug console (REPL) filter input focused

Content sections:

Expression evaluation filtering
Variable inspection navigation
Command history (Up/Down arrows)
Filter vs. evaluation distinction
Debug session context awareness

7. Search Across Files Help

File: src/vs/workbench/contrib/search/browser/searchAccessibilityHelp.ts

Activation: Search view input focused

Content sections:

Include/exclude file patterns (glob syntax)
Search scope options (workspace, folder, open files)
Results tree navigation
Focus behavior: Enter runs search (focus stays), F4 on result moves to editor
Replace across files workflow
Keyboard shortcuts:
- Enter - Execute search
- F4 - Go to next result (moves focus to editor)
- Shift+F4 - Go to previous result

Technical Implementation

Provider Interface

All providers implement the same interfaces:

interface IAccessibleViewImplementation {
    readonly priority: number;
    readonly name: string;
    readonly when: ContextKeyExpression;
    readonly type: AccessibleViewType;
    getProvider(accessor: ServicesAccessor): IAccessibleViewContentProvider | undefined;
}

interface IAccessibleViewContentProvider {
    readonly id: AccessibleViewProviderId;
    readonly verbositySettingKey: AccessibilityVerbositySettingId;
    readonly options: IAccessibleViewOptions;
    provideContent(): string;
    onClose(): void;
}

Localization Pattern

All user-visible strings use nls.localize():

const header = nls.localize('editorFindHelp.header',
    "Editor Find and Replace Help");
const enterBehavior = nls.localize('editorFindHelp.enter',
    "Press Enter to navigate to the next match. Focus remains in the find input.");

Verbosity Setting Integration

Each provider references the verbosity setting from PR 1:

readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;

Testing & Validation

Unit Tests

Each provider includes smoke tests:

test('EditorFindAccessibilityHelp provides non-empty content', () => {
    const provider = new EditorFindAccessibilityHelpProvider(mockFindController, mockEditor);
    const content = provider.provideContent();
    assert.ok(content.length > 0);
    assert.ok(content.includes('Enter')); // Keyboard shortcuts present
});

Manual Validation Matrix

Component	Action	Expected Result
Editor	Ctrl+F, Alt+F1	Find help with Enter/Escape shortcuts
Editor	Ctrl+H, Alt+F1	Replace help with replace shortcuts
Terminal	Ctrl+F, Alt+F1	Terminal help noting Enter = previous
Webview	Ctrl+F, Alt+F1	Webview help with limitations noted
Output	Focus filter, Alt+F1	Filter help with channel info
Problems	Focus filter, Alt+F1	Filter help with severity/source info
Debug Console	Focus filter, Alt+F1	REPL help with expression info
Search	Focus input, Alt+F1	Search help with glob patterns

Screen Reader Testing

Test with:

NVDA 2024.x on Windows
JAWS 2024 on Windows
VoiceOver on macOS

Verify:

Content is announced in logical reading order
Keyboard shortcut text is pronounced correctly
No duplicate announcements
Escape closes help and returns focus correctly

Dependencies

PR	Status	Requirement
PR 1 (Foundation)	Must be merged first	Provides configuration and registry
PR 3 (Polish)	Depends on this PR	Adds ARIA hints that reference this help

Rollout Considerations

Localization: All strings use nls.localize() and will be translated
Performance: Providers are lazy-loaded; no impact until Alt+F1 is pressed
Backwards compatibility: Pure additions; no API changes
Telemetry: Consider adding usage telemetry in future PR

Release Note

Accessibility: Add comprehensive accessibility help content for find and filter experiences (Alt+F1) - provides keyboard shortcuts, navigation patterns, and focus behavior documentation for Editor, Terminal, Webview, Output, Problems, Debug Console, and Search.

Files Changed Summary

File	Lines	Type
`editorFindAccessibilityHelp.ts`	~180	New file
`terminalFindAccessibilityHelp.ts`	~150	New file
`webviewFindAccessibilityHelp.ts`	~120	New file
`outputAccessibilityHelp.ts`	~130	New file
`markersAccessibilityHelp.ts`	~140	New file
`replAccessibilityHelp.ts`	~125	New file
`searchAccessibilityHelp.ts`	~150	New file
Total	~994 / -11	7 files

…d/filter experiences This PR adds comprehensive accessibility help content for all find and filter experiences in VS Code. Each file provides rich help accessible via Alt+F1. New Accessibility Help Providers: - editorFindAccessibilityHelp.ts: Editor find/replace dialog help - terminalFindAccessibilityHelp.ts: Terminal find help - webviewFindAccessibilityHelp.ts: Webview find help - outputAccessibilityHelp.ts: Output panel filter help - markersAccessibilityHelp.ts: Problems panel filter help - replAccessibilityHelp.ts: Debug console filter help - searchAccessibilityHelp.ts: Search across files help Each provider implements IAccessibleViewContent with: - Comprehensive keyboard shortcut documentation - Context-specific navigation instructions - Settings and options explanations - Platform-specific shortcuts where applicable This is PR 2 of 3 for the Accessibility Help System. Depends on: PR 1 (Foundation and Infrastructure)

Copilot

Pull request overview

This pull request adds accessibility help providers for find and filter experiences across VS Code. When users press Alt+F1 while focused in any find or filter input, they receive comprehensive, context-aware guidance about keyboard shortcuts, navigation patterns, and available options.

Changes:

7 new accessibility help provider files that deliver localized help content for different find/filter contexts
Modified existing REPL accessibility help to expand its activation context
Each provider implements IAccessibleViewImplementation and IAccessibleViewContentProvider interfaces

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
editorFindAccessibilityHelp.ts	New provider for editor find/replace dialog with detailed keyboard shortcuts and options
terminalFindAccessibilityHelp.ts	New provider for terminal find with buffer search specifics
webviewFindAccessibilityHelp.ts	New provider for webview find with extension webview limitations
searchAccessibilityHelp.ts	New provider for workspace-wide search with glob patterns and results navigation
outputAccessibilityHelp.ts	New provider for output panel filter with filter syntax documentation
markersAccessibilityHelp.ts	New provider for problems panel filter with severity and scope filtering
replAccessibilityHelp.ts	Updated existing provider with new filter-focused help content and expanded activation context

Copilot · 2026-02-02T02:21:33Z

src/vs/workbench/contrib/debug/browser/replAccessibilityHelp.ts

+		// Settings
+		content.push(localize('repl.settingsHeader', "Settings You Can Adjust ({0} opens Settings):", '<keybinding:workbench.action.openSettings>'));
+		content.push(localize('repl.settingsIntro', "These settings affect the Debug Console."));
+		content.push(localize('repl.settingVerbosity', "- `accessibility.verbosity.find`: Controls whether the filter input announces the Accessibility Help hint."));


The documentation references 'accessibility.verbosity.find' setting, but the provider uses AccessibilityVerbositySettingId.Debug (line 37). This is inconsistent. The documentation should reference 'accessibility.verbosity.debug' to match the actual verbosity setting key used by this provider, or if this is intended to be a filter-specific help for the REPL, the verbosity setting should be changed to AccessibilityVerbositySettingId.Find (once that enum value is added).

Suggested change

content.push(localize('repl.settingVerbosity', "- `accessibility.verbosity.find`: Controls whether the filter input announces the Accessibility Help hint."));

content.push(localize('repl.settingVerbosity', "- `accessibility.verbosity.debug`: Controls whether the filter input announces the Accessibility Help hint."));

Copilot · 2026-02-02T02:21:33Z

src/vs/workbench/contrib/terminalContrib/find/browser/terminalFindAccessibilityHelp.ts

+
+class TerminalFindAccessibilityHelpProvider extends Disposable implements IAccessibleViewContentProvider {
+	readonly id = AccessibleViewProviderId.TerminalFindHelp;
+	readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;


The AccessibilityVerbositySettingId enum is missing the 'Find' value used on this line. This enum is defined in 'src/vs/workbench/contrib/accessibility/browser/accessibilityConfiguration.ts'.

Suggested change

readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;

readonly verbositySettingKey = AccessibilityVerbositySettingId.Terminal;

Copilot · 2026-02-02T02:21:33Z

src/vs/workbench/contrib/webview/browser/webviewFindAccessibilityHelp.ts

+}
+
+class WebviewFindAccessibilityHelpProvider extends Disposable implements IAccessibleViewContentProvider {
+	readonly id = AccessibleViewProviderId.WebviewFindHelp;


The AccessibleViewProviderId enum is missing the 'WebviewFindHelp' value. This enum is defined in 'src/vs/platform/accessibility/browser/accessibleView.ts'.

Suggested change

readonly id = AccessibleViewProviderId.WebviewFindHelp;

readonly id = 'webview-find-help';

Copilot · 2026-02-02T02:21:34Z

src/vs/workbench/contrib/webview/browser/webviewFindAccessibilityHelp.ts

+export class WebviewFindAccessibilityHelp implements IAccessibleViewImplementation {
+	readonly priority = 105;
+	readonly name = 'webview-find';
+	readonly type = AccessibleViewType.Help;
+	readonly when = KEYBINDING_CONTEXT_WEBVIEW_FIND_WIDGET_FOCUSED;
+
+	getProvider(accessor: ServicesAccessor): AccessibleContentProvider | undefined {
+		return new WebviewFindAccessibilityHelpProvider();
+	}
+}


This accessibility help provider is not registered. You need to add registration code like 'AccessibleViewRegistry.register(new WebviewFindAccessibilityHelp());' in a webview contribution file.

Copilot · 2026-02-02T02:21:34Z

src/vs/workbench/contrib/search/browser/searchAccessibilityHelp.ts

+
+class SearchAccessibilityHelpProvider extends Disposable implements IAccessibleViewContentProvider {
+	readonly id = AccessibleViewProviderId.SearchHelp;
+	readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;


The AccessibilityVerbositySettingId enum is missing the 'Find' value used on this line. This enum is defined in 'src/vs/workbench/contrib/accessibility/browser/accessibilityConfiguration.ts'.

Suggested change

readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;

readonly verbositySettingKey: AccessibilityVerbositySettingId | undefined = undefined;

Copilot · 2026-02-02T02:21:37Z

src/vs/workbench/contrib/output/browser/outputAccessibilityHelp.ts

+}
+
+class OutputAccessibilityHelpProvider extends Disposable implements IAccessibleViewContentProvider {
+	readonly id = AccessibleViewProviderId.OutputFindHelp;


The AccessibleViewProviderId enum is missing the 'OutputFindHelp' value. This enum is defined in 'src/vs/platform/accessibility/browser/accessibleView.ts'.

Suggested change

readonly id = AccessibleViewProviderId.OutputFindHelp;

readonly id = AccessibleViewProviderId.Output;

Copilot · 2026-02-02T02:21:37Z

src/vs/workbench/contrib/markers/browser/markersAccessibilityHelp.ts

+}
+
+class ProblemsAccessibilityHelpProvider extends Disposable implements IAccessibleViewContentProvider {
+	readonly id = AccessibleViewProviderId.ProblemsFilterHelp;


The AccessibleViewProviderId enum is missing the 'ProblemsFilterHelp' value. This enum is defined in 'src/vs/platform/accessibility/browser/accessibleView.ts'.

Copilot · 2026-02-02T02:21:37Z

src/vs/workbench/contrib/markers/browser/markersAccessibilityHelp.ts

+export class ProblemsAccessibilityHelp implements IAccessibleViewImplementation {
+	readonly type = AccessibleViewType.Help;
+	readonly priority = 105;
+	readonly name = 'problemsFilter';
+	readonly when = MarkersContextKeys.MarkerViewFilterFocusContextKey;
+
+	getProvider(accessor: ServicesAccessor): AccessibleContentProvider {
+		return new ProblemsAccessibilityHelpProvider(accessor.get(IKeybindingService));
+	}
+}


This accessibility help provider is not registered. You need to add registration code like 'AccessibleViewRegistry.register(new ProblemsAccessibilityHelp());' in a markers/problems contribution file.

Copilot · 2026-02-02T02:21:37Z

src/vs/workbench/contrib/output/browser/outputAccessibilityHelp.ts

+
+class OutputAccessibilityHelpProvider extends Disposable implements IAccessibleViewContentProvider {
+	readonly id = AccessibleViewProviderId.OutputFindHelp;
+	readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;


The AccessibilityVerbositySettingId enum is missing the 'Find' value used on this line. This enum is defined in 'src/vs/workbench/contrib/accessibility/browser/accessibilityConfiguration.ts'.

Suggested change

readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;

readonly verbositySettingKey = AccessibilityVerbositySettingId.Output;

Copilot · 2026-02-02T02:21:37Z

src/vs/workbench/contrib/output/browser/outputAccessibilityHelp.ts

+export class OutputAccessibilityHelp implements IAccessibleViewImplementation {
+	readonly type = AccessibleViewType.Help;
+	readonly priority = 105;
+	readonly name = 'outputFilter';
+	readonly when = OUTPUT_FILTER_FOCUS_CONTEXT;
+
+	getProvider(accessor: ServicesAccessor): AccessibleContentProvider {
+		return new OutputAccessibilityHelpProvider(accessor.get(IKeybindingService));
+	}
+}


This accessibility help provider is not registered. You need to add registration code like 'AccessibleViewRegistry.register(new OutputAccessibilityHelp());' in an output contribution file.

meganrogge · 2026-02-02T18:01:02Z

we're closing these in favor of a new one that merges the changes

GitHub Copilot added 3 commits February 1, 2026 15:21

docs: Add PR2 description

c32e5d1

chore: Remove PR description template (not part of actual PR)

d9dfc0d

Copilot AI review requested due to automatic review settings February 2, 2026 02:10

Copilot started reviewing on behalf of accesswatch February 2, 2026 02:11 View session

Copilot AI reviewed Feb 2, 2026

View reviewed changes

vs-code-engineering bot assigned meganrogge Feb 2, 2026

meganrogge closed this Feb 2, 2026

accesswatch mentioned this pull request Feb 2, 2026

feat(accessibility): Add Accessibility Help System for find/filter dialogs #292373

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Accessibility] Content: Accessibility Help Providers for Find and Filter Experiences#292220

[Accessibility] Content: Accessibility Help Providers for Find and Filter Experiences#292220
accesswatch wants to merge 3 commits intomicrosoft:mainfrom
accesswatch:feature/accessibility-help-content

accesswatch commented Feb 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

meganrogge commented Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	content.push(localize('repl.settingVerbosity', "- `accessibility.verbosity.find`: Controls whether the filter input announces the Accessibility Help hint."));
	content.push(localize('repl.settingVerbosity', "- `accessibility.verbosity.debug`: Controls whether the filter input announces the Accessibility Help hint."));

	readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;
	readonly verbositySettingKey = AccessibilityVerbositySettingId.Terminal;

	readonly id = AccessibleViewProviderId.WebviewFindHelp;
	readonly id = 'webview-find-help';

	readonly verbositySettingKey = AccessibilityVerbositySettingId.Find;
	readonly verbositySettingKey: AccessibilityVerbositySettingId \| undefined = undefined;

	readonly id = AccessibleViewProviderId.OutputFindHelp;
	readonly id = AccessibleViewProviderId.Output;

Conversation

accesswatch commented Feb 2, 2026

[Accessibility] Content: Accessibility Help Providers for Find and Filter Experiences

Executive Summary

Checklist

What This PR Includes

7 New Accessibility Help Provider Files

1. Editor Find/Replace Help

2. Terminal Find Help

3. Webview Find Help

4. Output Panel Filter Help

5. Problems Panel Filter Help

6. Debug Console Filter Help

7. Search Across Files Help

Technical Implementation

Provider Interface

Localization Pattern

Verbosity Setting Integration

Testing & Validation

Unit Tests

Manual Validation Matrix

Screen Reader Testing

Dependencies

Rollout Considerations

Release Note

Files Changed Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

meganrogge commented Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants