Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion guides/accessibility.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Accessibility"
description: "Create documentation that as many people as possible can use with WCAG compliance."

Check warning on line 3 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L3

Spell out 'WCAG', if it's unfamiliar to the audience.
keywords: ["WCAG", "a11y", "screen readers", "accessibility"]
---

Expand Down Expand Up @@ -59,7 +59,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.

Check warning on line 62 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L62

In general, use active voice instead of passive voice ('is defined').

```mdx
<!-- Good -->
Expand Down Expand Up @@ -109,7 +109,7 @@
<!-- Good -->
Learn how to [configure your navigation](/organize/navigation).

<!-- Unclear relation between -->
<!-- Unclear relation between link text and destination -->
[Learn more](/organize/navigation).
```

Expand All @@ -134,13 +134,13 @@

## 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.

Check warning on line 137 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L137

In general, use active voice instead of passive voice ('is included').

### 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 will 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.

Check warning on line 143 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L143

Avoid using 'will'.

Check warning on line 143 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L143

In general, use active voice instead of passive voice ('is associated').

```mdx
<!-- Good -->
Expand Down Expand Up @@ -184,7 +184,7 @@

### Ensure sufficient color contrast

If you customize your theme colors, verify the contrast ratios meet WCAG requirements:

Check warning on line 187 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L187

Spell out 'WCAG', if it's unfamiliar to the audience.

- Body text: minimum 4.5:1 contrast ratio
- Large text: minimum 3:1 contrast ratio
Expand All @@ -210,7 +210,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.

Check warning on line 213 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L213

Spell out 'ASCII', if it's unfamiliar to the audience.

### Specify the programming language

Expand Down Expand Up @@ -326,7 +326,7 @@

- **Screen readers**: Test with [NVDA (Windows)](https://www.nvaccess.org/) or [VoiceOver (Mac)](https://www.apple.com/accessibility/voiceover/).
- **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.

Check warning on line 329 in guides/accessibility.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/accessibility.mdx#L329

Spell out 'WCAG', if it's unfamiliar to the audience.

## Additional resources

Expand Down