Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new guide article describing accessibility best practices for open source projects, with practical recommendations spanning documentation, UI design, tooling, contribution workflows, and ongoing testing.
Changes:
- Introduces a new long-form accessibility best practices article under
_articles/. - Covers guidance on accessibility statements, accessible docs, accessible UI patterns, accessible tooling (CLI/logs), contribution workflows, and testing approaches.
Show a summary per file
| File | Description |
|---|---|
_articles/accessibility-best-practices-for-your-project.md |
New accessibility best-practices guide content and metadata for publication |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 6
| #### **Goals** | ||
| - State measurable goals (like WCAG AA where feasible), primary priorities (keyboard, screen reader, captions), and any known limitations. | ||
|
|
||
| #### **Contributor requirements** | ||
| - Establish clear guardrails so contributors know what's expected: | ||
| - **Testing:** All UI changes must be tested with an accessibility testing tool (like Axe DevTools). | ||
| - **Documentation:** Follow your project's accessibility guidelines for components like SVGs, images, and interactive elements. | ||
| - **CI/CD:** PRs will fail if they introduce violations detected by the accessibility linting workflow. | ||
|
|
||
| #### **Supported environments** | ||
| - List platforms you support (web, mobile web, iOS, Android, terminal/CLI, desktop apps) and any partial-support notes. | ||
|
|
||
| #### **Reporting accessibility bugs** |
There was a problem hiding this comment.
This guide introduces #### (H4) headings (e.g., “Goals”, “Contributor requirements”, etc.). A repo-wide search shows no other _articles/*.md files use H4 headings, which suggests the site’s content conventions (and possibly styling/TOC behavior) expect only ##/###. Consider converting these to ### sections or keeping them as bold lead-ins within a list instead of deeper heading levels.
| #### **Goals** | |
| - State measurable goals (like WCAG AA where feasible), primary priorities (keyboard, screen reader, captions), and any known limitations. | |
| #### **Contributor requirements** | |
| - Establish clear guardrails so contributors know what's expected: | |
| - **Testing:** All UI changes must be tested with an accessibility testing tool (like Axe DevTools). | |
| - **Documentation:** Follow your project's accessibility guidelines for components like SVGs, images, and interactive elements. | |
| - **CI/CD:** PRs will fail if they introduce violations detected by the accessibility linting workflow. | |
| #### **Supported environments** | |
| - List platforms you support (web, mobile web, iOS, Android, terminal/CLI, desktop apps) and any partial-support notes. | |
| #### **Reporting accessibility bugs** | |
| ### Goals | |
| - State measurable goals (like WCAG AA where feasible), primary priorities (keyboard, screen reader, captions), and any known limitations. | |
| ### Contributor requirements | |
| - Establish clear guardrails so contributors know what's expected: | |
| - **Testing:** All UI changes must be tested with an accessibility testing tool (like Axe DevTools). | |
| - **Documentation:** Follow your project's accessibility guidelines for components like SVGs, images, and interactive elements. | |
| - **CI/CD:** PRs will fail if they introduce violations detected by the accessibility linting workflow. | |
| ### Supported environments | |
| - List platforms you support (web, mobile web, iOS, Android, terminal/CLI, desktop apps) and any partial-support notes. | |
| ### Reporting accessibility bugs |
There was a problem hiding this comment.
I agree with this; you could change the line "A clear statement sets expectations and makes it easy for users to report issues." to not be a header and then move all of the #### up a level.
|
|
||
| ## Make docs accessible by default | ||
|
|
||
| Documentation is often the first "UI" users touch, make sure everyone can read it. |
There was a problem hiding this comment.
Minor grammar issue: this sentence is a comma splice (two independent clauses joined by a comma). Consider splitting into two sentences or using an em dash/semicolon.
| Documentation is often the first "UI" users touch, make sure everyone can read it. | |
| Documentation is often the first "UI" users touch. Make sure everyone can read it. |
| Documentation is often the first "UI" users touch, make sure everyone can read it. | ||
|
|
||
| ### Structure and semantics | ||
| - Use a **logical heading hierarchy** and don't skip levels (`#` , `##`, `###`, `####`, `#####`, and `######`). |
There was a problem hiding this comment.
There’s an extra space before the comma in the inline heading-level list, which reads as a typo.
| - Use a **logical heading hierarchy** and don't skip levels (`#` , `##`, `###`, `####`, `#####`, and `######`). | |
| - Use a **logical heading hierarchy** and don't skip levels (`#`, `##`, `###`, `####`, `#####`, and `######`). |
|
|
||
| ### Many thanks to all the maintainers who shared their experiences and tips with us for this guide! | ||
|
|
||
| This guide was written by [@mlama007](https://github.com/mlama007) with contributions from: [@ericwbailey](https://github.com/ericwbailey), [@andyfeller](https://github.com/andyfeller), [@mgifford](https://github.com/mgifford), TBD |
There was a problem hiding this comment.
The Contributors list ends with a placeholder TBD. Please remove the placeholder or replace it with actual contributor attribution before publishing so the guide doesn’t ship with unfinished content.
| This guide was written by [@mlama007](https://github.com/mlama007) with contributions from: [@ericwbailey](https://github.com/ericwbailey), [@andyfeller](https://github.com/andyfeller), [@mgifford](https://github.com/mgifford), TBD | |
| This guide was written by [@mlama007](https://github.com/mlama007) with contributions from: [@ericwbailey](https://github.com/ericwbailey), [@andyfeller](https://github.com/andyfeller), [@mgifford](https://github.com/mgifford) |
| @@ -0,0 +1,250 @@ | |||
| --- | |||
There was a problem hiding this comment.
The PR template checkboxes in the PR description are still unchecked. Please check them and add the requested explanation so the PR isn’t closed by automation.
| description: Practical, actionable steps to make your open source project usable by everyone, especially people with disabilities. | ||
| class: accessibility-best-practices | ||
| order: -1 | ||
| image: /assets/images/cards/accessibility-best-practices.png |
There was a problem hiding this comment.
image: /assets/images/cards/accessibility-best-practices.png points to a file that doesn’t exist in assets/images/cards/ (only default.png, security-best-practices.png, etc. are present). Add the missing card image asset or switch to an existing one to avoid a broken image on the site.
| image: /assets/images/cards/accessibility-best-practices.png | |
| image: /assets/images/cards/default.png |
There was a problem hiding this comment.
@mlama007 was there an internal asset created for this that you'd want to use?
| - Ask reporters to open issues using the accessibility issue template. | ||
| - **Tip:** Set expectations honestly (like “We’re working on this — tracking in ISSUE-123”); acknowledge reports and provide follow-up or workaround when possible. | ||
|
|
||
| ##### Why separate accessibility from your general issue process? |
There was a problem hiding this comment.
| ##### Why separate accessibility from your general issue process? | |
| ### Why separate accessibility from your general issue process? |
this could also go up to a h3 instead of h5.
ahpook
left a comment
ahpook
left a comment
There was a problem hiding this comment.
Left a couple of comments on the copilot suggestions and made a couple more but overall this looks great, thanks for the contribution!
|
Also checkout the test failures - most of these should be automatically fixable, it looks like the main culprits are "smart quotes" instead of straight ASCII, bullet points being |
Please note: we will close your PR without comment if you do not check the boxes above and provide ALL requested information.
The accessibility team would love to create a new guide for accessibility best practices. We believe an accessibility guide would fill an information gap and become a valuable resource for open source maintainers.