Skip to main content

Making docassemble interviews accessible

Web accessibility means designing websites and tools (like docassemble interviews) so that people with disabilities can use them. Web accessibility also benefits everyone by making websites more usable across a range of situations.

Making docassemble interviews accessible involves structuring interviews for people who use keyboard controls and screen readers, which docassemble handles by default. To the extent the AssemblyLine software adds features (such as AL object classes), they are also built to be accessible by default.

Interview builders must address accessibility, too, so the Document Assembly Line has powerful accessibility tools, a style guide for writing questions, and user interface guidelines. These address readability and UI choices that improve interview accessibility overall. (Translation can also be considered part of web accessibility, and AssemblyLine also adds helpful translation tools.)

AssemblyLine accessibility tools​

The Document Assembly Line provides multiple automated tools to check accessibility during development and continuous integration:

  • DAYamlChecker: A command-line static analysis tool that checks Docassemble YAML interviews, Python code, and DOCX templates for WCAG violations, skipped headings, missing alt text, non-descriptive links, unlabelled fields, low contrast in custom themes, and template accessibility issues.
  • ALActions da_build: Runs dayamlchecker over interview YAML and Word templates on every pull request, and audits PDF templates against PDF/UA-1 with veraPDF.
  • ALDashboard & ALWeaver: The built-in interview style check (lint) in the ALDashboard provides in-browser linting for interview authors.

ALDashboard icon for the code linter. The text reads "Interview style check (lint)"

Automated accessibility checks include:

  • Web Content Accessibility Guidelines (WCAG 2.1/2.2) clear static failures
  • DOCX and PDF template accessibility (veraPDF PDF/UA-1 checks and DOCX accessibility rules)
  • DAL style guide and plain language issues
  • Low color contrast in custom themes
  • Skipped heading levels
  • Empty links and non-descriptive link text
  • Missing alt text on images ([FILE ...], Markdown, and HTML <img>)
  • Missing field labels on multi-field screens
  • Combobox usage detection
  • Translatability & sentence fragmentation

General tips for improving interview accessibility​

Use strongly contrasting colors​

When customizing the look and feel of your interviews, make sure the colors you choose for text and background have high contrast. This is important to both low-vision and sighted users. WCAG 2 defines the minimum color contrast between an element and it's background as 4.5:1. For larger text like headings, the minimum is 3:1.

Check for proper contrast with these tools:

Use alt-text with images​

To describe images, screen readers read out descriptions called alternative text, or alt-text. Without alt-text, people using a screen reader won't get any of the benefits of the graphic. The W3 WAI group has a good decision tree on how to write alt-text.

To describe an image in docassemble, set the alt_text attribute of a DAFile, or use the set_alt_text() function. If you are writing HTML directly, add an alt property to all img tags:

<img src="my_image.png" alt="A drawing of a flowchart: the question is 'do you have any children?', the option 'yes' leads to 'scenario 1', and the option 'no' leads to 'scenario 2'."/>
tip

Don't forget to add alt-text to your organization's logo. It can be a simple description like "Organization A's logo", but it should be present.

Don't skip heading levels​

Headings provide semantic structure to web pages and help screen readers navigate. When using headings, increment one level at a time. Don't skip from h2 to h4.

Screen readers have special features that let users navigate between different headings in order to navigate quickly, and skipped heading levels can disorient users.

Like this:

<!-- Markdown -->
## Heading 2
### Heading 3
### Heading 3
## Heading 2
<!-- HTML -->
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h3>Heading 3</h3>
<h2>Heading 2</h2>

Not like this:

<!-- Markdown -->
## Heading 2
#### Heading 4
#### Heading 4
## Heading 2
<!-- HTML -->
<h2>Heading 2</h2>
<h4>Heading 4</h4>
<h4>Heading 4</h4>
<h2>Heading 2</h2>

Don't use h1​

There should only be one h1 heading on a page. In docassemble, that will be the question attribute. Don't use a single # Markdown heading or an <h1> HTML tag in a subquestion or note.

How to change heading sizes​

You might notice that the question heading in docassemble looks smaller than headings in the subquestion. This is because docassemble manually styles the question to look like an h3 heading even though it is really an h1 heading.

