GitBook Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance

Documentation is screenshot-heavy: UI walkthroughs, dashboards, and architecture diagrams. When images are inserted without a text alternative, screen reader users hear only a filename or nothing at all, so the step being illustrated is lost. On GitBook this is common because the image upload flow makes adding alt text optional, and authors often paste screenshots quickly while drafting. Decorative images that carry no information also need handling so they are not announced as meaningless noise.

Long docs pages rely on headings for both visual scanning and screen reader navigation. Authors often pick a heading level by how big it looks rather than by structure, jumping from an H2 straight to an H4 or scattering multiple H1s on one page. Screen reader users navigate by heading and lose their place when the hierarchy is broken, and the on-page outline or 'On this page' table of contents can become misleading when levels are skipped.

GitBook lets you set a brand color that is often applied to links, buttons, and accents. Many brand palettes use light or mid-tone colors that look good on a marketing site but fail the 4.5:1 contrast ratio for normal text against the page background. The result is in-line links and UI labels that low-vision users and people in bright environments cannot read reliably, a problem that affects every page of the published site at once.

Code samples are core to most GitBook docs. Problems arise when essential information is conveyed only through color (syntax highlighting) or when long, horizontally scrolling code is hard to reach with the keyboard. Code that is pasted as an image of a terminal is the worst case: screen reader users get nothing and the snippet cannot be copied. Relying solely on highlight color to distinguish, say, an added versus removed line also fails users who do not perceive that color difference.

Authors frequently embed diagrams, flowcharts, or callout banners that contain important text baked into the image. This text cannot be resized, recolored, selected, or translated, and it often blurs when users zoom. On a docs site this hurts readers who enlarge pages, use high-contrast modes, or rely on browser translation. It also means the diagram's meaning is unavailable to screen reader users unless equivalent text is provided elsewhere.

Reference docs lean on tables for parameters, options, and comparisons. When a table has no designated header row, or when headers are not programmatically associated with their columns, screen reader users hear a flat stream of cells with no way to know which value belongs to which column. GitBook tables created quickly can end up with the first row styled like a header visually but not marked up as header cells, which passes a sighted glance but fails assistive technology.

Screen reader users often pull up a list of all links on a page to navigate. Links labeled 'click here', 'read more', 'see here', or a bare URL give no indication of their destination out of context, so that list becomes useless. This pattern is common in docs that say things like 'for details, click here'. It also weakens the experience for sighted users scanning quickly and provides poor information scent for search engines.

GitBook sites include a search box, and search is often how readers actually find content. If the results list or autocomplete suggestions can only be opened or selected with a mouse, keyboard and screen reader users are blocked from a primary navigation path. Common failure patterns on search widgets include results that cannot be reached with the arrow keys, no way to activate a result with Enter, or focus that is not moved sensibly when results appear or are dismissed.

Screen readers use the page's declared language to choose pronunciation rules. If the published HTML has no lang attribute, or it is set to a language that does not match the content, the text is read with the wrong accent and phonetics, which is hard to understand. This is easy to overlook because the editor looks the same regardless. Multilingual docs are especially affected when a passage in one language sits inside a page declared as another.

GitBook lets you embed OpenAPI and Swagger references, Loom and YouTube videos, CodeSandbox demos, and other third-party content via iframes. When an embedded frame has no accessible name (title), screen reader users hear only 'iframe' or 'frame' with no idea what it contains, and they may struggle to decide whether to enter it. Embedded API explorers in particular can be complex interactive regions that are confusing without an announced purpose.

Some teams add custom CSS to a GitBook site to match brand styling and, in the process, remove the visible outline that appears when an element receives keyboard focus. Without a visible focus indicator, keyboard users cannot tell which link, button, or sidebar item is currently selected, making the whole site effectively unusable without a mouse. This is one of the most common regressions introduced by well-meaning visual customization.

On mobile, docs sites pack many small controls into a tight space: sidebar expand and collapse toggles, the copy-code button on snippets, anchor-link icons, and theme switches. WCAG 2.2 adds target size (minimum) of 24 by 24 CSS pixels, with adequate spacing, so users with motor impairments or large fingers can activate controls without mis-tapping a neighbor. Tiny or tightly clustered icons are a frequent source of frustration on small screens.