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 0000000000..98b5c10f12 --- /dev/null +++ b/_articles/accessibility-best-practices-for-your-project.md @@ -0,0 +1,265 @@ +--- +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 +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. + +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 - they may represent more people than you think. + + +### 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 more fully participate. +- **It’s often required.** Many orgs (and some governments) require accessibility for procurement and compliance. +- **Our future is uncertain.** Nobody today can be confident about the abilities we will have tomorrow. + + +## 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. For guidance, refer to the [W3C's Developing an Accessibility Statement](https://www.w3.org/WAI/planning/statements/). + +### 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. + +##### Why separate accessibility from your general issue process? + +Users have come to expect a dedicated accessibility statement and reporting path - it's a well-established convention in the private sector and across government sites, and many users look for it first when they hit a barrier. Keeping accessibility distinct from your general issue flow matters because: + +- **Impact is time-sensitive.** An accessibility bug can block a user from using your project at all, not just inconvenience them. A dedicated path helps these reported issues get triaged faster. +- **Context is different.** Accessibility reported issues need specific information (assistive tech, OS, browser, severity) that a generic bug template doesn't prompt for. +- **It signals commitment.** A visible, separate statement tells users and contributors that accessibility is a first-class concern, not something folded into "other bugs." +- **Reporters may use assistive technology to file the report itself.** A clear, predictable process (a known file, a known label, a known template) reduces friction for the people most affected. + + +## 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 inline 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 (`