accessibility-001 must GuidesAPI docs Never convey information using color alone; always pair color with a secondary cue such as pattern, text label, or underline.
Accessibility
These rules keep documentation usable for readers who rely on screen readers, keyboard navigation, magnification, or other assistive technology. They cover wording, structure, and a few presentation requirements; language about people with disabilities is covered in inclusive content.
Don’t rely on color alone
Section titled “Don’t rely on color alone”Examples
- ✓ Required fields are shown in red and marked with an asterisk.
- ✗ Required fields are shown in red.
Rationale
A reader with color blindness or a grayscale display misses information carried only by color, so a second cue reaches everyone.
Meet minimum color contrast
Section titled “Meet minimum color contrast”accessibility-002 should GuidesAPI docs Use a minimum color contrast ratio of 4.5:1 for text.
Rationale
Text below the contrast threshold is hard to read for low-vision users and in bright light; 4.5:1 is the WCAG AA baseline.
Don’t break lines manually
Section titled “Don’t break lines manually”accessibility-003 should GuidesAPI docs Do not insert hard line breaks (hard returns) within sentences or paragraphs.
Examples
- ✓ The request fails if the token is missing.
- ✗ “The request fails” on one source line and “if the token is missing.” on the next — a hard return inside the sentence
Rationale
Hard returns inside a paragraph do not reflow, so text wraps badly when the window resizes or the font enlarges.
Don’t orient by direction alone
Section titled “Don’t orient by direction alone”accessibility-004 should GuidesAPI docs Do not use directional language (above, below, left, right) as the sole means of orienting the reader. Supplement with or replace with structural references.
Examples
- ✓ Use the Filters panel to narrow the results.
- ✗ Use the panel on the left to narrow the results.
Rationale
A screen-reader or reflowed-layout user cannot tell what is “above” or “to the left,” so a structural reference works for everyone.
Spell out words, not symbols
Section titled “Spell out words, not symbols”accessibility-005 should GuidesAPI docs Spell out ‘and’, ‘plus’, ‘about’, and similar words rather than using special characters or symbols, because screen readers may misread them.
Examples
- ✓ Setup takes about 5 minutes and requires at least two restarts.
- ✗ Setup takes ~5 minutes & requires 2+ restarts.
Rationale
Screen readers may skip or misread symbols, so the spelled-out word is read reliably.
Use person-first language
Section titled “Use person-first language”accessibility-006 should GuidesAPI docs Use person-first language when referring to people with disabilities (‘a person who has a disability’ rather than ‘a disabled person’).
Examples
- ✓ The setting helps users who have disabilities navigate faster.
- ✗ The setting helps disabled users navigate faster.
Rationale
Person-first phrasing keeps the person, not the condition, as the subject.
No flashing or flickering elements
Section titled “No flashing or flickering elements”accessibility-007 should GuidesAPI docs Do not use flickering or flashing elements, as they can cause motion sickness or seizures.
Rationale
Flashing content can trigger motion sickness or seizures, so it is avoided regardless of visual appeal.
Avoid camel case and all caps
Section titled “Avoid camel case and all caps”accessibility-008 should GuidesAPI docs Avoid camel case and all caps where possible, as some screen readers read capitalized letters individually.
Examples
- ✓ Turn on the autosave feature to save your work immediately.
- ✗ Turn on the AutoSave feature to save your work IMMEDIATELY.
Rationale
Some screen readers spell out camel case and all caps letter by letter, which garbles the word.
Make everything keyboard-reachable
Section titled “Make everything keyboard-reachable”accessibility-009 must GuidesAPI docs Ensure all interactive elements and all parts of a document are reachable by keyboard alone, without a mouse or trackpad.
Rationale
Many users navigate by keyboard alone, so every interactive element must be reachable without a mouse.
Test with a screen reader
Section titled “Test with a screen reader”accessibility-010 should GuidesAPI docs Test documentation with a screen reader to identify accessibility issues.
Rationale
Testing with a screen reader surfaces problems that are not visible on screen.
Use semantic HTML
Section titled “Use semantic HTML”accessibility-011 should GuidesAPI docs Use semantic HTML elements (‘em’ for emphasis, ‘button’ for form submission) rather than custom styles or non-semantic elements.
Examples
- ✓
<button type="submit">Save</button> - ✗
<div class="btn" onclick="submit()">Save</div>
Rationale
Semantic elements carry meaning that assistive technology relies on, which custom styling on a plain element does not.
Don’t depend on one channel
Section titled “Don’t depend on one channel”accessibility-012 should GuidesAPI docs Ensure documentation conveys all intended information when rendered without color, without images, without sound, using only sound, using a keyboard, with screen magnification, and without punctuation.
Rationale
Content that depends on a single channel fails for anyone who cannot use that channel, so the meaning should survive when any one is removed.
Left-align body text
Section titled “Left-align body text”accessibility-013 should GuidesAPI docs Left-align body text; do not center, right-align, or fully justify.
Rationale
Centered or justified body text creates uneven spacing and ragged starts that slow reading, especially for dyslexic readers.