Appendix M: VS Code Accessibility Reference

Listen to Episode 30: VS Code Accessibility Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

Complete Technical Reference for Screen Reader Users

Purpose: This appendix provides comprehensive technical documentation for all VS Code accessibility features, settings, and keyboard shortcuts. The main chapters cover essentials; this appendix is your complete reference manual.

Referenced by: VS Code Setup & Accessibility Basics, GitHub Copilot

Table of Contents

1. Complete Accessibility Settings Reference
2. Audio Cues - All Options
3. Accessible Diff Viewer - Complete Guide
4. Screen Reader-Specific Configurations
5. Complete Keyboard Shortcuts
6. Accessibility Signals Types and Customization
7. Settings.json Configuration Examples

1. Complete Accessibility Settings Reference

All settings can be accessed via Settings UI (Ctrl+,) or by editing settings.json directly (Ctrl+Shift+P → "Open User Settings JSON").

Core Accessibility Settings

Diff and Merge Settings

Terminal Settings

Notification Settings

2. Audio Cues - All Options

Audio cues provide non-verbal feedback through sound. Each cue can be configured independently.

Accessing Audio Cue Settings

Settings UI: Ctrl+, → search "audio cue"

Settings.json: Edit directly (see Section 7)

Audio Cue Values

Complete Accessibility Signals List

Customizing Signal Sounds

Advanced feature: You can replace default sounds with custom audio files.

1. Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"
2. Add custom sound paths:

{
  "accessibility.signals.lineHasError.sound": "file:///C:/Users/YourName/sounds/error.wav",
  "accessibility.signals.taskCompleted.sound": "file:///C:/Users/YourName/sounds/success.wav",
  "accessibility.signals.diffLineInserted.sound": "file:///C:/Users/YourName/sounds/added.wav"
}

Sound file requirements

• Format: WAV, MP3, or OGG
• Duration: Keep under 2 seconds
• Volume: Normalize to avoid clipping

3. Accessible Diff Viewer - Complete Guide

The Accessible Diff Viewer presents file diffs as a structured, line-by-line list instead of a visual side-by-side view.

When to Use Accessible Diff Viewer

• Reviewing pull request changes
• Resolving merge conflicts
• Comparing file versions (Timeline view)
• Reviewing Copilot-generated edits
• Any time you need to understand what changed in a file

Opening Accessible Diff Viewer

Diff Viewer Structure

Top-level structure

Description

The Accessible Diff Viewer starts with a header showing the file path and change summary. It then shows each hunk (changed section) in order. Each hunk contains: the hunk location (line range), unchanged context lines, the modified, added, or removed lines with their prefix, and more context lines. After all hunks, a footer shows the totals for additions and deletions.

Line prefixes

Navigating Hunks

Hunk = a block of related changes

Screen Reader-Specific Navigation

NVDA/JAWS

1. Open diff: Enter on file in Source Control, or F7 in an open diff
2. Alt+F2 to open Accessible Diff Viewer
3. Navigate with Up/Down Arrow (line by line)
4. Use H key to jump between hunks (each hunk has a heading)
5. Escape to close and return to editor

VoiceOver

1. VO+Arrow to navigate to diff file → VO+Space to open
2. Option+F2 for Accessible Diff Viewer
3. VO+Arrow keys to navigate lines
4. VO+Command+H to jump between hunk headings
5. Escape to close

Understanding Context Lines

The diff shows 3 unchanged lines before and after each change for context. These are announced as "Unchanged: [content]".

Example

Hunk 1 of 3 - lines 42-48

  Unchanged: ## Screen Reader Setup
  Unchanged:
- Removed: This guide covers NVDA only.
+ Added: This guide covers NVDA, JAWS, and VoiceOver.
  Unchanged:
  Unchanged: ### Installing NVDA

The unchanged lines help you understand where in the file the change occurred.

Inline Diff View vs Side-by-Side

Inline view (recommended for screen readers)

• All changes in a single editor
• Removed lines followed by added lines
• Easier to navigate with screen reader reading commands

Side-by-side view (default, visual)

• Left panel: original file
• Right panel: modified file
• Requires navigating between panels

To switch to inline view

1. Open Settings: Ctrl+,
2. Search: "diffEditor.renderSideBySide"
3. Uncheck the box (or set to false in settings.json)

4. Screen Reader-Specific Configurations

NVDA Configuration for VS Code

Recommended NVDA settings

1. Browse Mode settings:

   • NVDA Menu → Preferences → Settings → Browse Mode
   • "Maximum length of text on a single line": 10000
   • "Automatic focus mode for focus changes": Checked
   • "Automatic focus mode for caret movement": Unchecked

