This guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.
Before starting this chapter, verify you have completed:
- Chapter 5: Working with Pull Requests - Understand PR structure, diffs, and comment workflows
- Chapter 13: GitHub Copilot - VS Code installed and configured
- Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use
- Access to at least one pull request to review (your own fork or a practice repo)
Estimated time for this chapter: 1 hour (including exercises)
You can review pull requests in two places - each with different strengths:
| Environment | Best For | Key Accessibility Feature |
|---|---|---|
| GitHub web (browser) | Quick reviews, inline comments on any machine | New Files Changed Experience + keyboard navigation |
| VS Code | Deep reviews, large diffs, local context | Accessible Diff Viewer (F7) |
Both environments give you full keyboard and screen reader access. Your choice depends on context, not accessibility.
As of January 2026, GitHub's improved Files Changed experience is enabled by default. The instructions below assume you have the modern interface (which you do).
If the interface seems different from what's described here, clear your browser cache and reload the page.
From any pull request page:
Visual / mouse users
Click the Files changed tab at the top of the PR page. The tab label shows the number of changed files (e.g., "Files changed 4").
Screen reader users (NVDA / JAWS)
Press D → navigate to "Pull request navigation tabs" landmark
Press → or Tab → find "Files changed" link → Enter
The tab label announces the number of changed files: "Files changed, 4 files changed"
Screen reader users (VoiceOver - macOS)
VO+U → Landmarks → navigate to "Pull request navigation tabs"
VO+Right or Quick Nav K → find "Files changed" link → VO+Space
VoiceOver announces the number of changed files: "Files changed, 4 files changed"
The file tree panel lists every changed file. Before reading any diff, scan this list to understand the scope of the PR.
Visual / mouse users
The file tree is the left panel on the Files Changed page. Each file shows its name and a +N / -N badge (lines added/removed). Click any filename to scroll directly to its diff.
Screen reader users (NVDA / JAWS)
Press D → navigate to "File tree" region
Press ↓ to move through files
Each file reads: "[filename] - [N additions, N deletions]"
Press Enter on a file to scroll its diff into view
Screen reader users (VoiceOver - macOS)
VO+U → Landmarks → navigate to "File tree" region
VO+Down to move through files
Each file reads: "[filename] - [N additions, N deletions]"
VO+Space on a file to scroll its diff into view
What to listen for / look for:
- How many files changed?
- Which areas of the codebase are affected?
- Are there unexpected files (generated files, lock files, configuration changes)?
Each changed file in the main area is an h3 heading containing the filename.
Visual / mouse users
Scroll through the page or click a filename in the file tree on the left. Collapsed files can be expanded by clicking the file header.
Screen reader users (NVDA / JAWS)
Press 3 to jump file-by-file through the diff
Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"
Press Enter or Space to expand a collapsed file
If a diff is very long, the file tree is usually faster than pressing 3 repeatedly.
Screen reader users (VoiceOver - macOS)
Quick Nav H or VO+Cmd+H to jump file-by-file through the diff
Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"
VO+Space to expand a collapsed file
If a diff is very long, the file tree is usually faster than using heading navigation.
Each file's diff is a table. Every row is one line of code.
Visual / mouse users
- Green highlighted lines (with a
+) = lines added - Red highlighted lines (with a
-) = lines removed - Plain/white lines = unchanged context
- Use
Ctrl+Fto search within the page for specific text in the diff
Screen reader users - NVDA
Press T to jump to the diff table → Insert+Space (Focus Mode)
Press ↓ to move through lines one at a time
Press Ctrl+Alt+→ to read across columns: [line number] | [change type] | [code content]
Screen reader users - JAWS
Press T to jump to the diff table → Insert+Z (Virtual PC Cursor off)
Press ↓ to move through lines
Press Ctrl+Alt+→ for column-by-column reading
Screen reader users - VoiceOver (macOS)
Press T or VO+U → Tables → select the diff table
VO+Shift+↓ to enter the table
VO+→/← to navigate columns, VO+↑/↓ to navigate rows
What each line announces / shows:
- Added lines:
"+ [code content]"- or announced as "inserted" - Removed lines:
"- [code content]"- or announced as "deleted" - Context lines: code without a
+or-
Tip: If the code on a line is very long, the screen reader will read the full line. For minified or generated files, consider collapsing the file in the tree and skipping it.
When you have a specific observation about a particular line, place an inline comment directly on it.
Visual / mouse users
- Hover your mouse over a line in the diff - a blue
+(comment) button appears on the left - Click it to open the inline comment box
- Type your comment
- Click "Start a review" (not "Add single comment" - see note below)
Screen reader users (NVDA / JAWS)
Step 1: Navigate to the target line in the diff table (see Step 4)
Step 2: While focused on that line, press Tab → look for a comment button
Step 3: Alternatively: press B to navigate buttons → look for "Add a comment to this line"
Step 4: Press Enter to open the inline comment box
Step 5: Insert+Space (NVDA) or Insert+Z (JAWS) → switch to Focus Mode
Step 6: Type your comment
Step 7: Tab to "Start a review" button (not "Add single comment" - see note below)
Step 8: Press Enter
Screen reader users (VoiceOver - macOS)
Step 1: Navigate to the target line in the diff table (see Step 4)
Step 2: While focused on that line, Tab → look for a comment button
Step 3: Alternatively: Quick Nav B → look for "Add a comment to this line"
Step 4: VO+Space to open the inline comment box
Step 5: VO+Shift+Down to interact with the text area
Step 6: Type your comment
Step 7: VO+Shift+Up to stop interacting → Tab to "Start a review" button
Step 8: VO+Space
Why "Start a review" instead of "Add single comment": A single comment posts immediately and sends a notification for each one. "Start a review" batches all your comments and sends one notification when you submit - far less disruptive for the author.
Placing a multi-line comment:
Visual / mouse users
Click and drag across multiple line numbers in the diff gutter to select a range. A comment button appears for the selected range.
Screen reader users (NVDA / JAWS)
Step 1: Navigate to the first line of the range
Step 2: Press Shift+↓ to extend selection to additional lines
Step 3: A comment button appears for the selected range
Step 4: Proceed as above
Screen reader users (VoiceOver - macOS)
Step 1: Navigate to the first line of the range
Step 2: Shift+↓ to extend selection to additional lines
Step 3: A comment button appears for the selected range
Step 4: VO+Space to activate, then proceed as above
Inline comments from other reviewers appear as h3 headings within the diff table. Each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button.
Visual / mouse users
Comments appear inline within the diff as collapsible cards. Click "Reply…" to add to a thread. Click "Resolve conversation" to mark a thread done (requires write access).
Screen reader users (NVDA / JAWS)
Navigate them with 3 (jump to h3 headings in the diff).
To add to a thread:
Step 1: Navigate to the thread heading (3)
Step 2: Tab to "Reply…" link
Step 3: Enter → text area appears → Focus Mode → type reply
Step 4: Ctrl+Enter to submit the reply
To mark a thread as resolved (if you have write access):
Tab to the "Resolve conversation" button → Enter
Screen reader users (VoiceOver - macOS)
Navigate with Quick Nav H or VO+Cmd+H (jump to headings in the diff).
To add to a thread:
Step 1: Quick Nav H to navigate to the thread heading
Step 2: Tab to "Reply…" link
Step 3: VO+Space → text area appears → VO+Shift+Down → type reply
Step 4: Cmd+Return to submit the reply
To mark a thread as resolved (if you have write access):
Tab to the "Resolve conversation" button → VO+Space
After adding all inline comments:
Visual / mouse users
- Click the "Review changes" button (top-right of the Files Changed page or bottom of the PR)
- A dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes
- Optionally type an overall summary in the text area
- Select your verdict
- Click "Submit review"
Screen reader users (NVDA / JAWS)
Step 1: Press D → navigate to "Pull request navigation tabs"
Step 2: Press ← to return to the Conversation tab → Enter
Step 3: Scroll to the bottom (End key, or ↓ repeatedly)
Step 4: Alternatively: press B repeatedly → find "Review changes" button
Step 5: Press Enter to open the review summary dialog
Step 6: Focus Mode → type your overall comment
Step 7: Tab to the radio button group → ↑/↓ to select a verdict
Step 8: Tab to "Submit review" button → Enter
Screen reader users (VoiceOver - macOS)
Step 1: VO+U → Landmarks → navigate to "Pull request navigation tabs"
Step 2: VO+Left to return to the Conversation tab → VO+Space
Step 3: VO+End or VO+Down to reach the bottom of the page
Step 4: Alternatively: Quick Nav B → find "Review changes" button
Step 5: VO+Space to open the review summary dialog
Step 6: VO+Shift+Down → type your overall comment
Step 7: VO+Shift+Up → Tab to the radio button group → VO+Left/Right to select a verdict
Step 8: Tab to "Submit review" button → VO+Space
Verdicts and their meaning:
| Verdict | When to use |
|---|---|
| Comment | You have observations but no strong position; does not block merge |
| Approve | You've reviewed and are satisfied; signals readiness to merge |
| Request changes | Changes are needed before this should merge; blocks merge |
After you address review comments on your own PR:
Visual / mouse users
Look in the right sidebar for the Reviewers section. Click the re-request icon (circular arrows) next to the reviewer's name to notify them that you've pushed changes.
Screen reader users (NVDA / JAWS)
Step 1: From your PR's Conversation tab, find the reviewer's name in the sidebar (3 → "Reviewers" heading)
Step 2: Activate the refresh/re-request icon next to their name
Step 3: This re-notifies the reviewer that you've made changes
Screen reader users (VoiceOver - macOS)
Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar
Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name
Step 3: VO+Space to activate - this re-notifies the reviewer that you've made changes
When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers.
If you have the GitHub Pull Requests extension:
- Open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request")
- Find the PR and open it - changed files appear in the file tree
- Navigate to any file in the tree and press
Enterto open its diff view
Without the extension, any git diff operation also opens the diff editor.
From any open diff editor:
Press F7 → Accessible Diff Viewer opens as a panel below the diff
The Accessible Diff Viewer reads each change as a structured block:
"Changed lines 14 to 14 in keyboard-shortcuts.md
[Change 1 of 3]
Removed:
#### NVDA Single-Key Navigation
Added:
### NVDA Single-Key Navigation"
Navigation:
F7- jump to next change (next hunk)Shift+F7- jump to previous changeAlt+F2- open VS Code's Accessible View for additional context on the current itemEscape- close the Accessible Diff Viewer
What makes this better than the raw diff editor:
- Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels
- You hear the change number of total changes ("Change 3 of 12")
- No table navigation required - purpose-built for sequential listening
- Works with all three major screen readers without any special configuration
From the diff editor with the GitHub PR extension:
Step 1: In the diff gutter, navigate to the line you want to comment on
Step 2: Ctrl+Shift+P → "GitHub Pull Requests: Add Comment"
Step 3: Or press Shift+F10 (Windows) or Control+Return (macOS) on the line → context menu → "GitHub Pull Requests: Add Comment"
Step 4: A text area opens - type your comment
Step 5: Submit from the inline UI
Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification.
A comment that helps the author is:
- Specific - link to the exact line and name the pattern you see
- Educational - say why something matters, not just what to change
- Graduated - signal whether this is blocking, or a preference
Blocking example:
"The heading on line 34 jumps from
##(level 2) to####(level 4), skipping heading level 3. Screen reader users who navigate by heading level will miss any content between those two levels. Please change####to###before this merges."
Non-blocking (nit) example:
"nit: The link text on line 22 reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. 'See the accessibility setup guide' would be clearer. Not blocking."
Question example:
"The PR description says this improves keyboard navigation of the shortcut table, but I only see a heading change in the diff. Am I missing a related file, or is the keyboard improvement a side effect of fixing the heading? Happy to re-review once I understand."
Using shorthand prefixes helps authors parse many comments quickly:
| Prefix | Meaning |
|---|---|
nit: |
Non-blocking stylistic preference |
question: |
Genuine question; not blocking |
suggestion: |
Alternative to consider; take it or leave it |
important: |
Should be addressed; may block |
blocking: |
Must be addressed before merge |
praise: |
Positive callout - works well, good pattern |
There is no hard limit, but quantity without prioritization is noise. If you have 15 comments, make clear which 2-3 are blocking. Authors can then focus energy on what matters most and address preferences in follow-up PRs.
| Action | Key |
|---|---|
| Navigate to Files Changed tab | D → PR tabs landmark → → → Enter |
| Jump between file diffs | 3 |
| Navigate diff lines (NVDA/JAWS) | Focus Mode + ↓ |
| Read across diff columns | Ctrl+Alt+→ |
| Open inline comment box | Line focused → B → comment button |
| Submit entire review | D → Conversation → B → "Review changes" |
| Navigate existing threads | 3 |
| Reply to a thread | 3 → thread → Tab → "Reply" → Enter |
| Action | Key |
|---|---|
| Open Accessible Diff Viewer | F7 |
| Next change (hunk) | F7 |
| Previous change (hunk) | Shift+F7 |
| Open Accessible View | Alt+F2 |
| Accessible Help (any widget) | Alt+H |
| Close Accessible Diff Viewer | Escape |
1. File tree → count the files, read the names
2. 3 → navigate each file heading → listen to the stats line (N additions, N deletions)
3. For each file: skim with T → Focus Mode → ↓ through lines
4. If a file feels unrelated: leave a comment on the first line of that file
1. In VS Code: open the file → Ctrl+G → jump to the section's line number
2. F7 → Accessible Diff Viewer → listen for changes near that line
3. Or on GitHub: file tree → expand that file → T → navigate the diff table
1. Go to the Commits tab (D → PR tabs → "Commits" → Enter)
2. 3 to navigate commits - find any commits after your last review
3. Press `Enter` on the commit to see only what changed in that push (not the full diff)
1. Read the full thread (3 → navigate to the thread heading)
2. Tab to the "Reply" button
3. Ask: "Can you clarify what change you're suggesting? I want to understand before I act on this."
4. Or: reference a specific line in your reply using the line number
These exercises use the files in learning-room/docs/ in this repository. All examples involve documentation changes - no code required.
Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. Your job is to review it before it merges.
What You'll Learn: How to use screen reader heading navigation to spot accessibility issues in a GitHub PR diff.
What to do:
- Open GitHub in your browser and navigate to the workshop repository (
github.com/[your-fork]/[workshop-repo]orcommunity-access/accessibility-agents) - Click the Pull Requests tab (top navigation)
- Look for a PR titled "Add screen reader tips to the setup guide" - click it to open
- You should now see the PR page with sections: Conversation, Commits, Files Changed
How to know you're in the right place:
- The PR title is visible at the top
- You see a description box with text about what this PR does
- You see tabs labeled "Conversation," "Commits," "Files Changed"
If you can't find the PR:
- Use
Ctrl+Fto search the PR list for "screen reader tips" - Or ask in the workshop Slack - someone can share the exact URL
What to do:
- You are currently on the Conversation tab
- Read the PR description (the text immediately under the PR title)
- Look for: "What does this PR change?" and "Why does it change it?"
- With screen reader: Navigate to the description with
D(NVDA) or pressCtrl+Option+Up(VoiceOver) to find main landmarks, then read the content region
What to look for:
- Does the PR author explain what file changed? (should mention
setup-guide.md) - Does it explain why? (should mention "improve accessibility" or "add tips")
- Is it clear enough that a reviewer can understand the goal without reading the diff?
What success looks like:
- You can answer: "This PR adds [specific content] to [specific file] because [clear reason]"
- Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance"
What to do:
- Click the Files Changed tab (top of the PR page, to the right of "Commits")
- You are now viewing the diff
- With keyboard (all screen readers): Press
Tto jump to the diff table. The page focuses on the file comparison area.
What you should see:
- A section showing the file name
setup-guide.mdwith a small badge showing "+20 −0" (20 lines added, 0 lines removed) - Below it, the diff with removed lines (preceded by
−) and added lines (preceded by+)
If you see multiple files:
- Scroll up to see if there are other files. For this exercise, only
setup-guide.mdshould be changed. - If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes)
What to do:
- Look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area)
- With keyboard: Press
Fto toggle Focus Mode (may need to be in the diff area first) - With mouse: Click the Focus Mode button/icon
What happens in Focus Mode:
- The page simplifies: sidebars disappear
- Only the diff is visible - easier for screen reader navigation and less cognitive load
- The diff is now the main content area
With screen reader (once in Focus Mode):
- NVDA/JAWS: Press
Tto jump to the diff table - VoiceOver: Navigate with
VO+Right Arrowto find the table/content region - Read through the changes:
↓arrow moves to each line
What to do:
- Read through the entire diff line by line. Pay special attention to lines starting with
# - You are looking for: a line with
####(four hashes, heading level 4) that comes directly after a##(two hashes, heading level 2) - When you find it, note the exact line number shown in the diff
Example of what you're looking for:
## Setup Basics ← Heading level 2
...several lines...
#### Advanced Tips ← Heading level 4 (skipped level 3!)
Why this matters:
- Screen reader users navigate documents by heading level:
1→2→3→4 - A skip from
##to####breaks that navigation - When a user presses "jump to heading level 3," they'll find none, wondering if content is missing
What success looks like:
- You found the line with
####that violates hierarchy - You can say the line number and what heading text appears there
- You understand why this is an accessibility problem
What to do:
- Find the diff line with the problematic
####heading - Hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table)
- A button should appear (or press the Add Comment hotkey - usually
Cin GitHub) - Click it or press
Enterto open a comment box
In the comment box:
- Type:
blocking:(tells reviewers this stops the PR from merging) - Press Space, then explain:
Heading hierarchy violation. This heading uses #### (level 4) directly after ## (level 2), skipping level 3. Screen reader users navigating by heading level will miss this section. Change to ### (level 3). - Click the Comment button (or press
Ctrl+Enterfor keyboard submit)
What happens next:
- Your comment appears in the thread under that line
- The PR author sees it and can make the fix
If the comment button doesn't appear:
- Make sure you're hovering over the line number area (left side of the line)
- Try refreshing the page and trying again
- Or use the "Add a reply" field at the bottom of the PR and mention the line number manually
What to do:
- Continue reading the diff (from where you left off)
- Look for a line containing link text that reads
"click here"or"click here for more information" - Note the line number
Why this matters:
- Screen reader users can ask their reader to "list all links on this page" - they hear only the link text
- If the text is "click here," they have no context about where it goes
- Descriptive link text is WCAG 2.4.4 (Link Purpose)
What success looks like:
- You found a link with non-descriptive text
- You can explain why "click here" is bad and what would be better
What to do:
- Find the line in the diff with the problematic link
- Hover over the line number and click to open a comment box (or press
C) - Type:
nit: Link text "click here" is not descriptive. Screen reader users who list links won't know the context. Suggest: "Read the accessibility checklist" or another descriptive phrase. - Click Comment or press
Ctrl+Enter
Note: nit: means "nice-to-have improvement" (not blocking, but good to fix)
What to do:
- Look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments)
- Click it (or navigate with keyboard and press
Enter) - A dialog appears with options:
- Comment - provide feedback but don't block (for minor notes)
- Approve - the PR is ready to merge
- Request changes - this PR cannot merge until changes are made
For this exercise:
- Select "Request changes" (you found two things to fix)
- In the summary field, write:
Found 2 accessibility issues that must be fixed before merging. - Click "Submit review"
What happens:
- Your review is submitted
- The PR author gets a notification
- The PR shows your review with the two comments
- GitHub blocks merging until the author responds to or fixes the changes
What success looks like:
- You see your review appear on the PR page
- It shows 2 comments you made
- The PR status shows "Changes requested"
After submitting, answer:
- Did heading-level navigation help? When you were looking for the
####issue, was it easier to navigate by heading level (1-6) than to scan every line? - Would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious?
- Why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document.
Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review.
Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. You'll compare the browser experience with the VS Code experience.
What You'll Learn: How the VS Code Accessible Diff Viewer announces changes differently than the browser diff, and when each environment is most useful.
Before starting:
- VS Code must be installed on your machine
- The GitHub Pull Requests extension must be installed (see Chapter 12 for installation)
- You must be signed into GitHub from VS Code (use
Ctrl+Shift+P→ "GitHub: Sign in")
What to do:
- Open VS Code
- With keyboard (all screen readers): Press
Ctrl+Shift+Xto open the Extensions sidebar- With mouse: Click the Extensions icon on the left sidebar (looks like four squares)
- Search for "GitHub Pull Requests"
- If it's not installed, click Install
- If it is installed, click GitHub Pull Requests to view its details
What you should see:
- The extension is listed as active
- It mentions: "Review and manage GitHub pull requests and issues"
What to do:
- Look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it
- With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3
- A sidebar appears showing open pull requests on repositories you have access to
- Find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list
- Click it to open
What happens:
- VS Code opens a new editor tab for this PR
- Below the PR title, you see a "Changes" section listing modified files
- You should see
setup-guide.mdin the changes list
If you can't find the PR:
- Use
Ctrl+Shift+P→ searchGitHub Pull Requests: Open Pull Request - Paste the PR URL:
https://github.com/[owner]/[repo]/pull/[number] - Press Enter
What to do:
- In the Changes section, locate
setup-guide.md - Click on the filename to open it
What happens:
- A diff editor opens showing two columns:
- Left: the original file (before changes)
- Right: the new file (after changes)
- Different colors show added (green), removed (red), and modified (blue) lines
- The file name appears at the top:
setup-guide.md
With screen reader:
- NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md"
- Use
Ctrl+Hometo jump to the start of the diff - Use
Ctrl+Endto jump to the end
What to do:
- With keyboard: Press
F7to open the Accessible Diff Viewer- With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff"
- If no button is visible, try
Alt+F2(VS Code Accessible View toggle)
What happens:
- A new panel opens at the bottom of VS Code
- The panel announces each change one at a time
- Changes appear in text format with labels: "Added: " and "Removed: "
- The panel is read-only (you read the changes, you don't edit here)
If the Accessible Diff Viewer doesn't open:
- Make sure the diff editor is active (click in the diff area first)
- Try
Ctrl+Shift+P→ searchOpen Accessible Diff - If available, select it
What to do:
- The first change is automatically announced when you open the Accessible Diff Viewer
- Let your screen reader read it completely - don't interrupt
- Write down the exact text announced:
Removed: [write what the viewer said] Added: [write what the viewer said] - Press the Down arrow to move to the next change
What to expect (example):
Removed: ## Old Heading
Added: ## New Heading with More Details
With screen reader:
- NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content
- VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords
What to do:
- Continue pressing Down arrow to move through changes
- Listen carefully for a change involving headings (lines starting with
#) - Specifically, listen for: "Added: ####" (four hashes)
- When you hear this, stop and write it down:
Line number: [if available] Removed: [what was removed, if anything] Added: [the four-hash heading] Context: [is there a ## heading just before this?]
Why listen for this?
- Four hashes (
####) indicate a level 4 heading - In the diff, you're looking for it appearing after a level 2 heading (
##) - This creates the hierarchy skip you caught in Exercise A
What success looks like:
- You found the explanation in the Accessible Diff Viewer's format
- You can explain: "The added line with
####directly follows a##, skipping level 3" - The Accessible Diff Viewer made this pattern clearer than scanning raw
+characters
What to do:
- Once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press
F7again orAlt+F2) - You're back in the regular Diff Editor
- Find the line with the problematic
####heading:- Use
Ctrl+Fto open Find - Search for
####to locate it quickly - Press
Enterto jump to it
- Use
- Close Find (
Escape) - Place your cursor on that line
- Right-click and select "Add Comment" or press the Comment icon that appears on the left margin
- With keyboard: The comment button may appear on the current line; navigate to it and press
Enter
- With keyboard: The comment button may appear on the current line; navigate to it and press
What happens:
- A comment box opens
- You can type your comment
What to do:
- In the comment box, type:
blocking: Heading hierarchy violation. The Accessible Diff Viewer clearly showed this #### heading appearing directly after ##, skipping level 3. Screen reader users navigating by heading level will miss this content. Change to ###. - Press
Ctrl+Enteror click Comment to submit
Why mention the Accessible Diff Viewer?
- It shows that the tool itself helps you see the issue
- It documents how you caught the problem (useful for learning)
Special Section: Comparing Tools
Now you've reviewed the same PR in:
- Browser (Exercise A): You spot-checked line numbers manually
- VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes
What to do:
- Go to GitHub in your browser and open the same PR
- Scroll to the bottom and leave a comment in the Conversation tab:
I've now reviewed this PR in both the browser and VS Code. Here's
what I found:
**Browser review:** I had to manually navigate with heading commands
and scan for the skip visually. Found 2 issues.
**VS Code + Accessible Diff Viewer:** The Accessible Diff Viewer
announced changes in a linear format, making it easier to follow
the story of what changed without scanning back and forth.
**My conclusion:** [Choose one]
- The browser method was clearer for me
- VS Code was clearer for me
- Both have strengths; I'd use each for different purposes
- Browser best for: [specific reason]
- VS Code best for: [specific reason]
- Click Comment
After completing Steps 1-9, answer:
- Announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading
+and−prefixes in the browser? - Navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change?
- When would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool.
Record your answers. In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes.
Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings.
What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.
Before writing your reflection, collect all the information you gathered:
From Exercise A (Browser Review):
- Which line number had the heading hierarchy skip?
- Which line number had the link text issue?
- How many steps did it take to find each issue?
- Did you use screen reader commands or visual scanning more?
From Exercise B (VS Code Review):
- What did the Accessible Diff Viewer announce for the heading change?
- Was the announcement clearer than the browser's
+and−format? - Did you need to switch between the Accessible Diff Viewer and the regular editor?
- How many steps to find the problem?
Write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.
What to do:
- Go to GitHub in your browser
- Open the same PR ("Add screen reader tips to the setup guide")
- Scroll to the Conversation tab
- Scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment")
- Click in the comment box
What you should see:
- A text editing area with formatting options (Bold, Italic, Link, etc.)
- A Comment button below the text area
What to do: Type your response to these three questions. Be specific - reference exact tools, steps, and what you discovered:
Question 1: Environment Preference
After reviewing this PR in both environments, my preferred tool was:
[Browser / VS Code / Both equally]
Why: [1-2 sentences explaining your choice]
Example: "I preferred VS Code because the Accessible Diff Viewer
separated changes into 'Added:' and 'Removed:', making it obvious
what the new content was. In the browser, I had to mentally filter
the + and − characters."
Question 2: Strengths of Each Environment
Browser made this easier: [One specific task, e.g., "Finding the PR URL"]
because [Why]
VS Code made this easier: [One specific task, e.g., "Following the diff linearly"]
because [Why]
Example Browser: "Finding context about *why* the change was made,
because all the discussion is in one place"
Example VS Code: "The Accessible Diff Viewer announcing changes sequentially
meant I didn't miss anything by accidentally scrolling past it"
Question 3: Real-World Impact
For someone reading the published document (not the diff), the heading
skip matters because: [1-2 sentences]
Example: "A screen reader user pressing the '3' key to navigate to level-3
headings will find none, and might think the document skipped a section.
This breaks the information hierarchy."
Full template to copy into the comment box:
## Code Review Reflection - Browser vs VS Code
After reviewing this PR using both the browser and VS Code environments,
here's what I found:
### Environment Preference
My preferred tool was: **[Browser / VS Code]**
Why: [1-2 sentences]
### Specific Strengths
**Browser made this easier:**
- Task: [specific thing]
- Why: [explanation]
**VS Code made this easier:**
- Task: [specific thing]
- Why: [explanation]
### Real-World Impact
The heading hierarchy skip in the published document matters because:
[1-2 sentences about why screen reader users would be affected]
What to do:
- Before submitting, re-read your comment using your screen reader or by reading aloud
- Ask yourself:
- Is it clear which tool I preferred?
- Did I explain why with concrete examples?
- Am I describing the real-world impact accurately?
- Would someone else reading this understand how I caught the issue?
- Make any corrections needed
- Do not submit yet - continue to Step 5
What to do:
- Locate the Comment button at the bottom right of the comment box
- With keyboard: Press
Tabuntil the Comment button is focused, thenEnter - With mouse: Click the Comment button
- Your comment is submitted and appears on the PR page
What happens:
- Your comment is now visible on the PR
- Other reviewers can see your comparison
- You have completed the three-part exercise series
What success looks like:
- Your comment appears on the PR thread
- It includes all three reflections
- The PR author and other reviewers can see your thought process
Before moving forward, verify you understand:
-
Heading Hierarchy: Can you explain in one sentence why a
##→####skip breaks screen reader navigation?- Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing."
-
Tool Strengths: For each tool you used, name one task it made easier.
- Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes."
-
Real-World Testing: How would you test the heading issue in the published document (not the PR diff)?
- Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4)."
If you can answer all three, you're ready for the next chapter.
Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation - are the foundation for understanding automated review.
In Chapter 16 (Accessibility Agents), you'll use the @pr-review agent to generate a draft review of this same PR. The agent will:
- Suggest changes automatically
- Identify accessibility issues
- Create a review checklist
But - and this is critical - the agent's suggestions will only make sense because you already know what to look for. You'll be able to:
- Verify the agent didn't miss anything
- Add context the agent can't see
- Decide whether the agent's suggestions are correct
That's the power of "manual skill first, agent second." You're building that skill right now.
Review at least two pull requests manually - using the techniques in this guide - before running
@pr-review. The agent generates a first-draft review: a line-numbered diff map, risk assessment, before/after snapshots, and suggested inline comments. Your job as reviewer is to read that draft, correct it, enrich it with context the diff cannot contain, and decide what is actually worth saying to the author.Once you have that manual foundation:
- In VS Code -
@pr-review review PR #Nproduces a structured, annotated review draft- In your repo - Accessibility Agents' review capabilities work in any repository you can access; fork
accessibility-agentsand those capabilities travel with your project- In the cloud - GitHub Agentic Workflows can auto-post PR summaries and accessibility impact assessments the moment a PR is opened, without anyone being online
The Accessible Diff Viewer teaches you to hear changes. The agent drafts the notes. You bring the judgment.
Next: Issue Templates Back: GitHub Copilot Related: Screen Reader Cheat Sheet | Merge Conflicts | Git & Source Control in VS Code