Balisage Paper: Experiences from declarative markup to improve the accessibility of HTML

Accessibility standards

Currently, information on how to develop accessible websites and application and author accessible content is spread across various W3C recommendations and their related support documents. The Web Content Accessibility Guidelines (WCAG) 2.1 wcag21 are the basis of such documentation, as they settle the four main principles which lay the foundations for anyone to access and use Web content. Accessible Web means content that is:

other than the four accessibility foundational principles, WCAG 2.1 provides guidelines, i.e. abstract rules to follow in order to produce content respecting such principles. For each guideline, so called "success criteria" are provided, i.e. practically testable statements to check wether content conforms to it or not. This is clearly explained in "Understanding WCAG 2.1" understandingwcag21, an informative (thus non-normative) document produced by the Accessibility Working Group at W3C providing any additional information on how to interpret the WCAG recommendation.

Information on how to comply with such guidelines when using specific technologies, along with practical examples of how to do that, are illustrated in Techniques for WCAG 2.1" wcag21techniques, another informative document being constantly updated over time by the same group at W3C.

While such documents and attributes available in HTML where enough to make websites accessible, the advent of AJAX and complex desktop-like web applications introduced many new challenges for web accessibility. The WAI-ARIa specification aria11, now at version 1.1, was born to address such challenges, especially in case of dynamic content and advanced user interface controls. To support developers implementing this specification in their projects, the WAI-ARIA authoring practices aria11authoringpractices is provided, a W3C working group note that explains how to make the most commonly used design patterns accessible leveraging this specification and providing code examples to implement them.

A W3C recommendation on how WAI-ARIA support should be implemented by user agents is available, but it currently refers to version 1.0 of the WAI-ARIA specification; its equivalent for the latest version is still in draft aria11implementation. A more in depth discussion on how user agents should be made accessible, and what information assistive technologies could expect to be exposed through native platform accessibility APIs, is available in User Agent Accessibility Guidelines (UAAG) 2.0 uaag20, published as a W3C working group note.

Finally, another W3C recommendation has been specifically crafted with regards to authoring tools accessibility, i.e. any tool that allow to produce, edit or manipulate in any way content, including automatic conversions. Authoring Tools Accessibility Guidelines (ATAG) 2.0 atag20. This recommendation is divided in two parts: in part A principles, guidelines and testable success criteria are provided to ensure that such tools can be used by people with disabilities; in part B, the same is done with regards to the ability of such tools to allow and encourage end users, not limiting to those with disabilities, to produce content that is accessible and, in any case, to not deteriorate its accessibility during automatic processes (i.e. format conversions). Guidance on how to meet such guidelines, perform conformance testing and in dept practical examples are provided in a separate document implementingatag20.

Declarative frameworks and the Web

Implementing a declarative framework on top of web technologies to make their use more effective and efficient is not new, as other examples have been already proposed in the literature over time. Hanus and Koschnicke erdeclarativewebprogramming, for example, describe a declarative framework to support the implementation of web-based systems to manipulate data stored in relational databases. Li et all echarts proposed ECharts, an open-source, web-based, cross-platform framework that supports the rapid construction of interactive visualization and is regarded as a leading visualization development tool.

The more general topic of improving web application development by leveraging declarative languages has also been discussed in the literature. In applicationembedding, Wild presents Application Embedding, a novel approach to application development which allows all aspects of a web application, including its business-logic, to be programmed declaratively. Lorenz & Rosenan declarativeweb20 argue that the contextual nature of Web 2.0 content needs a better representation, and that the same can also be used to better describe the rich interfaces for applications building on that contextual content, identifying in a declarative way of representing Web 2.0 data such representation.

