diff --git a/guides/accessibility.mdx b/guides/accessibility.mdx index f9816e528..bb9934176 100644 --- a/guides/accessibility.mdx +++ b/guides/accessibility.mdx @@ -7,9 +7,9 @@ keywords: ["accessible documentation", "WCAG", "a11y", "screen readers", "access When you create accessible documentation, you prioritize content design that makes your documentation usable by as many people as possible regardless of how they access and interact with your documentation. -Accessible documentation improves the user experience for everyone. Your content is more clear, better structured, and easier to navigate. +Accessible documentation improves the experience for everyone. Your content is clearer, better structured, and easier to navigate—whether users access it with a screen reader, keyboard navigation, mobile device, or slow network connections. -This guide offers some best practices for creating accessible documentation, but it is not exhaustive. You should consider accessibility an ongoing process. Technologies and standards change over time, which introduce new opportunities to improve documentation. +This guide covers best practices for accessible documentation. Accessibility is an ongoing process. Technologies and standards evolve, and there are always opportunities to improve. Start with high-impact changes and build accessibility into your workflow. ## What is accessibility? @@ -17,9 +17,9 @@ Accessibility (sometimes abbreviated as a11y for the number of letters between t Accessible documentation follows web accessibility standards, primarily the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/WCAG22/quickref/). These guidelines help ensure your content is perceivable, operable, understandable, and robust. -## Getting started with accessibility +## Get started with accessibility -Making your documentation accessible is a process. You don't have to fix everything all at once and you can't do it only once. +Making your documentation accessible is a process. You don't have to fix everything all at once and you can't do it only once. If you're just beginning to implement accessibility practices for your documentation, consider a phased approach where you start with high-impact changes and build from there. @@ -126,17 +126,34 @@ Use tables sparingly and only for tabular data that has meaning inherited from t When using tables, include headers so screen readers can associate data with the correct column: -```mdx -| Feature | Status | -| ------- | ------ | -| Search | Active | -| Analytics | Active | + + +```mdx Good table structure +| Feature | Status | Last updated | +| ------- | ------ | ------------ | +| Search | Active | 2024-03-15 | +| Analytics | Active | 2024-03-10 | +| Exports | Beta | 2024-03-20 | +``` + +```mdx Poor table structure +| Search | Active | 2024-03-15 | +| Analytics | Active | 2024-03-10 | +| Exports | Beta | 2024-03-20 | ``` + + +The poor example lacks headers, making it impossible for screen readers to announce what each column represents. + ## Write descriptive alt text Alt text makes images accessible to screen reader users and appears when images fail to load. Images in your documentation should have alt text that describes the image and makes it clear why the image is included. Even with alt text, you should not rely on images alone to convey information. Make sure your content describes what the image communicates. + +Learn more about working with images in the [media guide](/guides/media). + + ### Write effective alt text - **Be specific**: Describe what the image shows, not just that it's an image. @@ -193,6 +210,36 @@ If you customize your theme colors, verify the contrast ratios meet WCAG require Test both light and dark mode. The `mint a11y` command checks for color contrast. + + +```json Good contrast example +{ + "colors": { + "primary": "#0066CC", + "background": { + "light": "#FFFFFF", + "dark": "#1A1A1A" + } + } +} +``` + +```json Poor contrast example +{ + "colors": { + "primary": "#FFCC00", + "background": { + "light": "#FFFFFF", + "dark": "#333333" + } + } +} +``` + + + +In the poor example, yellow (#FFCC00) on white has insufficient contrast. The dark mode background (#333333) is too light for optimal readability. + ### Don't rely on color alone If you use color to convey information, include a text label or icon as well. For example, don't mark errors only with red text. Include an error icon or the word "Error." @@ -204,6 +251,10 @@ If you use color to convey information, include a text label or icon as well. Fo - Avoid run-on sentences. - Use active voice. + +See the [style and tone guide](/guides/style-and-tone) for more writing best practices. + + ## Make code examples accessible Code blocks are a core part of technical documentation, but they require specific accessibility considerations to ensure screen reader users can understand them. In general, follow these guidelines: @@ -300,9 +351,54 @@ The command checks for: - Missing alt text on images and videos. - Insufficient color contrast. -When the scan completes, review the reported issues and fix them in your content. Run the command again to verify your fixes. +#### Interpret the output + +When the scan completes, you'll see a report like this: + +```bash +Accessibility Issues Found: + +❌ Missing alt text (3 issues) + - /guides/quickstart.mdx:45 - Image missing alt text + - /api-reference/users.mdx:12 - Image missing alt text + - /guides/setup.mdx:89 - Video missing title attribute + +⚠️ Color contrast (2 issues) + - Primary color (#FFCC00) on light background fails WCAG AA (2.1:1) + - Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1) + +✅ 0 issues found in 15 other pages +``` + +#### Fix common issues + +**Missing alt text**: Add descriptive alt text to the image or video: + +```mdx + +![](/images/dashboard.png) + + +![Dashboard showing three active projects and two pending invitations](/images/dashboard.png) +``` + +**Color contrast failures**: Update your theme colors in `docs.json`: + +```json +{ + "colors": { + "primary": "#0066CC", // Changed from #FFCC00 + "light": "#3399FF", + "dark": "#004C99" + } +} +``` + +Run `mint a11y` again to verify your fixes. -Use flags to check for specific accessibility issues. +#### Use flags for targeted checks + +Use flags to check for specific accessibility issues: ```bash # Check only for missing alt text @@ -310,6 +406,9 @@ mint a11y --skip-contrast # Check only for color contrast issues mint a11y --skip-alt-text + +# Fail CI/CD pipeline if issues are found +mint a11y --fail-on-error ``` ### Basic keyboard navigation test @@ -329,6 +428,42 @@ For more comprehensive testing: - **Browser extensions**: Install [axe DevTools](https://www.deque.com/axe/browser-extensions/) or [WAVE](https://wave.webaim.org/extension/) to scan pages for issues. - **WCAG guidelines**: Review the [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG22/quickref/) for detailed standards. +## Frequently asked questions + + + + +Most organizations aim for WCAG 2.1 Level AA compliance, which is the standard for many legal requirements and provides a good balance of accessibility and feasibility. Level AAA is more stringent and may not be achievable for all content types. + +Start with Level AA as your baseline. The `mint a11y` command checks for common Level AA requirements like color contrast and alt text. + + + +On Mac, use the built-in VoiceOver (press Cmd + F5 to enable). On Windows, download [NVDA](https://www.nvaccess.org/) (free and open source). Navigate through your documentation using only the screen reader and listen for proper heading announcements, descriptive link text, alt text on images, and logical reading order. You don't need to be an expert to catch major issues. + + + +**Alt text** is read by screen readers and appears when images fail to load. It describes what the image shows and why it's relevant. Alt text is required for accessibility. + +**Captions** appear below images for all users. They provide additional context, attribution, or explanation. Captions are optional and supplement alt text. + +Use both when an image needs description (alt text) and additional context (caption). + + + +Yes, but sparingly. Screen readers announce emoji names out loud, so multiple emojis in a row become disruptive. For example, 🎉 becomes "party popper" and 🚀 becomes "rocket" so 🎉 🚀 becomes "party popper rocket". Avoid using emojis to convey critical information. If the emoji were removed, the meaning should still be clear. When in doubt, use text instead. + + + +Specify the language on every code block for syntax highlighting. Provide context before and after code blocks so screen reader users understand what the code does—screen readers often skim code itself. Break long examples into smaller chunks and use descriptive variable names that make sense when read aloud. + + + +Prioritize by impact. Fix missing alt text, broken keyboard navigation, and insufficient color contrast first—these affect the most users. Poor heading hierarchy and vague link text come next. Document known issues with a plan to address them. Progress is better than perfection. + + + + ## Additional resources Continue learning about accessibility with these trusted resources: