Skip to content
https://sphinx-doc.org

Accessibility

· 13 checks — Landmarks, headings, alt text, forms, and link quality rolled into one auditable list.
SCORE
63
GRADE
D
FIX
5
REVIEW
4
PASS
4
INFO
0
Checks
13
4 PASS 4 REVIEW 5 FIX
F
Favicon & Branding
Action
2 icon(s) detected
FIX
2 icon(s) detected
Info::
favicon.ico present at site root
Info::
HTML icon links detected
Info::
No apple-touch-icon detected
iOS devices use this when users add your site to their home screen. Add <link rel='apple-touch-icon' sizes='180x180' href='/apple-touch-icon.png'>.
✓ favicon.ico Present
✓ PNG Icons Present
✗ Apple Touch Missing
✗ SVG Favicon Missing
✗ Manifest Icons Missing
✗ Multiple Sizes Missing
D
Web Manifest
Action
Not found
FIX
Not found
Info::
No web manifest found
No manifest at standard paths (/manifest.json, /site.webmanifest). A manifest is optional but enables PWA features like home screen installation and standalone display.

No web manifest found.

D
Dark Mode Support
Action
No dark mode signals
FIX
No dark mode signals
Info::
No dark mode signals detected
Consider adding CSS with @media (prefers-color-scheme: dark) and <meta name='color-scheme' content='light dark'>.
Info::
Detection limited to meta tags and inline styles
External CSS files may contain prefers-color-scheme rules not visible to this scan.
Dark ModeNo Dark Mode Detected
color-scheme meta Not set ✗Dark theme-color Not set ✗CSS indicators Not detected ✗

Detection limited to meta tags and inline styles.

D
Print Stylesheet
Action
No print styles
FIX
No print styles
Info::
No print-specific styles detected
When users print this page, they get the screen layout including navigation and non-essential elements. Add @media print rules to hide navigation and optimize layout for paper.
Print Stylesheet No Print Styles
Print stylesheet Not found ✗Inline @media print Not detected ✗
F
Navigation UX
Action
1 navigation pattern(s)
FIX
1 navigation pattern(s)
Info::
Search functionality detected
Got: role-search
Info::
3 navigation landmark(s) detected
Breadcrumbs
Search role='search' landmark
Skip Link
Labeled Navigation 3 <nav> element(s)
Back to Top
Hamburger Menu
Sticky Navigation Cannot reliably detect (CSS-based)
2 of 6 testable patterns navigation patterns detected. Limited navigation support. Consider adding breadcrumbs, search, and skip link.
B
Landmark Structure
6 landmarks
REVIEW
6 landmarks
Info::
<main> landmark present
Info::
3 <nav> landmark(s) found
Info::
All <nav> elements are properly labeled
Info::
No banner (header) landmark
Warning::
Skip navigation link is missing (WCAG 2.4.1)
Add a skip link as the first focusable element so keyboard users can bypass repeated navigation.
Info::
Search landmark present
Page Structure — as a screen reader sees it
BANNER (missing!) NAV "Related" SEARCH MAIN CONTENTINFO footer

Add a skip link as the first focusable element so keyboard users can bypass repeated navigation.

Why this matters

Without a skip-nav link, keyboard users tab through every nav item before reaching content — every page, every visit.

Learn more ▾

WCAG 2.4.1 (Bypass Blocks) requires a mechanism to skip past repeated content. The standard implementation is a 'Skip to main content' link that's the first focusable element, visually hidden until focused. Three lines of HTML + four of CSS.

Source: WCAG 2.1 SC 2.4.1

B
Form Accessibility
2 of 2 controls have issues
REVIEW
2 of 2 controls have issues
Critical::
1 control(s) without accessible label
Form controls need a <label>, aria-label, or aria-labelledby for screen readers.
Got: <input type="submit">
Warning::
1 control(s) rely on placeholder only
Placeholder text disappears on focus and is not a reliable label.
Got: <input type="text" name="q">
2 controls
0 labeled
1 placeholder only
1 unlabeled
ControlTypeLabelMethod
qtext(Search)placeholder only
inputsubmit(none)none

Form controls need a <label>, aria-label, or aria-labelledby for screen readers.

<input type="submit">

Why this matters

Form controls without labels — assistive tech announces 'edit text' with no context; users can't complete forms.

Source: WCAG 2.1 SC 3.3.2

Placeholder text disappears on focus and is not a reliable label.

<input type="text" name="q">

Why this matters

Placeholder-only labels disappear when the user starts typing — they must remember what the field was for.

Learn more ▾

Placeholders are NOT labels. They vanish on input, fail color contrast checks (most are gray), and don't satisfy WCAG SC 3.3.2. Always use a real <label> alongside (or aria-labelledby).

Source: WCAG 2.1 SC 3.3.2 / Nielsen Norman