While the usage of a declarative framework to improve both specific and general aspects of web programming has already been adopted in the past with various success degrees, it is legitimate to wonder why a declarative framework is necessary in the specific case of web accessibility. True, WCAG 2.1 wcag21 settle principles and guidelines that content should conform to in order to be considered accessible, as well as practically testable success criteria to assess its conformance to the standard according to determined levels (A, AA and AAA), and documents such as wcag21techniques provide practical examples and detailed resources on how to create such content leveraging specific technologies. Yet, web authors still have a hard time understanding and applying accessibility guidelines, as they are considered too technical, and not supporting adequately problem identification and solving personasaccessibilitytesting. This can be mitigated by providing better support for markup that is "accessible by default", i.e. without any specific intervention by the developer, and creating more advanced testing tools that do not require having previous competencies about web accessibility in order to detect issues and understand how to fix them.

Regarding the generation of accessible markup, HTML 5 can be considered a step in the right direction. This version (and the following ones) added to the language many features commonly used in web applications that, not being available in a standardized implementation, had to be implemented leveraging external solutions (think of audio and video playback) with a varying degree of accessibility. However, many commonly used interactive widgets have not natively become part of HTML and still require markup and code that may or may not be accessible. Other language features have been included in later versions, but are not supported properly by browsers and/or assistive technologies: for instance, according to the standard, autocomplete fields should be populated by a datalist element; yet, when using it, there is no indication that the field it is associated with supports autocompletion, and it looks exactly like a regular text field, so that screen readers treat the field exactly as a plain textbox.

Another commonly used widget that is often the source of subtle accessibility problems is the modal dialog, which, according to HTML 5, should be implemented by element dialog; however, many browsers still do not support this element at all (e.g., Apple Safari), others require its support to be enabled explicitly in their advanced preferences (e.g., Mozilla Firefox), and others implement it natively but with critical accessibility issues. Finally, many controls commonly used by web applications (for instance, tabs and associated tab panels, menu bars, toolbars, trees, to name a few) have still to find a good and agreed upon markup representation in HTML to build good accessibility support upon. In addition to this, even in the best possible scenario, no guarantee is made about whether all these widgets will be implemented consistently across browsers, or that styling them will be supported in the same way.

Due to this, many controls required by complex web applications have to be implemented by leveraging generic HTML tags enhanced with JavaScript code. Such elements can be made accessible by using the WAI-ARIA specification aria11, which allows to enrich the semantics of HTML elements by adding markup (e.g., specific attributes, and in particular the role attribute) that defines the semantics of the element in terms of accessibility. However, in this scenario the developer is responsible for manually implementing the exact behavior expected by assistive technology users for each element: marking an element as having a certain ARIA role is a promise, but the developer is responsible for fulfilling it: differently than HTML elements, ARIA roles do not directly cause browsers to provide keyboard behaviours or styling aria11authoringpractices.

Accessibility testing tools

With regards to accessibility testing, there is no automated tool that can compete with a human in terms of quality and depth of the analysis. Unfortunately, manual accessibility testing is a costly process in time and money, and requires specific and non-trivial competence. Thus, most projects in the real world are unwilling or stingy in spending about this. in truth, many automated tools have been proposed over time to facilitate web developers and content authors in identifying accessibility issues and determining appropriate fixes for them. Such tools come in different forms, and often the same tool is provided in different flavours to suit specific needs in different web development workflows. While they serve the exact same purpose, of course each tool can have characteristics and features that differentiates it from its competitors.

Automated accessibility testing tools are available as web services, both free to use achecker and commercial tenon.io, that allow checking a page for accessibility issues by url or by requiring its source code to be uploaded directly; some even support crawling an entire website starting from a certain page, so as to generate a single report for all accessibility issues contained in a whole site or subsite. Other tools (lighthouse, wave) are available as browser extensions, and allow to quickly test the page currently viewed in the browser for accessibility issues, sometimes highlighting where the errors generate and suggesting solutions for fixing them. More recently, automated testing tools have been made available as frameworks to support test driven development and command line tools axe exist for development workflows in which continuous integration (and therefore automated testing) play a critical role.

Finally, there is another critical aspect to consider when evaluating available automated accessibility testing tools. Thanks to JavaScript, more and more web pages are nowadays built and/or updated dynamically client-side, causing the runtime Document Object Model (DOM) to be vastly different from the one found in the static source code. Therefore, it is critical for automated accessibility testing tools to be able to work with the actual DOM of the page, and not just the original source code, as otherwise it would potentially miss many accessibility issues.