If you want to change the size of a heading, don't skip heading levels! Use HTML classes to style them as a smaller (or larger) heading level:

subquestion: |
  <h2 class="h4">Heading 2 (shown the same size as heading 4)</h2>
  ...

  <h3 class="h5">Heading 3 (shown the same size as heading 5)</h3>
  ...

Avoid comboboxes​

Comboboxes allow the user to choose a selection from a list or enter their own "other" value. As implemented in docassemble, comboboxes have several usability problems, especially for screen readers, so we recommend you don't use them. Instead, split the combobox into multiple fields or use a single text field with validation.

Two fields. Split the combobox into:

  1. A dropdown with an additional "other" option
  2. A text input hidden with show if when the dropdown is not "other"

This works best if the list of options is short and the user would expect to find an "other" option on the list.

fields:
  - What is your role?: role_name
    choices:
      - employee
      - manager
      - other
  - Enter your role: role_other
    show if:
      variable: role_name
      is: other

Three fields. Split the combobox into:

  1. A dropdown with options (e.g., a list of courts inside the user's state)
  2. A checkbox that indicates the list doesn't apply (e.g., "My court is not in Massachusetts")
  3. A fill-in-the-blank text input hidden with show if

This works better if the list of options is longer, and it makes the "other" option much more prominent.

fields:
  - What is your court name?: court_name
    required: False
    code: |
      list_of_courts
  - My court is outside of Massachusetts: outside_ma
    datatype: yesno
  - Enter your court's name: court_outside_ma_name
    show if: outside_ma

Text field with validation. Use a single text field with input validation by the interview. To help the user fill in the field correctly, include some valid values as examples on the page. Ensure validation errors are descriptive.

Accessibility testing tools​

Test your interview with assistive technology as much as you can! The best way to improve your interviews for assistive technology users is by actually experiencing it yourself.

Here are some common tools to help you test and validate the accessibility of your interviews:

Screen readers​

Screen readers read website copy aloud for users who are blind, have low vision, or have other challenges reading text. Each screen reader behaves differently, so test with as many as you can.

But don't rewrite your copy based on how it sounds in a screen reader. Screen readers may pronounce some words and acronyms differently than you might expect. This is fine; screen reader users are used to these differences. For more discussion of this, see Adrian Roselli's post about this.

tip

docassemble includes a built-in screen reader based on VoiceRSS.

Free screen readers:

  • NVDA (NonVisual Desktop Access) is a free, open-source screen reader for Windows that is widely used and regularly updated
  • VoiceOver is built into Apple devices. Activate with Command (⌘) + F5 on Mac.
  • TalkBack is Android's built-in screen reader
  • Orca is an open-source screen reader for Linux systems

Commercial screen readers:

Browser accessibility checkers​

These tools can automatically scan your interview pages for accessibility issues:

  • WAVE Web Accessibility Evaluator is a browser extension that highlights accessibility issues directly on the page
  • Axe DevTools is a browser extension for Chrome, Firefox, and Edge that integrates with developer tools
  • Lighthouse is built into Chrome DevTools and includes accessibility auditing alongside performance testing
  • Accessibility Insights is Microsoft's accessibility testing tool for web and Windows

Manual testing tools​

Mobile accessibility testing​

  • VoiceOver is iOS's built-in screen reader
  • TalkBack is Android's built-in screen reader
  • Switch Access is an Android feature for users with motor disabilities

Automated testing and CI integration​

  • DAYamlChecker: Static analysis for interview YAML and Word templates, catching skipped headings, unlabelled fields, missing alt text, and non-descriptive links while you are still editing.
  • SuffolkLITLab/ALActions: The GitHub Actions pipeline that runs dayamlchecker, checks hyperlinks, and validates PDF templates with veraPDF. See the automated quality checks overview.
  • ALKiln: Dynamic end-to-end browser testing framework with built-in accessibility testing using aXe-core.
  • aXe-core: An open-source accessibility testing engine used by ALKiln and browser DevTools.
  • Pa11y: A command-line accessibility testing tool for rendered HTML pages.