2. Object Presentation:

   • "Report tooltips": Unchecked (reduces interruptions; use Alt+F2 instead)
   • "Report notifications": Checked
   • "Report object descriptions": Checked

3. Speech settings:

   • "Punctuation/symbol level": Some or Most (for code reading)
   • "Automatic language switching": Checked (useful for multilingual docs)

4. Input Composition:

   • "Announce candidates during IME text composition": Checked

NVDA add-ons for VS Code

• Focus Highlight - shows focus location visually (helpful for sighted trainers)
• IndentNav - navigate by indentation level (useful for Python, YAML)

VS Code-specific NVDA commands

JAWS Configuration for VS Code

Recommended JAWS settings

1. Settings Center → HTML/PDF/Accessibility:

   • "Auto Forms Mode": Checked
   • "ARIA Live Region Verbosity": Polite or Assertive (depending on preference)
   • "Report tooltip text": Unchecked (use Alt+F2 instead)

2. Settings Center → Reading:

   • "Punctuation Level": Most (for code)
   • "Speak Long Lines Continuously": Yes

3. Settings Center → Text Processing:

   • "Blank Line Announcement": Tone (less verbose than speech)

JAWS scripts for VS Code

Custom JAWS scripts exist for VS Code. Check: jaws-vscode-scripts (GitHub) for community-maintained scripts.

VS Code-specific JAWS commands

VoiceOver Configuration for VS Code (macOS)

Recommended VoiceOver Utility settings

1. Verbosity → Text:

   • "Punctuation": All (for code and Markdown)
   • "Capitalization": Speak cap (useful for acronyms and code)
   • "Reading Units": Set to sentenceboundary for prose, word for code

2. Verbosity → Announcements:

   • "Content Changes": On (for live regions like Copilot Chat)
   • "Status Messages": On

3. Navigation:

   • "Quick Nav": OFF when inside editor (use Left+Right Arrow to toggle)
   • "Auto-interact with elements": Off (manual control preferred)

4. Sound:

   • "Enable positional audio": On (helps orient focus location)
   • "Mute sound effects": Off (audio cues are helpful)

VS Code-specific VoiceOver commands

Quick Nav navigation (when enabled)

Note: Quick Nav should be OFF when editing text (conflicts with text navigation).

5. Complete Keyboard Shortcuts

For screen reader navigation shortcuts when using GitHub in a browser (NVDA, JAWS, VoiceOver), see Appendix B - Screen Reader Cheat Sheet.

Global Navigation

Sidebar Panels

Editor - File Operations

Editor - Navigation

Editor - Editing

Editor - Find and Replace

Editor - Multi-Cursor

Terminal

Source Control (Git)

Diff Viewer

Copilot

Accessibility Features

Problems Panel

Markdown Preview

6. Accessibility Signals Types and Customization

Accessibility signals are events that trigger announcements or audio cues. Beyond audio cues, VS Code has verbal announcements for various events.

Announcement Verbosity Settings

Control how much information VS Code announces:

verbose: Announces full context and details
minimal: Announces only essential information
off: No automatic announcements (use Accessible View manually)

Custom Announcement Timing

Control when and how often announcements occur:

Signal Priorities

When multiple signals occur simultaneously, VS Code prioritizes them:

1. Errors (highest priority) - always announced
2. Warnings - announced after errors
3. Completions - announced if no errors/warnings
4. Focus changes - announced last

This prevents overlapping announcements.

7. Settings.json Configuration Examples

The configuration examples below are JSON blocks you paste into your settings.json file. To apply a complete set at once, consider using VS Code Profiles -- named configuration bundles that let you switch your entire setup instantly. See Chapter 5, Section 9: Profiles for how to create, switch, export, and share profiles.

Minimal Screen Reader Profile

For users who prefer minimal announcements and use Accessible View manually

{
  "editor.accessibilitySupport": "on",
  "editor.minimap.enabled": false,
  "editor.renderWhitespace": "none",
  "editor.wordWrap": "on",
  "diffEditor.renderSideBySide": false,
  "accessibility.verbosity.diffEditor": "minimal",
  "accessibility.verbosity.editor": "minimal",
  "accessibility.verbosity.hover": "minimal",
  "accessibility.verbosity.inlineCompletions": "minimal",
  "accessibility.signals.lineHasError": "on",
  "accessibility.signals.taskCompleted": "on",
  "accessibility.signals.taskFailed": "on"
}

Maximum Feedback Profile

For users who want all audio and verbal announcements