Declarative markup to the rescue.

According to the original authoritative sources on the topic (sgml),

A declarative style of markup in web design is therefore the specification of permanent logical, structural and semantic characteristics of all parts and fragments of a web page or application, rather than of their transient and task-specific characteristics such as presentation, in-browser behavior, etc. In our vision, this is exactly what is needed to help assistive tools make web pages and applications accessible and usable by people with disabilities: designers and authors are not expected to provide special services, but just to describe the content and features of the page/application in a sufficiently precise way to allow (existing) assistive technologies to perform their job in the right way and at the right time.

As such, scholars of declarative markup styles learned in the ways of SGML and XML would immediately see the problem and the way to address the problem. They are the standard ways to use markup in this world:

Our proposal therefore is threefold:

In order to facilitate their adoption, our tools are designed to be used even without our declarative framework. The automated testing integration provided by the declarative framework enables a developer to test even parts of a web page that are not generated by the framework itself, and our manual accessibility visualizer, Saharian, is useable on any website, without any specific additional requirement other than installing the tool itself.

A framework for sighted developers

The implementation of a declarative framework of accessible web components as required by our approach is a challenging process, and providing a full featured solution is likely to require more iterations over time as well as gathering feedback from the community and acting consequently. The necessity of creating a highly extensible and maintainable solution naturally arises from these simple considerations. We also believe that good documentation is key to the success of such a framework, therefore significant efforts are being dedicated to documenting its components (the public API) as well as its internals, in order to provide web developers and content authors all they need to use it at the maximum of its potential.

By definition, the framework should enforce the generation of accessible markup as much as possible. The nature of a declarative solution helps with this, as the correctness of hierarchical relationships (i.e. prevent using an input of type "radio" outside of a fieldset) can be easily enforced as required in order to generate accessible markup. Not only that, but specifying required parameters when instantiating components (take the case of form control labels as an example) can be enforced as well. When such conditions are not met, the framework should not render the offending component or make it de-facto unusable, rendering the error in an appropriate way and providing instructions on how to fix it instead.

Our idea is based on the extension of the markup language through the use of components. Introduced and shamelessly promoted by all three of the major web development libraries currently in favour (Angular, React and Vue, and recently even standardized by W3C ), components are small, autonomous modules containing markup, styling and executable code that can be aggregated and composed to build full web applications with reliable and sophisticated functionalities. The HTML language is therefore replaced by an open set of elements each of which is mapped onto a complete component providing for its deployment, including the markup to make it presented on screen. A framework can then become responsible for ensuring the accessibility of the generated markup, and determining the most suitable HTML markup representation of the many that are possible, shifting this burden away from the developers. By doing so, it also shifts away from the developer the responsibility of looking at guidelines and techniques for implementing that component in a way that is accessible, and most of the effort to determine which solution is the most appropriate to each case.

In contrast to the scenarios described above, consider instantiating the input field to become be as simple as writing:

<textfield label="Name:">

This is clearly not an HTML tag, but a markup placeholder for a textfield component handled by our framework. Upon rendering the page on the browser, or through a compilation process, the above markup is automatically converted into a combination of markup, styling and code, whose markup contribution automatically includes accessibility specifications (chosen from any of the above-mentioned approaches): the developer is not faced with the task of studying and choosing solutions, yet the final result is perfectly accessible for disabled users.

As is often the case for newly introduced frameworks, it is very important for our solution to be able to coexist with parts of a web page that do not use it. This would allow developers and content authors to gradually adopt the framework, as well as letting consumers use it since its early development phases, even if it does not include every component they need. We argue that this could significantly increase its adoption rate since the early stages, and allow us to gather feedback even in the earliest development stages. For the same reason, we need to be compatible with older browsers even if adopting the latest and greatest modern web development practices and language features; in this context, however, supported browsers need to be determined by keeping into account the degree of support offered for the essential accessibility features leveraged by the generated markup.

