Skip to content

Commit 1da146d

Browse files
rachel-fenichelrachel-fenichel
authored
chore(docs): add accessibility best practices and screen reader docs (#9914)
* chore(docs): add accessibility section under app integration * chore(docs): add information about accessibility best practices and screen reader usage * chore(docs): fix formatting * chore(docs): fix typo
1 parent cd2f5d3 commit 1da146d

5 files changed

Lines changed: 311 additions & 16 deletions

File tree

‎packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
description: Best practices for making a Blockly-based application accessible.
3+
title: Accessibility best practices
4+
image: images/blockly_banner.png
5+
---
6+
7+
# Accessibility best practices
8+
9+
Since Blockly is a library that is used in a wide variety of applications it
10+
cannot fix all accessibility problems through its default configuration.
11+
Similarly, Blockly is not responsible for content on the rest of the page.
12+
This page lists our suggestions for accessibility best practices when using
13+
Blockly.
14+
15+
## Keyboard shortcuts
16+
17+
### Shortcut mapping
18+
19+
Use Blockly's default keyboard shortcuts unless they conflict with
20+
preexisting shortcuts in your application. The Blockly team has worked with
21+
partners and the community to create a standard set of shortcuts that should
22+
work across a wide range of Blockly applications, and to encourage adoption.
23+
Using standard keyboard shortcuts allows your users to transfer their knowledge
24+
to and from other Blockly-based programming environments instead of learning a
25+
new set of shortcuts for each tool.
26+
27+
### Multi-key shortcuts
28+
29+
Blockly uses single-key shortcuts to support young users without strong
30+
keyboarding skills, older users with dexterity impairments, and usage across a
31+
wide range of browser/OS combinations.
32+
33+
Advanced operations and standard actions such as copy and paste require users to
34+
press multiple keys at once. If a user cannot press multiple keys at the same
35+
time they should use the
36+
[sticky keys](https://en.wikipedia.org/wiki/Sticky_keys) setting in their
37+
operating system.
38+
39+
### Teaching shortcuts
40+
41+
Provide an interactive tutorial to introduce users to
42+
[basic keyboard navigation](/guides/configure/web/keyboard-nav#basic-operation).
43+
Start users off with only basic operations to reduce cognitive load. At the end
44+
of the tutorial, tell users where to look for additional help.
45+
46+
Blockly's keyboard shortcuts are intended to be useful for all users, not only
47+
those with disabilities. Provide information about basic shortcuts in your
48+
documentation and instructions for all users. If you provide professional
49+
development resources, explicitly train teachers on keyboard shortcuts.
50+
51+
### Shortcut help
52+
53+
Make it easy for users to look up shortcuts on their own. To support a wide
54+
variety of computers and users, the list of keyboard shortcuts should be
55+
available within the Blockly workspace, as a separate web page, and as a
56+
printable resource.
57+
58+
(June 2026): The Blockly team plans to release a plugin that displays the
59+
default keyboard shortcuts. If you have additional keyboard shortcuts in Blockly
60+
or on your page, you must update your shortcut list accordingly.
61+
62+
## Vocabulary
63+
64+
When working with users with visual impairments we recommend that you use
65+
tangible resources to introduce vocabulary. The
66+
[micro:bit documentation](https://microbit.org/accessibility/visual-impairment/#start-with-cut-out-cards)
67+
provides good examples.
68+
69+
## Zoom
70+
71+
Enable [resizing up to 200%](https://www.w3.org/WAI/WCAG22/Understanding/resize-text)
72+
through Blockly's [zoom controls](/guides/configure/web/zoom).
73+
74+
## Colours
75+
76+
Check your colours against [WCAG contrast standards](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum).
77+
If you cannot meet the standards with your default colours and cannot change
78+
colours due to published resources, use [themes](/guides/configure/web/appearance/themes)
79+
to provide colorblind-friendly modes and high-contrast mode.
80+
81+
It may also be appropriate to provide a dark mode for your application. You can
82+
use themes to change Blockly's colours, but those changes should be synced with
83+
settings for the rest of your application.
84+
85+
If you have an account system, save this information in user preferences.
86+
87+
## Search
88+
89+
Provide workspace search and toolbox search to help users jump to blocks.
90+
Linear traversal of a workspace or toolbox can be slow and tiring.
91+
92+
(June 2026): The Blockly team will update the published toolbox search and
93+
workspace search plugins to work with v13. You may need custom implementations
94+
to fit your application.
95+
96+
## Skip links
97+
98+
Provide a [link that jumps directly to the Blockly workspace](https://www.w3.org/WAI/WCAG22/Techniques/general/G1)
99+
on each page.
100+
101+
Provide an "area menu" that allows users to quickly jump between regions of the
102+
page (e.g. the block editor and the runtime area). See the "navigating between
103+
areas" section of the [Microsoft MakeCode accessibility page](https://makecode.com/accessibility)
104+
for an example implementation.
105+
106+
## Clean up and reflow
107+
108+
You may choose to force blocks into a single vertical stack, if appropriate for
109+
your application. You can do this by automatically reflowing the blocks after
110+
each drag by calling `workspace.cleanUp()`.
111+
112+
Blockly does not need to meet the
113+
[WCAG Reflow criterion](https://www.w3.org/WAI/WCAG21/Understanding/reflow)
114+
because there is an exception for "content requiring two-dimensional layout".
115+
116+
Consider carefully when making this choice. The intent of the criterion is to
117+
"let users enlarge text and other related content without having to scroll in
118+
two dimensions to read". However, in some Blockly applications users explicitly
119+
use the two-dimensional layout to structure their code. One example is
120+
[this Scratch project](https://scratch.mit.edu/projects/907456472/editor/)
121+
where the scripts are positioned to be visible at the same time. In this context
122+
a forced vertical layout would make it harder to read the code and require the
123+
user to hold more state in their mind when reading or editing. It would also
124+
increase the drag distance for most edits.
125+
126+
An intermediate approach is to prompt users to use the
127+
[cleanup shortcut](/guides/configure/web/keyboard-nav#cleanup).
128+
129+
## Screenreader optimizations
130+
131+
Suggest that users turn on [screen reader optimizations](/guides/configure/web/screen-reader#screen-reader-optimizations)
132+
when they first navigate to the workspace using the keyboard. If you have an
133+
account system, save this information so users don't have to set it on every
134+
visit.
135+
136+
## Documentation
137+
138+
Publish an accessibility page on your product website. Include a statement on
139+
the compliance level of your product and links to all of your
140+
accessibility-related resources. You can use Blockly's Accessibility
141+
Conformance Report (ACR) as a portion of your compliance reporting.

packages/docs/docs/guides/app-integration/compliance.mdx renamed to packages/docs/docs/guides/app-integration/accessibility/compliance.mdx

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
description: How to make your use of Blockly meet accessibility standards. .
3-
title: Accessibility compliance
2+
description: How to make your use of Blockly meet accessibility standards.
3+
title: Compliance
44
image: images/blockly_banner.png
55
---
66

7-
# Accessibility Compliance
7+
# Compliance
88

99
The [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/)
1010
are international standards for the development of accessible web content.
@@ -45,10 +45,12 @@ Explanations column describes which customizations the developer must check.
4545

4646
## Screen reader support
4747

48-
Blockly provides extensive support for screen reader usage through its keyboard
49-
navigation system. As of Blockly v13 (released in June 2026) the core library
50-
meets standards for keyboard controls. v13 also includes APIs to support
51-
developers in creating accessible custom fields and blocks.
48+
Blockly provides extensive support for
49+
[screen reader usage](/guides/configure/web/screen-reader) through its
50+
[keyboard navigation](/guides/configure/web/keyboard-nav) system. As of Blockly
51+
v13 (released in June 2026) the core library meets standards for keyboard
52+
controls. v13 also includes APIs to support developers in creating accessible
53+
custom fields and blocks.
5254

5355
Blockly computes text descriptions of blocks and fields for use by screen
5456
readers and other assistive technology. By default, descriptions are computed
@@ -59,11 +61,11 @@ label generation can take advantage of Blockly's
5961

6062
### Standard interfaces
6163

62-
Blockly's screen reader and keyboard navigation systems are based on extensive
63-
user research with sighted and visually impaired children. The keyboard
64-
shortcuts and vocabulary were selected to balance the needs of novice and
65-
advanced users. We recommend that developers use the default key mappings and
66-
terms unless they conflict with pre-existing portions of your application.
64+
Blockly's screen reader and keyboard navigation systems are based on
65+
extensive user research with sighted and visually impaired children. The
66+
keyboard shortcuts and vocabulary were selected to balance the needs of novice
67+
and advanced users. We recommend that developers use the default key mappings
68+
and terms unless they conflict with pre-existing portions of your application.
6769
Doing so will allow users to transfer experience between block-based programming
6870
environments. Please speak to the Blockly team about your options before
6971
diverging from the standard interface.

‎packages/docs/docs/guides/configure/web/keyboard-nav.mdx‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,11 +50,38 @@ field value.
5050

5151
## Advanced operation
5252

53-
Blockly provides many other keyboard shortcuts, including **I** to get
54-
information about the cursor location and **control + enter** (Windows) or
55-
**command + enter** (Mac) to open the context menu. Cut, copy/paste, and
53+
Blockly provides many other keyboard shortcuts. Cut, copy/paste, and
5654
undo/redo all follow conventions for keyboard shortcuts.
5755

56+
### Toolboxes and flyouts
57+
58+
Pressing **t** moves focus to the toolbox or flyout. Category toolboxes can be
59+
navigated with the **arrow keys** like a standard tree. Pressing **enter** opens
60+
the flyout and moves focus to the first block, label, or button.
61+
62+
The **up and down arrow keys** can be used to navigate within the flyout.
63+
**Enter** selects a block and places it on the workspace in move mode.
64+
65+
### Comments and mutators
66+
67+
In core Blockly, comments and mutators are bubbles attached to icons on a block.
68+
Use the **arrow keys** to navigate to the icon and press **enter** to open the
69+
bubble. Focus will move to the bubble. Press **enter** again to edit it, or
70+
**m** to move the bubble. Press **escape** to leave the bubble context.
71+
Interacting with blocks in a mutator bubble is the same as in the main
72+
workspace.
73+
74+
### Context menu
75+
76+
Press **control + enter** (Windows) or **command + enter** (Mac) to open the
77+
context menu. Use the arrow keys to navigate within the context menu. Keyboard
78+
shortcuts are displayed in the context menu.
79+
80+
### Cleanup
81+
82+
Press **C** to clean up the workspace by moving all block stacks into a single
83+
column with no overlaps, preserving their order on the page.
84+
5885
## Technical details
5986

6087
Blockly keyboard navigation uses the [focus system](/guides/configure/web/focus)

‎packages/docs/docs/guides/configure/web/screen-reader.mdx‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
description: Screen reader support in Blockly
3+
title: Screen reader
4+
image: images/blockly_banner.png
5+
---
6+
7+
# Screen reader support
8+
9+
Blockly supports usage with a screen reader starting in Blockly v13. Screen
10+
reader support is closely tied to
11+
[keyboard navigation](/guides/configure/web/keyboard-nav).
12+
13+
When developing Blockly's screen reader interactions, a guiding principle was
14+
that screen reader users should be able to easily collaborate with sighted
15+
users. Collaboration is important for pair programming and debugging. To the
16+
maximum extent possible, Blockly should just work when used with a screen
17+
reader. This page documents the additional text output that is available to a
18+
screen reader user, which is presented in parallel with the visual output.
19+
20+
## Application role
21+
Blockly uses the [`application` ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role)
22+
to indicate that it handles all keyboard shortcuts. Block programming cannot
23+
be mapped to semantic HTML without losing critical information. For more
24+
information on Blockly's approach to accessibility and the justification for
25+
this decision, see the [accessibility principles](/guides/design/accessibility)
26+
page.
27+
28+
## Block labels
29+
30+
Screen readers rely on the [`aria-label` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
31+
to name elements that do not have visible labels in the DOM.
32+
Block labels must give screen reader users information about where they are in
33+
a program and what actions they can take at that location. Blockly dynamically
34+
calculates labels for blocks based on the block definition, rendered text, and
35+
connected blocks. Blockly also uses the [`aria-roledescription` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription)
36+
to describe the shape of the block.
37+
38+
Screen readers vary in how they present `aria-labels` and
39+
`aria-roledescriptions`. The Blockly team tested with JAWS, NVDA, VoiceOver,
40+
and ChromeVox during development and selected a labeling strategy that balanced
41+
the quirks of these screen readers.
42+
43+
:::note
44+
The best way to explore block labels is to try it yourself on the
45+
[Blockly playground](https://raspberrypifoundation.github.io/blockly/packages/blockly/tests/playground.html)
46+
with a screen reader enabled.
47+
:::
48+
49+
Block labels are built by combining strings. They may have the following
50+
information:
51+
- Position: the first block in a stack is labeled "begin stack".
52+
- Available connections: "has input", "has inputs", or no information. Both
53+
horizontal (value) and vertical (statement) inputs are considered.
54+
- Shape: generally "statement", "value", or "container". Statement blocks can
55+
be stacked vertically; value blocks can be connected horizontally; container
56+
blocks can contain statement blocks.
57+
- Block and field text: The contents of the block and selected children, generally read
58+
from left to right. The label is derived from the text displayed on the block,
59+
meaning that it is automatically internationalized.
60+
61+
### Extended descriptions
62+
63+
Screen reader users can replay the block label with **I** or play an extended
64+
description with **shift + I**. The extended description contains information
65+
about parent blocks. This information is disruptive when reading code linearly
66+
but helpful when debugging or reorienting within a program.
67+
68+
## Fields
69+
70+
### Built-in fields
71+
72+
Most editable fields in Blockly have an `aria-role` of `"button"` to indicate
73+
that pressing **enter** will open a field editor. Blockly sets more specific
74+
ARIA roles for built-in fields when appropriate (e.g. text inputs and
75+
checkboxes).
76+
77+
Blockly's number fields have an HTML input type of `text` rather than `number`.
78+
Developers are encouraged to add additional labels and validation about the
79+
type of number expected. See the [number field documentation](/guides/create-custom-blocks/fields/built-in-fields/number#accessibility)
80+
for more information.
81+
82+
### Custom fields
83+
84+
Blockly allows developers to create arbitrarily complex custom fields.
85+
Developers are responsible for the accessibility of their custom field editors.
86+
87+
## Dragging
88+
89+
During drags Blockly uses an [ARIA live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions)
90+
to provide updates on the location of the dragging block. This describes where
91+
the block will connect if the drag is immediately confirmed. Updates are
92+
generated by both mouse and keyboard drags.
93+
94+
## Screen reader optimizations
95+
96+
During testing we found cases where the preferences of screen reader users
97+
strongly diverged from the preferences of sighted users. Blockly exposes a
98+
"screen reader mode" that enables settings that were preferred by screen reader
99+
users. There is no way for Blockly to detect if a screen reader is in use, so
100+
users need to explicitly toggle this mode with **control + alt + z** (Windows)
101+
or **command + option + z** (Mac). Developers may also expose these options as
102+
user preferences for more granular control.
103+
104+
### Navigation looping
105+
106+
By default navigating **down** from the last item on a workspace moves the
107+
cursor back up to the top of the workspace. This is called "looping". Screen
108+
reader users preferred a hard stop, while sighted users preferred looping. In
109+
screen reader mode looping is disabled.
110+
111+
### Audio cues
112+
113+
By default Blockly does not play sounds when the cursor moves up and down. In
114+
screen reader mode tones play when the cursor moves to a new level of
115+
indentation.

‎packages/docs/sidebars.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -818,6 +818,11 @@ const sidebars = {
818818
label: 'Keyboard navigation',
819819
id: 'guides/configure/web/keyboard-nav',
820820
},
821+
{
822+
type: 'doc',
823+
label: 'Screen reader',
824+
id: 'guides/configure/web/screen-reader',
825+
},
821826
{
822827
type: 'doc',
823828
label: 'Colour and accessibility',
@@ -1280,7 +1285,12 @@ const sidebars = {
12801285
{
12811286
type: 'doc',
12821287
label: 'Compliance',
1283-
id: 'guides/app-integration/compliance',
1288+
id: 'guides/app-integration/accessibility/compliance',
1289+
},
1290+
{
1291+
type: 'doc',
1292+
label: 'Best practices',
1293+
id: 'guides/app-integration/accessibility/best-practices',
12841294
},
12851295
],
12861296
},

0 commit comments

Comments
 (0)