{
  "editor.accessibilitySupport": "on",
  "editor.minimap.enabled": false,
  "editor.renderWhitespace": "none",
  "editor.wordWrap": "on",
  "diffEditor.renderSideBySide": false,
  "accessibility.verbosity.diffEditor": "verbose",
  "accessibility.verbosity.editor": "verbose",
  "accessibility.verbosity.hover": "verbose",
  "accessibility.verbosity.inlineCompletions": "verbose",
  "accessibility.verbosity.terminal": "verbose",
  "accessibility.signals.lineHasError": "on",
  "accessibility.signals.lineHasWarning": "on",
  "accessibility.signals.taskCompleted": "on",
  "accessibility.signals.taskFailed": "on",
  "accessibility.signals.diffLineInserted": "on",
  "accessibility.signals.diffLineDeleted": "on",
  "accessibility.signals.chatResponseReceived": "on",
  "accessibility.signals.chatResponsePending": "on",
  "accessibility.signals.save": "on",
  "accessibility.signals.clear": "on",
  "accessibility.signals.format": "on",
  "accessibility.signals.terminalBell": "on",
  "accessibility.signals.terminalCommandFailed": "on",
  "terminal.integrated.enableBell": true
}

Copilot-Optimized Profile

For users working heavily with GitHub Copilot

{
  "editor.accessibilitySupport": "on",
  "editor.minimap.enabled": false,
  "editor.wordWrap": "on",
  "accessibility.verbosity.inlineCompletions": "minimal",
  "accessibility.verbosity.panelChat": "minimal",
  "accessibility.signals.lineHasInlineSuggestion": "on",
  "accessibility.signals.chatResponsePending": "on",
  "accessibility.signals.chatResponseReceived": "on",
  "accessibility.signals.chatRequestSent": "on",
  "github.copilot.enable": {
    "*": true,
    "yaml": true,
    "plaintext": false,
    "markdown": true
  }
}

Note: The github.copilot.enable object controls which file types get Copilot suggestions.

Git/Diff-Optimized Profile

For users doing heavy PR review and diff work

{
  "editor.accessibilitySupport": "on",
  "diffEditor.renderSideBySide": false,
  "diffEditor.ignoreTrimWhitespace": true,
  "diffEditor.wordWrap": "on",
  "diffEditor.diffAlgorithm": "advanced",
  "accessibility.verbosity.diffEditor": "verbose",
  "accessibility.signals.diffLineInserted": "on",
  "accessibility.signals.diffLineDeleted": "on",
  "accessibility.signals.diffLineModified": "on",
  "scm.diffDecorations": "gutter",
  "scm.diffDecorationsGutterWidth": 2
}

Performance-Optimized Profile

For users on slower machines or with large repositories

{
  "editor.accessibilitySupport": "on",
  "editor.minimap.enabled": false,
  "editor.renderWhitespace": "none",
  "editor.guides.indentation": false,
  "editor.guides.bracketPairs": false,
  "editor.occurrencesHighlight": false,
  "editor.selectionHighlight": false,
  "editor.hover.enabled": true,
  "editor.hover.delay": 1000,
  "files.exclude": {
    "**/.git": true,
    "**/.svn": true,
    "**/.hg": true,
    "**/CVS": true,
    "**/.DS_Store": true,
    "**/node_modules": true,
    "**/.vscode": false
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/bower_components": true,
    "**/*.code-search": true
  }
}

Quick Copy: Complete Recommended Settings

Paste this into your settings.json for a balanced screen reader profile

{
  "editor.accessibilitySupport": "on",
  "editor.minimap.enabled": false,
  "editor.renderWhitespace": "none",
  "editor.wordWrap": "on",
  "diffEditor.renderSideBySide": false,
  "diffEditor.ignoreTrimWhitespace": true,
  "diffEditor.wordWrap": "on",
  "accessibility.verbosity.diffEditor": "verbose",
  "accessibility.verbosity.editor": "verbose",
  "accessibility.verbosity.hover": "verbose",
  "accessibility.verbosity.inlineCompletions": "minimal",
  "accessibility.verbosity.panelChat": "minimal",
  "accessibility.signals.lineHasError": "on",
  "accessibility.signals.lineHasWarning": "auto",
  "accessibility.signals.taskCompleted": "on",
  "accessibility.signals.taskFailed": "on",
  "accessibility.signals.diffLineInserted": "on",
  "accessibility.signals.diffLineDeleted": "on",
  "accessibility.signals.chatResponseReceived": "on",
  "terminal.integrated.enableBell": true,
  "workbench.editor.enablePreview": false
}

Back to: VS Code Setup & Accessibility Basics | GitHub Copilot | Accessibility Agents
Related: Appendix B: Screen Reader Cheat Sheet