Accessibility and Performance

Accessibility¶

Most of the user-facing interface lives in myst-theme. These default themes build on top of Remix, which provides sensible accessibility defaults. This section describes the broader goals and considerations around accessibility for the MyST themes.^[1]

Our accessibility goals¶

The default MyST web themes aim to meet WCAG 2.1 AA, the level required of US public-sector and many private websites under ADA Title II.

Accessibility bugs there are treated like any other bug. See the a11y issues label for open accessibility issues. Accessibility contributions follow the normal contribution process.

How accessible is MyST today?¶

The MyST themes ship with these accessibility behaviors:

• Semantic HTML for articles, asides, figures, navigation, and captions.

• A skip-to-content shortcut and full keyboard navigation for menus, search, and the table of contents.

• Focusable, scrollable cell outputs so keyboard and screen-reader users can reach long stdout, stderr, and equation output.

• Color-contrast-aware defaults in the book and article themes, including code cells and error states.

• Pre-rendered math that ships as accessible HTML rather than images.

• Alt-text for images sourced from figure captions when present.

• aria labels and roles on interactive controls (theme toggle, document outline, search dialog, footnote return links).

In April 2026 we completed a focused round of work to align with WCAG 2.1 AA. We know there is always ongoing work to be done to improve accessibility and welcome both guidance and contributions, see Where can I follow along or contribute?.

Cell outputs are not under MyST’s control¶

Many libraries emit interactive JavaScript or images as part of executing code (e.g., Plotly, ipywidgets, etc). In these cases, MyST does not have control over the structure of what is created, and cannot guarantee their accessibility. If you find a cell output that is not accessible, please report it in the repository for the tool that produced it. The fix will most likely need to happen in that upstream tool rather than in the MyST theme.

Where can I follow along or contribute?¶

Open accessibility work is tracked under the a11y label in myst-theme. There’s a thread for broader discussion and tracking in the Accessibility Improvements tracking issue.

How can I check the accessibility of my own site?¶

A few tools that others in the community have found useful:

• The Jupyter Accessibility Working Group has a collection of accessibility resources for the broader Jupyter community.

• berkeley-cdss/myst-a11y is a GitHub Action built for MyST sites. It runs axe-core checks against WCAG 2.0 and 2.1 (A and AA) on every push and reports results as a tracking issue. See data-8/textbook for a working example.

• Lighthouse is built into Chrome DevTools and is useful for a quick audit of a single page.

• JupyCheck checks accessibility of source notebooks in Jupyter interfaces. This is useful if you also want readers to launch Jupyter sessions from your MyST site.

Performance¶

The default MyST themes are built on Remix and React. These provide link prefetching, smaller download sizes through modern bundlers, image optimization, and faster page transitions that update only the part of the page that changed. We follow the PRPL pattern where possible:

• Preload the most important resources.

• Render the initial route as soon as possible.

• Pre-cache remaining assets.

• Lazy load other routes and non-critical assets.

Hover over a link in the navigation with your browser’s developer tools open: the next page is fetched as soon as you hover, before you click. Only that page’s content and metadata are downloaded, not a full HTML document, and shared assets like fonts and styles are reused across pages. Pages you’ve already visited are served from your browser’s cache.

Locally, MyST rebuilds and rerenders in under 150ms and restores your scroll position, so you can preview changes without losing your place.

Performance of a deployed site depends on the infrastructure that serves it. See deployment for options.

Lighthouse¶

Lighthouse is a Chrome tool that measures performance, accessibility, and search-engine readiness. It flags asset, image, and crawler issues that affect both real-world load times and search rankings.