diff --git a/.github/ISSUE_TEMPLATE/accessibility-bug.yml b/.github/ISSUE_TEMPLATE/accessibility-bug.yml index 628b4cbb..a7fe5fc0 100644 --- a/.github/ISSUE_TEMPLATE/accessibility-bug.yml +++ b/.github/ISSUE_TEMPLATE/accessibility-bug.yml @@ -1,5 +1,5 @@ name: Accessibility Bug Report -description: Report a keyboard navigation, screen reader, or other accessibility issue +description: Something in this workshop is hard or impossible to use with your setup, including a screen reader, magnifier, braille display or keyboard alone. title: "[A11Y] " labels: ["accessibility", "bug"] assignees: [] @@ -7,32 +7,17 @@ body: - type: markdown attributes: value: | - Thanks for taking the time to file an accessibility bug report. The more detail you provide, the faster it can be reproduced and fixed. All fields marked as required are needed to triage your report. + Thank you for telling us. Accessibility reports are expertise, not complaints, and partial reports are welcome: fill in what you can. Only the first two fields are required. - - type: dropdown - id: issue-type - attributes: - label: Type of Accessibility Issue - description: Which category best describes what you encountered? - options: - - Keyboard navigation - cannot reach or operate a control with keyboard only - - Screen reader - missing, incorrect, or confusing announcements - - Focus management - focus jumps unexpectedly or is lost - - Heading structure - headings skipped, missing, or in wrong order - - Link / button labels - unlabeled, ambiguous, or "click here" - - Color / contrast - text or controls are hard to distinguish - - Images - missing or inadequate alternative text - - Forms - fields not labeled or error messages not announced - - Time limits - content changes or disappears before I can act - - Other (describe below) - validations: - required: true + You never need to tell us about a disability or diagnosis. If this form is hard to use, or you would rather not post publicly, email support@community-access.org or jeff@jeffbishop.com instead and we will file the issue for you if you want one. + + How we triage and respond is in [ACCESSIBILITY.md](https://github.com/Community-Access/git-going-with-github/blob/main/ACCESSIBILITY.md#reporting-accessibility-issues). If the barrier is on GitHub.com or in VS Code itself, report it here anyway: we document workarounds and pass it on. - type: textarea id: description attributes: - label: Describe the Issue - description: What happened? What did you expect to happen instead? + label: What happened + description: What you were trying to do, and what got in the way. Your own words are best. placeholder: | When I press Tab on the Issues list page, focus skips the filter buttons and lands on the first issue title. I expected Tab to move to the filter @@ -40,76 +25,153 @@ body: validations: required: true + - type: dropdown + id: area + attributes: + label: Where + description: The part of the workshop the barrier is in. + options: + - A page on the workshop website (published HTML) + - A chapter, appendix or challenge as Markdown on GitHub + - The ePub, Word or braille (BRF) download + - A podcast episode, its player or its transcript + - Registration or the student opt-in page + - My Learning Room repository, a challenge issue or a bot comment + - GitHub.com itself, while following the workshop + - VS Code, GitHub Copilot or another tool, while following the workshop + - Something else + validations: + required: true + + - type: input + id: page-url + attributes: + label: Page, file or episode + description: Optional. The URL, file name, chapter or episode number. + placeholder: "https://community-access.github.io/git-going-with-github/docs/05-working-with-issues.html" + validations: + required: false + - type: textarea id: steps attributes: - label: Steps to Reproduce - description: List the exact steps to reproduce the issue, starting from a known page or state. + label: Steps to reproduce + description: Optional but very helpful. Start from a page or state we can find. placeholder: | 1. Navigate to github.com/[org]/[repo]/issues 2. Press Tab from the page heading 3. Focus lands on the first issue title - 4. The "Label" and "Milestone" filter buttons are never reached by Tab validations: - required: true + required: false + + - type: dropdown + id: issue-type + attributes: + label: Type of accessibility issue + description: Optional. Which category best describes what you encountered? + options: + - Not sure + - Keyboard navigation - cannot reach or operate a control with keyboard only + - Screen reader - missing, incorrect, or confusing announcements + - Focus management - focus jumps unexpectedly or is lost + - Heading structure - headings skipped, missing, or in wrong order + - Link / button labels - unlabeled, ambiguous, or "click here" + - Color / contrast - text or controls are hard to distinguish + - Zoom or reflow - content is lost or overlaps when enlarged + - Images or diagrams - missing or inadequate text alternative + - Audio - missing or inaccurate transcript + - Braille - translation or formatting problem in a BRF file + - Forms - fields not labeled or error messages not announced + - Time limits - content changes or disappears before I can act + - Other (describe above) + default: 0 + validations: + required: false + + - type: dropdown + id: severity + attributes: + label: How much it gets in your way + description: | + Optional; maintainers confirm severity during triage. + - Critical: I cannot complete the task at all. + - Serious: I can complete it only with real difficulty or a workaround. + - Moderate: it works but is confusing, slow or inconsistent. + - Minor: a small problem with little effect. + options: + - Not sure + - Critical + - Serious + - Moderate + - Minor + default: 0 + validations: + required: false - type: dropdown id: screen-reader attributes: - label: Screen Reader - description: Which screen reader were you using? + label: Screen reader or other assistive technology + description: Optional. Add the version in "Anything else" if you know it. options: - NVDA (Windows) - JAWS (Windows) + - Narrator (Windows) - VoiceOver (macOS) - VoiceOver (iOS) - TalkBack (Android) - - Narrator (Windows) - Orca (Linux) - - Not using a screen reader + - Screen magnifier (ZoomText, Windows Magnifier, macOS Zoom) + - Braille display + - Voice control or dictation + - Keyboard only, no assistive technology + - Not using assistive technology - Other (describe below) validations: - required: true + required: false - type: dropdown id: browser attributes: label: Browser - description: Which browser were you using? + description: Optional. options: - Google Chrome - Mozilla Firefox - Microsoft Edge - Apple Safari + - Not in a browser (VS Code, an e-reader, a braille device, a podcast app) - Other (describe below) validations: - required: true + required: false - type: input id: os attributes: - label: Operating System and Version - description: For example - Windows 11, macOS Sonoma 14.3, iOS 17.2 + label: Operating system and version + description: Optional. For example - Windows 11, macOS 26, iOS 26 placeholder: Windows 11 validations: - required: true + required: false - type: dropdown id: wcag attributes: label: Relevant WCAG Success Criterion (if known) - description: If you know which WCAG criterion applies, select it. Leave blank if unsure - the team will assess. + description: Optional. Leave blank if unsure - the team will assess. options: - "1.1.1 Non-text Content (alt text)" - "1.3.1 Info and Relationships (semantic structure)" - "1.3.2 Meaningful Sequence (reading order)" - "1.4.1 Use of Color" - "1.4.3 Contrast (Minimum)" + - "1.4.10 Reflow" - "2.1.1 Keyboard (all functionality via keyboard)" - "2.1.2 No Keyboard Trap" - "2.4.3 Focus Order" - "2.4.6 Headings and Labels" - "2.4.7 Focus Visible" + - "2.5.3 Label in Name" - "3.2.2 On Input (no unexpected context changes)" - "3.3.2 Labels or Instructions" - "4.1.2 Name, Role, Value (ARIA)" @@ -121,20 +183,28 @@ body: - type: textarea id: impact attributes: - label: Impact on Your Workflow + label: Impact on your workflow description: | - How does this issue affect your ability to use this project? - Is there a workaround that lets you continue, or are you fully blocked? + Optional. Is there a workaround that lets you continue, or are you fully blocked? placeholder: | I cannot file new issues without mouse assistance because the "New issue" button is not reachable by keyboard. I am fully blocked from creating issues. validations: - required: true + required: false - type: textarea id: additional attributes: - label: Additional Context - description: Anything else that might help - screenshots with alt text, screen reader log excerpts, or links to related issues. + label: Anything else + description: Optional. Versions, workarounds you have tried, related issues, a screen reader speech log, or a recording or screenshot with a text description if you are comfortable sharing one. validations: required: false + + - type: checkboxes + id: follow-up + attributes: + label: Follow-up + description: Optional. + options: + - label: I am willing to test a fix and tell you whether it works for me. + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 764e08ea..fd649457 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: true contact_links: + - name: "Accessibility: Report a Barrier Without GitHub" + url: https://github.com/Community-Access/git-going-with-github/blob/main/ACCESSIBILITY.md#reporting-accessibility-issues + about: If the issue form is hard to use or you would rather not post publicly, email support@community-access.org. How we triage and respond is in ACCESSIBILITY.md. - name: Support Hub - Ongoing Help and Q&A url: https://github.com/Community-Access/support about: Post-workshop support, troubleshooting, and alumni discussion live in the open support hub. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f7870971..73530a4d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -19,15 +19,36 @@ Closes # -## Accessibility Considerations +## Accessibility Checklist - +Accessibility is the reason this workshop exists. Please read the [contributor expectations in ACCESSIBILITY.md](https://github.com/Community-Access/git-going-with-github/blob/main/ACCESSIBILITY.md#contributor-expectations) and check each item that applies to your change. Mark an item N/A when it does not apply (for example, a content-only change has no interface items). -- [ ] Heading levels are sequential (no skipped levels) -- [ ] Link text is descriptive (no "click here" or bare URLs) -- [ ] Any images include meaningful alt text, or `alt=""` if decorative -- [ ] No content relies on color alone to convey meaning -- [ ] Keyboard navigation still works as expected +### Content changes (chapters, appendices, challenges, solutions, README and other docs) + +- [ ] The page still has exactly one H1, and heading levels are sequential (no skipped levels) +- [ ] Link text is descriptive (no "click here", "read more" or bare URLs in running text) +- [ ] Any image has meaningful alt text, and any diagram (including ASCII diagrams) has the same information in text nearby +- [ ] Each new table has a header row and a sentence before it saying what it holds +- [ ] Commands and file contents are in fenced code blocks with a language (`bash`, `text`, `markdown`) +- [ ] Steps give a keyboard route, with NVDA, JAWS and VoiceOver commands where they differ +- [ ] Meaning is not conveyed by color, position or styling alone, and there are no emoji +- [ ] Plain language is used; abbreviations are spelled out on first use +- [ ] Any new audio has a transcript, and any linked video has captions +- [ ] I ran `npm run check:accessibility` and `npm run validate:authoritative-sources`, and `npm run build:html` with the regenerated `html/` committed + +### Interface changes (site template, search, audio player, registration page, issue forms, bot messages) + +- [ ] Everything interactive is reachable and operable with the keyboard alone, in a logical order, with no trap +- [ ] Focus is visible on every control; no focus outline was removed without an equally visible replacement +- [ ] Every control has a label, and its accessible name contains its visible text +- [ ] Contrast is sufficient in the light, dark and high contrast themes, and color is not the only indicator +- [ ] Content reflows at 320 CSS pixels wide and works at 200% zoom +- [ ] I checked the change with a screen reader at least once (say which one and which browser under Testing) +- [ ] A new dependency that affects what learners meet has a short accessibility review in this pull request + +### Accessibility notes + + ## Testing diff --git a/.github/README.md b/.github/README.md index 438e78a2..fb9e9bd7 100644 --- a/.github/README.md +++ b/.github/README.md @@ -19,6 +19,8 @@ These workflows operate on this repository itself: | `build-epub.yml` | Builds ePub version of workshop content | | `create-release.yml` | Creates tagged releases | | `deploy-pages.yml` | Deploys content to GitHub Pages | +| `docs-accessibility.yml` | Runs the documentation accessibility check on Markdown changes (see ACCESSIBILITY.md) | +| `accessibility-review-reminder.yml` | Opens the quarterly accessibility progress update and review issue | | `generate-diagram-svgs.yml` | Converts diagram sources to SVG | | `registration.yml` | Processes student registration | | `sync-docs-to-wiki.yml` | Syncs documentation to the repository wiki | diff --git a/.github/scripts/__tests__/check-docs-accessibility.test.js b/.github/scripts/__tests__/check-docs-accessibility.test.js new file mode 100644 index 00000000..3bad61ed --- /dev/null +++ b/.github/scripts/__tests__/check-docs-accessibility.test.js @@ -0,0 +1,98 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const { execFileSync } = require('node:child_process'); +const { checkMarkdown } = require('../../../scripts/check-docs-accessibility'); + +const repoRoot = path.resolve(__dirname, '../../../'); + +function rules(text, options) { + return checkMarkdown(text, options).map((f) => f.rule); +} + +test('a clean page has no findings', () => { + const page = [ + '# Title', + '', + '## Section', + '', + 'Read the [Contributing Guide](CONTRIBUTING.md).', + '', + '| Action | Key |', + '|---|---|', + '| Search | `/` |', + '', + '```bash', + 'npm run build:html', + '```' + ].join('\n'); + assert.deepEqual(rules(page), []); +}); + +test('heading rules: one H1 and no skipped levels', () => { + assert.deepEqual(rules('## No title'), ['heading-single-h1']); + assert.deepEqual(rules('# One\n\n# Two'), ['heading-single-h1']); + assert.deepEqual(rules('# Title\n\n### Skipped'), ['heading-increment']); + assert.deepEqual(rules('# Title\n\n## A\n\n### B\n\n## C'), []); +}); + +test('wiki fragments are exempt from the H1 rule', () => { + assert.deepEqual(rules('## Sidebar', { fragment: true }), []); +}); + +test('headings, links and emoji inside code are ignored', () => { + const page = '# Title\n\n```markdown\n#### not a heading [here](x) \u{1F680}\n```\n\nUse `[here](x)` as a bad example.'; + assert.deepEqual(rules(page), []); +}); + +test('HTML comments are ignored', () => { + assert.deepEqual(rules('# Title\n\n'), []); +}); + +test('images need real alternative text', () => { + assert.deepEqual(rules('# T\n\n![](a.png)'), ['image-alt']); + assert.deepEqual(rules('# T\n\n![Screenshot](a.png)'), ['image-alt']); + assert.deepEqual(rules('# T\n\n'), ['image-alt']); + assert.deepEqual(rules('# T\n\n'), []); + assert.deepEqual(rules('# T\n\n![The new issue form](a.png)'), []); +}); + +test('ambiguous link text is reported', () => { + assert.deepEqual(rules('# T\n\nClick [here](x).'), ['link-text']); + assert.deepEqual(rules('# T\n\n[Read more.](x)'), ['link-text']); + assert.deepEqual(rules('# T\n\nclick here'), ['link-text']); + assert.deepEqual(rules('# T\n\n[Read the setup guide](x)'), []); +}); + +test('table headers must not be empty; inline code counts as text', () => { + assert.deepEqual(rules('# T\n\n| | |\n|---|---|\n| a | b |'), ['table-empty-header']); + assert.deepEqual(rules('# T\n\n| `flag` | Result |\n| --- | --- |\n| a | b |'), []); +}); + +test('code fences need a language; closing fences are not counted', () => { + assert.deepEqual(rules('# T\n\n```\noutput\n```'), ['code-fence-language']); + assert.deepEqual(rules('# T\n\n````markdown\n```\ninner\n```\n````'), []); +}); + +test('emoji are reported, copyright and trademark signs are not', () => { + assert.deepEqual(rules('# T\n\nDone \u2705'), ['emoji']); + assert.deepEqual(rules('# T\n\n\u00a9 Community Access, GitHub\u2122'), []); +}); + +test('the repository has no findings beyond its recorded baseline', () => { + const env = { ...process.env }; + const output = execFileSync(process.execPath, [path.join(repoRoot, 'scripts/check-docs-accessibility.js')], { + cwd: repoRoot, + env, + encoding: 'utf8' + }); + assert.match(output, /No new accessibility findings/); +}); + +test('the baseline only lists files that exist', () => { + const baseline = JSON.parse(fs.readFileSync(path.join(repoRoot, 'scripts/docs-accessibility-baseline.json'), 'utf8')); + for (const rel of Object.keys(baseline.files)) { + assert.ok(fs.existsSync(path.join(repoRoot, rel)), `${rel} is in the baseline but does not exist`); + } +}); diff --git a/.github/workflows/accessibility-review-reminder.yml b/.github/workflows/accessibility-review-reminder.yml new file mode 100644 index 00000000..0007f8bc --- /dev/null +++ b/.github/workflows/accessibility-review-reminder.yml @@ -0,0 +1,79 @@ +name: Accessibility Review Reminder + +# Opens one issue each quarter that asks the accessibility owner to publish an +# accessibility progress update and review ACCESSIBILITY.md (Open Source +# Accessibility Framework, Community action 5, with the reviews that Testing +# action 6 and Workflow actions 7 and 10 ask for). The issue lists the +# accessibility issues opened and closed since the previous quarter, so the +# update starts from real numbers. See ACCESSIBILITY.md, "Progress updates". + +on: + schedule: + # 15:00 UTC on the first day of January, April, July and October. + - cron: "0 15 1 1,4,7,10 *" + workflow_dispatch: + +permissions: + contents: read + issues: write + +jobs: + open-review-issue: + name: Open the quarterly accessibility review issue + runs-on: ubuntu-latest + + steps: + - name: Open the review issue + uses: actions/github-script@v7 + with: + script: | + const { owner, repo } = context.repo; + const now = new Date(); + const quarter = Math.floor(now.getUTCMonth() / 3) + 1; + const title = `Accessibility progress update and review, ${now.getUTCFullYear()} Q${quarter}`; + + const existing = await github.paginate(github.rest.issues.listForRepo, { + owner, repo, state: 'all', labels: 'accessibility', per_page: 100 + }); + if (existing.some((issue) => issue.title === title)) { + core.info(`"${title}" already exists; nothing to do.`); + return; + } + + const since = new Date(now); + since.setUTCMonth(since.getUTCMonth() - 3); + const sinceDate = since.toISOString().slice(0, 10); + const search = async (q) => + (await github.rest.search.issuesAndPullRequests({ q: `repo:${owner}/${repo} label:accessibility ${q}`, per_page: 1 })).data.total_count; + const opened = await search(`created:>=${sinceDate} -label:"accessibility review"`); + const closed = await search(`closed:>=${sinceDate} -label:"accessibility review"`); + const open = await search('is:open -label:"accessibility review"'); + + const base = `https://github.com/${owner}/${repo}`; + const body = [ + `Quarterly accessibility review for ${now.getUTCFullYear()} Q${quarter}, opened automatically by \`accessibility-review-reminder.yml\`.`, + '', + '## Since ' + sinceDate, + '', + `- Accessibility issues and pull requests opened: ${opened}`, + `- Accessibility issues and pull requests closed: ${closed}`, + `- Still open: ${open} ([open accessibility work](${base}/issues?q=is%3Aopen+label%3Aaccessibility))`, + '', + '## Checklist', + '', + '- [ ] Add a dated entry to "Progress updates" in ACCESSIBILITY.md: completed work, remaining work, known barriers, links.', + '- [ ] Review "Supported environments" and "Known limitations"; add what was tested since the last review.', + '- [ ] Record any keyboard, screen reader or manual checks that were run in admin/ACCESSIBILITY_CORE_FLOWS.md.', + '- [ ] Check that open reports have an acknowledgement, a severity, a status and a next step.', + '- [ ] Keep a few `good first issue` and `help wanted` accessibility issues open, with context and acceptance criteria.', + '- [ ] Review the dependency list in ACCESSIBILITY.md and any upstream blockers.', + '- [ ] Credit accessibility contributors in the update, only in the form each person agreed to.', + '- [ ] Check the matching actions in the public Open Source Accessibility Framework tracking issue.', + '', + 'Close this issue with a link to the pull request that adds the update.' + ].join('\n'); + + const issue = await github.rest.issues.create({ + owner, repo, title, body, labels: ['accessibility', 'accessibility review'] + }); + core.info(`Opened #${issue.data.number}`); diff --git a/.github/workflows/docs-accessibility.yml b/.github/workflows/docs-accessibility.yml new file mode 100644 index 00000000..fe01d359 --- /dev/null +++ b/.github/workflows/docs-accessibility.yml @@ -0,0 +1,56 @@ +name: Documentation Accessibility Check + +# The repository's automated accessibility check (Open Source Accessibility +# Framework, Testing action 1). It checks the Markdown that becomes the +# published site, the ePub and the braille files for missing or skipped +# headings, missing alternative text, ambiguous link text, empty table +# headers, code blocks without a language, and emoji. Known findings are in +# scripts/docs-accessibility-baseline.json; a pull request fails only when it +# adds a new one. See ACCESSIBILITY.md, "Contributor expectations". + +on: + pull_request: + paths: + - "*.md" + - "docs/**/*.md" + - "admin/**/*.md" + - "classroom/**/*.md" + - "scripts/check-docs-accessibility.js" + - "scripts/docs-accessibility-baseline.json" + - ".github/workflows/docs-accessibility.yml" + push: + branches: + - main + paths: + - "*.md" + - "docs/**/*.md" + - "admin/**/*.md" + - "classroom/**/*.md" + - "scripts/check-docs-accessibility.js" + - "scripts/docs-accessibility-baseline.json" + - ".github/workflows/docs-accessibility.yml" + workflow_dispatch: + +permissions: + contents: read + +jobs: + check-docs-accessibility: + name: Check Markdown accessibility + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Check for new accessibility findings + run: npm run check:accessibility + + - name: List every known finding + if: always() + run: node scripts/check-docs-accessibility.js --report diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md new file mode 100644 index 00000000..668782dc --- /dev/null +++ b/ACCESSIBILITY.md @@ -0,0 +1,251 @@ +# 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](https://open-source-accessibility.github.io/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](https://www.w3.org/TR/WCAG22/) 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](docs/appendix-a-glossary.md), and never assume knowledge a chapter has not taught. + +## Contributor expectations + +These apply to every pull request. [CONTRIBUTING.md](CONTRIBUTING.md#6-accessibility-requirements) gives the detail and the commands, and the [pull request template](https://github.com/Community-Access/git-going-with-github/blob/main/.github/PULL_REQUEST_TEMPLATE.md) 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](#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](#automated-checks)), `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](#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. + +### Interface requirements + +The workshop's own interfaces are the published website (built by `scripts/build-html.js`), its search page, the companion audio player, the registration page, the issue forms in `.github/ISSUE_TEMPLATE/`, and the comments our automation posts. New and changed interfaces must meet these requirements, and reviewers check them against the pull request checklist: + +- Every page has a descriptive ``, `lang="en"`, a skip link to the main content, and `header`, `nav`, `main` and `footer` landmarks with distinct names. +- Everything interactive is reachable and operable from the keyboard, in a logical order, with no keyboard trap. +- Focus is always visible: never remove the focus outline without a replacement that is at least as visible. +- Every control has a visible label, and its accessible name contains the visible words; native HTML elements before ARIA. +- Text and focus indicators have sufficient contrast in the light, dark and high contrast themes the site supports. +- Content reflows at 320 CSS pixels wide and works at 200% zoom without loss of content or function. +- Changes that happen without a page load (search results, a live count) are announced or easy to find. +- Motion respects `prefers-reduced-motion`. +- Bot comments and issue forms use headings and lists, plain language, and no emoji. + +Barriers found in the current interfaces are tracked as issues labeled `accessibility` (see [Known limitations](#known-limitations)). + +### Automated checks + +`scripts/check-docs-accessibility.js` checks the Markdown that becomes the website, the ePub and the braille files: one H1 per page, no skipped heading levels, alternative text on images, descriptive link text, table headers, a language on every code block, and no emoji. It runs on every pull request that changes Markdown ([workflow](https://github.com/Community-Access/git-going-with-github/blob/main/.github/workflows/docs-accessibility.yml)) and in the automation test suite. Findings that predate the check are counted in `scripts/docs-accessibility-baseline.json` and tracked in [issue #267](https://github.com/Community-Access/git-going-with-github/issues/267); the check fails only when a change adds one. It does not check the rendered HTML, `learning-room/` (which contains deliberate defects for learners to fix), or anything a person must judge, which is what the [manual checks](admin/ACCESSIBILITY_CORE_FLOWS.md) are for. No automated check finds every barrier. + +## Reporting accessibility issues + +If something in this workshop is hard or impossible for you to use, please tell us. Accessibility reports are expertise, not complaints, and this includes barriers you meet on GitHub.com or in VS Code while following the workshop. + +- **On GitHub:** open an issue with the [accessibility bug report form](https://github.com/Community-Access/git-going-with-github/issues/new?template=accessibility-bug.yml). Only two fields are required; partial reports are welcome. +- **By email, if GitHub is a barrier for you, or you would rather not post publicly:** write to [support@community-access.org](mailto:support@community-access.org) or to Jeff Bishop at [jeff@jeffbishop.com](mailto:jeff@jeffbishop.com). We will file the issue for you if you want one, and keep your details private if you ask. +- **During a live workshop:** tell a facilitator in the room or in the workshop chat, and we will file it with you. + +Helpful details, all optional: + +- What you were trying to do, and what happened instead. +- Where: the page URL, the chapter or challenge, the download (ePub, Word, BRF), or the podcast episode. +- Your operating system, browser and assistive technology, with versions if you know them. +- How much it gets in your way (see [Severity](#severity)). +- Whether you would be willing to try a fix and tell us if it works. + +You never need to tell us about a disability or diagnosis. + +### Severity + +We use four levels, based on how much the barrier stops a person completing a task. Reporters do not need to choose one; maintainers assign or confirm it during triage. + +- **Critical:** you cannot complete a core task, such as reading a chapter, registering, or finishing a challenge, and there is no workaround. +- **Serious:** you can complete the task only with real difficulty or a workaround. +- **Moderate:** the task works but is confusing, slow or inconsistent. +- **Minor:** a small problem with little effect on getting things done. + +### How we respond + +- We acknowledge every accessibility report promptly and respectfully, thank the reporter, and say what happens next. We treat the report as expertise about the workshop, not a complaint. +- We do not ask you to justify your experience or to disclose personal information. If we need more detail, we ask specific questions about the steps and your setup, never whether the barrier is real. +- At triage the report gets the `accessibility` label, a severity, an owner and, where we can give one, a target date, all stated on the issue. +- Where we can, we give a workaround while a fix is in progress, and we add it to the relevant chapter so the next learner does not meet the same barrier. +- If the cause is on GitHub.com, in VS Code, in a screen reader or in another tool we do not control, we say so, document the workaround, report it upstream where we can, and link the upstream report on the issue. +- We post an update on the issue whenever its status or expected timing changes, and link the pull request that fixes it. +- Before we close a report, we write down the outcome on the issue, and we ask the reporter, or another person affected, to confirm the fix works for them when they are willing. +- We credit reporters and testers only in the way they choose (see [Recognizing contributions](#recognizing-contributions)). + +If we cannot meet a date we gave, we say why on the issue, share any workaround, and give a new date. + +## Taking part + +There are several ways to take part, and no single channel is required: + +- **Asynchronous, at any time:** read and listen on the [workshop website](https://community-access.github.io/git-going-with-github/); ask questions in [Discussions](https://github.com/Community-Access/git-going-with-github/discussions) or the [Community Access support hub](https://github.com/Community-Access/support); open issues and pull requests here; or email the addresses above. The whole curriculum, every challenge and every solution can be done self-paced. +- **Live cohorts:** the two-day workshop runs in person and remotely. Facilitation plans ([Day 1 agenda](admin/DAY1_AGENDA.md), [Day 2 agenda](admin/DAY2_AGENDA.md)) give remote participants the same links, chat channel and written checkpoints, with CART captioning or ASL interpretation where available. Every live block has a written "you are done when" checkpoint and can be finished afterwards, so missing part of a session does not mean missing the content. +- **Non-code contributions are as welcome as code:** reporting and reproducing barriers, testing with your screen reader or braille display, correcting a keyboard command, reviewing a chapter, improving a transcript, or reviewing other people's pull requests. + +**Accommodations.** If you need an accommodation to take part in a live session or to contribute, or a tool we use is a barrier for you, email [support@community-access.org](mailto:support@community-access.org) or [jeff@jeffbishop.com](mailto:jeff@jeffbishop.com) privately. You do not need to explain why, and we will not share what you tell us. + +**Collaboration tools we have reviewed.** The tools the workshop asks people to use, and where their accessibility is documented: + +- **GitHub.com** (issues, pull requests, Discussions, the Learning Room): chapters 02 to 10 and the [screen reader cheat sheet](docs/appendix-b-screen-reader-cheatsheet.md) teach each one with NVDA, JAWS and VoiceOver, including the known rough edges and workarounds. Known blockers are listed in [Dependencies and upstream blockers](#dependencies-and-upstream-blockers). +- **VS Code, github.dev and GitHub Copilot:** chapters 11, 12 and 16, the [VS Code accessibility reference](docs/appendix-g-vscode-reference.md) and the [GitHub Copilot reference](docs/appendix-k-copilot-reference.md) cover screen reader mode, Accessible View, accessibility signals and the Accessible Diff Viewer. +- **The workshop chat channel used in live cohorts** has not been reviewed by us; everything said there that matters is also posted in the repository or Discussions, which are the alternative. +- **The podcast** is an optional companion: each episode has a transcript, and every episode covers a chapter that is available as text. + +Everyone who takes part follows the [Code of Conduct](CODE_OF_CONDUCT.md). It names disability-related harassment, dismissing accessibility feedback, personal attacks and publishing private information as unacceptable, and gives a private contact for reports. The maintainers enforce it. + +**How to help.** Open accessibility work is labeled [`accessibility`](https://github.com/Community-Access/git-going-with-github/issues?q=is%3Aopen+label%3Aaccessibility). Issues that suit a first contribution are labeled [`accessibility` and `good first issue`](https://github.com/Community-Access/git-going-with-github/issues?q=is%3Aopen+label%3Aaccessibility+label%3A%22good+first+issue%22), and ones where we need specialist experience, such as daily use of a particular screen reader, are labeled [`accessibility` and `help wanted`](https://github.com/Community-Access/git-going-with-github/issues?q=is%3Aopen+label%3Aaccessibility+label%3A%22help+wanted%22). Each has the context, the steps and acceptance criteria to start from. Ask questions on the issue or in Discussions, and a maintainer will answer. + +**Feedback from learners.** After each cohort we ask participants to fill in the [workshop feedback form](https://github.com/Community-Access/git-going-with-github/issues/new?template=feedback-workshop.yml), which has a section on accessibility and inclusion. The accessibility owner reads every response, files the barriers it describes as `accessibility` issues, and summarizes what changed in the next progress update. + +## Ownership and maintenance + +Accessibility is owned by **Jeff Bishop**, workshop facilitator and maintainer ([@accesswatch](https://github.com/accesswatch) on GitHub, [jeff@jeffbishop.com](mailto:jeff@jeffbishop.com)), with the workshop facilitators. + +The accessibility owner: + +- triages accessibility reports, assigns severity and an owner, and makes sure each gets an acknowledgement, a status and a next step; +- keeps accessibility work visible with the `accessibility` label, and keeps a few well-described `good first issue` and `help wanted` accessibility issues open; +- reviews pull requests against the contributor expectations and interface requirements above (pull requests are routed for review by [CODEOWNERS](https://github.com/Community-Access/git-going-with-github/blob/main/.github/CODEOWNERS)); +- reviews the accessibility of new dependencies before they are adopted, and tracks upstream blockers; +- keeps this document, the supported environments, the known limitations, the [test records](admin/ACCESSIBILITY_CORE_FLOWS.md) and the framework progress current; +- publishes the quarterly progress update and escalates unresolved accessibility risks to the other maintainers, for example before a cohort starts. + +This document is reviewed every quarter, when the [review reminder](https://github.com/Community-Access/git-going-with-github/blob/main/.github/workflows/accessibility-review-reminder.yml) opens its issue, and before each cohort. If ownership changes, this section is updated in the same pull request that changes `.github/CODEOWNERS`. + +## Dependencies and upstream blockers + +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. +- **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. +- **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)). +- **Podcast audio:** episodes are generated with the Kokoro text-to-speech engine (Piper as a fallback) and served from an external host, `lp.csedesigns.com`, whose player page is outside this repository. Mitigation: every episode has a transcript, and the site links the audio file directly so any player can be used. +- **GitHub Pages and the repository wiki** host the published site and its wiki copy. + +## Supported environments + +What the workshop is written for and supported on, taken from [Chapter 00: Pre-Workshop Setup](docs/00-pre-workshop-setup.md): + +- **Operating systems:** Windows and macOS. Linux works for Git and VS Code, but the screen reader instructions do not cover Orca. +- **Screen readers:** NVDA and JAWS on Windows, VoiceOver on macOS. Every exercise gives commands for all three. VoiceOver on iOS and TalkBack on Android are covered only for the GitHub Mobile app, in the [GitHub Mobile appendix](docs/appendix-v-github-mobile.md). +- **Browsers:** Chrome or Firefox (recommended on Windows), Edge (acceptable), Safari (recommended with VoiceOver on macOS). +- **Input:** keyboard only is the primary method, and every step has a keyboard route. Pointer and touch also work. Voice control and switch access have not been tested. +- **Tools:** VS Code 1.113 or later, Git 2.20 or later, and a GitHub account with GitHub Copilot Free or a paid plan. +- **Formats:** the website (HTML), Markdown on GitHub, ePub, Word, and braille in UEB grade 2 and EBAE grade 2 (from the [releases page](https://github.com/Community-Access/git-going-with-github/releases)), and companion podcast audio with transcripts. + +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. + +## 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. +- **The Quick Jumps links hide their focus outline.** On every chapter page, keyboard focus on the Quick Jumps links shows only an underline and a faint background, which is hard to see with low vision ([#265](https://github.com/Community-Access/git-going-with-github/issues/265)). Workaround: the same links are in the "On this page" list and the page headings, which show the normal outline. +- **The site search box is named "Search documentation" but shows "Search docs".** Voice control users may need to say "Search documentation", or move to the field with Tab ([#266](https://github.com/Community-Access/git-going-with-github/issues/266)). +- **Some facilitator guides start headings with emoji**, which screen readers read aloud by name, and some code blocks do not say what they contain ([#264](https://github.com/Community-Access/git-going-with-github/issues/264), [#267](https://github.com/Community-Access/git-going-with-github/issues/267), [#268](https://github.com/Community-Access/git-going-with-github/issues/268)). Learner chapters are not affected by the emoji. +- **The braille files are machine translated.** They are produced automatically by liblouis from a plain-text version of the ePub, so tables are flattened into lines of text and print formatting is not converted to braille formatting. We have no record of review by a certified braille transcriber. Workaround: the ePub, Word or HTML version read with a refreshable braille display keeps the tables and headings. +- **Podcast episodes are companions, not readings.** Episodes use synthetic voices and summarize a chapter rather than reading it word for word. Every episode has a transcript, and the chapter itself is the complete source. +- **Linked videos are not ours.** Chapter 16 links four YouTube videos about Copilot with a screen reader; we have not checked their captions. The same steps are written in the chapter. +- **GitHub and VS Code change faster than the curriculum.** A button, label or announcement may differ from what a chapter says. Use the exploration skills the README describes, and file a curriculum issue so we can update the chapter. +- **The Learning Room has deliberate defects.** Files in `learning-room/` (for example `docs/keyboard-shortcuts.md`) contain accessibility problems on purpose, for learners to find and fix. They are exercises, not barriers to report, unless the exercise itself is hard to use. +- **Upstream barriers we can only work around:** see [Dependencies and upstream blockers](#dependencies-and-upstream-blockers). + +## Progress updates + +We publish accessibility progress here, every quarter and after each cohort, and in our public Open Source Accessibility Framework tracking issue. Each update lists completed work, remaining work, known barriers and links. The [review reminder workflow](https://github.com/Community-Access/git-going-with-github/blob/main/.github/workflows/accessibility-review-reminder.yml) opens an issue labeled `accessibility review` on the first day of each quarter with the numbers since the last update and a checklist; the update is added below in a pull request that closes it. + +### October 2026: adopting the framework + +- **Completed:** this document; a reworked [accessibility bug report form](https://github.com/Community-Access/git-going-with-github/issues/new?template=accessibility-bug.yml) with only two required fields and an email alternative; a full accessibility checklist in the pull request template; the documentation accessibility check in CI, with its first findings tracked in [#267](https://github.com/Community-Access/git-going-with-github/issues/267); fixes to a skipped heading level (Appendix Z), a second H1 (Appendix L), empty table headers on the registration pages, and a stray line above the title of CONTRIBUTING.md. Earlier in 2026: an EBAE braille file beside the UEB one ([#174](https://github.com/Community-Access/git-going-with-github/issues/174)), and Chapter 11's explanation of the VoiceOver "selection replaced" announcement ([#175](https://github.com/Community-Access/git-going-with-github/issues/175)). +- **Remaining:** run and record the [core flow checks](admin/ACCESSIBILITY_CORE_FLOWS.md); fix the site template findings ([#265](https://github.com/Community-Access/git-going-with-github/issues/265), [#266](https://github.com/Community-Access/git-going-with-github/issues/266)); work through the recorded documentation findings ([#264](https://github.com/Community-Access/git-going-with-github/issues/264), [#268](https://github.com/Community-Access/git-going-with-github/issues/268)); find the cause of [#175](https://github.com/Community-Access/git-going-with-github/issues/175). +- **Known barriers:** see [Known limitations](#known-limitations). +- **How to help:** issues labeled [`accessibility`](https://github.com/Community-Access/git-going-with-github/issues?q=is%3Aopen+label%3Aaccessibility). + +## 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. + +## 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. + +- **[Accessibility bug report form](https://github.com/Community-Access/git-going-with-github/blob/main/.github/ISSUE_TEMPLATE/accessibility-bug.yml):** a GitHub issue form that asks for the details triage needs while requiring only two fields, never asks about disability, and offers an email alternative. Replace the "Where" options and the contact addresses with your own. It cannot help people who cannot use GitHub at all; keep an email or other route beside it. +- **[Pull request accessibility checklist](https://github.com/Community-Access/git-going-with-github/blob/main/.github/PULL_REQUEST_TEMPLATE.md):** content and interface checks written for a documentation project. Drop the groups that do not apply; it prompts a contributor, it does not test anything. +- **[Documentation accessibility check](https://github.com/Community-Access/git-going-with-github/blob/main/scripts/check-docs-accessibility.js)** with its [baseline](https://github.com/Community-Access/git-going-with-github/blob/main/scripts/docs-accessibility-baseline.json) and [workflow](https://github.com/Community-Access/git-going-with-github/blob/main/.github/workflows/docs-accessibility.yml): a dependency-free Node.js script that checks Markdown for heading structure, alternative text, link text, table headers, code block languages and emoji, and blocks only new findings so an existing project can adopt it on day one. Needs Node.js 18 or later. It reads Markdown source, not rendered pages, so pair it with a check of your built site. +- **[Template testing checklist](admin/ACCESSIBILITY_TESTING.md)** and **[core flow checks](admin/ACCESSIBILITY_CORE_FLOWS.md):** step-by-step NVDA, JAWS and VoiceOver procedures for issue forms and web pages, and test records for key tasks. Adapt the tasks to your project's own. +- **This document:** a worked `ACCESSIBILITY.md` for a documentation and training project, following the framework's sections. +- **[Quarterly review reminder](https://github.com/Community-Access/git-going-with-github/blob/main/.github/workflows/accessibility-review-reminder.yml):** a scheduled workflow that opens a progress-update issue with the quarter's accessibility issue counts. It needs an `accessibility` label and issue write permission. +- **The curriculum itself:** a screen-reader-first course in contributing on GitHub, with the [screen reader cheat sheet](docs/appendix-b-screen-reader-cheatsheet.md) and the [accessibility standards reference](docs/appendix-m-accessibility-standards.md) as standalone references. + +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](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/) in its four phases and record our progress, action by action, in a public tracking issue in the framework's repository. Progress is self-reported. 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. Keyboard, screen reader and manual checks of the core tasks are written down but not yet run and recorded. +- **Community:** a feedback form after each cohort and labeled issues to invite help; documented responses to reports; 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. + +## 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](mailto:support@community-access.org). Thank you for helping make GIT Going with GitHub work for everyone. + +## Authoritative Sources + +Use these official references when you need the current source of truth for facts in this document. + +- [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/) +- [Open Source Accessibility Framework source and phase documents](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework) +- [Accessibility Toolkit, reference ACCESSIBILITY.md](https://github.com/open-source-accessibility/accessibility-toolkit/blob/main/ACCESSIBILITY.md) +- [W3C Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) +- [W3C Web Content Accessibility Guidelines (WCAG) 2 overview](https://www.w3.org/WAI/standards-guidelines/wcag/) +- [GitHub accessibility](https://accessibility.github.com/) +- [GitHub Docs, adding a code of conduct to your project](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) +- [GitHub Docs, syntax for issue forms](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms) + +### Section-Level Source Map + +Use this map to verify facts for each major section in this file. + +- **Priorities:** [W3C Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/) +- **Contributor expectations:** [W3C Web Content Accessibility Guidelines (WCAG) 2 overview](https://www.w3.org/WAI/standards-guidelines/wcag/), [Accessibility Toolkit, reference ACCESSIBILITY.md](https://github.com/open-source-accessibility/accessibility-toolkit/blob/main/ACCESSIBILITY.md) +- **Reporting accessibility issues:** [GitHub Docs, syntax for issue forms](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms), [Open Source Accessibility Framework source and phase documents](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework) +- **Taking part:** [GitHub Docs, adding a code of conduct to your project](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project), [GitHub accessibility](https://accessibility.github.com/) +- **Ownership and maintenance:** [Open Source Accessibility Framework source and phase documents](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework) +- **Dependencies and upstream blockers:** [GitHub accessibility](https://accessibility.github.com/), [Open Source Accessibility Framework source and phase documents](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework) +- **Supported environments:** [Open Source Accessibility Framework source and phase documents](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework) +- **Known limitations:** [Accessibility Toolkit, reference ACCESSIBILITY.md](https://github.com/open-source-accessibility/accessibility-toolkit/blob/main/ACCESSIBILITY.md) +- **Progress updates:** [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/) +- **Recognizing contributions:** [Open Source Accessibility Framework source and phase documents](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework) +- **Reusing our accessibility materials:** [Open Source Accessibility Framework source and phase documents](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework) +- **Open Source Accessibility Framework:** [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 007f72f2..7272e8d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,3 @@ - -**Table: Keyboard shortcut for focusing search in different screen readers** - # Contributing to This Workshop Repository Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome. @@ -209,7 +206,7 @@ git push origin fix-nvda-shortcut-section-05 ### Keyboard Shortcuts -Format all keyboard shortcuts in a table when listing more than two: +Format all keyboard shortcuts in a table when listing more than two. Introduce each table with a sentence that says what its rows are, as this example does: it shows the keyboard shortcut for focusing search in each screen reader. | Action | NVDA | JAWS | VoiceOver | |--------|------|------|-----------| @@ -227,6 +224,16 @@ When mentioning a single shortcut inline: use backticks - `NVDA+F7` Every document in this repository is used by screen reader users. Accessibility is not a nice-to-have - it is the primary requirement. All contributions must meet the following: +The full set of expectations, including the requirements for the website template and other interfaces, is in [the contributor expectations in ACCESSIBILITY.md](ACCESSIBILITY.md#contributor-expectations). The [pull request template](https://github.com/Community-Access/git-going-with-github/blob/main/.github/PULL_REQUEST_TEMPLATE.md) turns them into a checklist. Before you push, run the documentation accessibility check, which fails if your change adds a new finding: + +```bash +npm run check:accessibility +``` + +To see every finding with its line number, including the ones already recorded, run `node scripts/check-docs-accessibility.js --report`. If you fix a recorded finding, lower its count in `scripts/docs-accessibility-baseline.json` in the same pull request. + +To report an accessibility barrier in the workshop, use the [accessibility bug report form](https://github.com/Community-Access/git-going-with-github/issues/new?template=accessibility-bug.yml), or email the addresses in [ACCESSIBILITY.md](ACCESSIBILITY.md#reporting-accessibility-issues) if GitHub is a barrier for you. Accessibility issues that suit a first contribution are labeled `accessibility` and `good first issue`; ones where we need specialist experience are labeled `accessibility` and `help wanted`. + ### Heading Structure - Every heading must be in-sequence (no skipping from H2 to H4) @@ -423,7 +430,7 @@ If two weeks pass with no response, feel free to leave a comment on the PR to ch **For urgent issues with the workshop materials during a live event:** Contact the facilitator directly -**For accessibility concerns:** Tag your issue or comment with the `accessibility` label +**For accessibility concerns:** Use the [accessibility bug report form](https://github.com/Community-Access/git-going-with-github/issues/new?template=accessibility-bug.yml), which applies the `accessibility` label for you, or see [ACCESSIBILITY.md](ACCESSIBILITY.md#reporting-accessibility-issues) for other ways to report, including by email. If you need an accommodation to contribute, email us privately; you do not need to explain why *Workshops run better when participants contribute back. Every correction, every clarification, every additional exercise makes this material stronger for everyone who comes after you. Your name in the commit history is not the end of your participation - it is the beginning.* diff --git a/README.md b/README.md index 659763f0..4a579dbb 100644 --- a/README.md +++ b/README.md @@ -238,6 +238,7 @@ Every chapter has an "If You Get Stuck" section. Every challenge has a [referenc โ”œโ”€โ”€ README.md -- You are here โ”œโ”€โ”€ CONTRIBUTING.md -- How to contribute to this repo โ”œโ”€โ”€ CODE_OF_CONDUCT.md -- Community standards +โ”œโ”€โ”€ ACCESSIBILITY.md -- Accessibility commitment, reporting, and known limitations โ”œโ”€โ”€ admin/FACILITATOR_GUIDE.md -- For workshop organizers only โ”œโ”€โ”€ admin/DAY1_AGENDA.md -- Day 1 workshop schedule โ”œโ”€โ”€ admin/DAY2_AGENDA.md -- Day 2 workshop schedule @@ -314,6 +315,12 @@ And by the end of Day 2, you will not just be a learner. You will be a product m - **File an issue** in this repository if something in these docs is unclear - **Community:** [GitHub Accessibility Discussions](https://github.com/orgs/community/discussions/categories/accessibility) +## Accessibility of This Project + +How we work on the workshop's own accessibility, how to report a barrier (on GitHub or by email), how we respond, what the workshop supports and what we know is not yet good enough are all in [ACCESSIBILITY.md](ACCESSIBILITY.md). We follow GitHub's [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/), an improvement framework rather than a certification, and publish our progress in ACCESSIBILITY.md. + +To report a barrier, use the [accessibility bug report form](https://github.com/Community-Access/git-going-with-github/issues/new?template=accessibility-bug.yml) or email [support@community-access.org](mailto:support@community-access.org). To help, look for issues labeled [`accessibility`](https://github.com/Community-Access/git-going-with-github/issues?q=is%3Aopen+label%3Aaccessibility). + ## License All workshop documentation is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) - you are free to share and adapt with attribution. @@ -343,4 +350,5 @@ Use this map to verify facts for each major section in this file. - **Screen Reader Users: Start Here:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [W3C Web Content Accessibility Guidelines (WCAG) 2 overview](https://www.w3.org/WAI/standards-guidelines/wcag/), [WAI tutorials for accessible design patterns](https://www.w3.org/WAI/tutorials/), [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) - **The Goal of This Event:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) - **Questions Before the Event?:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Accessibility of This Project:** [Open Source Accessibility Framework](https://open-source-accessibility.github.io/Open-Source-Accessibility-Framework/), [W3C Web Content Accessibility Guidelines (WCAG) 2 overview](https://www.w3.org/WAI/standards-guidelines/wcag/) - **License:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) diff --git a/REGISTER.md b/REGISTER.md index bd807fc8..bc35ea16 100644 --- a/REGISTER.md +++ b/REGISTER.md @@ -22,7 +22,7 @@ Beyond class, I remain with you through the Support Hub, progression bots, and c You only need one path to begin. -| | | +| Item | Details | |---|---| | **Status** | Open for student opt-in | | **Current confirmed registrations** | **<span id="registration-count-live">Loading...</span>** | diff --git a/admin/ACCESSIBILITY_CORE_FLOWS.md b/admin/ACCESSIBILITY_CORE_FLOWS.md new file mode 100644 index 00000000..2891e27a --- /dev/null +++ b/admin/ACCESSIBILITY_CORE_FLOWS.md @@ -0,0 +1,138 @@ +# 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](../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. + +## 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 | Not yet run | Not yet run | Not yet run | +| 2. Search the website | Not yet run | Not yet run | Not yet run | +| 3. Listen to a companion episode and open its transcript | Not yet run | Not yet run | Not yet run | +| 4. Opt in on the registration page | Not yet run | 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](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 + +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". + +1. **Read a chapter on the website.** Start at the [workshop home page](https://community-access.github.io/git-going-with-github/), reach [Chapter 05: Working with Issues](https://community-access.github.io/git-going-with-github/docs/05-working-with-issues.html), read it by headings, use "On this page" and Quick Jumps, and move to the next chapter with the page progression links. +2. **Search the website.** From any page, search for "merge conflict", reach the results page and open a result. +3. **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. +4. **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. +5. **Report a barrier.** Open the [accessibility bug report form](https://github.com/Community-Access/git-going-with-github/issues/new?template=accessibility-bug.yml), fill in the two required fields and one optional field, and reach the Submit button (do not submit a test report). +6. **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. + +```markdown +### 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. + +```markdown +### 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 registration count, the audio player state) are announced or easy to find. +- [ ] Reading order is logical. +- [ ] The task can be completed end to end. + +Result: <pass, or the barriers found with issue numbers>. +``` + +## Manual visual checks + +```markdown +### Manual checks: <task name> + +Environment: <operating system>, <browser and version>, <display size>. Run by <person> on <date>. + +- [ ] Keyboard: the task can be completed by keyboard alone (see the keyboard record). +- [ ] Any image or diagram has a text alternative that serves its purpose. +- [ ] Page title, headings, labels and messages are descriptive. +- [ ] Plain language is used, and abbreviations are spelled out on first use. +- [ ] At 200% browser zoom, nothing is lost or overlaps. +- [ ] At a 320 CSS pixel wide window (400% zoom), content reflows without horizontal scrolling or loss of information. +- [ ] Text and focus indicators have sufficient contrast in the light, dark and high contrast themes, and color is never the only way meaning is shown. + +Result: <pass, or the barriers found with issue numbers>. +``` + +## Documentation checks + +Documentation is checked in two ways. The automated check (`npm run check:accessibility`, described in ACCESSIBILITY.md under "Automated checks") covers heading structure, image alternatives, link text, table headers, code block languages and emoji in every Markdown file outside `learning-room/`. A person reviews what it cannot judge: + +- **Structure:** headings describe their sections; lists are real lists; steps that must be done in order are numbered. +- **Alternatives:** each diagram, including ASCII diagrams in code blocks, has the same information in text nearby; alternative text describes the purpose of an image, not only its subject. +- **Links:** link text makes sense in a screen reader's links list; links to other chapters resolve. +- **Captions and transcripts:** every embedded or linked video has captions, and every podcast episode has a transcript. +- **Tables:** each table has a sentence before it saying what it holds, and is a data table, not a layout. +- **Code blocks:** commands are text, not images; long commands are explained in prose; expected output is shown separately and labeled. + +### Review record, 28 October 2026 + +Reviewed by Claude (an AI coding agent) while adopting the Open Source Accessibility Framework, for review by the accessibility owner. This is a documentation review, not a test with assistive technology. + +- **Automated, all 152 Markdown files** at the root and in `docs/`, `admin/` and `classroom/`: 268 findings before fixes. Four were fixed in the same change (a skipped heading level in Appendix Z, a second H1 in Appendix L, and empty header cells in the status tables of both registration pages), along with a stray line above the H1 of CONTRIBUTING.md that the check cannot detect. The remaining 264 are recorded in the baseline and tracked in [issue #267](https://github.com/Community-Access/git-going-with-github/issues/267): 172 emoji, all in four facilitator guides in `admin/`; 88 code blocks without a language in 34 files; three intentional "bad example" links in the link text table of Appendix C; and one untitled admin file. +- **Read in full or in part:** README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, Chapter 00 (requirements and screen reader setup), the link text and image sections of Appendix C, the opening of Appendix Z, Appendix L around its second title, the template testing checklist, the issue forms and the pull request template. +- **Captions and transcripts:** no video is embedded in the documentation. Chapter 16 links four YouTube videos; their captions were not checked. All 58 podcast episodes in `podcasts/manifest.json` have a transcript script under `podcasts/scripts/`. +- **Code blocks:** CONTRIBUTING.md shows expected output separately and labeled; its three unlabeled fences hold expected output, the commit message format and pull request title examples, and are among the tracked findings. Commands across the curriculum are text in fenced blocks; no screenshot of code or of a terminal was found. +- **Images:** the documentation contains no images outside code examples, in line with the text-first priority. + +## Records + +Add each run below, newest first, using the blocks above. Link any issue you file, labeled `accessibility`. + +No checks have been run yet. + +## Authoritative Sources + +Use these official references when you need the current source of truth for facts in this document. + +- [W3C Web Content Accessibility Guidelines (WCAG) 2 overview](https://www.w3.org/WAI/standards-guidelines/wcag/) +- [W3C Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) +- [W3C Understanding Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) +- [WAI: Easy Checks, a first review of web accessibility](https://www.w3.org/WAI/test-evaluate/preliminary/) +- [Open Source Accessibility Framework, Testing phase](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework/blob/main/framework/phases/testing-phase.md) + +### Section-Level Source Map + +Use this map to verify facts for each major section in this file. + +- **Status:** [Open Source Accessibility Framework, Testing phase](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework/blob/main/framework/phases/testing-phase.md) +- **The core tasks:** [Open Source Accessibility Framework, Testing phase](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework/blob/main/framework/phases/testing-phase.md) +- **Keyboard-only checks:** [W3C Understanding Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html), [WAI: Easy Checks, a first review of web accessibility](https://www.w3.org/WAI/test-evaluate/preliminary/) +- **Screen reader checks:** [WAI: Easy Checks, a first review of web accessibility](https://www.w3.org/WAI/test-evaluate/preliminary/) +- **Manual visual checks:** [W3C Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html), [W3C Web Content Accessibility Guidelines (WCAG) 2 overview](https://www.w3.org/WAI/standards-guidelines/wcag/) +- **Documentation checks:** [W3C Web Content Accessibility Guidelines (WCAG) 2 overview](https://www.w3.org/WAI/standards-guidelines/wcag/) +- **Records:** [Open Source Accessibility Framework, Testing phase](https://github.com/open-source-accessibility/Open-Source-Accessibility-Framework/blob/main/framework/phases/testing-phase.md) diff --git a/admin/REGISTER.md b/admin/REGISTER.md index f0b7fcbf..43a12418 100644 --- a/admin/REGISTER.md +++ b/admin/REGISTER.md @@ -6,7 +6,7 @@ This page is a fast, self-serve opt-in workflow. Students can opt in directly from GitHub Pages with no instructor handoff required. -| | | +| Item | Details | |---|---| | **Status** | Open for student opt-in | | **Current confirmed registrations** | **<span id="registration-count-live">Loading...</span>** | diff --git a/docs/appendix-l-agents-reference.md b/docs/appendix-l-agents-reference.md index 6edd6018..d8ff4f9c 100644 --- a/docs/appendix-l-agents-reference.md +++ b/docs/appendix-l-agents-reference.md @@ -333,7 +333,7 @@ The GitHub Workflow team includes 12 agents that automate common repository oper ### `@template-builder` - Issue Template Wizard -# Appendix L: Agents Reference +## Detailed Agents Reference This appendix is the authoritative reference for all Accessibility Agents, skills, slash commands, customization primitives, and file formats. Updated for Accessibility Agents v5.0.0+ and VS Code 1.120+. diff --git a/docs/appendix-z-github-skills.md b/docs/appendix-z-github-skills.md index ac890a1f..8fd7c58d 100644 --- a/docs/appendix-z-github-skills.md +++ b/docs/appendix-z-github-skills.md @@ -10,7 +10,7 @@ GitHub Skills is GitHub's free, self-paced interactive learning platform. Every This appendix catalogs every available GitHub Skills module, organized into learning paths that build on the skills you practiced in this workshop. Use it as a roadmap for continued learning after Day 2. -### Learning Cards: How GitHub Skills Works +## Learning Cards: How GitHub Skills Works <details> <summary>Screen reader users</summary> diff --git a/html/ACCESSIBILITY.html b/html/ACCESSIBILITY.html new file mode 100644 index 00000000..0216e12a --- /dev/null +++ b/html/ACCESSIBILITY.html @@ -0,0 +1,486 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content="GIT Going with GitHub - A two-day accessible open source workshop by Community Access"> + <title>Accessibility - GIT Going with GitHub + + + + + + + + +
+ +
+ + + +

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.
    • +
+

Interface requirements

+

The workshop's own interfaces are the published website (built by scripts/build-html.js), its search page, the companion audio player, the registration page, the issue forms in .github/ISSUE_TEMPLATE/, and the comments our automation posts. New and changed interfaces must meet these requirements, and reviewers check them against the pull request checklist:

+
    +
  • Every page has a descriptive <title>, lang="en", a skip link to the main content, and header, nav, main and footer landmarks with distinct names.
    • +
  • Everything interactive is reachable and operable from the keyboard, in a logical order, with no keyboard trap.
    • +
  • Focus is always visible: never remove the focus outline without a replacement that is at least as visible.
    • +
  • Every control has a visible label, and its accessible name contains the visible words; native HTML elements before ARIA.
    • +
  • Text and focus indicators have sufficient contrast in the light, dark and high contrast themes the site supports.
    • +
  • Content reflows at 320 CSS pixels wide and works at 200% zoom without loss of content or function.
    • +
  • Changes that happen without a page load (search results, a live count) are announced or easy to find.
    • +
  • Motion respects prefers-reduced-motion.
    • +
  • Bot comments and issue forms use headings and lists, plain language, and no emoji.
    • +
+

Barriers found in the current interfaces are tracked as issues labeled accessibility (see Known limitations).

+

Automated checks

+

scripts/check-docs-accessibility.js checks the Markdown that becomes the website, the ePub and the braille files: one H1 per page, no skipped heading levels, alternative text on images, descriptive link text, table headers, a language on every code block, and no emoji. It runs on every pull request that changes Markdown (workflow) and in the automation test suite. Findings that predate the check are counted in scripts/docs-accessibility-baseline.json and tracked in issue #267; the check fails only when a change adds one. It does not check the rendered HTML, learning-room/ (which contains deliberate defects for learners to fix), or anything a person must judge, which is what the manual checks are for. No automated check finds every barrier.

+

Reporting accessibility issues

+

If something in this workshop is hard or impossible for you to use, please tell us. Accessibility reports are expertise, not complaints, and this includes barriers you meet on GitHub.com or in VS Code while following the workshop.

+
    +
  • On GitHub: open an issue with the accessibility bug report form. Only two fields are required; partial reports are welcome.
    • +
  • By email, if GitHub is a barrier for you, or you would rather not post publicly: write to support@community-access.org or to Jeff Bishop at jeff@jeffbishop.com. We will file the issue for you if you want one, and keep your details private if you ask.
    • +
  • During a live workshop: tell a facilitator in the room or in the workshop chat, and we will file it with you.
    • +
+

Helpful details, all optional:

+
    +
  • What you were trying to do, and what happened instead.
    • +
  • Where: the page URL, the chapter or challenge, the download (ePub, Word, BRF), or the podcast episode.
    • +
  • Your operating system, browser and assistive technology, with versions if you know them.
    • +
  • How much it gets in your way (see Severity).
    • +
  • Whether you would be willing to try a fix and tell us if it works.
    • +
+

You never need to tell us about a disability or diagnosis.

+

Severity

+

We use four levels, based on how much the barrier stops a person completing a task. Reporters do not need to choose one; maintainers assign or confirm it during triage.

+
    +
  • Critical: you cannot complete a core task, such as reading a chapter, registering, or finishing a challenge, and there is no workaround.
    • +
  • Serious: you can complete the task only with real difficulty or a workaround.
    • +
  • Moderate: the task works but is confusing, slow or inconsistent.
    • +
  • Minor: a small problem with little effect on getting things done.
    • +
+

How we respond

+
    +
  • We acknowledge every accessibility report promptly and respectfully, thank the reporter, and say what happens next. We treat the report as expertise about the workshop, not a complaint.
    • +
  • We do not ask you to justify your experience or to disclose personal information. If we need more detail, we ask specific questions about the steps and your setup, never whether the barrier is real.
    • +
  • At triage the report gets the accessibility label, a severity, an owner and, where we can give one, a target date, all stated on the issue.
    • +
  • Where we can, we give a workaround while a fix is in progress, and we add it to the relevant chapter so the next learner does not meet the same barrier.
    • +
  • If the cause is on GitHub.com, in VS Code, in a screen reader or in another tool we do not control, we say so, document the workaround, report it upstream where we can, and link the upstream report on the issue.
    • +
  • We post an update on the issue whenever its status or expected timing changes, and link the pull request that fixes it.
    • +
  • Before we close a report, we write down the outcome on the issue, and we ask the reporter, or another person affected, to confirm the fix works for them when they are willing.
    • +
  • We credit reporters and testers only in the way they choose (see Recognizing contributions).
    • +
+

If we cannot meet a date we gave, we say why on the issue, share any workaround, and give a new date.

+

Taking part

+

There are several ways to take part, and no single channel is required:

+
    +
  • Asynchronous, at any time: read and listen on the workshop website; ask questions in Discussions or the Community Access support hub; open issues and pull requests here; or email the addresses above. The whole curriculum, every challenge and every solution can be done self-paced.
    • +
  • Live cohorts: the two-day workshop runs in person and remotely. Facilitation plans (Day 1 agenda, Day 2 agenda) give remote participants the same links, chat channel and written checkpoints, with CART captioning or ASL interpretation where available. Every live block has a written "you are done when" checkpoint and can be finished afterwards, so missing part of a session does not mean missing the content.
    • +
  • Non-code contributions are as welcome as code: reporting and reproducing barriers, testing with your screen reader or braille display, correcting a keyboard command, reviewing a chapter, improving a transcript, or reviewing other people's pull requests.
    • +
+

Accommodations. If you need an accommodation to take part in a live session or to contribute, or a tool we use is a barrier for you, email support@community-access.org or jeff@jeffbishop.com privately. You do not need to explain why, and we will not share what you tell us.

+

Collaboration tools we have reviewed. The tools the workshop asks people to use, and where their accessibility is documented:

+
    +
  • GitHub.com (issues, pull requests, Discussions, the Learning Room): chapters 02 to 10 and the screen reader cheat sheet teach each one with NVDA, JAWS and VoiceOver, including the known rough edges and workarounds. Known blockers are listed in Dependencies and upstream blockers.
    • +
  • VS Code, github.dev and GitHub Copilot: chapters 11, 12 and 16, the VS Code accessibility reference and the GitHub Copilot reference cover screen reader mode, Accessible View, accessibility signals and the Accessible Diff Viewer.
    • +
  • The workshop chat channel used in live cohorts has not been reviewed by us; everything said there that matters is also posted in the repository or Discussions, which are the alternative.
    • +
  • The podcast is an optional companion: each episode has a transcript, and every episode covers a chapter that is available as text.
    • +
+

Everyone who takes part follows the Code of Conduct. It names disability-related harassment, dismissing accessibility feedback, personal attacks and publishing private information as unacceptable, and gives a private contact for reports. The maintainers enforce it.

+

How to help. Open accessibility work is labeled accessibility. Issues that suit a first contribution are labeled accessibility and good first issue, and ones where we need specialist experience, such as daily use of a particular screen reader, are labeled accessibility and help wanted. Each has the context, the steps and acceptance criteria to start from. Ask questions on the issue or in Discussions, and a maintainer will answer.

+

Feedback from learners. After each cohort we ask participants to fill in the workshop feedback form, which has a section on accessibility and inclusion. The accessibility owner reads every response, files the barriers it describes as accessibility issues, and summarizes what changed in the next progress update.

+

Ownership and maintenance

+

Accessibility is owned by Jeff Bishop, workshop facilitator and maintainer (@accesswatch on GitHub, jeff@jeffbishop.com), with the workshop facilitators.

+

The accessibility owner:

+
    +
  • triages accessibility reports, assigns severity and an owner, and makes sure each gets an acknowledgement, a status and a next step;
    • +
  • keeps accessibility work visible with the accessibility label, and keeps a few well-described good first issue and help wanted accessibility issues open;
    • +
  • reviews pull requests against the contributor expectations and interface requirements above (pull requests are routed for review by CODEOWNERS);
    • +
  • reviews the accessibility of new dependencies before they are adopted, and tracks upstream blockers;
    • +
  • keeps this document, the supported environments, the known limitations, the test records and the framework progress current;
    • +
  • publishes the quarterly progress update and escalates unresolved accessibility risks to the other maintainers, for example before a cohort starts.
    • +
+

This document is reviewed every quarter, when the review reminder opens its issue, and before each cohort. If ownership changes, this section is updated in the same pull request that changes .github/CODEOWNERS.

+

Dependencies and upstream blockers

+

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

+
    +
  • 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.
      • +
    +
    • +
  • 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.
      • +
    +
    • +
  • 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 turns Markdown into HTML, github-markdown-css and a highlight.js theme supply the colors, and lunr 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 builds the ePub and Word files, and liblouis translates the braille files from a plain-text conversion of the ePub. Braille layout and tables depend on both (see Known limitations).
    • +
  • Podcast audio: episodes are generated with the Kokoro text-to-speech engine (Piper as a fallback) and served from an external host, lp.csedesigns.com, whose player page is outside this repository. Mitigation: every episode has a transcript, and the site links the audio file directly so any player can be used.
    • +
  • GitHub Pages and the repository wiki host the published site and its wiki copy.
    • +
+

Supported environments

+

What the workshop is written for and supported on, taken from Chapter 00: Pre-Workshop Setup:

+
    +
  • Operating systems: Windows and macOS. Linux works for Git and VS Code, but the screen reader instructions do not cover Orca.
    • +
  • Screen readers: NVDA and JAWS on Windows, VoiceOver on macOS. Every exercise gives commands for all three. VoiceOver on iOS and TalkBack on Android are covered only for the GitHub Mobile app, in the GitHub Mobile appendix.
    • +
  • Browsers: Chrome or Firefox (recommended on Windows), Edge (acceptable), Safari (recommended with VoiceOver on macOS).
    • +
  • Input: keyboard only is the primary method, and every step has a keyboard route. Pointer and touch also work. Voice control and switch access have not been tested.
    • +
  • Tools: VS Code 1.113 or later, Git 2.20 or later, and a GitHub account with GitHub Copilot Free or a paid plan.
    • +
  • Formats: the website (HTML), Markdown on GitHub, ePub, Word, and braille in UEB grade 2 and EBAE grade 2 (from the releases page), and companion podcast audio with transcripts.
    • +
+

What has been checked:

+
    +
  • 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.
    • +
+

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.
    • +
  • The Quick Jumps links hide their focus outline. On every chapter page, keyboard focus on the Quick Jumps links shows only an underline and a faint background, which is hard to see with low vision (#265). Workaround: the same links are in the "On this page" list and the page headings, which show the normal outline.
    • +
  • The site search box is named "Search documentation" but shows "Search docs". Voice control users may need to say "Search documentation", or move to the field with Tab (#266).
    • +
  • Some facilitator guides start headings with emoji, which screen readers read aloud by name, and some code blocks do not say what they contain (#264, #267, #268). Learner chapters are not affected by the emoji.
    • +
  • The braille files are machine translated. They are produced automatically by liblouis from a plain-text version of the ePub, so tables are flattened into lines of text and print formatting is not converted to braille formatting. We have no record of review by a certified braille transcriber. Workaround: the ePub, Word or HTML version read with a refreshable braille display keeps the tables and headings.
    • +
  • Podcast episodes are companions, not readings. Episodes use synthetic voices and summarize a chapter rather than reading it word for word. Every episode has a transcript, and the chapter itself is the complete source.
    • +
  • Linked videos are not ours. Chapter 16 links four YouTube videos about Copilot with a screen reader; we have not checked their captions. The same steps are written in the chapter.
    • +
  • GitHub and VS Code change faster than the curriculum. A button, label or announcement may differ from what a chapter says. Use the exploration skills the README describes, and file a curriculum issue so we can update the chapter.
    • +
  • The Learning Room has deliberate defects. Files in learning-room/ (for example docs/keyboard-shortcuts.md) contain accessibility problems on purpose, for learners to find and fix. They are exercises, not barriers to report, unless the exercise itself is hard to use.
    • +
  • Upstream barriers we can only work around: see Dependencies and upstream blockers.
    • +
+

Progress updates

+

We publish accessibility progress here, every quarter and after each cohort, and in our public Open Source Accessibility Framework tracking issue. Each update lists completed work, remaining work, known barriers and links. The review reminder workflow opens an issue labeled accessibility review on the first day of each quarter with the numbers since the last update and a checklist; the update is added below in a pull request that closes it.

+

October 2026: adopting the framework

+
    +
  • Completed: this document; a reworked accessibility bug report form with only two required fields and an email alternative; a full accessibility checklist in the pull request template; the documentation accessibility check in CI, with its first findings tracked in #267; fixes to a skipped heading level (Appendix Z), a second H1 (Appendix L), empty table headers on the registration pages, and a stray line above the title of CONTRIBUTING.md. Earlier in 2026: an EBAE braille file beside the UEB one (#174), and Chapter 11's explanation of the VoiceOver "selection replaced" announcement (#175).
    • +
  • Remaining: run and record the core flow checks; fix the site template findings (#265, #266); work through the recorded documentation findings (#264, #268); find the cause of #175.
    • +
  • Known barriers: see Known limitations.
    • +
  • How to help: issues labeled accessibility.
    • +
+

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.

+

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.

+
    +
  • Accessibility bug report form: a GitHub issue form that asks for the details triage needs while requiring only two fields, never asks about disability, and offers an email alternative. Replace the "Where" options and the contact addresses with your own. It cannot help people who cannot use GitHub at all; keep an email or other route beside it.
    • +
  • Pull request accessibility checklist: content and interface checks written for a documentation project. Drop the groups that do not apply; it prompts a contributor, it does not test anything.
    • +
  • Documentation accessibility check with its baseline and workflow: a dependency-free Node.js script that checks Markdown for heading structure, alternative text, link text, table headers, code block languages and emoji, and blocks only new findings so an existing project can adopt it on day one. Needs Node.js 18 or later. It reads Markdown source, not rendered pages, so pair it with a check of your built site.
    • +
  • Template testing checklist and core flow checks: step-by-step NVDA, JAWS and VoiceOver procedures for issue forms and web pages, and test records for key tasks. Adapt the tasks to your project's own.
    • +
  • This document: a worked ACCESSIBILITY.md for a documentation and training project, following the framework's sections.
    • +
  • Quarterly review reminder: a scheduled workflow that opens a progress-update issue with the quarter's accessibility issue counts. It needs an accessibility label and issue write permission.
    • +
  • The curriculum itself: a screen-reader-first course in contributing on GitHub, with the screen reader cheat sheet and the accessibility standards reference as standalone references.
    • +
+

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 a public tracking issue in the framework's repository. Progress is self-reported. 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. Keyboard, screen reader and manual checks of the core tasks are written down but not yet run and recorded.
    • +
  • Community: a feedback form after each cohort and labeled issues to invite help; documented responses to reports; 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.
    • +
+

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.

+

Authoritative Sources

+

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

+ +

Section-Level Source Map

+

Use this map to verify facts for each major section in this file.

+ +
+ +
+
+ + + + + diff --git a/html/CONTRIBUTING.html b/html/CONTRIBUTING.html index 79a1bdbc..63985e85 100644 --- a/html/CONTRIBUTING.html +++ b/html/CONTRIBUTING.html @@ -255,8 +255,7 @@

On This Page

  • Section-Level Source Map
    • -

    Table: Keyboard shortcut for focusing search in different screen readers

    -

    Contributing to This Workshop Repository

    +

    Contributing to This Workshop Repository

    Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome.

    This guide covers contributing to this workshop learning repository. For contributing to Accessibility Agents itself (the project you work on during Day 2), see Accessibility Agents' CONTRIBUTING.md.

    Table of Contents

    @@ -404,7 +403,7 @@

    Structure

  • Inline code (``) for short references to a key name, command name, or file name

    • Keyboard Shortcuts

    -

    Format all keyboard shortcuts in a table when listing more than two:

    +

    Format all keyboard shortcuts in a table when listing more than two. Introduce each table with a sentence that says what its rows are, as this example does: it shows the keyboard shortcut for focusing search in each screen reader.

    @@ -430,6 +429,10 @@

    6. Accessibility Requirements

    Every document in this repository is used by screen reader users. Accessibility is not a nice-to-have - it is the primary requirement. All contributions must meet the following:

    +

    The full set of expectations, including the requirements for the website template and other interfaces, is in the contributor expectations in ACCESSIBILITY.md. The pull request template turns them into a checklist. Before you push, run the documentation accessibility check, which fails if your change adds a new finding:

    +
    npm run check:accessibility
    +

    To see every finding with its line number, including the ones already recorded, run node scripts/check-docs-accessibility.js --report. If you fix a recorded finding, lower its count in scripts/docs-accessibility-baseline.json in the same pull request.

    +

    To report an accessibility barrier in the workshop, use the accessibility bug report form, or email the addresses in ACCESSIBILITY.md if GitHub is a barrier for you. Accessibility issues that suit a first contribution are labeled accessibility and good first issue; ones where we need specialist experience are labeled accessibility and help wanted.

    Heading Structure

    +

    Accessibility of This Project

    +

    How we work on the workshop's own accessibility, how to report a barrier (on GitHub or by email), how we respond, what the workshop supports and what we know is not yet good enough are all in ACCESSIBILITY.md. We follow GitHub's Open Source Accessibility Framework, an improvement framework rather than a certification, and publish our progress in ACCESSIBILITY.md.

    +

    To report a barrier, use the accessibility bug report form or email support@community-access.org. To help, look for issues labeled accessibility.

    License

    All workshop documentation is licensed under CC BY 4.0 - you are free to share and adapt with attribution.

    Last reviewed: May 2026 @@ -839,6 +844,7 @@

    Section-Level Source Map

  • Screen Reader Users: Start Here: GitHub Docs, home, GitHub Changelog, W3C Web Content Accessibility Guidelines (WCAG) 2 overview, WAI tutorials for accessible design patterns, WAI-ARIA Authoring Practices Guide
  • The Goal of This Event: GitHub Docs, home, GitHub Changelog
  • Questions Before the Event?: GitHub Docs, home, GitHub Changelog
    • +
  • Accessibility of This Project: Open Source Accessibility Framework, W3C Web Content Accessibility Guidelines (WCAG) 2 overview
  • License: GitHub Docs, home, GitHub Changelog
    • diff --git a/html/REGISTER.html b/html/REGISTER.html index a5ab47d9..df7246d3 100644 --- a/html/REGISTER.html +++ b/html/REGISTER.html @@ -232,8 +232,8 @@

    A magical welcome

    - - + + diff --git a/html/admin/ACCESSIBILITY_CORE_FLOWS.html b/html/admin/ACCESSIBILITY_CORE_FLOWS.html new file mode 100644 index 00000000..1e34c922 --- /dev/null +++ b/html/admin/ACCESSIBILITY_CORE_FLOWS.html @@ -0,0 +1,400 @@ + + + + + + + Accessibility Checks for Core Flows - GIT Going with GitHub + + + + + + + + +
    + +
    + + + +

    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.

    +

    Status

    +

    The table below shows, for each core task, which records exist and whether they have been run.

    +
    ItemDetails
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Core taskKeyboard onlyScreen readerManual visual checks
    1. Read a chapter on the websiteNot yet runNot yet runNot yet run
    2. Search the websiteNot yet runNot yet runNot yet run
    3. Listen to a companion episode and open its transcriptNot yet runNot yet runNot yet run
    4. Opt in on the registration pageNot yet runNot yet runNot yet run
    5. Report a barrier with the accessibility bug report formNot yet runNot yet runNot yet run
    6. Read the ePub and braille downloadsNot applicableNot yet runNot 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".

    +
      +
    1. 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.
      2. +
    2. Search the website. From any page, search for "merge conflict", reach the results page and open a result.
      3. +
    3. 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.
      4. +
    4. 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.
      5. +
    5. 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).
      6. +
    6. 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.
      7. +
    +

    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 registration count, the audio player state) are announced or easy to find.
+- [ ] Reading order is logical.
+- [ ] The task can be completed end to end.
+
+Result: <pass, or the barriers found with issue numbers>.
    +

    Manual visual checks

    +
    ### Manual checks: <task name>
+
+Environment: <operating system>, <browser and version>, <display size>. Run by <person> on <date>.
+
+- [ ] Keyboard: the task can be completed by keyboard alone (see the keyboard record).
+- [ ] Any image or diagram has a text alternative that serves its purpose.
+- [ ] Page title, headings, labels and messages are descriptive.
+- [ ] Plain language is used, and abbreviations are spelled out on first use.
+- [ ] At 200% browser zoom, nothing is lost or overlaps.
+- [ ] At a 320 CSS pixel wide window (400% zoom), content reflows without horizontal scrolling or loss of information.
+- [ ] Text and focus indicators have sufficient contrast in the light, dark and high contrast themes, and color is never the only way meaning is shown.
+
+Result: <pass, or the barriers found with issue numbers>.
    +

    Documentation checks

    +

    Documentation is checked in two ways. The automated check (npm run check:accessibility, described in ACCESSIBILITY.md under "Automated checks") covers heading structure, image alternatives, link text, table headers, code block languages and emoji in every Markdown file outside learning-room/. A person reviews what it cannot judge:

    + +

    Review record, 28 October 2026

    +

    Reviewed by Claude (an AI coding agent) while adopting the Open Source Accessibility Framework, for review by the accessibility owner. This is a documentation review, not a test with assistive technology.

    + +

    Records

    +

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

    +

    No checks have been run yet.

    +

    Authoritative Sources

    +

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

    + +

    Section-Level Source Map

    +

    Use this map to verify facts for each major section in this file.

    + +
    + + +
    + + + + + diff --git a/html/admin/REGISTER.html b/html/admin/REGISTER.html index b907fd3a..ff25c190 100644 --- a/html/admin/REGISTER.html +++ b/html/admin/REGISTER.html @@ -222,8 +222,8 @@

    Join the next GIT Going with - - + + diff --git a/html/docs/appendix-l-agents-reference.html b/html/docs/appendix-l-agents-reference.html index 25644aed..74f5fc4c 100644 --- a/html/docs/appendix-l-agents-reference.html +++ b/html/docs/appendix-l-agents-reference.html @@ -245,6 +245,7 @@

    On This Page

  • @analytics - Team Analytics
  • @insiders-a11y-tracker - Accessibility Change Monitor
  • @template-builder - Issue Template Wizard
    • +
  • Detailed Agents Reference
  • 1. Agent Teams, Roles, and Platforms
  • 2. Agent and Skill Table
  • 3. Slash Commands and Prompts
    • @@ -1141,7 +1142,7 @@

    What it monitors

    ItemDetails

    Risk levels: High (regression), Medium (degraded), Low (improvement opportunity)

    @template-builder - Issue Template Wizard

    -

    Appendix L: Agents Reference

    +

    Detailed Agents Reference

    This appendix is the authoritative reference for all Accessibility Agents, skills, slash commands, customization primitives, and file formats. Updated for Accessibility Agents v5.0.0+ and VS Code 1.120+.

    1. Agent Teams, Roles, and Platforms

    Accessibility Agents v5.0.0+ includes 80+ agents, 25+ skills, and 30+ MCP tools, organized into three teams and five platforms. The agent ecosystem now supports:

    diff --git a/html/docs/appendix-z-github-skills.html b/html/docs/appendix-z-github-skills.html index 572fbdb7..d95b871e 100644 --- a/html/docs/appendix-z-github-skills.html +++ b/html/docs/appendix-z-github-skills.html @@ -228,7 +228,7 @@

    GitHub Skills - Complete Course Catalog