Another important point to note is that our framework is not meant as a replacement for very well established Javascript libraries designed to facilitate web application development, like JQuery, Angular, React or Vue, to name a few. Instead, we want to design it to be low-level enough to be used in combination with such libraries.

One might argue that in such a situation a developer could easily mess up with the framework internals, thus vanishing the original efforts in guaranteeing the accessibility of its generated markup. In order to minimize this risk, UI state management (operations such as enabling a checkbox) is built-in into the framework, so that a developer does not need to manually change and/or alter the markup generated by the framework. Rather, the ability to provide callbacks for being notified and act upon significant events is provided at the framework level, so as to minimize unwanted side effects caused by their custom implementation. Whenever necessary to guarantee the accessibility of a certain component, handling of significant events (for example support of specific keyboard shortcuts) is built-in into those components.

Finally, in order to provide the accessible equivalent of a majority of components whose use is nowadays widespread in web development, a strong, possibly controversial principle has been adopted: making an opinionated decision is better than not making a decision at all. Application of this principle should be restricted to the minimum, so that the framework does not condition unduly the developer, yet its adoption is critical in order to provide working components even in situations in which multiple solutions may be acceptable but would need a conscious implementation strategy. For instance, there are many different ways to implement accessible date pickers in HTML, each of which would require a different markup approach. We are choosing just ONE of such approaches to the detriment of all others that may have been preferred by some developers.

The Saharian browser's extension

Even if there is some margin for possible improvements of automated accessibility testing, checking a page manually for accessibility issues is nowadays required. We believe that tools to help developers perceive accessible issues as they arise should be provided, so as to let them perceive their impact on people with disabilities. While negative effects of accessibility issues are often documented, in fact, we believe that mapping their effects to concepts that developers and content authors are more familiar with could make them more perceivable, thus help users recognize their gravity. It's our intention to develop a set of tools to implement this philosophy, the main of which is "Saharian".

Figure 1: The main interface of Saharian

The main interface of Saharian, allowing to activate, deactivate and switch between document and application modes.

Saharian is a browser extension (currently working on Chrome and Firefox) aimed at letting developers perceive the effects of ARIA annotations (roles, states and properties) used to enrich a certain web page, but in an innovative way. Unlike existing solutions (e.g. visualaria), Saharian does not limit its features to visualizing aria annotations and offering recommendations to implement the correct behaviours to support them in JavaScript, but rather uses the existing annotations and their supporting behaviours as implemented by the author to create a visual and alternative representation of the generated page.

