Accessibility Writing
Parent: Writing and Documentation · researched 2026-05-29T19:22:07.477Z· 12 sources · 10 concepts · skill accessibility-writing
Reference for writing content that is usable by screen-reader users, low-vision users, deaf and hard-of-hearing users, users with cognitive disabilities, and users on assistive tech.
Accessibility Writing
- Reference for writing content that is usable by screen-reader users, low-vision users, deaf and hard-of-hearing users, users with cognitive disabilities, and users on assistive tech. [source]
The 8-point accessibility-writing test
- Headings form a proper outline. Exactly one <h1> per page. No skipped levels. [source]
- Every image has an alt attribute. Decorative images use alt="". Informative images get a 1–2 sentence description. [source]
- Every link reads as a self-contained label. "Click here," "read more," "learn more," and bare URLs fail. [source]
- Every form control has a programmatically associated label. <label for> matched to input id. [source]
- Every icon-only button has an accessible name. aria-label describing the action ("Close dialog," not "X icon"). [source]
- Information is never conveyed by color alone. Status indicated by "Error: …" prefix or icon plus color. [source]
- The page declares its language. <html lang="en">. [source]
- Time-based media has alternatives. Video has synchronized captions and a transcript. [source]
1. Alt text by image purpose
- Decorative images - alt="" (empty, not missing). [source]
- Informative images - describe the information the image carries: [source]
- alt="CPU usage spikes to 95% at 14:30 UTC then returns to baseline by 14:35." [source]
- Functional images - describe the action or destination: [source]
- alt="View cart" (NOT alt="shopping cart icon") [source]
- Complex images - short alt plus a long description: [source]
- alt="Latency percentile chart for production over the past 24 hours." [source]
- Plus aria-describedby pointing to a <figcaption> with full details. [source]
2. Heading structure
- One <h1> per page. The page title. [source]
- No skipped levels going down. After <h2> you may use another <h2> or an <h3>. You may not jump to <h5>. [source]
- Headings are not for styling. Don't use <h3> because it looks right. [source]
- Descriptive headings. "Introduction" fails WCAG 2.4.6. "How to reset your password" passes. [source]
3. Link text
4. Form labels
5. Icon-only buttons
- The aria-label describes what the button does ("Close dialog," "Search," "Open menu"). NOT what it looks like ("X," "Magnifying glass"). [source]
6. Color independence (WCAG 1.4.1)
7. Captions, transcripts, audio descriptions
9. The "skip to main content" link
References
- W3C WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/ [source]
- W3C, Alternative Text Tutorial: https://www.w3.org/WAI/tutorials/images/ [source]
- W3C, Labeling Controls Tutorial: https://www.w3.org/WAI/tutorials/forms/labels/ [source]
- WebAIM, Creating Accessible Forms: https://webaim.org/techniques/forms/advanced [source]
- The A11y Project, Patterns: https://www.a11yproject.com/patterns/ [source]
- Section 508: https://www.section508.gov/ [source]
Children
- Heading Structure (H1-H2-H3 no skips) (frontier)
- Descriptive Link Text (frontier)
- Alt-Text Writing (W3C four-category decision tree) (frontier)
- Form Label Association (frontier)
- ARIA Labels for Icon-Only Controls (frontier)
- Skip to Main Content Link (frontier)
- Color-Independent Information (frontier)
- Table Captions and Headers (frontier)
- Captions and Transcripts (frontier)
- Reading Level (WCAG) (frontier)
Frontier under this node: ARIA Labels for Icon-Only Controls, Alt-Text Writing (W3C four-category decision tree), Captions and Transcripts, Color-Independent Information, Descriptive Link Text, Form Label Association, Heading Structure (H1-H2-H3 no skips), Reading Level (WCAG), Skip to Main Content Link, Table Captions and Headers