diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md index cd95c2be..bef5b9a8 100644 --- a/ACCESSIBILITY.md +++ b/ACCESSIBILITY.md @@ -143,9 +143,9 @@ This document is reviewed every quarter, when the [review reminder](https://gith Much of what a learner meets is not ours: the workshop teaches GitHub, VS Code and Copilot as they are. These are the dependencies that shape accessibility, what we know about each, and what we do about it. A new one is reviewed before it is adopted (see [Contributor expectations](#contributor-expectations)). - **GitHub.com.** The platform the whole workshop teaches. Its interface changes often, so a documented label or key can move. GitHub documents its accessibility work on [GitHub accessibility](https://accessibility.github.com/) and takes feedback in the [GitHub Community accessibility discussions](https://github.com/orgs/community/discussions/categories/accessibility). Mitigation: every chapter links its authoritative source, and the README asks learners to report a changed path as a curriculum issue. - - Known blocker: on the "Authorize Visual Studio Code" page that opens when signing in from VS Code, NVDA can announce the Authorize button as unavailable while it is active ([#70](https://github.com/Community-Access/git-going-with-github/issues/70)). Workarounds, from the issue: wait for the page to load fully and press Enter on the button anyway; reload the page; open the same link in another browser; or sign in with `gh auth login` instead. The reporter got through by signing in again and opening the link in Microsoft Edge. Not yet reported upstream with a public link. + - Known blocker: on the "Authorize Visual Studio Code" page that opens when signing in from VS Code, NVDA can announce the Authorize button as unavailable while it is active ([#70](https://github.com/Community-Access/git-going-with-github/issues/70)). Workarounds, from the issue: wait for the page to load fully and press Enter on the button anyway; reload the page; open the same link in another browser; or sign in with `gh auth login` instead. The reporter got through by signing in again and opening the link in Microsoft Edge. Reported upstream on 29 October 2026, in the Accessibility category of GitHub Community: [community discussion 211602](https://github.com/orgs/community/discussions/211602). - **VS Code, github.dev and GitHub Copilot** (Day 2). Accessibility is maintained upstream in [microsoft/vscode](https://github.com/microsoft/vscode). Mitigation: chapters 11, 12 and 16 give the settings that matter, and a minimum VS Code version in Chapter 00. - - Open: VoiceOver on macOS can say "selection replaced" when the first character is typed in the editor, though nothing is replaced ([#175](https://github.com/Community-Access/git-going-with-github/issues/175)). The cause, VoiceOver or VS Code, is not yet known, so there is no upstream report yet; Chapter 11 explains it to learners. + - Open: VoiceOver on macOS can say "selection replaced" when the first character is typed in the editor, though nothing is replaced ([#175](https://github.com/Community-Access/git-going-with-github/issues/175)). The cause, VoiceOver or VS Code, is not yet known. Reported upstream on 29 October 2026 as [microsoft/vscode#345026](https://github.com/microsoft/vscode/issues/345026), so the VS Code team can tell whether it comes from the editor; Chapter 11 explains it to learners. - **Screen readers** (NVDA, JAWS, VoiceOver). Commands differ between them and between versions; Appendix B is the single place we keep them, and corrections from daily users are always welcome. - **The website build:** [marked](https://github.com/markedjs/marked) turns Markdown into HTML, [github-markdown-css](https://github.com/sindresorhus/github-markdown-css) and a [highlight.js](https://github.com/highlightjs/highlight.js) theme supply the colors, and [lunr](https://github.com/olivernn/lunr.js) the search index. The page template, landmarks, skip link, focus styles and search page are ours, in `scripts/build-html.js`; barriers there are tracked as our own issues. - **Downloads:** [Pandoc](https://pandoc.org/) builds the ePub and Word files, and [liblouis](https://liblouis.io/) translates the braille files from a plain-text conversion of the ePub. Braille layout and tables depend on both (see [Known limitations](#known-limitations)). @@ -167,13 +167,13 @@ What has been checked: - The documentation accessibility check runs on every pull request that changes Markdown (see [Automated checks](#automated-checks)). - Learners using screen readers have taken the workshop in live cohorts, and their reports (for example [#70](https://github.com/Community-Access/git-going-with-github/issues/70), [#174](https://github.com/Community-Access/git-going-with-github/issues/174) and [#175](https://github.com/Community-Access/git-going-with-github/issues/175)) have changed the curriculum. -- Keyboard, screen reader and visual checks of the published website's core tasks are written down in [Accessibility Checks for Core Flows](admin/ACCESSIBILITY_CORE_FLOWS.md), but not yet run and recorded. Until they are, treat any combination above as supported but not formally tested. +- Keyboard, screen reader and manual visual checks of the published website's core tasks 1 to 4 are recorded in [Accessibility Checks for Core Flows](admin/ACCESSIBILITY_CORE_FLOWS.md). The screen reader run was made by the accessibility owner on his test machine: Windows 11 Pro with JAWS 2026 (2026.2608.25.400) and NVDA 2026.2, in Chrome 156 and Edge 156. VoiceOver, Firefox and Safari have not had a recorded run, so treat those combinations as supported but not formally tested. ## 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](#reporting-accessibility-issues). -- **No recorded test of the website yet.** We have not yet run and recorded keyboard, screen reader and zoom checks of the published site for each release. The [test plan](admin/ACCESSIBILITY_CORE_FLOWS.md) is written; results will be added there. +- **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. @@ -201,6 +201,18 @@ Accessibility work, including reports, testing, reviews and documentation, is pr A workflow does the asking. When an accessibility pull request from outside the maintainers is merged, or your report closes as fixed, a bot asks you once how you would like to be credited, and you reply with one line: `credit: @handle`, `credit: name `, `credit: anonymous` or `credit: no`. Only your own reply counts, you can change it later, and nothing about you beyond the credit you choose is published. The answer is recorded as a `credit:` label. Before each progress update, the accessibility owner runs `node .github/scripts/a11y-credits.mjs --since ` and pastes the block it prints; it lists items labeled `credit: yes` or `credit: anonymous` closed since then, as code and other contributions, and warns about `credit: asked` items with no answer after 14 days, whose contributors are left out or asked again. +### Contributions so far + +These contributions came before the asking workflow started on 29 October 2026, so, by the accessibility owner's decision, they are credited here by public GitHub handle, for the work only, as it appears in this repository's public history. Thank you to: + +- [@evangeline-dionisio](https://github.com/evangeline-dionisio), for reporting that the Authorize button on GitHub's "Authorize Visual Studio Code" page could not be used ([#70](https://github.com/Community-Access/git-going-with-github/issues/70)), and for coming back to share the steps that got them through. Those steps are now among the workarounds we give learners, and the report has gone upstream to GitHub. +- [@Mark-Iott](https://github.com/Mark-Iott), for confirming the same problem on [#70](https://github.com/Community-Access/git-going-with-github/issues/70). +- [@ssawczyn](https://github.com/ssawczyn), for reporting the "selection replaced" announcement in the VS Code editor ([#175](https://github.com/Community-Access/git-going-with-github/issues/175)), testing the suggested fixes, and proposing the learner guidance that became Chapter 11's explanation; and for [pull request 184](https://github.com/Community-Access/git-going-with-github/pull/184), which tells Mac users in Chapter 00 to use Cmd where a VS Code shortcut says Ctrl. +- [@stickbear2015](https://github.com/stickbear2015), for asking for a braille file in EBAE as well as UEB ([#174](https://github.com/Community-Access/git-going-with-github/issues/174)), which each release now includes. +- [@taylorarndt](https://github.com/taylorarndt), workshop facilitator, for the braille, ePub and Word build pipeline, text descriptions for the diagrams ([pull request 168](https://github.com/Community-Access/git-going-with-github/pull/168)), and for investigating [#175](https://github.com/Community-Access/git-going-with-github/issues/175) with its reporter. + +If you are named here and would rather be credited another way, or not at all, say so in a comment on any of these issues or pull requests, or email [support@community-access.org](mailto:support@community-access.org), and we will change it. + ## Reusing our accessibility materials Other projects are welcome to reuse what we built for this workshop, under the repository's [CC BY 4.0 license](https://github.com/Community-Access/git-going-with-github/blob/main/LICENSE), with attribution. Each item below says what problem it solves and where it falls short. @@ -217,12 +229,12 @@ The accessibility owner keeps these current. Report a problem with any of them t ## Open Source Accessibility Framework -We follow the [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/) in its four phases and record our progress, action by action, in our public tracking issue, [GIT Going with GitHub, issue 55](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework/issues/55), in the framework's repository. Progress is self-reported, and an action is checked there only when its definition of done is fully met: 20 of 24 as of 28 October 2026. The keyboard-only smoke test is checked: tasks 1 to 4 passed with real key presses in a browser, a run the accessibility owner accepted (see admin/ACCESSIBILITY_CORE_FLOWS.md). Docs accessible by default is checked: the documentation check's 264 findings were fixed in pull request 271, and the 3 left are deliberate bad examples in Appendix C. Accessible interfaces is checked: the site's fixes from issues 265 and 266 were confirmed on the live site in a browser, with a visible focus outline in light and dark mode (5.19:1 and 3.49:1) and a search box named by its visible label. Responding constructively to reports is checked: [How we respond](#how-we-respond) sets out the guidance, and since 29 October 2026 the accessibility-reports workflow (`.github/workflows/accessibility-reports.yml`) acknowledges every report, reminds the owner after 5 business days without a reply, reopens a report closed without a documented outcome (a merged fix or an `Outcome:` line), and invites the reporter to confirm a fix; the accessibility owner decided that past reports are not reopened. One workflow action described below is in place but stays unchecked for now: dependencies (the two known blockers have no upstream report yet). As of October 2026: +We follow the [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/) in its four phases and record our progress, action by action, in our public tracking issue, [GIT Going with GitHub, issue 55](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework/issues/55), in the framework's repository. Progress is self-reported, and an action is checked there only when its definition of done is fully met: all 24 of 24 as of 29 October 2026. Checking every action means each one's definition of done is met, not that the workshop is fully accessible; the work goes on. The keyboard-only smoke test is checked: tasks 1 to 4 passed with real key presses in a browser, a run the accessibility owner accepted (see admin/ACCESSIBILITY_CORE_FLOWS.md). Docs accessible by default is checked: the documentation check's 264 findings were fixed in pull request 271, and the 3 left are deliberate bad examples in Appendix C. Accessible interfaces is checked: the site's fixes from issues 265 and 266 were confirmed on the live site in a browser, with a visible focus outline in light and dark mode (5.19:1 and 3.49:1) and a search box named by its visible label. Responding constructively to reports is checked: [How we respond](#how-we-respond) sets out the guidance, and since 29 October 2026 the accessibility-reports workflow (`.github/workflows/accessibility-reports.yml`) acknowledges every report, reminds the owner after 5 business days without a reply, reopens a report closed without a documented outcome (a merged fix or an `Outcome:` line), and invites the reporter to confirm a fix; the accessibility owner decided that past reports are not reopened. Dependencies and upstream blockers is checked: both known blockers now have public upstream reports, [community discussion 211602](https://github.com/orgs/community/discussions/211602) for #70 and [microsoft/vscode#345026](https://github.com/microsoft/vscode/issues/345026) for #175, linked under [Dependencies and upstream blockers](#dependencies-and-upstream-blockers). The screen reader spot check is checked: the accessibility owner ran the website's core tasks with JAWS and NVDA on his test machine and signed them off. Manual accessibility checks are checked: an agent's manual visual run of tasks 1 to 4 on the live site (200% zoom, reflow at 320 CSS pixels, contrast in light and dark mode, titles, headings, labels, plain language and text alternatives), accepted as a result by the accessibility owner, with its two findings tracked in issues 279 and 280. Recognizing contributions is checked: past accessibility contributions are credited under [Contributions so far](#contributions-so-far), and new ones go through the asking workflow. As of October 2026: - **Foundational:** this document; the `accessibility` label, applied to accessibility reports and work. - **Workflow:** priorities, contributor expectations and interface requirements above, linked from [CONTRIBUTING.md](CONTRIBUTING.md); the accessibility bug report form with an email alternative; severity and response; the pull request checklist; `good first issue` and `help wanted` accessibility issues with acceptance criteria; an owner; documentation checked by the automated check; dependencies and upstream blockers recorded. -- **Testing:** the documentation accessibility check in CI, with its findings tracked; documentation reviewed; supported environments and known limitations above. A keyboard-only run of the core tasks on the website passed and is recorded; screen reader and manual checks are written down but not yet run by a person. -- **Community:** a feedback form after each cohort and labeled issues to invite help; documented responses to reports, enforced by the accessibility-reports workflow; asynchronous and live ways to take part, a private route for accommodations and a Code of Conduct; quarterly progress updates; reusable materials. Crediting accessibility contributors with their consent is the practice above, and has not yet happened. +- **Testing:** the documentation accessibility check in CI, with its findings tracked; documentation reviewed; supported environments and known limitations above. Keyboard, screen reader and manual visual runs of core tasks 1 to 4 on the website are recorded, with the manual run's findings tracked; tasks 5 and 6 are still to be run. +- **Community:** a feedback form after each cohort and labeled issues to invite help; documented responses to reports, enforced by the accessibility-reports workflow; asynchronous and live ways to take part, a private route for accommodations and a Code of Conduct; quarterly progress updates; reusable materials. Crediting accessibility contributors with their consent is the practice above, and past contributions are credited under [Contributions so far](#contributions-so-far). ## Feedback diff --git a/admin/ACCESSIBILITY_CORE_FLOWS.md b/admin/ACCESSIBILITY_CORE_FLOWS.md index 2e1373a5..4a3356bd 100644 --- a/admin/ACCESSIBILITY_CORE_FLOWS.md +++ b/admin/ACCESSIBILITY_CORE_FLOWS.md @@ -2,7 +2,7 @@ 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](../ACCESSIBILITY.md). For checking a new issue template or form, use the [template testing checklist](ACCESSIBILITY_TESTING.md) 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 a keyboard-only run made with real key presses in a real browser: the accessibility owner may accept it as a result, and says so in its record. Screen reader and manual visual checks always need a person. +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 @@ -10,14 +10,14 @@ The table below shows, for each core task, which records exist and whether they | Core task | Keyboard only | Screen reader | Manual visual checks | |---|---|---|---| -| 1. Read a chapter on the website | Pass, 28 October 2026 (agent run, accepted) | Not yet run | Not yet run | -| 2. Search the website | Pass, 28 October 2026 (agent run, accepted) | Not yet run | Not yet run | -| 3. Listen to a companion episode and open its transcript | Pass, 28 October 2026 (agent run, accepted) | Not yet run | Not yet run | -| 4. Opt in on the registration page | Pass, 28 October 2026 (agent run, accepted) | Not yet run | Not yet run | +| 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: 28 October 2026. The quarterly [accessibility review issue](https://github.com/Community-Access/git-going-with-github/blob/main/.github/workflows/accessibility-review-reminder.yml) asks for this table to be brought up to date. +Last reviewed: 29 October 2026. The quarterly [accessibility review issue](https://github.com/Community-Access/git-going-with-github/blob/main/.github/workflows/accessibility-review-reminder.yml) asks for this table to be brought up to date. ## The core tasks @@ -113,11 +113,32 @@ Reviewed by Claude (an AI coding agent) while adopting the Open Source Accessibi Add each run below, newest first, using the blocks above. Link any issue you file, labeled `accessibility`. -No checks by a person have been run yet. +### Screen reader: tasks 1 to 4, 29 October 2026 + +Environment: the accessibility owner's test machine, which has Windows 11 Pro, JAWS 2026 (2026.2608.25.400) and NVDA 2026.2, with Chrome 156 and Edge 156. Tested by Jeff Bishop, accessibility owner. + +Jeff ran the screen reader checks of the website's core tasks himself and signed them off on 29 October 2026. No per-task findings were written down, and no barrier was reported from the run. + +Result: pass for tasks 1 to 4, signed off by the accessibility owner. VoiceOver on macOS, task 5 (GitHub's own issue form) and task 6 (the downloads) are still to be run. ## Agent runs -These runs were made by Claude (an AI agent) on the live site, with real key presses in a real browser. The keyboard run was accepted as a result by the accessibility owner, Jeff Bishop, on 28 October 2026, under the exception at the top of this document, and the status table shows it. The manual visual run stays preparation only: it caught one real defect, which is fixed, and a person's run still has to be recorded under "Records". +These runs were made by Claude (an AI agent) on the live site, in a real browser. The keyboard run of 28 October 2026 and the manual visual run of 29 October 2026 were accepted as results by the accessibility owner, Jeff Bishop, under the exception at the top of this document, and the status table shows them. The manual visual run of 28 October 2026 was preparation only: it caught one real defect, which is fixed. + +### Agent run: manual visual checks, tasks 1 to 4, 29 October 2026 + +Environment: Chromium in the Claude desktop app's browser pane, Windows, light and dark mode. Pages: the home page, Chapter 05, Chapter 07, the search results page for "merge conflict", and REGISTER.html. Browser zoom was not set directly: 200% zoom was checked as a 640 CSS pixel wide window, the same layout as 200% zoom on a 1280 pixel window, and 400% zoom as a 320 CSS pixel wide window. + +- Keyboard: see the accepted keyboard run of 28 October 2026. +- Text alternatives: the only images on these pages are two decorative icons, hidden from assistive technology. No content image lacks a text alternative. +- Titles, headings and labels: each page title names the page and the site (for example "Working with Issues - GIT Going with GitHub"); each page has one H1 that matches it; the only heading before the H1 is the sidebar's "Guided Reference". Every form control has a name, and no link is empty. The search results page announces "80 results found" in a live region. +- Plain language: the opening of Chapter 05 is short and direct, but CLI, ARIA, PR and WCAG are used without being spelled out on first use. Tracked in [#279](https://github.com/Community-Access/git-going-with-github/issues/279). +- 200% zoom (640 pixels): all five pages reflow with no horizontal scrolling and nothing cut off. +- 320 CSS pixels: no page scrolls horizontally, but the header breadcrumb is squeezed to 8 pixels, so only the "H" of its Home link shows and the rest is behind the Wiki button. It is cut off below about 480 pixels. Tracked in [#280](https://github.com/Community-Access/git-going-with-github/issues/280); the same link is in the sidebar as "Workshop Home". +- Contrast: every text element measured against its actual background on all five pages, at 320 and 640 pixels in light mode and at 320 pixels in dark mode: nothing under 4.5:1 (3:1 for large text). +- Not checked: Windows High Contrast (forced colors), and whether color is ever the only way meaning is shown. + +Result: run for tasks 1 to 4, with two findings, [#279](https://github.com/Community-Access/git-going-with-github/issues/279) and [#280](https://github.com/Community-Access/git-going-with-github/issues/280). Accepted as a result by the accessibility owner on 29 October 2026. ### Agent run: keyboard, tasks 1 to 4, 28 October 2026 diff --git a/admin/ACCESSIBILITY_TESTING.md b/admin/ACCESSIBILITY_TESTING.md index dba96894..27277bc6 100644 --- a/admin/ACCESSIBILITY_TESTING.md +++ b/admin/ACCESSIBILITY_TESTING.md @@ -300,7 +300,7 @@ OS: Windows 11 ## Testing the Built HTML Output -This repository includes a build system that converts all Markdown files to HTML (see `BUILD.md`). If participants will use the HTML versions, test them separately: +This repository includes a build system that converts all Markdown files to HTML (see `BUILD.md`). If participants will use the HTML versions, test them separately with the lists below. The keyboard, screen reader and manual checks of the published site's core tasks, and the record of each run, are in [Accessibility Checks for Core Flows](ACCESSIBILITY_CORE_FLOWS.md); add website results there, not here. ### Heading Hierarchy @@ -334,7 +334,7 @@ This repository includes a build system that converts all Markdown files to HTML - **Need screen reader help?** See `docs/appendix-b-screen-reader-cheatsheet.md` - **Want resources?** See `docs/appendix-x-resources.md` -*Last updated: February 2026* +*Last updated: October 2026* *Accessibility is foundational to inclusive workflows.* ## Authoritative Sources diff --git a/html/ACCESSIBILITY.html b/html/ACCESSIBILITY.html index 743896ba..46a2069c 100644 --- a/html/ACCESSIBILITY.html +++ b/html/ACCESSIBILITY.html @@ -219,6 +219,7 @@

On This Page

  • Progress updates
  • October 2026: adopting the framework
  • Recognizing contributions
    • +
  • Contributions so far
  • Reusing our accessibility materials
  • Open Source Accessibility Framework
  • Feedback
    • @@ -352,11 +353,11 @@

    Dependencies and upstream blockersMuch of what a learner meets is not ours: the workshop teaches GitHub, VS Code and Copilot as they are. These are the dependencies that shape accessibility, what we know about each, and what we do about it. A new one is reviewed before it is adopted (see Contributor expectations).

    • GitHub.com. The platform the whole workshop teaches. Its interface changes often, so a documented label or key can move. GitHub documents its accessibility work on GitHub accessibility and takes feedback in the GitHub Community accessibility discussions. Mitigation: every chapter links its authoritative source, and the README asks learners to report a changed path as a curriculum issue.
        -
      • Known blocker: on the "Authorize Visual Studio Code" page that opens when signing in from VS Code, NVDA can announce the Authorize button as unavailable while it is active (#70). Workarounds, from the issue: wait for the page to load fully and press Enter on the button anyway; reload the page; open the same link in another browser; or sign in with gh auth login instead. The reporter got through by signing in again and opening the link in Microsoft Edge. Not yet reported upstream with a public link.
        • +
      • Known blocker: on the "Authorize Visual Studio Code" page that opens when signing in from VS Code, NVDA can announce the Authorize button as unavailable while it is active (#70). Workarounds, from the issue: wait for the page to load fully and press Enter on the button anyway; reload the page; open the same link in another browser; or sign in with gh auth login instead. The reporter got through by signing in again and opening the link in Microsoft Edge. Reported upstream on 29 October 2026, in the Accessibility category of GitHub Community: community discussion 211602.
    • VS Code, github.dev and GitHub Copilot (Day 2). Accessibility is maintained upstream in microsoft/vscode. Mitigation: chapters 11, 12 and 16 give the settings that matter, and a minimum VS Code version in Chapter 00.
        -
      • Open: VoiceOver on macOS can say "selection replaced" when the first character is typed in the editor, though nothing is replaced (#175). The cause, VoiceOver or VS Code, is not yet known, so there is no upstream report yet; Chapter 11 explains it to learners.
        • +
      • Open: VoiceOver on macOS can say "selection replaced" when the first character is typed in the editor, though nothing is replaced (#175). The cause, VoiceOver or VS Code, is not yet known. Reported upstream on 29 October 2026 as microsoft/vscode#345026, so the VS Code team can tell whether it comes from the editor; Chapter 11 explains it to learners.
    • Screen readers (NVDA, JAWS, VoiceOver). Commands differ between them and between versions; Appendix B is the single place we keep them, and corrections from daily users are always welcome.
      • @@ -379,12 +380,12 @@

      Supported environments

      • The documentation accessibility check runs on every pull request that changes Markdown (see Automated checks).
      • Learners using screen readers have taken the workshop in live cohorts, and their reports (for example #70, #174 and #175) have changed the curriculum.
        • -
      • Keyboard, screen reader and visual checks of the published website's core tasks are written down in Accessibility Checks for Core Flows, but not yet run and recorded. Until they are, treat any combination above as supported but not formally tested.
        • +
      • Keyboard, screen reader and manual visual checks of the published website's core tasks 1 to 4 are recorded in Accessibility Checks for Core Flows. The screen reader run was made by the accessibility owner on his test machine: Windows 11 Pro with JAWS 2026 (2026.2608.25.400) and NVDA 2026.2, in Chrome 156 and Edge 156. VoiceOver, Firefox and Safari have not had a recorded run, so treat those combinations as supported but not formally tested.

      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.

        -
      • No recorded test of the website yet. We have not yet run and recorded keyboard, screen reader and zoom checks of the published site for each release. The test plan is written; results will be added there.
        • +
      • 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.
        • @@ -407,6 +408,16 @@

        October 2026: adopting the framewor

        Recognizing contributions

        Accessibility work, including reports, testing, reviews and documentation, is project work, and we say so publicly. Before we name anyone in a progress update, release notes or a community post, we ask how they would like to be credited: by GitHub handle, by name, or not at all, and we record the answer on the issue or pull request. We describe the work, never the person's disability, diagnosis or assistive technology, even if they mentioned it in a report, and we never present one person as speaking for a disability community.

        A workflow does the asking. When an accessibility pull request from outside the maintainers is merged, or your report closes as fixed, a bot asks you once how you would like to be credited, and you reply with one line: credit: @handle, credit: name <Name>, credit: anonymous or credit: no. Only your own reply counts, you can change it later, and nothing about you beyond the credit you choose is published. The answer is recorded as a credit: label. Before each progress update, the accessibility owner runs node .github/scripts/a11y-credits.mjs --since <date of the last update> and pastes the block it prints; it lists items labeled credit: yes or credit: anonymous closed since then, as code and other contributions, and warns about credit: asked items with no answer after 14 days, whose contributors are left out or asked again.

        +

        Contributions so far

        +

        These contributions came before the asking workflow started on 29 October 2026, so, by the accessibility owner's decision, they are credited here by public GitHub handle, for the work only, as it appears in this repository's public history. Thank you to:

        +
          +
        • @evangeline-dionisio, for reporting that the Authorize button on GitHub's "Authorize Visual Studio Code" page could not be used (#70), and for coming back to share the steps that got them through. Those steps are now among the workarounds we give learners, and the report has gone upstream to GitHub.
          • +
        • @Mark-Iott, for confirming the same problem on #70.
          • +
        • @ssawczyn, for reporting the "selection replaced" announcement in the VS Code editor (#175), testing the suggested fixes, and proposing the learner guidance that became Chapter 11's explanation; and for pull request 184, which tells Mac users in Chapter 00 to use Cmd where a VS Code shortcut says Ctrl.
          • +
        • @stickbear2015, for asking for a braille file in EBAE as well as UEB (#174), which each release now includes.
          • +
        • @taylorarndt, workshop facilitator, for the braille, ePub and Word build pipeline, text descriptions for the diagrams (pull request 168), and for investigating #175 with its reporter.
          • +
        +

        If you are named here and would rather be credited another way, or not at all, say so in a comment on any of these issues or pull requests, or email support@community-access.org, and we will change it.

        Reusing our accessibility materials

        Other projects are welcome to reuse what we built for this workshop, under the repository's CC BY 4.0 license, with attribution. Each item below says what problem it solves and where it falls short.

          @@ -420,12 +431,12 @@

          Reusing our accessibility materials

        The accessibility owner keeps these current. Report a problem with any of them the same way as any other barrier.

        Open Source Accessibility Framework

        -

        We follow the Open Source Accessibility Framework in its four phases and record our progress, action by action, in our public tracking issue, GIT Going with GitHub, issue 55, in the framework's repository. Progress is self-reported, and an action is checked there only when its definition of done is fully met: 20 of 24 as of 28 October 2026. The keyboard-only smoke test is checked: tasks 1 to 4 passed with real key presses in a browser, a run the accessibility owner accepted (see admin/ACCESSIBILITY_CORE_FLOWS.md). Docs accessible by default is checked: the documentation check's 264 findings were fixed in pull request 271, and the 3 left are deliberate bad examples in Appendix C. Accessible interfaces is checked: the site's fixes from issues 265 and 266 were confirmed on the live site in a browser, with a visible focus outline in light and dark mode (5.19:1 and 3.49:1) and a search box named by its visible label. Responding constructively to reports is checked: How we respond sets out the guidance, and since 29 October 2026 the accessibility-reports workflow (.github/workflows/accessibility-reports.yml) acknowledges every report, reminds the owner after 5 business days without a reply, reopens a report closed without a documented outcome (a merged fix or an Outcome: line), and invites the reporter to confirm a fix; the accessibility owner decided that past reports are not reopened. One workflow action described below is in place but stays unchecked for now: dependencies (the two known blockers have no upstream report yet). As of October 2026:

        +

        We follow the Open Source Accessibility Framework in its four phases and record our progress, action by action, in our public tracking issue, GIT Going with GitHub, issue 55, in the framework's repository. Progress is self-reported, and an action is checked there only when its definition of done is fully met: all 24 of 24 as of 29 October 2026. Checking every action means each one's definition of done is met, not that the workshop is fully accessible; the work goes on. The keyboard-only smoke test is checked: tasks 1 to 4 passed with real key presses in a browser, a run the accessibility owner accepted (see admin/ACCESSIBILITY_CORE_FLOWS.md). Docs accessible by default is checked: the documentation check's 264 findings were fixed in pull request 271, and the 3 left are deliberate bad examples in Appendix C. Accessible interfaces is checked: the site's fixes from issues 265 and 266 were confirmed on the live site in a browser, with a visible focus outline in light and dark mode (5.19:1 and 3.49:1) and a search box named by its visible label. Responding constructively to reports is checked: How we respond sets out the guidance, and since 29 October 2026 the accessibility-reports workflow (.github/workflows/accessibility-reports.yml) acknowledges every report, reminds the owner after 5 business days without a reply, reopens a report closed without a documented outcome (a merged fix or an Outcome: line), and invites the reporter to confirm a fix; the accessibility owner decided that past reports are not reopened. Dependencies and upstream blockers is checked: both known blockers now have public upstream reports, community discussion 211602 for #70 and microsoft/vscode#345026 for #175, linked under Dependencies and upstream blockers. The screen reader spot check is checked: the accessibility owner ran the website's core tasks with JAWS and NVDA on his test machine and signed them off. Manual accessibility checks are checked: an agent's manual visual run of tasks 1 to 4 on the live site (200% zoom, reflow at 320 CSS pixels, contrast in light and dark mode, titles, headings, labels, plain language and text alternatives), accepted as a result by the accessibility owner, with its two findings tracked in issues 279 and 280. Recognizing contributions is checked: past accessibility contributions are credited under Contributions so far, and new ones go through the asking workflow. As of October 2026:

        • Foundational: this document; the accessibility label, applied to accessibility reports and work.
        • Workflow: priorities, contributor expectations and interface requirements above, linked from CONTRIBUTING.md; the accessibility bug report form with an email alternative; severity and response; the pull request checklist; good first issue and help wanted accessibility issues with acceptance criteria; an owner; documentation checked by the automated check; dependencies and upstream blockers recorded.
          • -
        • Testing: the documentation accessibility check in CI, with its findings tracked; documentation reviewed; supported environments and known limitations above. A keyboard-only run of the core tasks on the website passed and is recorded; screen reader and manual checks are written down but not yet run by a person.
          • -
        • Community: a feedback form after each cohort and labeled issues to invite help; documented responses to reports, enforced by the accessibility-reports workflow; asynchronous and live ways to take part, a private route for accommodations and a Code of Conduct; quarterly progress updates; reusable materials. Crediting accessibility contributors with their consent is the practice above, and has not yet happened.
          • +
        • Testing: the documentation accessibility check in CI, with its findings tracked; documentation reviewed; supported environments and known limitations above. Keyboard, screen reader and manual visual runs of core tasks 1 to 4 on the website are recorded, with the manual run's findings tracked; tasks 5 and 6 are still to be run.
          • +
        • Community: a feedback form after each cohort and labeled issues to invite help; documented responses to reports, enforced by the accessibility-reports workflow; asynchronous and live ways to take part, a private route for accommodations and a Code of Conduct; quarterly progress updates; reusable materials. Crediting accessibility contributors with their consent is the practice above, and past contributions are credited under Contributions so far.

        Feedback

        To suggest an improvement to this document or to how we work, open an issue or a pull request, or write to support@community-access.org. Thank you for helping make GIT Going with GitHub work for everyone.

        diff --git a/html/admin/ACCESSIBILITY_CORE_FLOWS.html b/html/admin/ACCESSIBILITY_CORE_FLOWS.html index 52a52e49..9860de25 100644 --- a/html/admin/ACCESSIBILITY_CORE_FLOWS.html +++ b/html/admin/ACCESSIBILITY_CORE_FLOWS.html @@ -212,7 +212,9 @@

        On This Page

      • Documentation checks
      • Review record, 28 October 2026
      • Records
        • +
      • Screen reader: tasks 1 to 4, 29 October 2026
      • Agent runs
        • +
      • Agent run: manual visual checks, tasks 1 to 4, 29 October 2026
      • Agent run: keyboard, tasks 1 to 4, 28 October 2026
      • Agent run: manual visual checks, tasks 1 to 4, 28 October 2026
      • Authoritative Sources
        • @@ -221,7 +223,7 @@

        On This Page

        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 a keyboard-only run made with real key presses in a real browser: the accessibility owner may accept it as a result, and says so in its record. Screen reader and manual visual checks always need a person.

        +

        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.

        @@ -236,26 +238,26 @@

        Status

        - - + + - - + + - - + + - - + + @@ -270,7 +272,7 @@

        Status

        1. Read a chapter on the website Pass, 28 October 2026 (agent run, accepted)Not yet runNot yet runPass, 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)Not yet runNot yet runPass, 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)Not yet runNot yet runPass, 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)Not yet runNot yet runPass, 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 applicable
        -

        Last reviewed: 28 October 2026. The quarterly accessibility review issue asks for this table to be brought up to date.

        +

        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".

          @@ -346,9 +348,25 @@

          Review record, 28 October 2026

      Records

      Add each run below, newest first, using the blocks above. Link any issue you file, labeled accessibility.

      -

      No checks by a person have been run yet.

      +

      Screen reader: tasks 1 to 4, 29 October 2026

      +

      Environment: the accessibility owner's test machine, which has Windows 11 Pro, JAWS 2026 (2026.2608.25.400) and NVDA 2026.2, with Chrome 156 and Edge 156. Tested by Jeff Bishop, accessibility owner.

      +

      Jeff ran the screen reader checks of the website's core tasks himself and signed them off on 29 October 2026. No per-task findings were written down, and no barrier was reported from the run.

      +

      Result: pass for tasks 1 to 4, signed off by the accessibility owner. VoiceOver on macOS, task 5 (GitHub's own issue form) and task 6 (the downloads) are still to be run.

      Agent runs

      -

      These runs were made by Claude (an AI agent) on the live site, with real key presses in a real browser. The keyboard run was accepted as a result by the accessibility owner, Jeff Bishop, on 28 October 2026, under the exception at the top of this document, and the status table shows it. The manual visual run stays preparation only: it caught one real defect, which is fixed, and a person's run still has to be recorded under "Records".

      +

      These runs were made by Claude (an AI agent) on the live site, in a real browser. The keyboard run of 28 October 2026 and the manual visual run of 29 October 2026 were accepted as results by the accessibility owner, Jeff Bishop, under the exception at the top of this document, and the status table shows them. The manual visual run of 28 October 2026 was preparation only: it caught one real defect, which is fixed.

      +

      Agent run: manual visual checks, tasks 1 to 4, 29 October 2026

      +

      Environment: Chromium in the Claude desktop app's browser pane, Windows, light and dark mode. Pages: the home page, Chapter 05, Chapter 07, the search results page for "merge conflict", and REGISTER.html. Browser zoom was not set directly: 200% zoom was checked as a 640 CSS pixel wide window, the same layout as 200% zoom on a 1280 pixel window, and 400% zoom as a 320 CSS pixel wide window.

      +
        +
      • Keyboard: see the accepted keyboard run of 28 October 2026.
        • +
      • Text alternatives: the only images on these pages are two decorative icons, hidden from assistive technology. No content image lacks a text alternative.
        • +
      • Titles, headings and labels: each page title names the page and the site (for example "Working with Issues - GIT Going with GitHub"); each page has one H1 that matches it; the only heading before the H1 is the sidebar's "Guided Reference". Every form control has a name, and no link is empty. The search results page announces "80 results found" in a live region.
        • +
      • Plain language: the opening of Chapter 05 is short and direct, but CLI, ARIA, PR and WCAG are used without being spelled out on first use. Tracked in #279.
        • +
      • 200% zoom (640 pixels): all five pages reflow with no horizontal scrolling and nothing cut off.
        • +
      • 320 CSS pixels: no page scrolls horizontally, but the header breadcrumb is squeezed to 8 pixels, so only the "H" of its Home link shows and the rest is behind the Wiki button. It is cut off below about 480 pixels. Tracked in #280; the same link is in the sidebar as "Workshop Home".
        • +
      • Contrast: every text element measured against its actual background on all five pages, at 320 and 640 pixels in light mode and at 320 pixels in dark mode: nothing under 4.5:1 (3:1 for large text).
        • +
      • Not checked: Windows High Contrast (forced colors), and whether color is ever the only way meaning is shown.
        • +
      +

      Result: run for tasks 1 to 4, with two findings, #279 and #280. Accepted as a result by the accessibility owner on 29 October 2026.

      Agent run: keyboard, tasks 1 to 4, 28 October 2026

      Environment: Chromium in the Claude desktop app's browser pane, Windows, 1280 by 900 and 320 by 720 windows. Pages: the home page, Chapter 05, Chapter 07, the search results page for "merge conflict", and REGISTER.html.

        diff --git a/html/admin/ACCESSIBILITY_TESTING.html b/html/admin/ACCESSIBILITY_TESTING.html index 50ae4fb3..20bee6e2 100644 --- a/html/admin/ACCESSIBILITY_TESTING.html +++ b/html/admin/ACCESSIBILITY_TESTING.html @@ -545,7 +545,7 @@

        After Testing: Recording Issues

        Browser: Chrome 130 OS: Windows 11

        Testing the Built HTML Output

        -

        This repository includes a build system that converts all Markdown files to HTML (see BUILD.md). If participants will use the HTML versions, test them separately:

        +

        This repository includes a build system that converts all Markdown files to HTML (see BUILD.md). If participants will use the HTML versions, test them separately with the lists below. The keyboard, screen reader and manual checks of the published site's core tasks, and the record of each run, are in Accessibility Checks for Core Flows; add website results there, not here.

        Heading Hierarchy

        • Each HTML page has exactly one <h1> element
          • @@ -577,7 +577,7 @@

          Questions or Feedback?

        • Need screen reader help? See docs/appendix-b-screen-reader-cheatsheet.md
        • Want resources? See docs/appendix-x-resources.md
        -

        Last updated: February 2026
        Accessibility is foundational to inclusive workflows.

        +

        Last updated: October 2026
        Accessibility is foundational to inclusive workflows.

        Authoritative Sources

        Use these official references when you need the current source of truth for facts in this chapter.

          diff --git a/html/search-index.json b/html/search-index.json index ca3d432d..c5d390ea 100644 --- a/html/search-index.json +++ b/html/search-index.json @@ -1,10 +1,4 @@ [ - { - "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", @@ -81,13 +75,7 @@ "id": "admin/ACCESSIBILITY_CORE_FLOWS.html", "title": "Accessibility Checks for Core Flows", "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 a keyboard-only run made with real key presses in a real browser: the accessibility owner may accept it as a result, and says so in its record. Screen reader and manual visual 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) Not yet run Not yet run 2. Search the website Pass, 28 October 2026 (agent run, accepted) Not yet run Not yet run 3. Listen to a companion episode and open its transcript Pass, 28 October 2026 (agent run, accepted) Not yet run Not yet run 4. Opt in on the registration page Pass, 28 October 2026 (agent run, accepted) Not yet run Not yet run 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: 28 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 this is. - [ ] I can move by headings (H) and by landmarks (D, or the VoiceOver rotor), and the outline makes sense. - [ ] Links and controls have names that say where they go or what they do. - [ ] Lists, tables and code blocks are announced as such, and tables can be read cell by cell. - [ ] Changes without a page load (search results, the regist" - }, - { - "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 " + "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/AGENTS_ROADMAP.html", @@ -395,6 +383,12 @@ "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", @@ -1204,5 +1198,11 @@ "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" } ]