From 570fd2a5995ad8460c8eb5d3a569363ba306f815 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Mon, 27 Jul 2026 00:47:11 -0700 Subject: [PATCH 1/2] accessibility guide --- doc/AccessibilityGuide.md | 167 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 doc/AccessibilityGuide.md diff --git a/doc/AccessibilityGuide.md b/doc/AccessibilityGuide.md new file mode 100644 index 0000000000..a34e1ee6f0 --- /dev/null +++ b/doc/AccessibilityGuide.md @@ -0,0 +1,167 @@ +# WeBWorK Accessibility Guide + +## Purpose of this guide + +Accessibility in WeBWorK comes from three different layers: + +1. **The WeBWorK web application** which renders the course interface: + navigation, grades, login, the instructor tools, and so on. +2. **The PG rendering** engine that converts problem code into problems a user + will interact with. +3. **PG problems** which are written by individual problem authors. They may + come from a shared library of problem files, might be uploaded into a course, + or might be written by the course instructor. + +A course can run with fully accessible infrastructure from 1 and 2 above and +still have individual problems with accessibility concerns because the problem +content (an image, a graph, a table) was authored without accessibility in mind. +Sections 1 and 2 below describe the interface itself. Section 3 addresses +problem content and gives problem authors (including course instructors) +concrete steps they can take to write or maintain accessible problems. + +--- + +## 1. The student experience + +### What works well + +- There is a Student Orientation that ships with WeBWorK, which orients students + to navigation and accessibility features. +- Site navigation is built with accessibility and user experience in mind. +- Answer blanks have labeling and other accessible features. +- Popups announce themselves. +- Light, dark, and auto color themes are available. +- Math is rendered with MathJax v4, providing a large array of features that + make math accessible. +- Timed tests may have their times adjusted, and students can be assigned an + "accommodation factor" to expand all timed tests by the same factor. + +### Known shortfalls + +- An alternative to viewing problems in pages at the WeBWorK site is to generate + PDF hardcopies of problem sets. These PDFs are far from accessible. +- Some problems that a student might be assigned may have accissibility + shortcomings. See section 3 below. + +--- + +## 2. The instructor experience + +The instructor interface has historically had less attention addressing +accessibility concerns, but has been catching up with recent versions of WeBWorK. + +### What works well + +- Instructor tools share the same accessible base layout and theming as student + pages. +- Forms are built from labeled, standard HTML controls. +- The PG Problem Editor is a plain-text code editor with standard + textarea/CodeMirror editing semantics. + +### Known shortfalls + +- Certain instructor tools are dense interactive HTML tables with many form + controls. While the structure of these tables uses correct markup, screen + reader operation of these tools may be challenging. +- The tool for browsing problems works by rendering lots of problems down a + page. While a sighted user might quickly scroll and assess which problems they + are looking for, a screen reader user might need much more time entering each + problem. + +--- + +## 3. Problem content (PG problems) — authored separately + +Every PG problem is a small program written by an instructor or author, not by +the WeBWorK/PG development team. The PG rendering engine provides substantial +accessibility *tools*, but whether an individual problem is accessible depends +heavily on whether its author used them, and used them correctly. + +A problem file that is in use in a course might be: + +- Local, within that course. In this case the instructor has permissions needed + to edit it. +- Within a communal library. In this case, an instructor cannot directly edit + the file. However they will be able to make a local copy of the file, edit + that file, and easily replace all instances that are assigned to students to + use the local copy. + +If a problem does come from a communal library and you make accessibility +improvements, please contribute your improvements upstream to that library. + +### Guidance for problem authors and editors + +**Use PGML.** +Write new problems using PGML, and convert old ones to PGML. When in the problem +editor, there is a PGML link leading to tutorials on how to write using PGML. + +**Describe images** + +- `alt` text should be a short (under ~125 character) description of the + important content of the image — not "a picture of a triangle" but what a + sighted student would actually read off the image (the given measurements, the + shape of a graph, the labels in a diagram). +- If an image is purely decorative (a border, a logo, a flourish), use + `alt => ''` explicitly. Leaving `alt` unset is different from setting it to an + empty string — an unset `alt` is a signal that the author simply forgot, so + always set one or the other deliberately. +- For anything more complex than a one-line description — a graph with several + labeled features, a data plot, a multi-part diagram — use `long_description` + in addition to `alt`. `long_description` can include full sentences, or even a + data table (for example, a table of the (x, y) points that a plotted curve + passes through), and is included in both the HTML output and hardcopy PDF. +- If you already generate a caption or descriptive paragraph near the image for + sighted students, consider building that same text into a variable and passing + it to `long_description` instead of (or in addition to) leaving it only as + visible text. + +**A note on interactive graphing tools.** +Problems that use `parserGraphTool.pl` have an interactive graph with buttons +for creating plots of lines, circles, and more. Recent versions of WeBWorK have +made significant acccessibility improvements for this tool, and it is expected +to be largely accessible. Field tests and issue reports are still welcome, and +the development team will work to address any reports. + +There are other interactive tools, usually only used by older problems in the +communal liibraries. These tools may fall short of accessibility standards and +should be avoided. + +**Use headers and captions with tables.** +For example, in PGML: + +```perl +[# + [. .] [. 2020 .] [. 2021 .]*{headerrow => 1} + [. Revenue .] [. $10k .] [. $12k .] +#]{rowheaders => 1, caption => "Company revenue by year"} +``` + +**Don't rely on color alone.** +If a problem distinguishes cases, categories, or correct/incorrect regions using +color (e.g. "the red curve" vs. "the blue curve"), also distinguish them with a +label, line style, or position in the text ("the curve labeled $f$" or "the +dashed curve"), since colorblind students and screen reader users get no +information from color alone. + +**Test with a keyboard.** +Before publishing a problem with anything beyond a plain answer blank (pop-up +menus, checkboxes, custom JavaScript widgets such as GraphTool or a custom +applet), tab through it without using a mouse. If you cannot complete the +problem using only the keyboard, a keyboard-only student cannot either. + +--- + +## Reporting problems + +If you experience an accessibilty shortcoming with WeBWorK, please report the +issue. + +- When you believe the issue is with the WeBWorK interface (navigation, grades, + login, instructor tools, and more) report at the + [webwork2 repository](https://github.com/openwebwork/webwork2/issues) +- When you believe the issue is a systemic issue with problem rendering or with + how a student submits an answer, report at the + [pg repository](https://github.com/openwebwork/pg/issues) +- If the issue stems from how a specific problem was (mis)coded, please see + section 3 of this guide. + From b9d667e67f693575c0c131b68199a7bda9d2f6db Mon Sep 17 00:00:00 2001 From: Jaimos Skriletz Date: Tue, 28 Jul 2026 14:41:45 -0700 Subject: [PATCH 2/2] formatting, typos, and image descriptions in the accessibility guide --- doc/AccessibilityGuide.md | 161 +++++++++++++++++++++----------------- 1 file changed, 88 insertions(+), 73 deletions(-) diff --git a/doc/AccessibilityGuide.md b/doc/AccessibilityGuide.md index a34e1ee6f0..fefe199f23 100644 --- a/doc/AccessibilityGuide.md +++ b/doc/AccessibilityGuide.md @@ -4,20 +4,21 @@ Accessibility in WeBWorK comes from three different layers: -1. **The WeBWorK web application** which renders the course interface: +1. **The WeBWorK web application** which renders the course interface: navigation, grades, login, the instructor tools, and so on. -2. **The PG rendering** engine that converts problem code into problems a user - will interact with. +2. **The PG rendering** engine that converts problem code into problems a + user will interact with. 3. **PG problems** which are written by individual problem authors. They may - come from a shared library of problem files, might be uploaded into a course, - or might be written by the course instructor. + come from a shared library of problem files, might be uploaded into a + course, or might be written by the course instructor. -A course can run with fully accessible infrastructure from 1 and 2 above and -still have individual problems with accessibility concerns because the problem -content (an image, a graph, a table) was authored without accessibility in mind. -Sections 1 and 2 below describe the interface itself. Section 3 addresses -problem content and gives problem authors (including course instructors) -concrete steps they can take to write or maintain accessible problems. +A course can run with fully accessible infrastructure from 1 and 2 above +and still have individual problems with accessibility concerns because the +problem content (an image, a graph, a table) was authored without +accessibility in mind. Sections 1 and 2 below describe the interface itself. +Section 3 addresses problem content and gives problem authors (including +course instructors) concrete steps they can take to write or maintain +accessible problems. --- @@ -25,8 +26,8 @@ concrete steps they can take to write or maintain accessible problems. ### What works well -- There is a Student Orientation that ships with WeBWorK, which orients students - to navigation and accessibility features. +- There is a Student Orientation that ships with WeBWorK, which orients + students to navigation and accessibility features. - Site navigation is built with accessibility and user experience in mind. - Answer blanks have labeling and other accessible features. - Popups announce themselves. @@ -38,9 +39,9 @@ concrete steps they can take to write or maintain accessible problems. ### Known shortfalls -- An alternative to viewing problems in pages at the WeBWorK site is to generate - PDF hardcopies of problem sets. These PDFs are far from accessible. -- Some problems that a student might be assigned may have accissibility +- An alternative to viewing problems in pages at the WeBWorK site is to + generate PDF hardcopies of problem sets. These PDFs are far from accessible. +- Some problems that a student might be assigned may have accessibility shortcomings. See section 3 below. --- @@ -48,12 +49,13 @@ concrete steps they can take to write or maintain accessible problems. ## 2. The instructor experience The instructor interface has historically had less attention addressing -accessibility concerns, but has been catching up with recent versions of WeBWorK. +accessibility concerns, but has been catching up with recent versions of +WeBWorK. ### What works well -- Instructor tools share the same accessible base layout and theming as student - pages. +- Instructor tools share the same accessible base layout and theming as + student pages. - Forms are built from labeled, standard HTML controls. - The PG Problem Editor is a plain-text code editor with standard textarea/CodeMirror editing semantics. @@ -64,84 +66,95 @@ accessibility concerns, but has been catching up with recent versions of WeBWorK controls. While the structure of these tables uses correct markup, screen reader operation of these tools may be challenging. - The tool for browsing problems works by rendering lots of problems down a - page. While a sighted user might quickly scroll and assess which problems they - are looking for, a screen reader user might need much more time entering each - problem. + page. While a sighted user might quickly scroll and assess which problems + they are looking for, a screen reader user might need much more time + entering each problem. --- -## 3. Problem content (PG problems) — authored separately +## 3. Problem content (PG problems) Every PG problem is a small program written by an instructor or author, not by the WeBWorK/PG development team. The PG rendering engine provides substantial accessibility *tools*, but whether an individual problem is accessible depends heavily on whether its author used them, and used them correctly. -A problem file that is in use in a course might be: +A problem file might be: -- Local, within that course. In this case the instructor has permissions needed - to edit it. +- Local, within a course. In this case the instructor has permissions needed to + edit it. - Within a communal library. In this case, an instructor cannot directly edit the file. However they will be able to make a local copy of the file, edit that file, and easily replace all instances that are assigned to students to use the local copy. -If a problem does come from a communal library and you make accessibility +If a problem comes from a communal library and you make accessibility improvements, please contribute your improvements upstream to that library. ### Guidance for problem authors and editors **Use PGML.** -Write new problems using PGML, and convert old ones to PGML. When in the problem -editor, there is a PGML link leading to tutorials on how to write using PGML. +Write new problems using PGML, and convert old ones to PGML. When in the +problem editor, there is a PGML link leading to tutorials on how to write +using PGML. There are also tools to automatically convert problem code to +PGML and to give code critiques in the problem editor, under Code Maintenance. + +**Describe images.** +All images/graphs need to include a description of important content in the +image — not "a picture of a triangle" but what a sighted student would +actually read off the image (the given measurements, the shape of a graph, +labels in a diagram, etc). + +- Graphs should be created using the `plots.pl` macro. When creating the + `Plots::Plot` object, use the `aria_label` to add a short title to the + graph — such as "Graph of y equals x squared" (default is "Graph"). When + displaying the graph, the `alt` text is converted to an `aria_description` + which has no character limit. An optional `long_description` can be added + to give both a shorter `aria_descripition` and longer description. + +- Descriptions of static images (`.png`, `.jpeg`, etc) are provided via the + `alt` text. `alt` text should be short, under ~125 characters, since many + screen readers may only read the first ~125 characters of the `alt` text. + See the PGML help for syntax options to add `alt` text. For anything more + complicated than a one-line description, provide both a short `alt` text + and a full `long_descripition` of the image. + +- Graphs created using the `PGlatex.pl`, `PGtikz.pl`, or `PGgraphmacros.pl` + macros generate static images and follow the same guidelines as static + images above. Graphs created using the deprecated `PGgraphmacros.pl` should + migrate to using `plots.pl`. Consider also migrating images created using + `PGlatex.pl` or `PGtikz.pl` to `plots.pl` as well. + +- `long_descripition` can include more than a sentence or paragraph for + the image. It can include data tables (for example, a table of (x, y) + points a plotted curve passes through), and is included in both the HTML + and hardcopy PDF output, and is visible for sighted users. -**Describe images** - -- `alt` text should be a short (under ~125 character) description of the - important content of the image — not "a picture of a triangle" but what a - sighted student would actually read off the image (the given measurements, the - shape of a graph, the labels in a diagram). - If an image is purely decorative (a border, a logo, a flourish), use - `alt => ''` explicitly. Leaving `alt` unset is different from setting it to an - empty string — an unset `alt` is a signal that the author simply forgot, so - always set one or the other deliberately. -- For anything more complex than a one-line description — a graph with several - labeled features, a data plot, a multi-part diagram — use `long_description` - in addition to `alt`. `long_description` can include full sentences, or even a - data table (for example, a table of the (x, y) points that a plotted curve - passes through), and is included in both the HTML output and hardcopy PDF. -- If you already generate a caption or descriptive paragraph near the image for - sighted students, consider building that same text into a variable and passing - it to `long_description` instead of (or in addition to) leaving it only as - visible text. + `alt => ''` explicitly. Leaving `alt` unset is different from setting it to + an empty string — an unset `alt` is a signal that the author simply forgot, + so always set one or the other deliberately. **A note on interactive graphing tools.** Problems that use `parserGraphTool.pl` have an interactive graph with buttons -for creating plots of lines, circles, and more. Recent versions of WeBWorK have -made significant acccessibility improvements for this tool, and it is expected -to be largely accessible. Field tests and issue reports are still welcome, and -the development team will work to address any reports. +for creating plots of lines, circles, and more. Recent versions of WeBWorK +have made significant accessibility improvements for this tool, and it is +expected to be largely accessible. Field tests and issue reports are still +welcome, and the development team will work to address any reports. -There are other interactive tools, usually only used by older problems in the -communal liibraries. These tools may fall short of accessibility standards and -should be avoided. +There are other interactive tools used by older problems in the communal +libraries. These tools may fall short of accessibility standards and should be +avoided. **Use headers and captions with tables.** -For example, in PGML: - -```perl -[# - [. .] [. 2020 .] [. 2021 .]*{headerrow => 1} - [. Revenue .] [. $10k .] [. $12k .] -#]{rowheaders => 1, caption => "Company revenue by year"} -``` +See the PGML help for the syntax to include headers and captions in a table. **Don't rely on color alone.** -If a problem distinguishes cases, categories, or correct/incorrect regions using -color (e.g. "the red curve" vs. "the blue curve"), also distinguish them with a -label, line style, or position in the text ("the curve labeled $f$" or "the -dashed curve"), since colorblind students and screen reader users get no -information from color alone. +If a problem distinguishes cases, categories, or correct/incorrect regions +using color (e.g. "the red curve" vs. "the blue curve"), also distinguish +them with a label, line style, or position in the text ("the curve labeled +f" or "the dashed curve"), since colorblind students and screen reader +users get no information from color alone. **Test with a keyboard.** Before publishing a problem with anything beyond a plain answer blank (pop-up @@ -153,15 +166,17 @@ problem using only the keyboard, a keyboard-only student cannot either. ## Reporting problems -If you experience an accessibilty shortcoming with WeBWorK, please report the +If you experience an accessibility shortcoming with WeBWorK, please report the issue. -- When you believe the issue is with the WeBWorK interface (navigation, grades, - login, instructor tools, and more) report at the +- When you believe the issue is with the WeBWorK interface (navigation, + grades, login, instructor tools, and more) report at the [webwork2 repository](https://github.com/openwebwork/webwork2/issues) -- When you believe the issue is a systemic issue with problem rendering or with - how a student submits an answer, report at the +- When you believe the issue is a systemic issue with problem rendering or + with how a student submits an answer, report at the [pg repository](https://github.com/openwebwork/pg/issues) - If the issue stems from how a specific problem was (mis)coded, please see - section 3 of this guide. + section 3 of this guide. And if you improve the accessibility of the + problem, contact your WeBWorK administrator to ask how you could contirubute + the improvement upstream.