How to create accessible documentation

Accessible documentation is documentation as many people as possible can use, however they reach it. That includes readers on a screen reader, readers who navigate by keyboard, readers with low vision or color blindness, and readers on a phone over a bad connection.

The work pays off for everyone. Pages built for a screen reader are also clearer, better structured and easier to scan for a sighted reader in a hurry.

Accessibility is never finished. Standards move, content changes, and there is always something to improve. Start with the changes that help the most people, then build the rest into how you work.

What accessibility means

Accessibility — often shortened to a11y, for the eleven letters between the “a” and the “y” — is the practice of building sites and tools that people with temporary or permanent disabilities can use as fully as anyone else.

The reference standard is the Web Content Accessibility Guidelines (WCAG). It organizes the work around four ideas: content must be perceivable, operable, understandable and robust.

Get started

You do not have to fix everything at once, and you cannot fix it once and walk away.

Three things to do today

1. Run reed check. It reports three accessibility problems as build-failing errors.
2. Give every image real alt text.
3. Fix your heading hierarchy. No H1 in the body, and no skipped levels.

What Reed checks, and what it does not

Reed has three accessibility checks, all in the DS-A* family, and all errors rather than warnings — each one produces a page a screen reader cannot convey properly:

Code	What it catches
DS-A01	An image or <img> with no non-empty alt.
DS-A02	An H1 in the page body, or a skipped heading level such as h2 to h4.
DS-A03	An Icon that is the only content of a link or button and has no label.

The template takes care of the page shell: pages render as semantic HTML with landmarks and a skip link, and the sidebar and search are keyboard-navigable.

Everything else is yours: whether your alt text is useful, whether link text makes sense, whether your colors have enough contrast, whether your videos have captions. Reed does not claim a WCAG conformance level for your site, and no tool can check those things for you. See the diagnostics catalog for the full list of codes.

Plan the work in phases

Use whatever workflow suits your team. One that works:

Phase 1: images and structure

• Make reed check pass — alt text present, headings in order, icon links labelled.
• Read your alt text and rewrite anything vague.
• Replace generic link text like “click here”.

Phase 2: navigation and media

• Walk the site with only a keyboard.
• Try it with a screen reader.
• Add captions and transcripts to your videos.
• Check your color contrast in both light and dark mode.

Phase 3: make it routine

• Run reed check on every pull request. It is offline and fast.
• Add accessibility to your content review checklist.
• Retest with a keyboard whenever you add something interactive.

Small, steady improvements last. A one-off audit decays the moment the next page ships.

Structure your content

Structure is what screen reader users navigate by. Many jump from heading to heading to find the section they need, the same way a sighted reader skims.

Use a proper heading hierarchy

Each page has one H1, and it comes from the title in frontmatter. Start body headings at ## and go down one level at a time:

mdx

## Main section

### Subsection

### Another subsection

## Another main section

Jumping from ## to #### breaks the outline a screen reader presents. So does writing a # heading in the body, which gives the page two competing H1s. Both are DS-A02 errors.

Give headings at the same level distinct names. A page with three sections all called “Tip” gives a reader navigating by heading nothing to choose between.

Write descriptive link text

Screen readers can list every link on a page out of context. A list of five “read more” links is useless. Make link text name its destination:

mdx

Learn how to [structure your navigation](/docs/guides/navigation).

Write [structure your navigation], not [Learn more]. The linking guide has more on this.

Keep content scannable

• Break up long paragraphs.
• Use lists for steps and options.
• Use callouts such as Note and Warning for information that must stand out.

Use tables for tabular data

Use tables only for data that genuinely has rows and columns, and always give them a header row, so a screen reader can announce which column each cell belongs to:

mdx

| Feature   | Status | Last updated |
| --------- | ------ | ------------ |
| Search    | Active | 2026-03-15   |
| Analytics | Active | 2026-03-10   |

A table without a header row leaves a screen reader user guessing what each column means.

Write alt text that helps

Alt text is read aloud by screen readers and shown when an image fails to load. It should describe the image and make clear why it is there. Even with good alt text, do not let an image carry information alone — say it in the text as well.

What good alt text looks like

• Specific. Describe what the image shows, not just that there is one.
• Concise. One or two sentences.
• Not redundant. Do not start with “Image of”; the screen reader already announces an image. Say “Screenshot of” or “Diagram of” only when the kind of image matters.

mdx

![Screenshot of the dashboard showing three active projects and two pending invitations](./images/dashboard.png)

“Dashboard screenshot” would pass DS-A01 and tell a listener almost nothing.

Where alt text goes

In markdown, alt text sits between the square brackets:

mdx

![Description of the image](./images/example.png)

On an <img> element, it is the alt attribute:

html

<img
  src="https://cdn.example.com/settings-panel.png"
  alt="Settings panel with the accessibility options enabled and outlined in orange"
/>

Reed has no decorative-image escape hatch. An empty alt="" fails DS-A01 like a missing one. The media guide covers images in more depth.

Design for readability

Color and visual design decide whether readers with low vision or color blindness can use your docs at all.

Check color contrast

WCAG’s minimum contrast ratios:

• Body text: at least 4.5:1.
• Large text: at least 3:1.
• Interactive elements and their boundaries: at least 3:1.

In Reed, your palette is six required keys in docs.json, each with a light and a dark value: accent-primary, background, border, sidebar-background, header-background and card-background. See Colors.

Reed does some of this work for you. From accent-primary, it derives the accent text color used for links and measures it against your background for each mode; if it falls short of 4.5:1, Reed moves it darker or lighter until it clears. The text placed on top of an accent fill is chosen as whichever of a near-white or near-black gives more contrast.

That is where the guarantees stop. Reed does not check your sidebar, header or card backgrounds against the text that sits on them, does not check border against anything, and does not check colors you set in customCss, which overrides everything else. If you customize any of those, measure the result with a contrast checker — in light and dark mode, since each is a separate set of values.

Do not rely on color alone

If color carries meaning, say it in words or with a labelled icon as well. An error marked only in red is invisible to many readers; “Error:” is not.

The same applies to icons. An Icon that stands alone inside a link or button needs a label, or a screen reader announces nothing useful — that is DS-A03. Give any meaningful icon a label, even where the check does not require it.

Use plain language

• Write in plain words.
• Define technical terms the first time you use them.
• Keep sentences short.
• Prefer active voice.

The style and tone guide goes further.

Make code examples accessible

Code blocks are central to technical docs, and they need care for screen reader users:

• Break long examples into shorter, logical pieces.
• Comment the non-obvious logic.
• Describe complex algorithms in prose as well.
• Show file trees in a code block with a language tag rather than as decorative art.

Tag every fence with a language

Declare the language on every fenced block. It drives syntax highlighting, and it tells readers and tools what they are looking at:

javascript

function getUserData(id) {
  return fetch(`/api/users/${id}`);
}

Put context around code

Say what the code does before it, and what it returns after it. Screen reader users often skip through code, and the surrounding sentences are what tell them whether they need to stop. “The following function fetches a user from the API” before the block, and “It returns a promise that resolves to the user object” after it, is enough.

Video and multimedia

Anything shown only in a video or animation needs a text alternative.

Captions

Captions serve readers who are deaf or hard of hearing, and anyone watching without sound:

• Caption all speech.
• Include sound effects that matter.
• Keep captions in sync with the audio.
• Identify speakers when there is more than one.

Most video platforms support caption files. Auto-generated captions are a starting point; review them before you publish.

Transcripts

A transcript is searchable, easy to quote, and readable by any screen reader. Put it on the page next to your link to the video. An Accordion keeps a long transcript out of the way without hiding it from anyone — content inside a closed accordion is still in the page and still indexed by search:

mdx

Watch the [authentication walkthrough](https://videos.example.com/auth-setup) (6 minutes).

<Accordion title="Video transcript">
  In this walkthrough we create an API key, store it as an environment variable, and send
  an authenticated request.
</Accordion>

Never put essential information only in a video

If a reader must know something to finish their task, it belongs in text:

• Write out the same steps in prose.
• Add key screenshots with descriptive alt text.
• Or write a full text tutorial covering the same ground.

Test your documentation

Run reed check

bash

reed check

It fails on DS-A01, DS-A02 and DS-A03, alongside every other content error. reed build runs the same checks, so an inaccessible page of those three kinds cannot ship. See reed check.

Test with a keyboard

Build the site, serve it, and use only the keyboard:

1. Tab moves forward through links and controls.
2. Shift+Tab moves back.
3. Enter follows links and activates buttons.
4. Confirm every interactive element is reachable and shows a visible focus indicator.

Pay closest attention to anything you added yourself — custom CSS that restyles focus states is the usual way a keyboard path breaks.

Go further

• Screen readers. VoiceOver is built into macOS; NVDA is free on Windows.
• Browser extensions. axe DevTools and WAVE scan a rendered page. Run them against the built site, since that is what readers get.
• The standard itself. The WCAG quick reference is searchable and filterable.

Frequently asked questions

Should I aim for WCAG AA or AAA?

Most organizations target WCAG 2.1 or 2.2 Level AA. It is the level most legal requirements reference, and it is achievable. AAA is stricter and not realistic for every kind of content. Treat AA as your baseline. Reed’s checks cover three specific failures, not a conformance level, so reaching AA still takes review and manual testing.

How do I test with a screen reader?

On a Mac, turn on VoiceOver with Command+F5. On Windows, install NVDA, which is free and open source. Move through a page using only the screen reader and listen for sensible heading announcements, link text that makes sense on its own, alt text on images and a logical reading order. You do not need to be an expert to hear the big problems.

What is the difference between alt text and a caption?

Alt text is read by screen readers and shown when an image fails to load. It describes what the image shows and why it matters, and Reed requires it. A caption is visible to everyone, below the image, and adds context or attribution. In Reed, the Frame component’s caption prop provides one. Captions are optional and never replace alt text; use both when an image needs a description and extra context.

Can I use emoji?

Sparingly. Screen readers read emoji names aloud, so a row of them becomes a string of words like “party popper rocket”. Never let an emoji carry information on its own: if you delete it, the sentence should still mean the same thing. When in doubt, use words.

How do I make code examples accessible?

Tag every code block with its language. Explain what the code does before it and what it returns after it, because screen reader users often skip over code itself. Keep examples short, and use variable names that make sense read aloud.

What if I cannot fix everything right away?

Prioritize by impact. Reed already forces the first three fixes: alt text, heading order and icon labels. After that, tackle keyboard access and color contrast, then link text and plain language. Keep a list of known issues with a plan for each. Progress beats perfection.

Further reading

• WebAIM — practical articles and tutorials.
• The A11y Project — a community checklist and resources.
• W3C Web Accessibility Initiative — the standards and official guidance, including WCAG itself.