Quarto
Ensure Quarto Meets WCAG 2.1 AA Standards #12644
Replies: 3 comments 12 replies
|
@IULibScholComm Thanks. FYI, your screenshots do not have alternative text. For reference: |
|
Thank you; they have alt-text now--and sorry; this was posted hastily. |
|
It's in our roadmap for 2025, and you should start to see improvements in 1.8. One thing we want to communicate very clearly to everyone interested in this subject is that there are a large numbers of slightly different accessibility checkers available online, and we will not be able to promise support for every one of those. With that said, we are almost certain that our accessibility standards will be to aim for full (or as close to as we can make) compliance with axe-core checks. |
|
In the pre-release versions, add this to your document: You will get a visual indicator at the bottom-right of your document with the resulting diagnostics. We're working on GitHub Actions support for testing a whole project against it in CI. Stay tuned. |
|
Amazing, I'll be making use of this!! Thank you! |
|
In Quarto version 1.8.11, |
|
@IULibScholComm I had a typo and fixed it, sorry. |
|
Thank you! This is great, btw--very helpful. |
|
Hello, I would like to add a more thorough accessibility review. Quarto version: 1.8.25 Tools used: NVDA, Chrome, WAVE, CCA, HTML Validator, Lighthouse. Methodology: Conduct visual checks, run web accessibility validation tools and validate with the following screen reader/browser combination: JAWS22 and NVDA 2022, Edge, Chrome and Firefox, and the following tools: CSS HTML Validator and Colour Contrast Analyzer. WCAG 2.1 findingsAdjacent links point to the same destinationDescription: The logo link and heading text link are right next to each other, and both navigate to the home page. Two adjacent links should not point to the same destination. Adjacent links that point to the same destination (for example, a separate image link and text link to the same URL) create redundant focus stops and duplicate announcements for assistive technologies. Screen reader users hear the same destination twice, and link lists become cluttered with duplicates, slowing navigation and increasing cognitive load. The Home page does not tell you are at the home page. Resolution: Combining the image and text into a single link provides one clear, accessible target with a single name, improves keyboard efficiency, and simplifies the DOM structure. Add 'Home page' to the page title follow by a dash e.g.: Home - WCAG 2.1 Reference: Focus orderDescription: If a Web page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability. The tab order is not sequential; it jumps from the Page title to the search, skipping the language switcher. Left navigation skips the Section title link - When tabbing via keyboard, the "Section title" is not tab-able to (including the pages contained within). If the section is "expanded" then it is tab-able, but not when it's in its default state. • When users increase browser zoom, the content within the header (primary navigation menu) reflows and becomes stacked vertically. However, the keyboard focus order does not follow the same order in which the content is visually presented on the page. When focus order does not align with the visual layout, users may become disoriented, miss content, or have difficulty understanding the structure of the navigation. Resolution: When the user hits the tab button, the links/clickable items should be highlighted in the same order as what is seen on the page (Language toggle, gitlab, dark mode switch, search button). Section titles in the sidebar menu section elements must be keyboard accessible. Focus visibleDescription: Resolution: WCAG 2.1 Reference: Headings and LabelsDescription: Resolution: WCAG 2.1 Reference: Info and relationshipsDescription: Every section (nested sub-headings) needs to have a Resolution: Ensure sub headings are wrapped by WCAG 2.1 Reference: Meaningful sequenceDescription: “On this page” table of contents section appears before the Main content. We want to make sure it appears on the aside component, and it is not part of the main content. If it is part of the main content, then it should appear after the H1. Resolution: By default, assign table of contents as part of the main content. WCAG 2.1 Reference: Use of colourDescription: The colour used for active links does not differentiate from the regular links. Resolution: Apply a different colour for active links to differentiate them from all other links state. In the left navigation sidebar, the page that we are currently on is highlighted. "About" is highlighted / differently coloured because we are on the "About" page. A screen reader cannot currently determine this same information, so the most straightforward way to fix this is to add screen reader only text as part of the sidebar content that says something along the lines of "Currently selected page: ". WCAG: 2.1 Reference: Dropdown control identified as a linkDescription: The dropdown control is implemented as a link and has role=”link”, causing assistive technologies to identify and announce the control as a link rather than as a button that performs an action. Links and buttons have different expected roles, behaviors, and keyboard interaction patterns, and when controls are assigned incorrect roles or lack appropriate semantics, their purpose and behavior cannot be reliably determined by assistive technologies. Resolution: Ensure that all interactive elements use the correct semantic role that matches their function. Controls that perform actions or change page state, such as dropdown triggers, must be implemented as native elements, or assigned role="button" when a native button cannot be used. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Search panel – Submit buttonDescription: Resolution: WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Search panel – Headings and LabelsDescription: The Search results modal does not have an Resolution: Add heading structure to the search results WCAG 2.1 Reference: Search panel – Multiple focus pointsDescription: When users type in the search field, autocomplete results appear and the first result receives keyboard focus while the search input also remains focused. Users can continue typing while focus is simultaneously placed on a result, and arrow keys move through the results list. This creates multiple active focus points, causing assistive technologies to announce focus on a result the user did not navigate to each time they type a letter, making it unclear that typing can continue and potentially disorienting keyboard and screen reader users. Note: Latest version of Quarto has search modal inaccessible by screen reader – screen reader does not read elements on search modal and reads content from the page in the background. Tested on Quarto website 
Resolution: Ensure that only one element can receive keyboard focus at a time. While users are typing, focus must remain on the search input, and results must not receive focus until the user explicitly navigates the list. Announce the number of available results to screen reader users without moving focus. Ensure screen reader is also focused on search panel results. Refer to ✎ Technique: Autocomplete input controls | Digital Accessibility Services for a good example. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Search panel – No visible focus indicatorDescription: When tabbing through the documents in the search results list, the visible focus indicator does not move with keyboard focus. The dark green focus indicator remains on the first result while keyboard focus moves to other options. Keyboard users may be unable to determine which search result currently has focus. Resolution: Ensure the visible focus indicator follows keyboard focus as users navigate through the search results with the tab key. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Search panel – Close panel focus managementDescription: When a keyboard user closes the search panel overlay by selecting the Cancel button or pressing the Esc key, keyboard focus moves to the top of the page instead of returning to the control that opened the overlay. Resolution: Ensure that when the search panel overlay is dismissed, keyboard focus is returned to the button that originally opened it. Returning focus to the triggering control helps users maintain their place in the interface and continue interacting with the page without unnecessary navigation. Visual check/Tools used: Chrome + NVDA; Visual Check Background content remains accessible when an overlay is openDescription: When the Search panel is opened, it visually overlays and blocks access to the rest of the page. However, keyboard and screen reader users can still navigate to and interact with content behind the panel. Resolution: When an overlay, modal, or expanded side panel is displayed, restrict keyboard focus and screen reader navigation to the active panel until it is closed. Content outside the active panel should be hidden from assistive technologies and removed from the keyboard navigation sequence. Once the panel is closed, focus should be returned to the control that opened it. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Back to top button not keyboard accessibleDescription: The page includes a “Back to top” button that is visually present but not included in the sequential keyboard focus order. Although it can be accessed using screen reader shortcut keys, it is not operable through standard keyboard navigation. As a result, keyboard only users may be unable to discover or activate the “Back to top” button. Resolution: Ensure that the “Back to top” button is included in the sequential keyboard focus order so it can be reached using standard Tab navigation. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Duplicate anchor links - purpose is unclearDescription: Several headings contain an anchor link that is identified only as "anchor link". The purpose of the link itself is unclear, as selecting it just brings users to the heading text right next to it. Users of assistive technologies may be unable to determine what activating the link will do, particularly when navigating through links on the page, where numerous identical links are presented. Resolution: Provide a descriptive accessible name that clearly identifies the purpose of each anchor link and the section with which it is associated. If the anchor links serve no meaningful purpose for users, consider removing them. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Checkbox symbols not identifiedDescription: The output for the checkbox symbol varies across assistive technologies. JAWS announces the symbols as "ballot box" and "ballot box with X", while NVDA may not announce the symbols at all or identify them only by their Unicode character reference ("Symbol 2610" and "Symbol 2612"). Resolution: Ensure the checked and unchecked symbols are identified consistently and meaningfully by screen readers and other assistive technologies. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Keyboard trapDescription: In some cases, activating the Close button with the keyboard or pressing the Esc key does not close the lightbox overlay. Instead, the button visually disappears, and users are blocked from exiting the overlay and returning to the underlying page content. Keyboard users become trapped within the overlay and must refresh the page to continue. Resolution: Ensure the lightbox can always be dismissed using the Close button and the Esc key. Users should never become trapped within the overlay and must always have a reliable keyboard-accessible method to return to the page. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Lightbox - Close button focus managementDescription: When a keyboard user closes the lightbox overlay using the Close button or the Esc key, keyboard focus moves to the top of the page instead of returning to the control that originally opened the overlay. Users may lose their place on the page and must navigate back to their previous location to continue their task. Resolution: When the lightbox is closed, ensure the keyboard focus is back on the control that opened the overlay. This helps users maintain their place within the page and continue interacting with content without unnecessary navigation. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Lightbox – Close button labelDescription: When keyboard focus moves to the Close button in the lightbox overlay, screen readers announce "Close button previous button next button" instead of identifying only the Close button. This may make it difficult for users to understand which control currently has focus and what action will be performed when the control is activated. Resolution: Ensure the Close button has a clear and accurate accessible name that identifies only the Close button. Information about other controls should not be included in the button's accessible name unless it is required for understanding the button's purpose. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Visible label not included in accessible nameDescription: The visible heading for the expandable section is "Tip". However, the programmatic name of the control is "Toggle callout". Because the visible label is not included in the button's accessible name, users of assistive technologies may have difficulty determining which section the button controls. This may also create challenges for speech recognition users who may attempt to activate the control using the visible label. Resolution: Ensure that the words which visually label a component are also the words associated with the component programmatically. This helps ensure that people with disabilities can rely on visible labels to interact with the components. For example, a speech recognition user saying, "Click Submit", works only if the visible label and the programmatic name are both “Submit”. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA, IBM Equal Access Accessibility Checker Links open in a new tab without warningDescription: Several links open in a new browser window or tab without informing users beforehand. Individuals who are blind or have low vision may have difficulty knowing when a visual context change has occurred, such as a new window popping up. In this case, warning users of context changes in advance minimizes confusion when the user discovers that the back button no longer behaves as expected. Resolution: Review all links on the page and ensure that links that open in a new browser window or tab provide a notification that is available to screen reader users. WCAG 2.1 Reference: Visual check/Tools used: Chrome + NVDA; Visual Check Sidebar navigationDescription: Subsections are not keyboard accessible unless they have an href. Resolution: Ensure collapsible section titles can be reached by keyboard and collapsible state is togglable. Visual check/Tools used: Visual Check Inconsistent functionsDescription: The sidebar navigation subsections with href have the “button” role, but they behave like links when activated, which causes a mismatch between semantics and functionality. Other buttons are announced by screen readers as “XXX button expanded/ collapse” and correctly function to expand or collapse the toggle menu. Resolution: Ensure buttons with the same functionality are marked up consistently. WCAG 2.1 Reference: Visual check/Tools used: Edge + NVDA; Visual Check |
|
@DennisH3 Thanks, but please do so with the latest release (1.10.18) or even the pre-release/dev version. Additionally, you could review the already opened issues about accessibility: Nota that it's not really possible for Quarto to fulfil all tools that exist and flag accessibility elements, especially when those cannot be checked without manual inspection. Finally, a bit of irony: Important Accessibility: To improve accessibility, please add alternative text to your screenshots. This helps all users, including those using screen readers, to understand the context of the images. A brief description can make a big difference! See Good Alt Text, Bad Alt Text — Making Your Content Perceivable. |
|
@mcanouil Thanks for the quick reply! For additional context, the website is published on an internal GitLab instance. I will try to provide a public minimal reprex for the repository to highlight these issues. Some of these issues can be directly found on the official Quarto website . I will also update to the latest Quarto version 🙂 and update the comment for all addressed issues. I have reviewed the changelogs of more recent Quarto versions and the open GitHub issues before posting. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Description
May Quarto be brought into conformance with WCAG 2.1 AA accessibility standards by April 2026, given last year's update to Title II of the Americans with Disabilities Act (ADA)? Otherwise, my institution (Indiana University) will no longer be able to publish with Quarto.
For instance, in HTML Books:
These issues were found using SiteImprove.
All reactions