C
404 Error Page
Action
HTTP 404, custom page
REVIEW
HTTP 404, custom page
Info::
Correct 404 status code returned
Got: HTTP 404
Info::
Custom styled 404 page
Info::
Homepage link present on 404 page
404 Page Quality ✓ Custom 404 Page
Status Code HTTP 404 ✓Page Title Page not found - Read the Docs Community ✓Custom Styling ✓Navigation ✗Homepage Link ✓Search Form ✗
C
Color Contrast (Screenshot)
Action
20 text elements analyzed, 2 fail WCAG AA
REVIEW

Analyzes text contrast against the actual rendered page, including background images, gradients, and overlays that CSS-based tools cannot detect.

18 pass 2 fail WCAG AA
title Sphinx — Sphinx documentation
2.44:1
#000000
on
#0A507A
needs 4.5:1 (normal text)
16px · top of page (header area)
span Sphinx
2.44:1
#000000
on
#0A507A
needs 4.5:1 (normal text)
16px · top of page (header area)
Show all checked elements (20)
ElementRatioRequiredFGBGResult
h1 Sphinx21.00:13.0:1
#000000
#FFFFFF
Pass
h2 Get started21.00:13.0:1
#000000
#FFFFFF
Pass
h2 User guide21.00:13.0:1
#000000
#FFFFFF
Pass
h2 Community guide21.00:13.0:1
#000000
#FFFFFF
Pass
h2 Reference guide21.00:13.0:1
#000000
#FFFFFF
Pass
h3 Navigation10.23:13.0:1
#000000
#9DB9CA
Pass
h3 On this page21.00:13.0:1
#000000
#FFFFFF
Pass
title Sphinx — Sphinx do…2.44:14.5:1
#000000
#0A507A
Fail
span Sphinx2.44:14.5:1
#000000
#0A507A
Fail
a Documentation21.00:14.5:1
#000000
#FFFFFF
Pass
a Sphinx21.00:14.5:1
#000000
#FFFFFF
Pass
a Sphinx21.00:14.5:1
#000000
#FFFFFF
Pass
a Get started21.00:14.5:1
#000000
#FFFFFF
Pass
a User guide21.00:14.5:1
#000000
#FFFFFF
Pass
a Community guide21.00:14.5:1
#000000
#FFFFFF
Pass
a Reference guide21.00:14.5:1
#000000
#FFFFFF
Pass
span The Basics21.00:14.5:1
#000000
#FFFFFF
Pass
a Installing Sphinx21.00:14.5:1
#000000
#FFFFFF
Pass
a Getting started21.00:14.5:1
#000000
#FFFFFF
Pass
a Build your first pro…21.00:14.5:1
#000000
#FFFFFF
Pass

Methodology: The top 20 text elements by font size were checked. Background color was sampled from the desktop screenshot using a 5-point pattern. WCAG 2.1 AA requires 4.5:1 for normal text and 3:1 for large text.

A+
Heading Hierarchy
7 headings
PASS
7 headings
Info::
Single H1 present
  • H3 Navigation
  • H3 On this page
  • H1 Sphinx¶
  • H2 Get started¶
  • H2 User guide¶
  • H2 Community guide¶
  • H2 Reference guide¶
A+
Alt Text Quality
1 of 4 images have issues
PASS
1 of 4 images have issues
Warning::
1 image(s) with generic alt text
Info::
3 image(s) with good alt text
4 images 3 good alt text 1 generic
IssueCount
generic1 image(s)
A
Lighthouse Accessibility Audits
Score 90/100 — 2 failing, 22 passed
PASS
90

Accessibility

These checks highlight opportunities to improve the accessibility of your web app. Automatic detection can only detect a subset of issues and does not guarantee the accessibility of your web app, so manual testing is also encouraged.

ARIA

Some ARIA roles have required attributes that describe the state of the element to screen readers. Learn more about roles and required attributes.

Why this matters

Performance issues directly impact user engagement and conversion rates.

Failing Elements
The Basics section#sphinx > section#get-started > div.toctree-wrapper > p.caption
User guide section#sphinx > section#user-guide > div.toctree-wrapper > p.caption
Community section#sphinx > section#community-guide > div.toctree-wrapper > p.caption
Reference section#sphinx > section#reference-guide > div.toctree-wrapper > p.caption

These are opportunities to improve the usage of ARIA in your application which may enhance the experience for users of assistive technology, like a screen reader.

Best practices

Touch targets with sufficient size and spacing help users who may have difficulty targeting small controls to activate the targets. Learn more about touch targets.

Why this matters

Performance issues directly impact user engagement and conversion rates.

