From b8aa46648d46179c38859a0a47df7a3100e6d6dd Mon Sep 17 00:00:00 2001 From: samglover Date: Thu, 27 Aug 2026 10:38:57 -0500 Subject: [PATCH 1/5] Update title and sidebar label --- docs/coding_style/accessibility.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/coding_style/accessibility.md b/docs/coding_style/accessibility.md index fe64a2573..e1bbf2834 100644 --- a/docs/coding_style/accessibility.md +++ b/docs/coding_style/accessibility.md @@ -1,7 +1,7 @@ --- id: accessibility -title: Making your interview accessible -sidebar_label: Interview accessibility +title: Making docassemble interviews accessible +sidebar_label: Accessibility slug: accessibility --- From aeaddfc9e6f4c8af6bbe84a9bef43e8dff67db36 Mon Sep 17 00:00:00 2001 From: samglover Date: Thu, 27 Aug 2026 11:33:39 -0500 Subject: [PATCH 2/5] General proofread and minor changes and improvements of the existing copy --- docs/coding_style/accessibility.md | 209 ++++++++++++++++++----------- 1 file changed, 133 insertions(+), 76 deletions(-) diff --git a/docs/coding_style/accessibility.md b/docs/coding_style/accessibility.md index e1bbf2834..6465320bb 100644 --- a/docs/coding_style/accessibility.md +++ b/docs/coding_style/accessibility.md @@ -5,15 +5,17 @@ sidebar_label: Accessibility slug: accessibility --- -**Web Accessibility** is the practice of making your website usable by many different users, such as those who use keyboard controls or screen readers. +**Web accessibility** is the practice of making your website usable by many different users, such as those who use keyboard controls or screen readers. -Making your guided interviews accessible is first and foremost about making them easy to understand and use. Following [our advice about writing good questions](../style_guide/question_overview) can make your interview overall easier to understand and complete, which helps everyone! +Making guided interviews accessible is first and foremost about making them easy to understand and use. Following [our advice about writing good questions](../style_guide/question_overview) can make your interview easier to understand and complete overall, which helps everyone! -Other parts of web accessibility involve writing the interview in a way that the user's browser and other accessibility tools (like screen readers) can understand. docassemble [handles many of these things](https://docassemble.org/docs/accessibility.html) for you, but there are some parts that you'll have to address when writing your interview. +Web accessibility also involves writing interviews in a way the user's browser or accessibility tools like screen readers can understand. docassemble [handles many of these things](https://docassemble.org/docs/accessibility.html) for you, but there are some parts that you have to address when building your interview. To help you find accessibility problems in your interview you can use the [WAVE browser extension](https://wave.webaim.org/extension/), or if you want to check accessibility of your interview automatically, you can use the [ALKiln testing framework](../components/ALKiln/automated_testing.mdx#accessibility). -## Use colors that contrast strongly with their backgrounds +## Best practices for accessibility + +### Use colors that contrast strongly with their backgrounds One thing that you have control over in your interviews is your interview "branding", including fonts, styles, and importantly, colors. Making sure the text colors and background colors that you choose have high enough contrast is important to both low-vision and sighted users. Web accessibility standards like WCAG 2 define the **minimum** proper color contrast between an element and it's background color as 4.5:1. For larger text like headings, the minimum is 3:1. @@ -22,123 +24,178 @@ You can check that the colors you are using in your interview's branding have pr * [WebAIM's contrast checker](https://webaim.org/resources/contrastchecker/) * [Accessible Web's contrast checker](https://accessibleweb.com/color-contrast-checker/) -## Use alt-text with images +### Use alt-text with images -To describe images in webpages, screen readers read out author-provided descriptions called alternative text, or "alt-text". Without alt-text, people visiting your page with screen readers 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](https://www.w3.org/WAI/tutorials/images/decision-tree/). +To describe images in webpages, screen readers read out author-provided descriptions called alternative text, or alt-text. Without alt-text, people visiting your page with screen readers 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](https://www.w3.org/WAI/tutorials/images/decision-tree/). -In docassemble, you should [set the `alt_text` attribute of a DAFile](https://docassemble.org/docs/objects.html#DAFile), or use [the `set_alt_text()` function](https://docassemble.org/docs/objects.html#DAFile.set_alt_text). If you are writing HTML directly, you can add an `alt` property to any `img` tags you use (see below). +In docassemble, you should [set the `alt_text` attribute of a DAFile](https://docassemble.org/docs/objects.html#DAFile), or use [the `set_alt_text()` function](https://docassemble.org/docs/objects.html#DAFile.set_alt_text). If you are writing HTML directly, you can add an `alt` property to any `img` tags you use: ```html -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'. +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'. ``` -### Logos +:::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. +::: + +### Maintain consistent heading increments + +Headings provide semantic structure to web pages and help screen readers navigate. + +If you use headings in your questions, always increment your heading levels one step at a time. In other words, always go from heading level 2 to 3, not from 2 to 4. + +
+
+ Like this: + + ```markdown + + ## Heading 2 + ### Heading 3 + ### Heading 3 + ## Heading 2 + ``` -You should add alt-text to your organizations logo. This alt-text can be simple, such as "Organization A's logo", but it should be present. + ```html + +

Heading 2

+

Heading 3

+

Heading 3

+

Heading 2

+ ``` +
+
+ **Not** like this: -## Maintain consistent header increments + ```markdown + + ## Heading 2 + #### Heading 4 + #### Heading 4 + ## Heading 2 + ``` -If you use headers in your question markdown, make sure that you always increment your header levels by one. For examples, always go from header level 2 to 3, and not 2 to 4. Screen readers have special features that let users navigate between different headers in order to navigate quickly, and skipped header levels can disorient users. + ```html + +

Heading 2

+

Heading 4

+

Heading 4

+

Heading 2

+ ``` +
+
-### Don't use `h1` in sub questions +Screen readers have special features that let users navigate between different headings in order to navigate quickly, and skipped heading levels can disorient users. -There should only ever be one `h1` header on a page, and in docassemble, that header is the `question` attribute. Because of that, you shouldn't use a `#` header (or if you use HTML, an `

` tag) in a subquestion. +#### Don't use `h1` in sub questions -### Header sizes +There should only ever be one `h1` heading on a page. In docassemble, that heading is the `question` attribute. Don't use a single `#` Markdown heading or an `

` HTML tag in a subquestion or note. -You might notice that the question header in docassemble looks smaller than headers in the subquestion. This is because docassemble manually styles the question to -look like an `h3` header, even though it is really a `h1` header. If you want the headers in your subquestion, don't skip header levels until they "look right". Instead, you can manually use HTML and style them as such: +#### Changing 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 a `h1` heading. + +If you want to change the size of a heading, don't skip heading levels until they "look right." Instead, use HTML to style them as a smaller (or larger) heading level: ```yaml subquestion: | -

Main Description

+

Heading 2 (shown the same size as heading 4)

+ ... +

Heading 3 (shown the same size as heading 5)

... -

More Details

+``` - ... +### Avoid comboboxes + +[Comboboxes](https://docassemble.org/docs/fields.html#field%20with%20combobox) allow the user to choose a selection from a list or enter their own "other" value. But as implemented in docassemble, have [several usability problems](https://github.com/SuffolkLITLab/docassemble-AssemblyLine/issues/548), especially with 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. + +```yaml +fields: + - What is your role?: role_name + choices: + - employee + - manager + - other + - Enter your role: role_other + show if: + variable: role_name + is: other ``` -## Avoid comboboxes - -Comboboxes, as implemented in docassemble, have [several usability problems](https://github.com/SuffolkLITLab/docassemble-AssemblyLine/issues/548), especially with screen readers. We recommend that you don't use comboboxes in new interviews, instead using one of the below alternatives: - -* split out the combo box into two fields: a dropdown with the same fields and an additional "other" option, and a fill-in-the-blank text input hidden behind a `show if` when the dropdown is not "other". This only works if the list of predefined options is short and the user will expect to find an "other" option on the list. - - ```yaml - fields: - - What is your role?: role_name - choices: - - employee - - manager - - other - - Enter your role: role_other - show if: - variable: role_name - is: other - ``` - -* split the combo box into three fields: a dropdown menu with options (like a list of courts inside the user's state), a checkbox that indicates the list doesn't apply, and a fill-in-the-blank text input hidden behind a `show if`. This is appropriate if the list of options represents the most common selections, and there is an obvious "mode" switch. For example, the checkbox might read "My court is outside of Massachusetts". - - ```yaml - 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 - ``` - -* if the combo box suggestions are validated by the interview, add some some of those suggestions into examples on the page (which makes them easier to discover for some users) and turn the field into a text input where the validation errors are descriptive. +**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. + +```yaml +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 You should 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 them yourself. + Here are some common tools to help you test and validate the accessibility of your interviews: ### Screen readers -Screen readers are assistive technologies that read content aloud for users who are blind or have low vision. Each of these screen readers behaves differently, so test with as many of them as -you can. +Screen readers read content aloud for users who are blind, have low vision, or other challenges reading text. Each screen reader behaves differently, so test with as many as you can. -It's important to note that you shouldn't rewrite your content based on how it sounds in the screen reader. When using a screen reader, some words and acronyms will be pronounced differently than you might expect. This is fine; screen reader users are used to these differences. For more discussion here, see [Adrian Roselli's post about this](https://adrianroselli.com/2023/04/dont-override-screen-reader-pronunciation.html). +Do not rewrite your content 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](https://adrianroselli.com/2023/04/dont-override-screen-reader-pronunciation.html). -**Free screen readers:** -* **[NVDA (NonVisual Desktop Access)](https://www.nvaccess.org/)** - Free, open-source screen reader for Windows. Widely used and regularly updated. -* **[VoiceOver](https://www.apple.com/accessibility/vision/)** - Built into macOS and iOS devices. Activate with Command+F5 on Mac. -* **[Orca](https://help.gnome.org/users/orca/stable/)** - Open-source screen reader for Linux systems. +Free screen readers: +* **[NVDA (NonVisual Desktop Access)](https://www.nvaccess.org/)** is a free, open-source screen reader for Windows that is widely used and regularly updated +* **[VoiceOver](https://www.apple.com/accessibility/vision/)** is built into Apple devices. Activate with Command (⌘) + F5 on Mac. +* **[TalkBack](https://support.google.com/accessibility/android/answer/6283677)** is Android's built-in screen reader +* **[Orca](https://help.gnome.org/users/orca/stable/)** is an open-source screen reader for Linux systems -**Commercial screen readers:** -* **[JAWS (Job Access With Speech)](https://www.freedomscientific.com/products/software/jaws/)** - The most popular screen reader for Windows with advanced features. +Commercial screen readers: +* **[JAWS (Job Access With Speech)](https://www.freedomscientific.com/products/software/jaws/)** is the most popular screen reader for Windows with advanced features ### Browser accessibility checkers These tools can automatically scan your interview pages for accessibility issues: -* **[WAVE Web Accessibility Evaluator](https://wave.webaim.org/extension/)** - Browser extension that highlights accessibility issues directly on the page. -* **[axe DevTools](https://www.deque.com/axe/devtools/)** - Browser extension for Chrome, Firefox, and Edge that integrates with developer tools. -* **[Lighthouse](https://developer.chrome.com/docs/lighthouse/)** - Built into Chrome DevTools, includes accessibility auditing alongside performance testing. -* **[Accessibility Insights](https://accessibilityinsights.io/)** - Microsoft's accessibility testing tools for web and Windows applications. +* **[WAVE Web Accessibility Evaluator](https://wave.webaim.org/extension/)** is a browser extension that highlights accessibility issues directly on the page +* **[Axe DevTools](https://www.deque.com/axe/devtools/)** is a browser extension for Chrome, Firefox, and Edge that integrates with developer tools +* **[Lighthouse](https://developer.chrome.com/docs/lighthouse/)** is built into Chrome DevTools and includes accessibility auditing alongside performance testing +* **[Accessibility Insights](https://accessibilityinsights.io/)** is Microsoft's accessibility testing tool for web and Windows ### Manual testing tools -* **[Colour Contrast Analyser](https://www.tpgi.com/color-contrast-checker/)** - Desktop application for testing color contrast ratios. -* **[Accessibility bookmarklets](https://accessibility-bookmarklets.org/)** - Collection of browser bookmarklets for quick accessibility checks. +* **[Colour Contrast Analyser](https://www.tpgi.com/color-contrast-checker/)** is a desktop application for testing color contrast ratios +* **[Accessibility bookmarklets](https://accessibility-bookmarklets.org/)** is a collection of browser bookmarklets for quick accessibility checks ### Mobile accessibility testing -* **[TalkBack](https://support.google.com/accessibility/android/answer/6283677)** - Android's built-in screen reader. -* **[Switch Access](https://support.google.com/accessibility/android/answer/6122836)** - Android feature for users with motor disabilities. -* **[VoiceOver](https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/ios)** - iOS's built-in screen reader. +* **[VoiceOver](https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/ios)** is iOS's built-in screen reader +* **[TalkBack](https://support.google.com/accessibility/android/answer/6283677)** is Android's built-in screen reader +* **[Switch Access](https://support.google.com/accessibility/android/answer/6122836)** is an Android feature for users with motor disabilities ### Automated testing integration -* **[ALKiln](../components/ALKiln/automated_testing.mdx#accessibility)** - Assembly Line's testing framework with built-in accessibility testing using aXe-core. -* **[aXe-core](https://github.com/dequelabs/axe-core)** - Open-source accessibility testing engine used by many tools. -* **[Pa11y](https://pa11y.org/)** - Command-line accessibility testing tool that can be integrated into CI/CD pipelines. +* **[ALKiln](../components/ALKiln/automated_testing.mdx#accessibility)** is the Document Assembly Line's testing framework with built-in accessibility testing using [axe-core](https://github.com/dequelabs/axe-core) +* **[aXe-core](https://github.com/dequelabs/axe-core)** is an open-source accessibility testing engine used by many tools +* **[Pa11y](https://pa11y.org/)** is a command-line accessibility testing tool that can be integrated into CI/CD pipelines From 4df4eb4da31be1120d663290538e9f2824bcc015 Mon Sep 17 00:00:00 2001 From: samglover Date: Mon, 31 Aug 2026 13:43:29 -0500 Subject: [PATCH 3/5] Add AssemblyLine accessibility tools --- .../aldashboard-interview-linter-icon.png | Bin 0 -> 15358 bytes docs/coding_style/accessibility.md | 77 ++++++++++++------ 2 files changed, 50 insertions(+), 27 deletions(-) create mode 100644 docs/assets/aldashboard-interview-linter-icon.png diff --git a/docs/assets/aldashboard-interview-linter-icon.png b/docs/assets/aldashboard-interview-linter-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..3cfd3ad561f6004c2dee8cb68cf886e868eb0813 GIT binary patch literal 15358 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 TygI;)R6tr%UZO-y|MUL>y)o9P literal 0 HcmV?d00001 diff --git a/docs/coding_style/accessibility.md b/docs/coding_style/accessibility.md index 6465320bb..27acc1991 100644 --- a/docs/coding_style/accessibility.md +++ b/docs/coding_style/accessibility.md @@ -5,15 +5,34 @@ sidebar_label: Accessibility slug: accessibility --- -**Web accessibility** is the practice of making your website usable by many different users, such as those who use keyboard controls or screen readers. +**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 guided interviews accessible is first and foremost about making them easy to understand and use. Following [our advice about writing good questions](../style_guide/question_overview) can make your interview easier to understand and complete overall, which helps everyone! +Making docassemble interviews accessible involves structuring interviews for people who use keyboard controls and screen readers, which [docassemble handles by default](https://docassemble.org/docs/accessibility.html). To the extent the AssemblyLine software adds features (such as [`AL` object classes](../components/AssemblyLine/reserved_keywords#full-list-of-reserved-variable-names)), they are also built to be accessible by default. -Web accessibility also involves writing interviews in a way the user's browser or accessibility tools like screen readers can understand. docassemble [handles many of these things](https://docassemble.org/docs/accessibility.html) for you, but there are some parts that you have to address when building your interview. +Interview builders must address accessibility, too, so the Document Assembly Line has powerful accessibility tools, a [style guide for writing questions](../style_guide/question_style_overview.md), and [user interface guidelines](./yaml_interface.md). 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](../components/AssemblyLine/translation.md).) -To help you find accessibility problems in your interview you can use the [WAVE browser extension](https://wave.webaim.org/extension/), or if you want to check accessibility of your interview automatically, you can use the [ALKiln testing framework](../components/ALKiln/automated_testing.mdx#accessibility). +## AssemblyLine accessibility tools -## Best practices for accessibility + +The AssemblyLine software includes a [code linter](https://en.wikipedia.org/wiki/Lint_(software)) used in the [ALDashboard](../components/ALDashboard/overview) and [ALWeaver](../authoring/weaver/weaver_overview) packages. It can check interviews against the Document Assembly Line style guide, interface guidelines, and [WCAG accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/). (WCAG accessibility checks must be run manually from the Dashboard **Interview style check (lint)** link.) + +

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

+ +Accessibility checks include: + +- Web Content Accessibility Guidelines (WCAG) clear failures +- DOCX and PDF template accessibility +- DAL style guide issues +- Low contrast +- Skipped [heading levels](#heading-levels) +- Empty links +- Non-descriptive link text +- Missing [alt text](#alt-text) +- Missing field labels +- [Combobox](#avoid-comboboxes) use +- Translateability + +## General tips for improving interview accessibility ### Use colors that contrast strongly with their backgrounds @@ -24,7 +43,7 @@ You can check that the colors you are using in your interview's branding have pr * [WebAIM's contrast checker](https://webaim.org/resources/contrastchecker/) * [Accessible Web's contrast checker](https://accessibleweb.com/color-contrast-checker/) -### Use alt-text with images +### Use alt-text with images {#alt-text} To describe images in webpages, screen readers read out author-provided descriptions called alternative text, or alt-text. Without alt-text, people visiting your page with screen readers 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](https://www.w3.org/WAI/tutorials/images/decision-tree/). @@ -38,7 +57,7 @@ In docassemble, you should [set the `alt_text` attribute of a DAFile](https://do 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. ::: -### Maintain consistent heading increments +### Maintain consistent heading increments {#heading-levels} Headings provide semantic structure to web pages and help screen readers navigate. @@ -107,7 +126,7 @@ subquestion: | ``` -### Avoid comboboxes +### Avoid comboboxes {#avoid-comboboxes} [Comboboxes](https://docassemble.org/docs/fields.html#field%20with%20combobox) allow the user to choose a selection from a list or enter their own "other" value. But as implemented in docassemble, have [several usability problems](https://github.com/SuffolkLITLab/docassemble-AssemblyLine/issues/548), especially with 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. @@ -153,7 +172,7 @@ fields: **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 +## Accessibility testing tools {#accessibility-tools} You should 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 them yourself. @@ -163,39 +182,43 @@ Here are some common tools to help you test and validate the accessibility of yo Screen readers read content aloud for users who are blind, have low vision, or other challenges reading text. Each screen reader behaves differently, so test with as many as you can. -Do not rewrite your content 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](https://adrianroselli.com/2023/04/dont-override-screen-reader-pronunciation.html). +Do not rewrite your content 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](https://adrianroselli.com/2023/04/dont-override-screen-reader-pronunciation.html). + +:::tip +docassemble includes a [built-in screen reader based on VoiceRSS](https://docassemble.org/docs/config.html#voicerss). +::: Free screen readers: -* **[NVDA (NonVisual Desktop Access)](https://www.nvaccess.org/)** is a free, open-source screen reader for Windows that is widely used and regularly updated -* **[VoiceOver](https://www.apple.com/accessibility/vision/)** is built into Apple devices. Activate with Command (⌘) + F5 on Mac. -* **[TalkBack](https://support.google.com/accessibility/android/answer/6283677)** is Android's built-in screen reader -* **[Orca](https://help.gnome.org/users/orca/stable/)** is an open-source screen reader for Linux systems +- **[NVDA (NonVisual Desktop Access)](https://www.nvaccess.org/)** is a free, open-source screen reader for Windows that is widely used and regularly updated +- **[VoiceOver](https://www.apple.com/accessibility/vision/)** is built into Apple devices. Activate with Command (⌘) + F5 on Mac. +- **[TalkBack](https://support.google.com/accessibility/android/answer/6283677)** is Android's built-in screen reader +- **[Orca](https://help.gnome.org/users/orca/stable/)** is an open-source screen reader for Linux systems Commercial screen readers: -* **[JAWS (Job Access With Speech)](https://www.freedomscientific.com/products/software/jaws/)** is the most popular screen reader for Windows with advanced features +- **[JAWS (Job Access With Speech)](https://www.freedomscientific.com/products/software/jaws/)** is the most popular screen reader for Windows with advanced features ### Browser accessibility checkers These tools can automatically scan your interview pages for accessibility issues: -* **[WAVE Web Accessibility Evaluator](https://wave.webaim.org/extension/)** is a browser extension that highlights accessibility issues directly on the page -* **[Axe DevTools](https://www.deque.com/axe/devtools/)** is a browser extension for Chrome, Firefox, and Edge that integrates with developer tools -* **[Lighthouse](https://developer.chrome.com/docs/lighthouse/)** is built into Chrome DevTools and includes accessibility auditing alongside performance testing -* **[Accessibility Insights](https://accessibilityinsights.io/)** is Microsoft's accessibility testing tool for web and Windows +- **[WAVE Web Accessibility Evaluator](https://wave.webaim.org/extension/)** is a browser extension that highlights accessibility issues directly on the page +- **[Axe DevTools](https://www.deque.com/axe/devtools/)** is a browser extension for Chrome, Firefox, and Edge that integrates with developer tools +- **[Lighthouse](https://developer.chrome.com/docs/lighthouse/)** is built into Chrome DevTools and includes accessibility auditing alongside performance testing +- **[Accessibility Insights](https://accessibilityinsights.io/)** is Microsoft's accessibility testing tool for web and Windows ### Manual testing tools -* **[Colour Contrast Analyser](https://www.tpgi.com/color-contrast-checker/)** is a desktop application for testing color contrast ratios -* **[Accessibility bookmarklets](https://accessibility-bookmarklets.org/)** is a collection of browser bookmarklets for quick accessibility checks +- **[Colour Contrast Analyser](https://www.tpgi.com/color-contrast-checker/)** is a desktop application for testing color contrast ratios +- **[Accessibility bookmarklets](https://accessibility-bookmarklets.org/)** is a collection of browser bookmarklets for quick accessibility checks ### Mobile accessibility testing -* **[VoiceOver](https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/ios)** is iOS's built-in screen reader -* **[TalkBack](https://support.google.com/accessibility/android/answer/6283677)** is Android's built-in screen reader -* **[Switch Access](https://support.google.com/accessibility/android/answer/6122836)** is an Android feature for users with motor disabilities +- **[VoiceOver](https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/ios)** is iOS's built-in screen reader +- **[TalkBack](https://support.google.com/accessibility/android/answer/6283677)** is Android's built-in screen reader +- **[Switch Access](https://support.google.com/accessibility/android/answer/6122836)** is an Android feature for users with motor disabilities ### Automated testing integration -* **[ALKiln](../components/ALKiln/automated_testing.mdx#accessibility)** is the Document Assembly Line's testing framework with built-in accessibility testing using [axe-core](https://github.com/dequelabs/axe-core) -* **[aXe-core](https://github.com/dequelabs/axe-core)** is an open-source accessibility testing engine used by many tools -* **[Pa11y](https://pa11y.org/)** is a command-line accessibility testing tool that can be integrated into CI/CD pipelines +- **[ALKiln](../components/ALKiln/automated_testing.mdx#accessibility)** is the Document Assembly Line's testing framework with built-in accessibility testing using [axe-core](https://github.com/dequelabs/axe-core) +- **[aXe-core](https://github.com/dequelabs/axe-core)** is an open-source accessibility testing engine used by many tools +- **[Pa11y](https://pa11y.org/)** is a command-line accessibility testing tool that can be integrated into CI/CD pipelines From 7827a4edab6c3da8a7e0ebc72a24ba37ff11ffec Mon Sep 17 00:00:00 2001 From: samglover Date: Mon, 31 Aug 2026 13:57:53 -0500 Subject: [PATCH 4/5] Edit tips and tools --- docs/coding_style/accessibility.md | 37 ++++++++++++++---------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/docs/coding_style/accessibility.md b/docs/coding_style/accessibility.md index 27acc1991..715c1be37 100644 --- a/docs/coding_style/accessibility.md +++ b/docs/coding_style/accessibility.md @@ -34,20 +34,20 @@ Accessibility checks include: ## General tips for improving interview accessibility -### Use colors that contrast strongly with their backgrounds +### Use strongly contrasting colors -One thing that you have control over in your interviews is your interview "branding", including fonts, styles, and importantly, colors. Making sure the text colors and background colors that you choose have high enough contrast is important to both low-vision and sighted users. Web accessibility standards like WCAG 2 define the **minimum** proper color contrast between an element and it's background color as 4.5:1. For larger text like headings, the minimum is 3:1. +When [customizing the look and feel of your interviews](../components/ALThemeTemplate/overview), 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. -You can check that the colors you are using in your interview's branding have proper contrast with the following tools: +Check for proper contrast with these tools: * [WebAIM's contrast checker](https://webaim.org/resources/contrastchecker/) * [Accessible Web's contrast checker](https://accessibleweb.com/color-contrast-checker/) ### Use alt-text with images {#alt-text} -To describe images in webpages, screen readers read out author-provided descriptions called alternative text, or alt-text. Without alt-text, people visiting your page with screen readers 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](https://www.w3.org/WAI/tutorials/images/decision-tree/). +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](https://www.w3.org/WAI/tutorials/images/decision-tree/). -In docassemble, you should [set the `alt_text` attribute of a DAFile](https://docassemble.org/docs/objects.html#DAFile), or use [the `set_alt_text()` function](https://docassemble.org/docs/objects.html#DAFile.set_alt_text). If you are writing HTML directly, you can add an `alt` property to any `img` tags you use: +So describe an image in docassemble, [set the `alt_text` attribute of a DAFile](https://docassemble.org/docs/objects.html#DAFile), or use [the `set_alt_text()` function](https://docassemble.org/docs/objects.html#DAFile.set_alt_text). If you are writing HTML directly, add an `alt` property to all `img` tags: ```html 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'. @@ -57,11 +57,11 @@ In docassemble, you should [set the `alt_text` attribute of a DAFile](https://do 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. ::: -### Maintain consistent heading increments {#heading-levels} +### Don't skip heading levels {#heading-levels} -Headings provide semantic structure to web pages and help screen readers navigate. +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`. -If you use headings in your questions, always increment your heading levels one step at a time. In other words, always go from heading level 2 to 3, not from 2 to 4. +Screen readers have special features that let users navigate between different headings in order to navigate quickly, and skipped heading levels can disorient users.
@@ -104,17 +104,15 @@ If you use headings in your questions, always increment your heading levels one
-Screen readers have special features that let users navigate between different headings in order to navigate quickly, and skipped heading levels can disorient users. - -#### Don't use `h1` in sub questions +#### Don't use `h1` -There should only ever be one `h1` heading on a page. In docassemble, that heading is the `question` attribute. Don't use a single `#` Markdown heading or an `

` HTML tag in a subquestion or note. +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 `

` HTML tag in a subquestion or note. -#### Changing heading sizes +#### 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 a `h1` heading. +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 until they "look right." Instead, use HTML to style them as a smaller (or larger) heading level: +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: ```yaml subquestion: | @@ -123,12 +121,11 @@ subquestion: |

Heading 3 (shown the same size as heading 5)

... - ``` ### Avoid comboboxes {#avoid-comboboxes} -[Comboboxes](https://docassemble.org/docs/fields.html#field%20with%20combobox) allow the user to choose a selection from a list or enter their own "other" value. But as implemented in docassemble, have [several usability problems](https://github.com/SuffolkLITLab/docassemble-AssemblyLine/issues/548), especially with 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. +[Comboboxes](https://docassemble.org/docs/fields.html#field%20with%20combobox) 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](https://github.com/SuffolkLITLab/docassemble-AssemblyLine/issues/548), 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: @@ -174,15 +171,15 @@ fields: ## Accessibility testing tools {#accessibility-tools} -You should 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 them yourself. +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 content aloud for users who are blind, have low vision, or other challenges reading text. Each screen reader behaves differently, so test with as many as you can. +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. -Do not rewrite your content 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](https://adrianroselli.com/2023/04/dont-override-screen-reader-pronunciation.html). +**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](https://adrianroselli.com/2023/04/dont-override-screen-reader-pronunciation.html). :::tip docassemble includes a [built-in screen reader based on VoiceRSS](https://docassemble.org/docs/config.html#voicerss). From d04d1eea969309581321ac9da3d1dd7865372b97 Mon Sep 17 00:00:00 2001 From: Quinten Steenhuis Date: Tue, 1 Sep 2026 09:19:12 -0400 Subject: [PATCH 5/5] Update docs/coding_style/accessibility.md --- docs/coding_style/accessibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/coding_style/accessibility.md b/docs/coding_style/accessibility.md index 715c1be37..6226f90fb 100644 --- a/docs/coding_style/accessibility.md +++ b/docs/coding_style/accessibility.md @@ -47,7 +47,7 @@ Check for proper contrast with these tools: 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](https://www.w3.org/WAI/tutorials/images/decision-tree/). -So describe an image in docassemble, [set the `alt_text` attribute of a DAFile](https://docassemble.org/docs/objects.html#DAFile), or use [the `set_alt_text()` function](https://docassemble.org/docs/objects.html#DAFile.set_alt_text). If you are writing HTML directly, add an `alt` property to all `img` tags: +To describe an image in docassemble, [set the `alt_text` attribute of a DAFile](https://docassemble.org/docs/objects.html#DAFile), or use [the `set_alt_text()` function](https://docassemble.org/docs/objects.html#DAFile.set_alt_text). If you are writing HTML directly, add an `alt` property to all `img` tags: ```html 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'.