Accessibility Writing
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill writing-expert/references/accessibility-writing.md
↓ Facts as markdownall context files
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.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#accessibility-writing]
The 8-point accessibility-writing test
- Headings form a proper outline. Exactly one <h1> per page. No skipped levels. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
- Every image has an alt attribute. Decorative images use alt="". Informative images get a 1–2 sentence description. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
- Every link reads as a self-contained label. "Click here," "read more," "learn more," and bare URLs fail. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
- Every form control has a programmatically associated label. <label for> matched to input id. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
- Every icon-only button has an accessible name. aria-label describing the action ("Close dialog," not "X icon"). [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
- Information is never conveyed by color alone. Status indicated by "Error: …" prefix or icon plus color. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
- The page declares its language. <html lang="en">. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
- Time-based media has alternatives. Video has synchronized captions and a transcript. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#the-8-point-accessibility-writing-test]
1. Alt text by image purpose
- Decorative images - alt="" (empty, not missing). [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#1-alt-text-by-image-purpose]
- Informative images - describe the information the image carries: alt="CPU usage spikes to 95% at 14:30 UTC then returns to baseline by 14:35." [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#1-alt-text-by-image-purpose]
- Functional images - describe the action or destination: alt="View cart" (NOT alt="shopping cart icon") [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#1-alt-text-by-image-purpose]
- Complex images - short alt plus a long description: alt="Latency percentile chart for production over the past 24 hours." Plus aria-describedby pointing to a <figcaption> with full details. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#1-alt-text-by-image-purpose]
2. Heading structure
- One <h1> per page. The page title. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#2-heading-structure]
- No skipped levels going down. After <h2> you may use another <h2> or an <h3>. You may not jump to <h5>. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#2-heading-structure]
- Headings are not for styling. Don't use <h3> because it looks right. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#2-heading-structure]
- Descriptive headings. "Introduction" fails WCAG 2.4.6. "How to reset your password" passes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#2-heading-structure]
3. Link text
- Don't include the word "link" in link text. Screen readers already announce that an element is a link. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#3-link-text]
- For downloadable files, include the file format: Download the Q1 incident report (PDF, 1.2 MB). [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#3-link-text]
4. Form labels
- <label for> matched to input id. The most robust. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#4-form-labels]
- Wrapped <label>. Works without explicit for/id. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#4-form-labels]
- aria-labelledby pointing at a visible element. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#4-form-labels]
- aria-label. Last resort only when no visible label is possible. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#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"). [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#5-icon-only-buttons]
6. Color independence (WCAG 1.4.1)
- Status with a prefix word. "Error: Email is invalid." "Warning: Unsaved changes." [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#6-color-independence-wcag-141]
- Status with an icon plus color. A red X icon plus the word "Failed." [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#6-color-independence-wcag-141]
- Links underlined as well as colored. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#6-color-independence-wcag-141]
7. Captions, transcripts, audio descriptions
- 1.2.2 Captions (prerecorded), Level A. Synchronized captions for prerecorded video with audio. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#7-captions-transcripts-audio-descriptions]
- 1.2.4 Captions (live), Level AA. Live captions for live audio. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#7-captions-transcripts-audio-descriptions]
- 1.2.5 Audio description (prerecorded), Level AA. Audio description of prerecorded video. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#7-captions-transcripts-audio-descriptions]
9. The "skip to main content" link
- The skip link is the first focusable element on the page. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#9-the-skip-to-main-content-link]
- It is visually hidden until focused. [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#9-the-skip-to-main-content-link]
References
- W3C WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#references]
- W3C, Alternative Text Tutorial: https://www.w3.org/WAI/tutorials/images/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#references]
- W3C, Labeling Controls Tutorial: https://www.w3.org/WAI/tutorials/forms/labels/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#references]
- WebAIM, Creating Accessible Forms: https://webaim.org/techniques/forms/advanced [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#references]
- The A11y Project, Patterns: https://www.a11yproject.com/patterns/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#references]
- Section 508: https://www.section508.gov/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/accessibility-writing/#references]
Where this helps
- Auditing an existing page or app for screen-reader usability before a compliance review or WCAG audit. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing alt text for a new image, deciding whether it's decorative, informative, functional, or complex before choosing what (if anything) to put in the alt attribute. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Reviewing form design so every input has a programmatically associated label rather than relying on placeholder text or visual proximity alone. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Preparing video or audio content for publication and needing to know which caption/transcript/audio-description WCAG success criteria apply at which level (A vs AA). [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Run the 8-point accessibility-writing test against a draft page before publishing: heading outline, alt text, link text, form labels, icon-button names, color independence, declared language, time-based media alternatives. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Rewrite vague link text ("click here," "read more") into self-contained labels that make sense read out of context by a screen reader. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Add a visually-hidden "skip to main content" link as the first focusable element on every page template, not just the homepage. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Pair every color-coded status indicator with a text prefix or icon so the information survives for users who can't perceive color. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Using an image's filename or generic description ("shopping cart icon") as alt text for a functional image instead of describing the action it performs ("View cart"). [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Skipping heading levels (jumping from <h2> to <h4>) or choosing a heading tag for its visual size rather than its place in the outline. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Using aria-label as the default way to label form fields instead of the more robust <label for> association, reserving aria-label for when no visible label is possible. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Describing an icon-only button's appearance ("X," "magnifying glass") in its aria-label instead of the action it performs ("Close dialog," "Search"). [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Limitations
- Complex images (charts, diagrams) can't be fully described in a short alt attribute alone — they need a short alt plus a long description via aria-describedby, which many CMS editors don't support natively. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- WCAG's caption and audio-description requirements differ by content type and level (1.2.2 prerecorded captions at Level A vs. 1.2.4 live captions and 1.2.5 audio description at Level AA), so a piece of media can pass one criterion and fail an adjacent one. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The 8-point test is a fast heuristic check, not a substitute for testing with an actual screen reader (VoiceOver, NVDA, JAWS) or with real assistive-technology users. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Decorative-image handling depends on correctly judging an image as decorative in the first place — misclassifying an informative image as decorative (alt="") hides real information from screen-reader users. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
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