From 158ba364c697908be3c098ec54fdb687063b7a1c Mon Sep 17 00:00:00 2001 From: Maria Lamardo Date: Fri, 24 Apr 2026 14:01:58 -0400 Subject: [PATCH 1/4] initial draft of Accessibility Best Practices for Your Project --- ...ibility-best-practices-for-your-project.md | 248 ++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 _articles/accessibility-best-practices-for-your-project.md diff --git a/_articles/accessibility-best-practices-for-your-project.md b/_articles/accessibility-best-practices-for-your-project.md new file mode 100644 index 00000000000..37ec30b1b92 --- /dev/null +++ b/_articles/accessibility-best-practices-for-your-project.md @@ -0,0 +1,248 @@ +--- +lang: en +untranslated: true +title: Accessibility Best Practices for Your Project +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 +--- + +Accessibility (often shortened to *a11y*) means people can use your project regardless of disability, assistive technology, environment, or device. It includes (but isn’t limited to) support for screen readers, keyboard-only navigation, captions/transcripts, color contrast, and clear content structure. + +## Partner with people with disabilities + +**"Nothing about us without us"** - The most important thing you can do for accessibility is to center the people it serves. Users, contributors, and testers with disabilities understand barriers in ways that guidelines and automated tools cannot. Seek out their lived experience early and often. + +### Put it into practice +Here are a few ways to center lived experience: +- Invite contributors with disabilities into design discussions, not just bug triage. +- Involve people with disabilities for usability testing and feedback when you can. +- Listen when someone describes how they use your project, even when it challenges your assumptions. +- Treat accessibility reports as expertise, not complaints. + +Decisions made without the people affected by them tend to miss the mark. Building with people with disabilities, rather than for them, leads to better software for everyone. + +### Accessibility benefits everyone +- **It impacts a lot of people.** An estimated 1.3 billion people (1 in 6) experience significant disability, according to the [World Health Organization](https://www.who.int/news-room/fact-sheets/detail/disability-and-health). +- **It’s part of quality.** Accessible products tend to be more usable for everyone. +- **It reduces support load.** Clearer UI and docs mean fewer confused users. +- **It expands your contributor base.** Assistive tech users can participate fully. +- **It’s often required.** Many orgs (and some governments) require accessibility for procurement and compliance. + + +## Start with an accessibility statement + +Before diving into code, take a moment to document your project's accessibility commitment. An accessibility statement signals to users and contributors that accessibility is a priority, not an afterthought. + +### A clear statement sets expectations and makes it easy for users to report issues. + +Add a short accessibility statement to your project. You can either add an accessibility section directly in your README, or create a dedicated ACCESSIBILITY.md file and link to it from your README for visibility. + +#### **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** +- 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. + +## Make docs accessible by default + +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 `######`). +- Use **unique, descriptive link text** (“Read the contributing guide” instead of “click here”). +- Use plain language, avoiding jargon and expanding any abbreviation the first time it is used. +- Use **real lists** over manually typed numbering. +- Keep **help and navigation in consistent locations** across pages so users can find them predictably. +- Avoid conveying meaning only through position or styling (“see the red text on the right”). + +### Images, diagrams and videos +- Provide meaningful **alt text** for images (refer to the [W3C’s alt Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)). +- Instead of using images of text, use real text whenever possible. +- For complex images (like architecture diagrams), include an additional **text alternative** nearby (bullets or a short explanation). +- If you publish demos, tutorials, talks, or release videos: + - Provide **captions** (prefer human-edited when possible). + - Provide a **transcript**. + - Describe important on-screen actions verbally. + +### Tables +- Use tables only for tabular data, not for layout. +- Include **header cells** (``) and use `scope` attributes to associate headers with data cells. +- Provide a **caption or summary** describing the table's purpose. + +### Code blocks +- Keep lines reasonably short (wrapping helps readability). +- Don’t rely on color highlighting alone to indicate meaning. +- Explain what the code does and what success looks like. + +## Design accessible UIs + +If your project has a web UI, these high-impact defaults will help all users. + +### Keyboard support +- Everything interactive should be reachable and usable with **keyboard only**. +- Ensure a **visible focus indicator** (don’t remove focus outlines unless you replace them). +- Maintain a logical **tab order** that matches the visual layout. +- Don’t trap focus inside components unless you intentionally manage focus (like modal dialogs) and provide a way out. + +### Semantics first +- Use native HTML elements (`