accessibility-001 must GuidesAPI docsMarketing Don’t use color as the only way to convey information. Pair color with text, a pattern, an icon, an underline, or another cue.
Accessibility
Accessible documentation benefits people with and without disabilities by supporting different input methods, display settings, and assistive technologies. Use this page when you write or review text, media, or interactive documentation.
For guidance on referring to people with disabilities, see the inclusive content topic.
Don’t rely on color alone
Section titled “Don’t rely on color alone”Examples
- ✓ Required fields have red labels and an asterisk.
- ✗ Required fields have red labels.
Rationale
Readers who can’t perceive a color difference need another way to find the same information.
Meet minimum color contrast
Section titled “Meet minimum color contrast”accessibility-002 should GuidesAPI docsMarketing Use a color contrast ratio of at least 4.5:1 between text and its background.
Rationale
A ratio of 4.5:1 meets the Level AA minimum in WCAG 2.2 for most text and helps readers with low vision or reduced contrast sensitivity distinguish text from its background.
Don’t break lines manually
Section titled “Don’t break lines manually”accessibility-003 should GuidesAPI docsMarketing Don’t insert hard line breaks within a sentence or paragraph.
Examples
- ✓ The request fails if the token is missing.
- ✗
The request fails<br>if the token is missing.
Rationale
A forced line break prevents text from reflowing with the viewport or font size. Let the renderer wrap paragraphs instead.
Don’t orient by direction alone
Section titled “Don’t orient by direction alone”accessibility-004 should GuidesAPI docsMarketing Don’t use directional words such as above, below, left, or right as the only way to identify content. Name the section, control, or other structural reference instead.
Examples
- ✓ Use the Filters panel to narrow the results.
- ✗ Use the panel on the left to narrow the results.
Rationale
Layout can change when content reflows, a screen is magnified, or a screen reader presents content linearly. A structural label identifies the same content in each presentation.
Spell out words, not symbols
Section titled “Spell out words, not symbols”accessibility-005 should GuidesAPI docsMarketing Spell out words such as and, plus, and about instead of using &, +, or ~. Keep symbols that are part of code, a proper name, or an established technical notation.
Examples
- ✓ Setup takes about 5 minutes and requires two restarts.
- ✗ Setup takes ~5 minutes & requires two restarts.
Rationale
Screen readers handle symbols differently according to the reader and its punctuation settings. Spelling out the intended word avoids an ambiguous or omitted pronunciation.
Don’t use flashing or flickering content
Section titled “Don’t use flashing or flickering content”accessibility-007 should GuidesAPI docsMarketing Don’t use content that flashes or flickers.
Rationale
Rapid flashing can trigger seizures, migraines, dizziness, or nausea. Avoiding it removes the need to measure flash frequency, brightness, and area against safety thresholds.
Avoid camel case and all caps
Section titled “Avoid camel case and all caps”accessibility-008 should GuidesAPI docsMarketing Avoid camel case and all-uppercase text in ordinary body text. Preserve required casing in code, UI labels, and proper names.
Examples
- ✓ The autosave setting saves your work immediately.
- ✗ The autoSave setting saves your work IMMEDIATELY.
Rationale
Unnecessary changes in capitalization can make words harder to recognize visually and can change how a screen reader pronounces them.
Make all functionality keyboard accessible
Section titled “Make all functionality keyboard accessible”accessibility-009 must GuidesAPI docsMarketing Make all functionality operable through a keyboard interface without requiring a mouse or trackpad.
Rationale
Keyboard access supports readers who can’t use a pointer and people who use alternative input devices that emulate a keyboard.
Test with a screen reader
Section titled “Test with a screen reader”accessibility-010 should GuidesAPI docsMarketing Test documentation with a screen reader as part of accessibility review.
Rationale
A screen-reader test can reveal missing labels, incorrect reading order, inaccessible controls, and unclear alternative text that a visual review misses.
Use semantic HTML
Section titled “Use semantic HTML”accessibility-011 should GuidesAPI docsMarketing Use semantic HTML elements for their intended purpose, such as <em> for stress emphasis and <button> for a form control. Don’t reproduce the appearance or behavior of an element with a generic element such as <div>.
Examples
- ✓
<button type="submit">Save</button> - ✗
<div class="btn" onclick="submit()">Save</div>
Rationale
Semantic elements expose roles, states, and relationships that browsers and assistive technologies can interpret. Styling a generic element doesn’t provide that information.
Preserve meaning across access modes
Section titled “Preserve meaning across access modes”accessibility-012 should GuidesAPI docsMarketing Ensure documentation conveys the same information without color, images, sound, or spoken punctuation, and when a reader uses audio alone, keyboard navigation, or screen magnification.
Rationale
An image, sound, color, or punctuation mark might not be available or announced in every presentation. A text or structural alternative preserves the meaning.
Left-align body text
Section titled “Left-align body text”accessibility-013 should GuidesAPI docsMarketing Left-align body text. Don’t center, right-align, or fully justify it.
Rationale
Centered and right-aligned text have inconsistent starting points. Fully justified text can create uneven spacing between words. These layouts can make paragraphs harder to track.
Deprecated rules
Section titled “Deprecated rules”accessibility-006(retired 2026-09-13): “Use person-first language when a person or community has not expressed a preference. Respect identity-first language when it is the preference.” Merged into incl-013 on the inclusive content page, which now states the person-first default and the identity-first exception as one rule. Referring to people with disabilities is that page’s subject; this page covers documentation that works with assistive technology. The ID stays reserved and is never reused.