diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md
index bef5b9a8..254c3963 100644
--- a/ACCESSIBILITY.md
+++ b/ACCESSIBILITY.md
@@ -174,8 +174,6 @@ What has been checked:
These are the barriers we know about, what they mean for you, and what to do instead. Please [report any we have missed](#reporting-accessibility-issues).
- **Website testing is partial.** Keyboard, screen reader and manual visual checks of the website's core tasks 1 to 4 are [recorded](admin/ACCESSIBILITY_CORE_FLOWS.md), on Windows only. Not yet run: the accessibility bug report form (task 5), the ePub and braille downloads (task 6), VoiceOver on macOS, and Windows High Contrast. The manual check found two barriers: the breadcrumb is cut off at narrow widths and high zoom ([#280](https://github.com/Community-Access/git-going-with-github/issues/280)), and Chapter 05 uses abbreviations without spelling them out ([#279](https://github.com/Community-Access/git-going-with-github/issues/279)). Workaround for the breadcrumb: the same Home link is in the sidebar as "Workshop Home".
-- **The Quick Jumps links hide their focus outline.** On every chapter page, keyboard focus on the Quick Jumps links shows only an underline and a faint background, which is hard to see with low vision ([#265](https://github.com/Community-Access/git-going-with-github/issues/265)). Workaround: the same links are in the "On this page" list and the page headings, which show the normal outline.
-- **The site search box is named "Search documentation" but shows "Search docs".** Voice control users may need to say "Search documentation", or move to the field with Tab ([#266](https://github.com/Community-Access/git-going-with-github/issues/266)).
- **Some facilitator guides start headings with emoji**, which screen readers read aloud by name, and some code blocks do not say what they contain ([#264](https://github.com/Community-Access/git-going-with-github/issues/264), [#267](https://github.com/Community-Access/git-going-with-github/issues/267), [#268](https://github.com/Community-Access/git-going-with-github/issues/268)). Learner chapters are not affected by the emoji.
- **The braille files are machine translated.** They are produced automatically by liblouis from a plain-text version of the ePub, so tables are flattened into lines of text and print formatting is not converted to braille formatting. We have no record of review by a certified braille transcriber. Workaround: the ePub, Word or HTML version read with a refreshable braille display keeps the tables and headings.
- **Podcast episodes are companions, not readings.** Episodes use synthetic voices and summarize a chapter rather than reading it word for word. Every episode has a transcript, and the chapter itself is the complete source.
@@ -191,7 +189,7 @@ We publish accessibility progress here, every quarter and after each cohort, and
### October 2026: adopting the framework
- **Completed:** this document; a reworked [accessibility bug report form](https://github.com/Community-Access/git-going-with-github/issues/new?template=accessibility-bug.yml) with only two required fields and an email alternative; a full accessibility checklist in the pull request template; the documentation accessibility check in CI, with its first findings tracked in [#267](https://github.com/Community-Access/git-going-with-github/issues/267); fixes to a skipped heading level (Appendix Z), a second H1 (Appendix L), empty table headers on the registration pages, and a stray line above the title of CONTRIBUTING.md. Earlier in 2026: an EBAE braille file beside the UEB one ([#174](https://github.com/Community-Access/git-going-with-github/issues/174)), and Chapter 11's explanation of the VoiceOver "selection replaced" announcement ([#175](https://github.com/Community-Access/git-going-with-github/issues/175)).
-- **Remaining:** run and record the [core flow checks](admin/ACCESSIBILITY_CORE_FLOWS.md); fix the site template findings ([#265](https://github.com/Community-Access/git-going-with-github/issues/265), [#266](https://github.com/Community-Access/git-going-with-github/issues/266)); work through the recorded documentation findings ([#264](https://github.com/Community-Access/git-going-with-github/issues/264), [#268](https://github.com/Community-Access/git-going-with-github/issues/268)); find the cause of [#175](https://github.com/Community-Access/git-going-with-github/issues/175).
+- **Remaining:** run and record the [core flow checks](admin/ACCESSIBILITY_CORE_FLOWS.md); work through the recorded documentation findings ([#264](https://github.com/Community-Access/git-going-with-github/issues/264), [#268](https://github.com/Community-Access/git-going-with-github/issues/268)); find the cause of [#175](https://github.com/Community-Access/git-going-with-github/issues/175).
- **Known barriers:** see [Known limitations](#known-limitations).
- **How to help:** issues labeled [`accessibility`](https://github.com/Community-Access/git-going-with-github/issues?q=is%3Aopen+label%3Aaccessibility).
diff --git a/html/ACCESSIBILITY.html b/html/ACCESSIBILITY.html
index 46a2069c..cb976077 100644
--- a/html/ACCESSIBILITY.html
+++ b/html/ACCESSIBILITY.html
@@ -386,8 +386,6 @@ Known limitations
These are the barriers we know about, what they mean for you, and what to do instead. Please report any we have missed.
- Website testing is partial. Keyboard, screen reader and manual visual checks of the website's core tasks 1 to 4 are recorded, on Windows only. Not yet run: the accessibility bug report form (task 5), the ePub and braille downloads (task 6), VoiceOver on macOS, and Windows High Contrast. The manual check found two barriers: the breadcrumb is cut off at narrow widths and high zoom (#280), and Chapter 05 uses abbreviations without spelling them out (#279). Workaround for the breadcrumb: the same Home link is in the sidebar as "Workshop Home".
-- The Quick Jumps links hide their focus outline. On every chapter page, keyboard focus on the Quick Jumps links shows only an underline and a faint background, which is hard to see with low vision (#265). Workaround: the same links are in the "On this page" list and the page headings, which show the normal outline.
-- The site search box is named "Search documentation" but shows "Search docs". Voice control users may need to say "Search documentation", or move to the field with Tab (#266).
- Some facilitator guides start headings with emoji, which screen readers read aloud by name, and some code blocks do not say what they contain (#264, #267, #268). Learner chapters are not affected by the emoji.
- The braille files are machine translated. They are produced automatically by liblouis from a plain-text version of the ePub, so tables are flattened into lines of text and print formatting is not converted to braille formatting. We have no record of review by a certified braille transcriber. Workaround: the ePub, Word or HTML version read with a refreshable braille display keeps the tables and headings.
- Podcast episodes are companions, not readings. Episodes use synthetic voices and summarize a chapter rather than reading it word for word. Every episode has a transcript, and the chapter itself is the complete source.
@@ -401,7 +399,7 @@ Progress updates
October 2026: adopting the framework
- Completed: this document; a reworked accessibility bug report form with only two required fields and an email alternative; a full accessibility checklist in the pull request template; the documentation accessibility check in CI, with its first findings tracked in #267; fixes to a skipped heading level (Appendix Z), a second H1 (Appendix L), empty table headers on the registration pages, and a stray line above the title of CONTRIBUTING.md. Earlier in 2026: an EBAE braille file beside the UEB one (#174), and Chapter 11's explanation of the VoiceOver "selection replaced" announcement (#175).
-- Remaining: run and record the core flow checks; fix the site template findings (#265, #266); work through the recorded documentation findings (#264, #268); find the cause of #175.
+- Remaining: run and record the core flow checks; work through the recorded documentation findings (#264, #268); find the cause of #175.
- Known barriers: see Known limitations.
- How to help: issues labeled
accessibility.
diff --git a/html/search-index.json b/html/search-index.json
index c5d390ea..ddb28efe 100644
--- a/html/search-index.json
+++ b/html/search-index.json
@@ -1,4 +1,10 @@
[
+ {
+ "id": "ACCESSIBILITY.html",
+ "title": "Accessibility",
+ "url": "ACCESSIBILITY.html",
+ "body": "Accessibility GIT Going with GitHub exists so that blind and low vision people, and anyone who works from the keyboard or with assistive technology, can learn to contribute to open source on GitHub. Accessibility is not a feature of this workshop; it is the reason the workshop exists. Everyone, including people who use a screen reader, magnification, a braille display, voice control or the keyboard alone, should be able to read the curriculum in any of its formats, listen to the podcast, complete the challenges, and contribute to this repository. This document describes our accessibility priorities, what we ask of contributors, how to report a barrier, how we respond, who owns this work, what the workshop supports and what we know is not yet good enough. It follows the Open Source Accessibility Framework , an improvement framework from GitHub. Taking part in the framework is a commitment to steady, visible improvement. It is not a certification, and it is not a claim that the workshop is fully accessible. Priorities Target: we work toward WCAG 2.2 Level AA for everything a learner reads or operates: the published website, the Markdown on GitHub, the ePub, Word and braille downloads, the issue forms and the messages our bots post. This is a goal that guides our work, not a claim of verified conformance. Screen reader first. Every instruction is written for NVDA, JAWS and VoiceOver users first, with the keys for each where they differ. Instructions name the heading, landmark, control or key to use, never only a position or a color ("the Save button in the dialog footer", not "the blue button on the right"). Keyboard only. No step in the workshop needs a mouse. Every instruction gives a keyboard route. Text before pictures. We avoid screenshots of user interfaces and write the steps instead. A diagram is always accompanied by the same information in text. Structure a reader can navigate: one H1 per page, no skipped heading levels, descriptive link text, a sentence before every table saying what it holds, real lists, and code in fenced blocks with a language. More than one format. The same curriculum is published as HTML, Markdown, ePub, Word and braille (UEB and EBAE), with companion podcast episodes and transcripts, so people can choose the format that works for them. Plain language. We spell out abbreviations the first time, explain jargon in the glossary , and never assume knowledge a chapter has not taught. Contributor expectations These apply to every pull request. CONTRIBUTING.md gives the detail and the commands, and the pull request template turns them into a checklist. Documentation and content (chapters, appendices, challenges, solutions, admin guides, README files): Exactly one H1, the page title; headings in sequence, never skipping a level. Unique, descriptive link text; no "click here", "read more" or bare URLs in running text. Meaningful alternative text for every image, and a text alternative next to every diagram, including ASCII and Mermaid diagrams. A header row on every table, a sentence before it that says what its rows are, and no merged or empty header cells. Commands and file contents in fenced code blocks with a language ( bash , text , markdown ); expected output shown separately and labeled. Keyboard instructions for every step, with NVDA, JAWS and VoiceOver commands where they differ. No meaning carried by color, position or styling alone, and no emoji anywhere: a screen reader reads each one by name. Keep the "Authoritative Sources" and "Section-Level Source Map" sections at the end of each document. The website template, search, player and other interfaces ( scripts/build-html.js , the podcast pages, the registration page, issue forms and bot messages): see Interface requirements below, and say in the pull request what you tested and with which browser and assistive technology. Audio: every podcast episode needs a transcript published with it. Braille and ePub: a change to scripts/build-epub.js , scripts/build-brf.py or the release workflow describes in the pull request how the output was checked. Automated checks: run npm run check:accessibility (the documentation accessibility check ), npm run validate:authoritative-sources and npm run build:html before you push. A pull request that adds a new accessibility finding fails the check. Fix it, or explain in the pull request why it cannot be fixed. New dependencies: a new library, tool or service that shapes what learners meet (site styling or scripts, document converters, the text-to-speech engine, an audio host) gets a short accessibility review in the pull request before it is adopted: its known accessibility issues, and how we would work around them. See Dependencies and upstream blockers . Accessibility claims are sourced. A statement about a standard, a screen reader or GitHub's interface links its authoritative source, as every chapter's source map does. Inter"
+ },
{
"id": "index.html",
"title": "GIT Going with GitHub",
@@ -77,6 +83,12 @@
"url": "admin/ACCESSIBILITY_CORE_FLOWS.html",
"body": "Accessibility Checks for Core Flows This document holds the keyboard-only, screen reader and manual accessibility checks for the tasks every learner must be able to complete with the workshop's own materials, and the record of each time they are run. It is the test plan behind the "Supported environments" and "Known limitations" sections of ACCESSIBILITY.md . For checking a new issue template or form, use the template testing checklist instead. A check counts as run only when a person has done it with the stated browser and assistive technology, and written down the date, the environment and the result. A simulation, a code review or an automated scan is useful preparation and is recorded separately as such; it is never a result here. The one exception is an agent's run in a real browser on the live site: the accessibility owner may accept a keyboard-only run made with real key presses, or a manual visual run, as a result, and says so in its record. Screen reader checks always need a person. Status The table below shows, for each core task, which records exist and whether they have been run. Core task Keyboard only Screen reader Manual visual checks 1. Read a chapter on the website Pass, 28 October 2026 (agent run, accepted) Pass, 29 October 2026 (accessibility owner) Run 29 October 2026 (agent run, accepted); findings #279, #280 2. Search the website Pass, 28 October 2026 (agent run, accepted) Pass, 29 October 2026 (accessibility owner) Run 29 October 2026 (agent run, accepted); finding #280 3. Listen to a companion episode and open its transcript Pass, 28 October 2026 (agent run, accepted) Pass, 29 October 2026 (accessibility owner) Run 29 October 2026 (agent run, accepted); finding #280 4. Opt in on the registration page Pass, 28 October 2026 (agent run, accepted) Pass, 29 October 2026 (accessibility owner) Run 29 October 2026 (agent run, accepted); finding #280 5. Report a barrier with the accessibility bug report form Not yet run Not yet run Not yet run 6. Read the ePub and braille downloads Not applicable Not yet run Not applicable Last reviewed: 29 October 2026. The quarterly accessibility review issue asks for this table to be brought up to date. The core tasks These are the tasks a new learner must be able to complete with materials this repository publishes. Tasks on GitHub.com itself (filing an issue, opening a pull request) are taught by the curriculum and depend on GitHub's interface; barriers there are recorded in ACCESSIBILITY.md under "Dependencies and upstream blockers". Read a chapter on the website. Start at the workshop home page , reach Chapter 05: Working with Issues , read it by headings, use "On this page" and Quick Jumps, and move to the next chapter with the page progression links. Search the website. From any page, search for "merge conflict", reach the results page and open a result. Listen to a companion episode and open its transcript. On a chapter page, use "Jump to companion audio", play and pause the episode, and open the full transcript. Opt in on the registration page. Open the student opt-in page, read the status table, and follow the link to the enrollment form on GitHub. Report a barrier. Open the accessibility bug report form , fill in the two required fields and one optional field, and reach the Submit button (do not submit a test report). Read the downloads. Open the ePub from the latest release in an e-reader with a screen reader, and the UEB BRF file on a braille display or in a braille viewer, and find Chapter 05. Keyboard-only checks Use this list for each task. Do not use a mouse, trackpad or touch screen. Copy the block into "Records" below with the task name, and fill it in. ### Keyboard: < task name > Environment: < operating system and version > , < browser and version > . Run by < person > on < date > . - [ ] Every link and control in the task can be reached with Tab and Shift+Tab. - [ ] Every control works from the keyboard (Enter, Space, arrow keys where expected). - [ ] A visible focus indicator is always present and has sufficient contrast. - [ ] Focus order is logical: no jumps, follows the reading order. - [ ] No keyboard trap: focus can move into and out of the audio player, the search box and any menu. - [ ] The skip link is the first stop and moves focus to the main content. - [ ] The task can be completed end to end. Result: <pass, or the failures with issue numbers> . Screen reader checks Use at least one of NVDA with Chrome or Firefox on Windows, JAWS with Chrome on Windows, or VoiceOver with Safari on macOS: the combinations the curriculum supports. Record the versions. ### Screen reader: < task name > Environment: < screen reader and version > , < browser and version > , < operating system and version > . Tested by < person > on < date > . - [ ] The page title is announced and says which page"
},
+ {
+ "id": "admin/ACCESSIBILITY_TESTING.html",
+ "title": "Accessibility Testing Checklist",
+ "url": "admin/ACCESSIBILITY_TESTING.html",
+ "body": "Accessibility Testing Checklist Verify GitHub Templates & Workflows Are Accessible This checklist helps you test issue templates, PRs, and GitHub workflows to ensure they're usable by people with disabilities (especially screen reader users). Quick Checklist for Templates Use before deploying any new issue template or form. Form Fields & Labels Every form field has a visible label Label text is clear and describes what's needed (not "Please enter") Required fields are marked and announced as required Help text is associated with each field (not just placeholder text) No fields rely on color alone to indicate required/error status Form Structure Form inputs are in logical order (top to bottom) Dropdown options are readable and include blank option or instruction Checkboxes and radio buttons are grouped and labeled No more than 6-8 required fields (reduces cognitive load) Preview or review step before submission (allows verification) Instructions & Guidance Markdown section explains what's needed and why Instructions use simple language (8th grade reading level) Headings are in order (H2, H3, H4 - not H2, H4) Links have descriptive text (not "click here") Code examples are formatted clearly (not in plain text) YAML & Technical YAML passes syntax validation ( https://www.yamllint.com/ ) No trailing spaces or mixed indentation All required fields present: name: , description: , body: Field IDs are unique and lowercase with hyphens (e.g., browser_type ) Screen Reader Testing Workflow Before Testing Prepare: Have form open in browser with screen reader ready Choose: Test with NVDA (Windows), JAWS (Windows), or VoiceOver (macOS) Record: Note any issues for fixing NVDA Testing (Windows) 1. Press NVDA+Space to enable browse mode on page 2. Press H to navigate to first heading 3. Use H repeatedly to scan all headings (should be H1 → H2 → H3, not jumps) 4. Press B to find buttons, forms 5. Navigate to form field: Tab or arrow keys 6. Screen reader should announce: "[Label text] [field type] [required if applicable]" Example: "Email address edit text, required" 7. Tab through every field in order 8. Check Tab order makes sense (left-to-right, top-to-bottom) 9. Verify instructions between fields are heard What to listen for: Every field label is announced "Required" is announced for required fields No fields are skipped Field types are clear (edit text, dropdown, checkbox, etc.) Help text is read before or near the field JAWS Testing (Windows) 1. Press Spacebar to enter browse mode 2. Press Insert+F6 to open headings list - Verify headings are in order (1 → 2 → 3, no jumps) - Close list (Escape) 3. Press Insert+F5 to open forms list - Should see every field - Close list 4. Tab through form field by field 5. JAWS should announce: "[Label] [field type] [required if applicable]" 6. Press Insert+Down to read entire form (simulates form-scanning) What to listen for: Form start is announced All fields are listed in Forms List Required fields say "required" Field order matches logical reading order No unlabeled fields VoiceOver Testing (macOS) 1. Press VO+U to open Web Rotor 2. Navigate to Form Controls section - Should list all fields - Verify count matches expected fields 3. Navigate to Headings section - Check heading hierarchy (no jumps) 4. Press VO+Right arrow to move through page - Should hear each field label before field 5. Press VO+Space on field to interact 6. VoiceOver should announce: "[Label], [field type] [required if applicable]" What to listen for: Rotor shows all form controls Heading levels are correct (no 1 → 3 jumps) Field labels are adjacent to fields Instructions are readable Accessibility Testing by Component Checkboxes & Radio Buttons Grouped label describes the entire group Individual labels describe each option Screen reader announces number of options Example: Screen reader says: "Browser, radio button group, 3 items. Chrome, radio button, not selected" Test: Tab to group, use arrow keys to select. Screen reader should guide you clearly. Dropdowns Visible label above or adjacent to dropdown Dropdown shows currently selected value Opening dropdown announces all options (or "expandable menu") Options include instruction or blank option if optional Focus style is visible (not invisible on dark backgrounds) Test: Tab to dropdown, press Down/Space to open, arrow through options. Links & Buttons Link text describes where it goes (not "click here", "link", "read more") Button text describes what happens (not "submit", "go", "continue") Focuses visible with keyboard (Tab key shows clear highlight) No links that are only images (images need alt text) Test: Press Tab to navigate, read labels aloud. Text Fields (Input, Textarea) Label directly associated with field (via label tag or aria-label) Placeholder text is NOT "
+ },
{
"id": "admin/AGENTS_ROADMAP.html",
"title": "Agents Roadmap & Version History",
@@ -383,12 +395,6 @@
"url": "admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html",
"body": "Unit Test Results - 2026-05-08 (Non-Podcast Scope) Execution Context Command: npm run test:automation Runtime: local PowerShell terminal Workspace: s:/code/git-going-with-github Scope: non-podcast readiness and reliability checks Expected Outcome Unit tests complete successfully. No failing tests in readiness-critical suites. Added readiness/reliability tests validate current runbook and release-gate language. Proven Outcome Total tests: 99 Passed: 99 Failed: 0 Skipped: 0 Result: PASS Revalidation: Full rerun after adding student reset/recovery automation also passed at 99/99. What Was Validated by This Run Challenge inventory and numbering consistency: 16 core challenge templates 5 bonus templates Complete numbering/lettering coverage Challenge quality gates: Required evidence fields and troubleshooting guidance Core and bonus template quality checks Classroom setup consistency: Assignment docs and autograding JSON integrity Required scripts and template files present Classroom README deployment section coverage Workflow configuration readiness: Concurrency settings in key workflows Critical permissions in bot/progression workflows Registration readiness: Workflow logic includes registration, duplicate, and waitlist paths Registration issue form template exists QA gate integrity: E2E runbook includes no-go gates and reliability matrix sections Top-level go-live guide includes non-podcast readiness gate checks Defects Found During Initial Run and Resolved Brittle assertion mismatch in new runbook gate test: Cause: expected wording did not match final runbook phrasing. Fix: updated test to assert actual required phrasing in runbook. Registration template name assertion too strict: Cause: regex did not account for quoted/suffixed template title. Fix: relaxed assertion to match real template naming format. After fixes, full suite passed. Remaining Risk After Local Unit Tests Local unit testing does not fully prove hosted-environment behavior for: GitHub Classroom acceptance timing and repo provisioning. Organization-level policy impacts on Actions permissions. Bot response latency under GitHub Actions queue pressure. Human challenge recovery quality in real student scenarios. These are covered by mandatory live gates in: admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md GO-LIVE-QA-GUIDE.md Recommendation Treat this result as strong local readiness evidence. Do not declare final go-live readiness until live environment gates and human reliability gates are also complete. Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog Section-Level Source Map Use this map to verify facts for each major section in this file. Execution Context: GitHub Docs, home , GitHub Changelog Expected Outcome: GitHub Docs, home , GitHub Changelog Proven Outcome: GitHub Docs, home , GitHub Changelog What Was Validated by This Run: GitHub Docs, home , GitHub Changelog Defects Found During Initial Run and Resolved: GitHub Docs, home , GitHub Changelog Remaining Risk After Local Unit Tests: GitHub Docs, home , GitHub Changelog Recommendation: GitHub Docs, home , GitHub Changelog"
},
- {
- "id": "admin/ACCESSIBILITY_TESTING.html",
- "title": "Accessibility Testing Checklist",
- "url": "admin/ACCESSIBILITY_TESTING.html",
- "body": "Accessibility Testing Checklist Verify GitHub Templates & Workflows Are Accessible This checklist helps you test issue templates, PRs, and GitHub workflows to ensure they're usable by people with disabilities (especially screen reader users). Quick Checklist for Templates Use before deploying any new issue template or form. Form Fields & Labels Every form field has a visible label Label text is clear and describes what's needed (not "Please enter") Required fields are marked and announced as required Help text is associated with each field (not just placeholder text) No fields rely on color alone to indicate required/error status Form Structure Form inputs are in logical order (top to bottom) Dropdown options are readable and include blank option or instruction Checkboxes and radio buttons are grouped and labeled No more than 6-8 required fields (reduces cognitive load) Preview or review step before submission (allows verification) Instructions & Guidance Markdown section explains what's needed and why Instructions use simple language (8th grade reading level) Headings are in order (H2, H3, H4 - not H2, H4) Links have descriptive text (not "click here") Code examples are formatted clearly (not in plain text) YAML & Technical YAML passes syntax validation ( https://www.yamllint.com/ ) No trailing spaces or mixed indentation All required fields present: name: , description: , body: Field IDs are unique and lowercase with hyphens (e.g., browser_type ) Screen Reader Testing Workflow Before Testing Prepare: Have form open in browser with screen reader ready Choose: Test with NVDA (Windows), JAWS (Windows), or VoiceOver (macOS) Record: Note any issues for fixing NVDA Testing (Windows) 1. Press NVDA+Space to enable browse mode on page 2. Press H to navigate to first heading 3. Use H repeatedly to scan all headings (should be H1 → H2 → H3, not jumps) 4. Press B to find buttons, forms 5. Navigate to form field: Tab or arrow keys 6. Screen reader should announce: "[Label text] [field type] [required if applicable]" Example: "Email address edit text, required" 7. Tab through every field in order 8. Check Tab order makes sense (left-to-right, top-to-bottom) 9. Verify instructions between fields are heard What to listen for: Every field label is announced "Required" is announced for required fields No fields are skipped Field types are clear (edit text, dropdown, checkbox, etc.) Help text is read before or near the field JAWS Testing (Windows) 1. Press Spacebar to enter browse mode 2. Press Insert+F6 to open headings list - Verify headings are in order (1 → 2 → 3, no jumps) - Close list (Escape) 3. Press Insert+F5 to open forms list - Should see every field - Close list 4. Tab through form field by field 5. JAWS should announce: "[Label] [field type] [required if applicable]" 6. Press Insert+Down to read entire form (simulates form-scanning) What to listen for: Form start is announced All fields are listed in Forms List Required fields say "required" Field order matches logical reading order No unlabeled fields VoiceOver Testing (macOS) 1. Press VO+U to open Web Rotor 2. Navigate to Form Controls section - Should list all fields - Verify count matches expected fields 3. Navigate to Headings section - Check heading hierarchy (no jumps) 4. Press VO+Right arrow to move through page - Should hear each field label before field 5. Press VO+Space on field to interact 6. VoiceOver should announce: "[Label], [field type] [required if applicable]" What to listen for: Rotor shows all form controls Heading levels are correct (no 1 → 3 jumps) Field labels are adjacent to fields Instructions are readable Accessibility Testing by Component Checkboxes & Radio Buttons Grouped label describes the entire group Individual labels describe each option Screen reader announces number of options Example: Screen reader says: "Browser, radio button group, 3 items. Chrome, radio button, not selected" Test: Tab to group, use arrow keys to select. Screen reader should guide you clearly. Dropdowns Visible label above or adjacent to dropdown Dropdown shows currently selected value Opening dropdown announces all options (or "expandable menu") Options include instruction or blank option if optional Focus style is visible (not invisible on dark backgrounds) Test: Tab to dropdown, press Down/Space to open, arrow through options. Links & Buttons Link text describes where it goes (not "click here", "link", "read more") Button text describes what happens (not "submit", "go", "continue") Focuses visible with keyboard (Tab key shows clear highlight) No links that are only images (images need alt text) Test: Press Tab to navigate, read labels aloud. Text Fields (Input, Textarea) Label directly associated with field (via label tag or aria-label) Placeholder text is NOT "
- },
{
"id": "agents/image alt text agent/IMAGE-ALT-TEXT-DOCS.html",
"title": "Image Alt Text Agent -- Enhanced Documentation",
@@ -1198,11 +1204,5 @@
"title": "Work.md",
"url": "work.html",
"body": "Work.md Consolidated walkthrough generated from the challenge issue templates in learning-room/.github/ISSUE_TEMPLATE/ . Do not edit this file manually. Run npm run build:html (or node scripts/generate-work-md.js ) to regenerate. Core challenges Challenge 1: Find Your Way Around Source template: challenge-01-find-your-way.yml Chapters: Ch02: Understanding GitHub | Ch03: Navigating Repositories | Ch04: The Learning Room What you will do: Explore this learning-room repository like a scavenger hunt. You will navigate tabs, the file tree, read key files, and find landmarks. Step-by-step scavenger hunt Task 1: Count files in the root Make sure you are on the Code tab (click it at the top) Look at the file/folder list Count how many items are showing (stop before the first folder) Write down this number Task 2: Find an open issue Click the Issues tab Look for issues with a green Open label Click on one to read it Write down its title Task 3: Read welcome.md Click the Code tab Look for a folder named docs/ Click to open it Find welcome.md and click it Read the first paragraph (the opening sentence) Write down what it says Task 4: Find the repo description Go to the Code tab Look at the top-right area - you should see a text description under the repo name This is the "About" section Write down what it says Task 5: Read the README On the Code tab, scroll down to find README.md Click it to open Find the section that says "Who this workshop is for" Write down the answer Task 6: Check the About section On the Code tab, look at the right sidebar You should see a section labeled "About" with repo information Write down what you see there Your evidence (fill in when closing this issue): 1. I found ___ files in the root of the repository. 2. The open issue I found was titled "___". 3. The first paragraph of welcome.md says... 4. The repository description is... 5. The README says this workshop is for... 6. The About section shows... Peer simulation check After you submit your evidence, open the Peer Simulation: Welcome Link Needs Context issue in this repository and leave an encouraging comment or reaction. If your facilitator gave you access to a real buddy repository, you may use your buddy's issue instead. If you get stuck Symptom Try this I cannot find the tabs Look for a horizontal navigation bar below the repository name. Screen reader users: navigate by heading level 2 or use the landmark navigation. I cannot find docs/welcome.md On the Code tab, look for a folder called docs . Select it, then select welcome.md . I am not sure what counts as evidence Any description of what you found works. There are no wrong answers in a scavenger hunt. I finished but want to check my work View the reference solution Challenge 2: File Your First Issue Source template: challenge-02-first-issue.yml Chapter: Ch05: Working with Issues What you will do: Find a TODO comment in docs/welcome.md , then file an issue describing the problem with a clear title and description. Instructions Open docs/welcome.md and look for a line that contains TODO -- this marks something that needs fixing. Go to the Issues tab and select New issue . Write a clear, descriptive title (not just "Fix TODO"). In the description, use this required format: - What: what needs to change - Where: where the problem is (must include docs/welcome.md ) - Why: why the change matters - Mention the exact TODO text you found Required format (checked automatically) Use this structure in your issue description: What: Replace the placeholder TODO with real welcome text. Where: docs/welcome.md, intro section. Why: New contributors need clear context when they open the file. TODO found: TODO: Add a short workshop welcome paragraph. ```text #### What makes a good issue title? | Instead of this | Write this | |---|---| | Fix TODO | Fix missing workshop description in welcome.md | | Bug | welcome.md TODO placeholder needs real content | | Update file | Replace TODO in welcome.md intro section with actual welcome text | --- **Your evidence** (fill in when closing this issue): ```text Issue URL: https://github.com/... I found a TODO in docs/welcome.md that said... My issue title was... Peer simulation check Open the Peer Simulation: Welcome Link Needs Context issue and leave a comment: Is the title clear? Would you know what needs fixing just from reading the title? If your facilitator gave you access to a real buddy repository, you may review your buddy's issue instead. If you get stuck Symptom Try this I cannot find the TODO Open docs/welcome.md and use your browser's find feature (Ctrl+F or Cmd+F) to search for "TODO". I am not sure what to write in the description Describe the problem as if you are explaining it to someone who has never seen the file. The New issue button is not visible Make sure you are on the Issues tab. If issues are disabled, ask your facilitator. I finished but want to check my work View t"
- },
- {
- "id": "ACCESSIBILITY.html",
- "title": "Accessibility",
- "url": "ACCESSIBILITY.html",
- "body": "Accessibility GIT Going with GitHub exists so that blind and low vision people, and anyone who works from the keyboard or with assistive technology, can learn to contribute to open source on GitHub. Accessibility is not a feature of this workshop; it is the reason the workshop exists. Everyone, including people who use a screen reader, magnification, a braille display, voice control or the keyboard alone, should be able to read the curriculum in any of its formats, listen to the podcast, complete the challenges, and contribute to this repository. This document describes our accessibility priorities, what we ask of contributors, how to report a barrier, how we respond, who owns this work, what the workshop supports and what we know is not yet good enough. It follows the Open Source Accessibility Framework , an improvement framework from GitHub. Taking part in the framework is a commitment to steady, visible improvement. It is not a certification, and it is not a claim that the workshop is fully accessible. Priorities Target: we work toward WCAG 2.2 Level AA for everything a learner reads or operates: the published website, the Markdown on GitHub, the ePub, Word and braille downloads, the issue forms and the messages our bots post. This is a goal that guides our work, not a claim of verified conformance. Screen reader first. Every instruction is written for NVDA, JAWS and VoiceOver users first, with the keys for each where they differ. Instructions name the heading, landmark, control or key to use, never only a position or a color ("the Save button in the dialog footer", not "the blue button on the right"). Keyboard only. No step in the workshop needs a mouse. Every instruction gives a keyboard route. Text before pictures. We avoid screenshots of user interfaces and write the steps instead. A diagram is always accompanied by the same information in text. Structure a reader can navigate: one H1 per page, no skipped heading levels, descriptive link text, a sentence before every table saying what it holds, real lists, and code in fenced blocks with a language. More than one format. The same curriculum is published as HTML, Markdown, ePub, Word and braille (UEB and EBAE), with companion podcast episodes and transcripts, so people can choose the format that works for them. Plain language. We spell out abbreviations the first time, explain jargon in the glossary , and never assume knowledge a chapter has not taught. Contributor expectations These apply to every pull request. CONTRIBUTING.md gives the detail and the commands, and the pull request template turns them into a checklist. Documentation and content (chapters, appendices, challenges, solutions, admin guides, README files): Exactly one H1, the page title; headings in sequence, never skipping a level. Unique, descriptive link text; no "click here", "read more" or bare URLs in running text. Meaningful alternative text for every image, and a text alternative next to every diagram, including ASCII and Mermaid diagrams. A header row on every table, a sentence before it that says what its rows are, and no merged or empty header cells. Commands and file contents in fenced code blocks with a language ( bash , text , markdown ); expected output shown separately and labeled. Keyboard instructions for every step, with NVDA, JAWS and VoiceOver commands where they differ. No meaning carried by color, position or styling alone, and no emoji anywhere: a screen reader reads each one by name. Keep the "Authoritative Sources" and "Section-Level Source Map" sections at the end of each document. The website template, search, player and other interfaces ( scripts/build-html.js , the podcast pages, the registration page, issue forms and bot messages): see Interface requirements below, and say in the pull request what you tested and with which browser and assistive technology. Audio: every podcast episode needs a transcript published with it. Braille and ePub: a change to scripts/build-epub.js , scripts/build-brf.py or the release workflow describes in the pull request how the output was checked. Automated checks: run npm run check:accessibility (the documentation accessibility check ), npm run validate:authoritative-sources and npm run build:html before you push. A pull request that adds a new accessibility finding fails the check. Fix it, or explain in the pull request why it cannot be fixed. New dependencies: a new library, tool or service that shapes what learners meet (site styling or scripts, document converters, the text-to-speech engine, an audio host) gets a short accessibility review in the pull request before it is adopted: its known accessibility issues, and how we would work around them. See Dependencies and upstream blockers . Accessibility claims are sourced. A statement about a standard, a screen reader or GitHub's interface links its authoritative source, as every chapter's source map does. Inter"
}
]