Failing Elements
Installing Sphinx div.toctree-wrapper > ul > li.toctree-l1 > a.reference
PyPI package li.toctree-l1 > ul > li.toctree-l2 > a.reference
Conda package li.toctree-l1 > ul > li.toctree-l2 > a.reference
OS-specific package manager li.toctree-l1 > ul > li.toctree-l2 > a.reference
Docker li.toctree-l1 > ul > li.toctree-l2 > a.reference
Installation from source li.toctree-l1 > ul > li.toctree-l2 > a.reference
Getting started div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Defining document structure li.toctree-l1 > ul > li.toctree-l2 > a.reference
Adding content li.toctree-l1 > ul > li.toctree-l2 > a.reference
Running the build li.toctree-l1 > ul > li.toctree-l2 > a.reference
Documenting objects li.toctree-l1 > ul > li.toctree-l2 > a.reference
Basic configuration li.toctree-l1 > ul > li.toctree-l2 > a.reference
Autodoc li.toctree-l1 > ul > li.toctree-l2 > a.reference
Intersphinx li.toctree-l1 > ul > li.toctree-l2 > a.reference
More topics to be covered li.toctree-l1 > ul > li.toctree-l2 > a.reference
Build your first project div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Getting started li.toctree-l1 > ul > li.toctree-l2 > a.reference
More Sphinx customization li.toctree-l1 > ul > li.toctree-l2 > a.reference
Describing code in Sphinx li.toctree-l1 > ul > li.toctree-l2 > a.reference
Where to go from here li.toctree-l1 > ul > li.toctree-l2 > a.reference
Using Sphinx div.toctree-wrapper > ul > li.toctree-l1 > a.reference
reStructuredText li.toctree-l1 > ul > li.toctree-l2 > a.reference
Markdown li.toctree-l1 > ul > li.toctree-l2 > a.reference
Cross-references li.toctree-l1 > ul > li.toctree-l2 > a.reference
Configuration li.toctree-l1 > ul > li.toctree-l2 > a.reference
Builders li.toctree-l1 > ul > li.toctree-l2 > a.reference
Domains li.toctree-l1 > ul > li.toctree-l2 > a.reference
Extensions li.toctree-l1 > ul > li.toctree-l2 > a.reference
HTML theming li.toctree-l1 > ul > li.toctree-l2 > a.reference
Internationalization li.toctree-l1 > ul > li.toctree-l2 > a.reference
Sphinx Web Support li.toctree-l1 > ul > li.toctree-l2 > a.reference
Extending Sphinx div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Tutorials li.toctree-l1 > ul > li.toctree-l2 > a.reference
How-tos li.toctree-l1 > ul > li.toctree-l2 > a.reference
Sphinx API div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Important objects li.toctree-l1 > ul > li.toctree-l2 > a.reference
Build phases li.toctree-l1 > ul > li.toctree-l2 > a.reference
Extension metadata li.toctree-l1 > ul > li.toctree-l2 > a.reference
LaTeX customization div.toctree-wrapper > ul > li.toctree-l1 > a.reference
LaTeX macros and environments li.toctree-l1 > ul > li.toctree-l2 > a.reference
Get support div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Contribute to Sphinx div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Contributing to Sphinx li.toctree-l1 > ul > li.toctree-l2 > a.reference
Sphinx’s release process li.toctree-l1 > ul > li.toctree-l2 > a.reference
Sphinx FAQ div.toctree-wrapper > ul > li.toctree-l1 > a.reference
How do I… li.toctree-l1 > ul > li.toctree-l2 > a.reference
Using Sphinx with… li.toctree-l1 > ul > li.toctree-l2 > a.reference
Sphinx vs. Docutils li.toctree-l1 > ul > li.toctree-l2 > a.reference
Epub info li.toctree-l1 > ul > li.toctree-l2 > a.reference
Texinfo info li.toctree-l1 > ul > li.toctree-l2 > a.reference
Sphinx authors div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Maintainers li.toctree-l1 > ul > li.toctree-l2 > a.reference
Contributors li.toctree-l1 > ul > li.toctree-l2 > a.reference
Former maintainers li.toctree-l1 > ul > li.toctree-l2 > a.reference
Command-line tools div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Core applications li.toctree-l1 > ul > li.toctree-l2 > a.reference
Additional applications li.toctree-l1 > ul > li.toctree-l2 > a.reference
Configuration div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Project tags li.toctree-l1 > ul > li.toctree-l2 > a.reference
Project information li.toctree-l1 > ul > li.toctree-l2 > a.reference
General configuration li.toctree-l1 > ul > li.toctree-l2 > a.reference
Builder options li.toctree-l1 > ul > li.toctree-l2 > a.reference
Domain options li.toctree-l1 > ul > li.toctree-l2 > a.reference
Extension options li.toctree-l1 > ul > li.toctree-l2 > a.reference
Example configuration file li.toctree-l1 > ul > li.toctree-l2 > a.reference
Extensions div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Built-in extensions li.toctree-l1 > ul > li.toctree-l2 > a.reference
Third-party extensions li.toctree-l1 > ul > li.toctree-l2 > a.reference
reStructuredText div.toctree-wrapper > ul > li.toctree-l1 > a.reference
reStructuredText Primer li.toctree-l1 > ul > li.toctree-l2 > a.reference
Roles li.toctree-l1 > ul > li.toctree-l2 > a.reference
Directives li.toctree-l1 > ul > li.toctree-l2 > a.reference
Field Lists li.toctree-l1 > ul > li.toctree-l2 > a.reference
Glossary div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Changelog div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Prior releases li.toctree-l1 > ul > li.toctree-l2 > a.reference
Projects using Sphinx div.toctree-wrapper > ul > li.toctree-l1 > a.reference
Documentation using Furo theme li.toctree-l1 > ul > li.toctree-l2 > a.reference
Books produced using Sphinx li.toctree-l1 > ul > li.toctree-l2 > a.reference
Theses produced using Sphinx li.toctree-l1 > ul > li.toctree-l2 > a.reference