For example, things like incomplete or inappropriate ARIA annotations will result in inappropriate visualizations of the corresponding elements; incorrect keyboard support will be translated into incorrect behaviours of those elements for mouse users (for instance, if an element cannot be focused or activated via the keyboard, the user won't be able to focus or activate it by using the mouse), etc.. Saharian is the first in a series of tools that will be developed over time to complement our approach.

Figure 2: The usual visual display of a web page

A normal web page, as it is shown visually by a browser.

SAHARIAN (which stands for "Sighted Architect's Helper for ARIA Notation") performs the above-mentioned purpose by

Figure 3: The Saharian visual rendering of the same web page

The same web page, shown on the same browser, with visual styles replaced by Saharian.

As a result, the sighted developer is still able to interact and check visually with all the features of the application or content being developed. Yet, these interactions and visual checks are done on a page that is on purpose limited to only the visual styles and the behaviors that are allowed by the ARIA markup, and is as usable and comprehensible visually by the developer as much as it is usable and comprehensible in a non-visual way by a blind user.

In this perspective, a sighted developer can easily and rapidly verify the impact on the accessibility of the page of a well thought out design choice or a rushed last minute edit: by activating the SAHARIAN tool, developers are forced to rely only on the ARIA notation to make sense of the page and interact with its items, and, even if sighted, they will be able to carry out tests and activities on the page only if the ARIA notation is correct and adequate.

Testing tools

Testing the end result of the design process is always a complicated process, and, as we know, there is never a last bug. Some considerations need to be made regarding the testing tools that are part of our proposal so as to illustrate the significant role they play in our vison.

Testing in our approach is not performed through an homemade tool, but by extending and customizing existing ones. We believe reinventing the wheel is not a good idea, especially when dealing with complex topics such as web accessibility testing: if valuable and open-source solutions exist, it is better to base our work on them instead of building everything from scratch.

For this reason we make use of axe-core axecore, a rule-based automated accessibility testing engine. The fact that Axe is rule-based makes it easily extensible, as the only requirement for implementing new automated accessibility tests is to implement a few new rules, and flexible, as we can decide which tests should be run at any given time and how results should be presented. In addition, this tool is highly popular in the accessibility community, the company behind its development is authoritative and reliable and many professional solutions by tech giants like Google and Microsoft rely on it.

Let's consider a simple example. WCAG 2.1 states that a color contrast of at least 4.5:1 for small text or 3:1 for large text is appropriate, even when the text is part of an image, to ensure it is readable by users with low vision or color blindness (success criterion 1.4.3). Enforcing conformance to this rule within the framework, i.e. during the generation of the markup, would be easy, yet pointless: many factors will affect the color scheme of an element, including the loading of external resources (e.g., images), conditional styling, and even browser defaults. The perfect time to perform such checks is therefore not statically on the markup, but at runtime, after the page is loaded in the browser, all CSS styling has been applied and all external resources have been fully loaded. Static testing of the markup in the fully dynamic world of modern web design is basically futile.

The Axe library already provides this rule and many others out of the box, but it is the runtime of our framework that is responsible for running it at the most appropriate moment within the page/app lifecycle (e.g., after the loading process is completed, after new content is inserted, or existing content is deleted, or replaced, etc) and translate its results in a form suitable for our examination. In particular, the default test results from Axe include a selector pointing to the DOM element that failed it, but do not highlight it in any way: it is the responsibility of our framework to parse these results and show the violations reported using the same mode and styles of accessibility issues ascertained statically in the markup generation phase (e.g., highlighting the visual rendering of the component to facilitate the developer understanding the issue and how to act upon it). This offers a consistent experience for the developers, and maximizes the usability of our design tools.

Another important concern for our testing tools is the so called "zero-false-positives principle": if something is reported as an accessibility issue, it must be an accessibility issue. There are times when something that looks like an accessibility issue (for instance, an image with an empty alt text) is not actually an accessibility issue (the image is decorative), thus automated testing in this regard may bring uncertainty on the table. In order to be reliable and trusted by designers, our tools should never report false positives. While automated testing on a bare HTML page is not able to discriminate such situations, our framework is in a good position to do so: in a truly "declarative fashion", decorative and content images are represented by different components, in order to have all the information necessary to disambiguate the situation at runtime. The img element is a good example of an HTML tag that is overloaded with many possible semantics, an evidence that the cooperation between a declarative framework and an automated runtime testing tool makes the overall result more reliable and less prone to ambiguity.

Eventually, whenever an accessibility error is detected (regardless of whether it was done by the components of the declarative framework during the markup generation phase, the automated testing tool or the manual accessibility visualizer), it should be reported prominently to the designer; the final goal of our system is to make it impossible for clear accessibility issues to end up unnoticed.

Finally, there is another aspect about accessibility testing tools that is worth discussing. More often than not, such tools report the line number of the source code that contain the error. We believe this is not the most effective representation to let non-disabled people perceive the impact of accessibility issues on people with disabilities; not only the source for runtime problems may be the result of several independent and apparently harmless bits of code spread in the HTML, CSS, Javascript and any of the various libraries being imported: the real need for a sighted designer is being informed of the impact on disabled users that the problem is causing in a manner that make these issues easier to grasp (such as the visual appearance of the page) without looking up additional documentation or external resources. This is the reason why components provided by our framework are designed so as to "visualize" accessibility issues to sighted developers: whenever a code fragment causes an accessibility issue, its visual rendering is altered to let the developer know what the issue is about and perceive its impact on people with disabilities. Once again, this is possible thanks to the abstraction provided by leveraging declarative markup to let the developer describe his/her intentions semantically.