Enhance accessibility guide with examples and FAQs

guides/accessibility.mdx

@@ -7,19 +7,19 @@
 
 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?
 
 Accessibility (sometimes abbreviated as a11y for the number of letters between the first and last letters of "accessibility") is intentionally designing and building websites and tools that as many people as possible can use. People with temporary or permanent disabilities should have the same level of access to digital technologies. And designing for accessibility benefits everyone, including people who access your website on mobile devices or slow networks.
 
 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.
 
@@ -60,7 +60,7 @@
 
 ### Use proper heading hierarchy
 
 Each page should have a single H1 heading, which is defined by the `title:` property in a page's frontmatter. Use additional headings in order without skipping. For example, don't skip from H2 to H4.
 
 ```mdx
 <!-- Good -->
@@ -126,22 +126,39 @@
 
 When using tables, include headers so screen readers can associate data with the correct column:
 
-```mdx
-| Feature | Status |
-| ------- | ------ |
-| Search  | Active |
-| Analytics | Active |
+<CodeGroup>
+
+```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 |
 ```
 
+</CodeGroup>
+
+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.
 
+<Tip>
+Learn more about working with images in the [media guide](/guides/media).
+</Tip>
+
 ### Write effective alt text
 
 - **Be specific**: Describe what the image shows, not just that it's an image.
 - **Be concise**: Aim for one to two sentences.
 - **Avoid redundancy**: Don't start with "Image of" because screen readers already know that the alt text is associated with an image. However, you should include descriptions like "Screenshot of" or "Diagram of" if that context is important to the image.
 
 ```mdx
 <!-- Good -->
@@ -170,7 +187,7 @@
 
 ### Add titles to embedded content
 
 Iframes and video embeds require descriptive titles:
 
 ```html
 <iframe
@@ -193,6 +210,36 @@
 
 Test both light and dark mode. The `mint a11y` command checks for color contrast.
 
+<CodeGroup>
+
+```json Good contrast example
+{
+  "colors": {
+    "primary": "#0066CC",
+    "background": {
+      "light": "#FFFFFF",
+      "dark": "#1A1A1A"
+    }
+  }
+}
+```
+
+```json Poor contrast example
+{
+  "colors": {
+    "primary": "#FFCC00",
+    "background": {
+      "light": "#FFFFFF",
+      "dark": "#333333"
+    }
+  }
+}
+```
+
+</CodeGroup>
+
+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 @@
 - Avoid run-on sentences.
 - Use active voice.
 
+<Tip>
+See the [style and tone guide](/guides/style-and-tone) for more writing best practices.
+</Tip>
+
 ## 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:
@@ -211,7 +262,7 @@
 - Break long code examples into smaller, logical chunks.
 - Comment complex logic within the code.
 - Consider providing a text description for complex algorithms.
 - When showing file structure, use actual code blocks with language labels rather than ASCII art.
 
 ### Specify the programming language
 
@@ -300,16 +351,64 @@
 - 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
+<!-- Before -->
+![](/images/dashboard.png)
+
+<!-- After -->
+![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
 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 @@
 - **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
+
+<AccordionGroup>
+
+<Accordion title="Do I need to make my documentation WCAG AA or AAA compliant?">
+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.
+</Accordion>
+
+<Accordion title="How do I test my documentation with a screen reader?">
+On Mac, use the built-in VoiceOver (press <kbd>Cmd</kbd> + <kbd>F5</kbd> 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.
+</Accordion>
+
+<Accordion title="What's the difference between alt text and image captions?">
+**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).
+</Accordion>
+
+<Accordion title="Can I use emojis in accessible documentation?">
+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.
+</Accordion>
+
+<Accordion title="How do I handle accessibility for code examples?">
+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.
+</Accordion>
+
+<Accordion title="What if I can't fix all accessibility issues right away?">
+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.
+</Accordion>
+
+</AccordionGroup>
+
 ## Additional resources
 
 Continue learning about accessibility with these trusted resources: