--- title: How to create accessible documentation description: Headings, alt text, colors and media that work for screen readers, keyboards and every other way in. --- 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)](https://www.w3.org/WAI/WCAG22/quickref/). 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 `` 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](/docs/reference/diagnostics) 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](/docs/guides/linking) 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 `` element, it is the `alt` attribute: ```html 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](/docs/guides/media) 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](/docs/design/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](/docs/guides/style-and-tone) 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). In this walkthrough we create an API key, store it as an environment variable, and send an authenticated request. ``` ### 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](/docs/reference/cli/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](https://www.nvaccess.org/) is free on Windows. - **Browser extensions.** [axe DevTools](https://www.deque.com/axe/browser-extensions/) and [WAVE](https://wave.webaim.org/extension/) scan a rendered page. Run them against the built site, since that is what readers get. - **The standard itself.** The [WCAG quick reference](https://www.w3.org/WAI/WCAG22/quickref/) is searchable and filterable. ## Frequently asked questions 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. 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. 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. 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. 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. 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](https://webaim.org/) — practical articles and tutorials. - [The A11y Project](https://www.a11yproject.com/) — a community checklist and resources. - [W3C Web Accessibility Initiative](https://www.w3.org/WAI/) — the standards and official guidance, including WCAG itself.