VitePress Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance
Last updated: 2026-07-19
VitePress is a Vue-powered static site generator built on Vite, widely used for technical documentation, developer guides, and marketing sites. Most of a VitePress site is authored in Markdown and rendered by the default theme, which is a real advantage for accessibility: the theme ships with reasonable semantics, keyboard-operable navigation, a skip link, and a light and dark mode toggle out of the box. That good foundation is easy to undermine, though. Markdown gives authors freedom to skip heading levels or open a page with an h2, images written in Markdown often ship with empty alt text, and link text like 'click here' or a bare URL provides no context out of link lists. The moments where VitePress accessibility most often breaks are the custom touches: bespoke Vue components dropped into Markdown, home-page hero layouts with low-contrast text over gradients, custom containers and badges, and theme overrides that change colors or remove focus styles. Dark mode adds a second color scheme to verify, because a palette that passes contrast in light mode can fail in dark mode and vice versa. Syntax-highlighted code blocks, custom containers, and embedded demos all need to remain readable and operable. With the European Accessibility Act now applying to many digital products and their documentation, teams shipping docs on VitePress should not assume the default theme alone guarantees conformance. This checklist covers the accessibility issues that appear most often in VitePress sites and how to fix them in Markdown, theme configuration, and custom components.
Common Accessibility Issues
Markdown authors frequently skip heading levels, start a page with an h2 or h3, or use multiple top-level headings across a document. VitePress builds its on-page outline and 'on this page' sidebar from these headings, so a broken hierarchy both confuses screen reader navigation and produces a misleading table of contents.
Use a single h1 (typically the page title or first-level heading) and then increment heading levels by one without skipping, so the document forms a logical outline. Reserve heading syntax for real section titles rather than for visual emphasis, and review the generated outline and page sidebar to confirm the structure is correct.
Images added with Markdown image syntax are often published with empty or unhelpful alt text such as the file name, and diagrams or screenshots that carry important information provide no text alternative. Screen reader users then miss the content the image conveys, which is common in technical documentation full of architecture diagrams and UI screenshots.
Provide descriptive alt text in the Markdown image syntax that conveys the image's meaning, and for complex diagrams add a nearby text description or a details element that explains the content. Use empty alt text only for purely decorative images so assistive technology skips them.
Documentation often uses link text like 'here', 'this', 'read more', or a raw URL. Screen reader users who navigate by pulling up a list of links hear these out of context and cannot tell where each leads, and the pattern is especially common in reference material with many cross-links.
Write link text that describes the destination, such as 'configuration reference' instead of 'click here', so the link makes sense on its own. Avoid using the same generic text for links that go to different places, and ensure links that open in a new tab or point to a download announce that fact.
VitePress lets authors embed custom Vue components in Markdown for tabs, interactive demos, collapsible sections, and widgets. When these components are built from divs with click handlers and no ARIA roles, states, or keyboard handling, they are unusable for keyboard and screen reader users even though the surrounding docs are accessible.
Build interactive Vue components on native button and a elements and follow the WAI-ARIA Authoring Practices for patterns like tabs and disclosures, implementing roles, states such as aria-expanded, focus management, and expected keyboard behavior. Ensure embedded live demos and iframes have accessible names and are keyboard operable.
Theme overrides, home-page hero gradients, custom containers, badges, and brand accent colors frequently fall below the 4.5:1 contrast ratio for text. Because VitePress ships both light and dark modes, a color that passes in one scheme often fails in the other, and overridden CSS variables can break the theme's default accessible values.
Test every text and interactive color against WCAG contrast requirements in both light and dark mode, adjusting the theme's CSS custom properties for each scheme. Pay particular attention to text over hero gradients, custom container backgrounds, badges, and muted 'secondary' text, and document accessible color pairings for reuse.
Custom CSS added to a VitePress theme sometimes removes or weakens the default focus outline on links, buttons, the search box, and navigation, leaving keyboard users unable to see where they are. Documentation is heavily link-based, so a missing focus indicator makes keyboard navigation especially disorienting.
Never remove focus outlines without replacing them; provide a clear, high-contrast focus-visible style on all interactive elements that meets contrast requirements in both light and dark mode. Verify focus visibility on the search input, sidebar links, navbar, and any custom components after applying theme customizations.
VitePress-Specific Tips
- Lean on the default theme's built-in accessibility (skip link, keyboard-operable nav, landmarks) and be cautious with heavy overrides, since custom CSS is the most common way those defaults get broken.
- Enforce heading discipline in Markdown: one h1 per page and no skipped levels, so both screen reader navigation and the auto-generated 'on this page' sidebar stay accurate.
- Write descriptive alt text and link text directly in Markdown as an authoring habit, since VitePress will faithfully render whatever authors provide, including empty alt and 'click here' links.
- Verify color contrast in both light and dark mode after any theme customization, because VitePress ships two color schemes and a fix in one can still fail in the other.
- Audit embedded custom Vue components for keyboard operability and correct roles; the Markdown around them may be accessible while an interactive demo or tabs widget is not.
Recommended Tools
axe DevTools
A browser extension that runs automated WCAG audits against your built VitePress site, flagging missing alt text, heading-order problems, contrast failures in light and dark mode, and ARIA issues in custom components.
HeadingsMap
A browser extension that visualizes a page's heading outline, making it easy to catch the skipped levels and multiple top-level headings that Markdown authoring in VitePress tends to introduce.
VoiceOver
The screen reader built into macOS and iOS, useful for testing how VitePress documentation, navigation, code blocks, and custom components are announced to assistive technology users without installing extra software.
Further Reading
Other CMS Checklists
Get our free accessibility toolkit
We're building a simple accessibility checker for non-developers. Join the waitlist for early access and a free EAA compliance checklist.
No spam. Unsubscribe anytime.