These items highlight common accessibility best practices.

○Interactive controls are keyboard focusable
○Interactive elements indicate their purpose and state
○The page has a logical tab order
○Visual order on the page follows DOM order
○User focus is not accidentally trapped in a region
○The user's focus is directed to new content added to the page
○HTML5 landmark elements are used to improve navigation
○Offscreen content is hidden from assistive technology
○Custom controls have associated labels
○Custom controls have ARIA roles
●`[aria-*]` attributes match their roles
●`[aria-hidden="true"]` is not present on the document `<body>`
●`[role]` values are valid
●`[aria-*]` attributes have valid values
●`[aria-*]` attributes are valid and not misspelled
●Image elements have `[alt]` attributes
●`[user-scalable="no"]` is not used in the `<meta name="viewport">` element and the `[maximum-scale]` attribute is not less than 5.
●ARIA attributes are used as specified for the element's role
●`[aria-hidden="true"]` elements do not contain focusable descendents
●Elements use only permitted ARIA attributes
●Background and foreground colors have a sufficient contrast ratio
●Document has a `<title>` element
●`<html>` element has a `[lang]` attribute
●`<html>` element has a valid value for its `[lang]` attribute
●Links are distinguishable without relying on color.
●Links have a discernible name
●Lists contain only `<li>` elements and script supporting elements (`<script>` and `<template>`).
●List items (`<li>`) are contained within `<ul>`, `<ol>` or `<menu>` parent elements
●Heading elements appear in a sequentially-descending order
●Document has a main landmark.
●Deprecated ARIA roles were not used
●Identical links have the same purpose.
○`[accesskey]` values are unique
○`button`, `link`, and `menuitem` elements have accessible names
○Elements with `role="dialog"` or `role="alertdialog"` have accessible names.
○ARIA input fields have accessible names
○ARIA `meter` elements have accessible names
○ARIA `progressbar` elements have accessible names
○Elements with an ARIA `[role]` that require children to contain a specific `[role]` have all required children.
○`[role]`s are contained by their required parent element
○Elements with the `role=text` attribute do not have focusable descendents.
○ARIA toggle fields have accessible names
○ARIA `tooltip` elements have accessible names
○ARIA `treeitem` elements have accessible names
○Buttons have an accessible name
○The page contains a heading, skip link, or landmark region
○`<dl>`'s contain only properly-ordered `<dt>` and `<dd>` groups, `<script>`, `<template>` or `<div>` elements.
○Definition list items are wrapped in `<dl>` elements
○ARIA IDs are unique
○No form fields have multiple labels
○`<frame>` or `<iframe>` elements have a title
○`<html>` element has an `[xml:lang]` attribute with the same base language as the `[lang]` attribute.
○Input buttons have discernible text.
○`<input type="image">` elements have `[alt]` text
○Form elements have associated labels
○The document does not use `<meta http-equiv="refresh">`
○`<object>` elements have alternate text
○Select elements have associated label elements.
○Skip links are focusable.
○No element has a `[tabindex]` value greater than 0
○Cells in a `<table>` element that use the `[headers]` attribute refer to table cells within the same table.
○`<th>` elements and elements with `[role="columnheader"/"rowheader"]` have data cells they describe.
○`[lang]` attributes have a valid value
○`<video>` elements contain a `<track>` element with `[kind="captions"]`
○Tables have different content in the summary attribute and `<caption>`.
○All heading elements contain content.
○Uses ARIA roles only on compatible elements
○Image elements do not have `[alt]` attributes that are redundant text.
○Elements with visible text labels have matching accessible names.
○Tables use `<caption>` instead of cells with the `[colspan]` attribute to indicate a caption.
○`<td>` elements in a large `<table>` have one or more table headers.
All checks on this page are automated. Results are estimates - run targeted manual reviews when the score affects a release decision.

Send Feedback