Enhance accessibility guide with examples and FAQs

guides/accessibility.mdx

@@ -7,29 +7,79 @@
 
 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 benefits everyone**, not just users with disabilities. When you design for accessibility, you create content that is:
 
-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.
+- **Clearer and better structured** for all readers
+- **Easier to navigate** with keyboard, mouse, or assistive technologies
+- **More discoverable** through improved semantic structure
+- **Usable in more contexts** like mobile devices, slow networks, or noisy environments
+
+This guide offers practical steps for creating 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
+## Quick wins: Start here
 
-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 new to accessibility, these high-impact changes will immediately improve your documentation for all users. You can implement each of these in minutes.
 
-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.
+<CardGroup cols={2}>
+
+<Card title="Run mint a11y" icon="terminal">
+Scan your documentation for accessibility issues:
+
+```bash
+mint a11y
+```
+
+This identifies missing alt text and color contrast problems automatically.
+</Card>
+
+<Card title="Add alt text to images" icon="image">
+Describe what each image shows and why it's included:
+
+```mdx
+![Dashboard showing three active projects](/images/dashboard.png)
+```
+
+Screen readers announce this description to users who can't see the image.
+</Card>
 
-### First steps
+<Card title="Fix heading hierarchy" icon="heading">
+Ensure one H1 per page and sequential heading levels:
 
-Here are three things you can do right now to improve the accessibility of your documentation:
+- H1 (page title) → H2 → H3
+- Never skip levels (H2 → H4)
 
-1. **Run `mint a11y`** to identify accessibility issues in your content.
-2. **Add alt text** to all images.
-3. **Check your heading hierarchy** to ensure one H1 per page and headings follow sequential order.
+Screen readers use headings to navigate content.
+</Card>
+
+<Card title="Write descriptive links" icon="link">
+Replace vague link text with meaningful descriptions:
+
+```mdx
+<!-- Good -->
+Learn how to [configure navigation](/organize/navigation).
+
+<!-- Bad -->
+[Click here](/organize/navigation) to learn more.
+```
+
+Users should understand where a link goes without surrounding context.
+</Card>
+
+</CardGroup>
+
+These four changes address the most common accessibility issues and take minimal time to implement.
+
+## Getting 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. 
+
+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.
 
 ### Plan your accessibility work
 
@@ -60,7 +110,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 +176,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](/writing-content/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 +237,7 @@
 
 ### Add titles to embedded content
 
 Iframes and video embeds require descriptive titles:
 
 ```html
 <iframe
@@ -193,6 +260,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 +301,10 @@
 - Avoid run-on sentences.
 - Use active voice.
 
+<Tip>
+See the [style and tone guide](/writing-content/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,8 +312,12 @@
 - 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.
 
+<Tip>
+Learn more about formatting code in the [code guide](/writing-content/code).
+</Tip>
+
 ### Specify the programming language
 
 Always declare the language for syntax highlighting. This helps screen readers announce the code context to users:
@@ -300,16 +405,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
 
-Use flags to check for specific accessibility issues.
+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 `mint.json`:
+
+```json
+{
+  "colors": {
+    "primary": "#0066CC",  // Changed from #FFCC00
+    "light": "#3399FF",
+    "dark": "#004C99"
+  }
+}
+```
+
+Run `mint a11y` again to verify your fixes.
+
+#### 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 +482,117 @@
 - **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.
 
+## Maintain accessibility over time
+
+Accessibility is not a one-time task. As your documentation grows and evolves, you need to maintain accessibility standards to ensure all users can access your content.
+
+### Build accessibility into your workflow
+
+Integrate accessibility checks into your regular documentation process:
+
+- **Run `mint a11y` before publishing**: Make it part of your pre-publish checklist or CI/CD pipeline.
+- **Include accessibility in content reviews**: Add accessibility criteria to your review process alongside technical accuracy and clarity.
+- **Test new features**: When adding interactive components, embeds, or custom elements, verify keyboard navigation and screen reader support.
+- **Audit regularly**: Schedule quarterly accessibility audits to catch issues that accumulate over time.
+
+### Set up automated checks
+
+Automate accessibility testing to catch issues early:
+
+```bash
+# Add to your CI/CD pipeline
+mint a11y --fail-on-error
+```
+
+This command exits with an error code if accessibility issues are found, preventing problematic content from being published.
+
+### Keep up with standards
+
+Web accessibility standards evolve. Stay informed about changes:
+
+- **Subscribe to WCAG updates**: Follow the [W3C Web Accessibility Initiative](https://www.w3.org/WAI/) for guideline updates.
+- **Review new features**: When Mintlify releases new components or features, check their accessibility documentation.
+- **Learn from user feedback**: If users report accessibility issues, document the fix and add it to your review checklist.
+
+### Document your accessibility practices
+
+Create internal documentation for your team:
+
+- **Accessibility checklist**: List specific checks for your documentation (alt text, heading hierarchy, color contrast).
+- **Common issues and fixes**: Document recurring problems and their solutions.
+- **Testing procedures**: Outline how to test with screen readers and keyboard navigation.
+
+This ensures everyone on your team can contribute to accessible documentation.
+
+## 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?">
+For basic testing:
+
+- **Windows**: Download [NVDA](https://www.nvaccess.org/) (free and open source)
+- **Mac**: Use built-in [VoiceOver](https://www.apple.com/accessibility/voiceover/) (press <kbd>Cmd</kbd> + <kbd>F5</kbd> to enable)
+
+Navigate through your documentation using only the screen reader. Listen for:
+- Proper heading announcements
+- Descriptive link text
+- Alt text on images
+- Logical reading order
+
+You don't need to be an expert screen reader user 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 use them sparingly and thoughtfully:
+
+- Screen readers announce emoji names (🎉 becomes "party popper")
+- Avoid using emojis to convey critical information
+- Don't use multiple emojis in a row (screen readers will announce each one)
+- Consider your audience—technical documentation typically uses emojis minimally
+
+When in doubt, use text instead of emojis for important information.
+</Accordion>
+
+<Accordion title="How do I handle accessibility for code examples?">
+Make code examples accessible by:
+
+1. **Always specify the language** for syntax highlighting
+2. **Provide context** before and after code blocks
+3. **Break up long examples** into smaller, logical chunks
+4. **Add comments** to explain complex logic
+5. **Use descriptive variable names** that make sense when read aloud
+
+Screen reader users often skim code blocks, so surrounding context is crucial for understanding what the code does.
+</Accordion>
+
+<Accordion title="What if I can't fix all accessibility issues right away?">
+Prioritize based on impact:
+
+1. **Critical**: Missing alt text, broken keyboard navigation, insufficient color contrast
+2. **High**: Poor heading hierarchy, vague link text, missing video captions
+3. **Medium**: Minor contrast issues, inconsistent structure
+4. **Low**: Optimization and refinement
+
+Fix critical issues first, then work through the list systematically. Document known issues and your plan to address them. Progress is better than perfection.
+</Accordion>
+
+</AccordionGroup>
+
 ## Additional resources
 
 Continue learning about accessibility with these trusted resources: