mirror of
https://github.com/google/blockly.git
synced 2026-06-02 09:20:06 +02:00
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
This commit is contained in:
Rachel Fenichel
GitHub
@@ -0,0 +1,141 @@
|
||||
---
|
||||
description: Best practices for making a Blockly-based application accessible.
|
||||
title: Accessibility best practices
|
||||
image: images/blockly_banner.png
|
||||
---
|
||||
|
||||
# Accessibility best practices
|
||||
|
||||
Since Blockly is a library that is used in a wide variety of applications it
|
||||
cannot fix all accessibility problems through its default configuration.
|
||||
Similarly, Blockly is not responsible for content on the rest of the page.
|
||||
This page lists our suggestions for accessibility best practices when using
|
||||
Blockly.
|
||||
|
||||
## Keyboard shortcuts
|
||||
|
||||
### Shortcut mapping
|
||||
|
||||
Use Blockly's default keyboard shortcuts unless they conflict with
|
||||
preexisting shortcuts in your application. The Blockly team has worked with
|
||||
partners and the community to create a standard set of shortcuts that should
|
||||
work across a wide range of Blockly applications, and to encourage adoption.
|
||||
Using standard keyboard shortcuts allows your users to transfer their knowledge
|
||||
to and from other Blockly-based programming environments instead of learning a
|
||||
new set of shortcuts for each tool.
|
||||
|
||||
### Multi-key shortcuts
|
||||
|
||||
Blockly uses single-key shortcuts to support young users without strong
|
||||
keyboarding skills, older users with dexterity impairments, and usage across a
|
||||
wide range of browser/OS combinations.
|
||||
|
||||
Advanced operations and standard actions such as copy and paste require users to
|
||||
press multiple keys at once. If a user cannot press multiple keys at the same
|
||||
time they should use the
|
||||
[sticky keys](https://en.wikipedia.org/wiki/Sticky_keys) setting in their
|
||||
operating system.
|
||||
|
||||
### Teaching shortcuts
|
||||
|
||||
Provide an interactive tutorial to introduce users to
|
||||
[basic keyboard navigation](/guides/configure/web/keyboard-nav#basic-operation).
|
||||
Start users off with only basic operations to reduce cognitive load. At the end
|
||||
of the tutorial, tell users where to look for additional help.
|
||||
|
||||
Blockly's keyboard shortcuts are intended to be useful for all users, not only
|
||||
those with disabilities. Provide information about basic shortcuts in your
|
||||
documentation and instructions for all users. If you provide professional
|
||||
development resources, explicitly train teachers on keyboard shortcuts.
|
||||
|
||||
### Shortcut help
|
||||
|
||||
Make it easy for users to look up shortcuts on their own. To support a wide
|
||||
variety of computers and users, the list of keyboard shortcuts should be
|
||||
available within the Blockly workspace, as a separate web page, and as a
|
||||
printable resource.
|
||||
|
||||
(June 2026): The Blockly team plans to release a plugin that displays the
|
||||
default keyboard shortcuts. If you have additional keyboard shortcuts in Blockly
|
||||
or on your page, you must update your shortcut list accordingly.
|
||||
|
||||
## Vocabulary
|
||||
|
||||
When working with users with visual impairments we recommend that you use
|
||||
tangible resources to introduce vocabulary. The
|
||||
[micro:bit documentation](https://microbit.org/accessibility/visual-impairment/#start-with-cut-out-cards)
|
||||
provides good examples.
|
||||
|
||||
## Zoom
|
||||
|
||||
Enable [resizing up to 200%](https://www.w3.org/WAI/WCAG22/Understanding/resize-text)
|
||||
through Blockly's [zoom controls](/guides/configure/web/zoom).
|
||||
|
||||
## Colours
|
||||
|
||||
Check your colours against [WCAG contrast standards](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum).
|
||||
If you cannot meet the standards with your default colours and cannot change
|
||||
colours due to published resources, use [themes](/guides/configure/web/appearance/themes)
|
||||
to provide colorblind-friendly modes and high-contrast mode.
|
||||
|
||||
It may also be appropriate to provide a dark mode for your application. You can
|
||||
use themes to change Blockly's colours, but those changes should be synced with
|
||||
settings for the rest of your application.
|
||||
|
||||
If you have an account system, save this information in user preferences.
|
||||
|
||||
## Search
|
||||
|
||||
Provide workspace search and toolbox search to help users jump to blocks.
|
||||
Linear traversal of a workspace or toolbox can be slow and tiring.
|
||||
|
||||
(June 2026): The Blockly team will update the published toolbox search and
|
||||
workspace search plugins to work with v13. You may need custom implementations
|
||||
to fit your application.
|
||||
|
||||
## Skip links
|
||||
|
||||
Provide a [link that jumps directly to the Blockly workspace](https://www.w3.org/WAI/WCAG22/Techniques/general/G1)
|
||||
on each page.
|
||||
|
||||
Provide an "area menu" that allows users to quickly jump between regions of the
|
||||
page (e.g. the block editor and the runtime area). See the "navigating between
|
||||
areas" section of the [Microsoft MakeCode accessibility page](https://makecode.com/accessibility)
|
||||
for an example implementation.
|
||||
|
||||
## Clean up and reflow
|
||||
|
||||
You may choose to force blocks into a single vertical stack, if appropriate for
|
||||
your application. You can do this by automatically reflowing the blocks after
|
||||
each drag by calling `workspace.cleanUp()`.
|
||||
|
||||
Blockly does not need to meet the
|
||||
[WCAG Reflow criterion](https://www.w3.org/WAI/WCAG21/Understanding/reflow)
|
||||
because there is an exception for "content requiring two-dimensional layout".
|
||||
|
||||
Consider carefully when making this choice. The intent of the criterion is to
|
||||
"let users enlarge text and other related content without having to scroll in
|
||||
two dimensions to read". However, in some Blockly applications users explicitly
|
||||
use the two-dimensional layout to structure their code. One example is
|
||||
[this Scratch project](https://scratch.mit.edu/projects/907456472/editor/)
|
||||
where the scripts are positioned to be visible at the same time. In this context
|
||||
a forced vertical layout would make it harder to read the code and require the
|
||||
user to hold more state in their mind when reading or editing. It would also
|
||||
increase the drag distance for most edits.
|
||||
|
||||
An intermediate approach is to prompt users to use the
|
||||
[cleanup shortcut](/guides/configure/web/keyboard-nav#cleanup).
|
||||
|
||||
## Screenreader optimizations
|
||||
|
||||
Suggest that users turn on [screen reader optimizations](/guides/configure/web/screen-reader#screen-reader-optimizations)
|
||||
when they first navigate to the workspace using the keyboard. If you have an
|
||||
account system, save this information so users don't have to set it on every
|
||||
visit.
|
||||
|
||||
## Documentation
|
||||
|
||||
Publish an accessibility page on your product website. Include a statement on
|
||||
the compliance level of your product and links to all of your
|
||||
accessibility-related resources. You can use Blockly's Accessibility
|
||||
Conformance Report (ACR) as a portion of your compliance reporting.
|
||||
+14
-12
@@ -1,10 +1,10 @@
|
||||
---
|
||||
description: How to make your use of Blockly meet accessibility standards. .
|
||||
title: Accessibility compliance
|
||||
description: How to make your use of Blockly meet accessibility standards.
|
||||
title: Compliance
|
||||
image: images/blockly_banner.png
|
||||
---
|
||||
|
||||
# Accessibility Compliance
|
||||
# Compliance
|
||||
|
||||
The [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/)
|
||||
are international standards for the development of accessible web content.
|
||||
@@ -45,10 +45,12 @@ Explanations column describes which customizations the developer must check.
|
||||
|
||||
## Screen reader support
|
||||
|
||||
Blockly provides extensive support for screen reader usage through its keyboard
|
||||
navigation system. As of Blockly v13 (released in June 2026) the core library
|
||||
meets standards for keyboard controls. v13 also includes APIs to support
|
||||
developers in creating accessible custom fields and blocks.
|
||||
Blockly provides extensive support for
|
||||
[screen reader usage](/guides/configure/web/screen-reader) through its
|
||||
[keyboard navigation](/guides/configure/web/keyboard-nav) system. As of Blockly
|
||||
v13 (released in June 2026) the core library meets standards for keyboard
|
||||
controls. v13 also includes APIs to support developers in creating accessible
|
||||
custom fields and blocks.
|
||||
|
||||
Blockly computes text descriptions of blocks and fields for use by screen
|
||||
readers and other assistive technology. By default, descriptions are computed
|
||||
@@ -59,11 +61,11 @@ label generation can take advantage of Blockly's
|
||||
|
||||
### Standard interfaces
|
||||
|
||||
Blockly's screen reader and keyboard navigation systems are based on extensive
|
||||
user research with sighted and visually impaired children. The keyboard
|
||||
shortcuts and vocabulary were selected to balance the needs of novice and
|
||||
advanced users. We recommend that developers use the default key mappings and
|
||||
terms unless they conflict with pre-existing portions of your application.
|
||||
Blockly's screen reader and keyboard navigation systems are based on
|
||||
extensive user research with sighted and visually impaired children. The
|
||||
keyboard shortcuts and vocabulary were selected to balance the needs of novice
|
||||
and advanced users. We recommend that developers use the default key mappings
|
||||
and terms unless they conflict with pre-existing portions of your application.
|
||||
Doing so will allow users to transfer experience between block-based programming
|
||||
environments. Please speak to the Blockly team about your options before
|
||||
diverging from the standard interface.
|
||||
@@ -50,11 +50,38 @@ field value.
|
||||
|
||||
## Advanced operation
|
||||
|
||||
Blockly provides many other keyboard shortcuts, including **I** to get
|
||||
information about the cursor location and **control + enter** (Windows) or
|
||||
**command + enter** (Mac) to open the context menu. Cut, copy/paste, and
|
||||
Blockly provides many other keyboard shortcuts. Cut, copy/paste, and
|
||||
undo/redo all follow conventions for keyboard shortcuts.
|
||||
|
||||
### Toolboxes and flyouts
|
||||
|
||||
Pressing **t** moves focus to the toolbox or flyout. Category toolboxes can be
|
||||
navigated with the **arrow keys** like a standard tree. Pressing **enter** opens
|
||||
the flyout and moves focus to the first block, label, or button.
|
||||
|
||||
The **up and down arrow keys** can be used to navigate within the flyout.
|
||||
**Enter** selects a block and places it on the workspace in move mode.
|
||||
|
||||
### Comments and mutators
|
||||
|
||||
In core Blockly, comments and mutators are bubbles attached to icons on a block.
|
||||
Use the **arrow keys** to navigate to the icon and press **enter** to open the
|
||||
bubble. Focus will move to the bubble. Press **enter** again to edit it, or
|
||||
**m** to move the bubble. Press **escape** to leave the bubble context.
|
||||
Interacting with blocks in a mutator bubble is the same as in the main
|
||||
workspace.
|
||||
|
||||
### Context menu
|
||||
|
||||
Press **control + enter** (Windows) or **command + enter** (Mac) to open the
|
||||
context menu. Use the arrow keys to navigate within the context menu. Keyboard
|
||||
shortcuts are displayed in the context menu.
|
||||
|
||||
### Cleanup
|
||||
|
||||
Press **C** to clean up the workspace by moving all block stacks into a single
|
||||
column with no overlaps, preserving their order on the page.
|
||||
|
||||
## Technical details
|
||||
|
||||
Blockly keyboard navigation uses the [focus system](/guides/configure/web/focus)
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
description: Screen reader support in Blockly
|
||||
title: Screen reader
|
||||
image: images/blockly_banner.png
|
||||
---
|
||||
|
||||
# Screen reader support
|
||||
|
||||
Blockly supports usage with a screen reader starting in Blockly v13. Screen
|
||||
reader support is closely tied to
|
||||
[keyboard navigation](/guides/configure/web/keyboard-nav).
|
||||
|
||||
When developing Blockly's screen reader interactions, a guiding principle was
|
||||
that screen reader users should be able to easily collaborate with sighted
|
||||
users. Collaboration is important for pair programming and debugging. To the
|
||||
maximum extent possible, Blockly should just work when used with a screen
|
||||
reader. This page documents the additional text output that is available to a
|
||||
screen reader user, which is presented in parallel with the visual output.
|
||||
|
||||
## Application role
|
||||
Blockly uses the [`application` ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role)
|
||||
to indicate that it handles all keyboard shortcuts. Block programming cannot
|
||||
be mapped to semantic HTML without losing critical information. For more
|
||||
information on Blockly's approach to accessibility and the justification for
|
||||
this decision, see the [accessibility principles](/guides/design/accessibility)
|
||||
page.
|
||||
|
||||
## Block labels
|
||||
|
||||
Screen readers rely on the [`aria-label` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
|
||||
to name elements that do not have visible labels in the DOM.
|
||||
Block labels must give screen reader users information about where they are in
|
||||
a program and what actions they can take at that location. Blockly dynamically
|
||||
calculates labels for blocks based on the block definition, rendered text, and
|
||||
connected blocks. Blockly also uses the [`aria-roledescription` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription)
|
||||
to describe the shape of the block.
|
||||
|
||||
Screen readers vary in how they present `aria-labels` and
|
||||
`aria-roledescriptions`. The Blockly team tested with JAWS, NVDA, VoiceOver,
|
||||
and ChromeVox during development and selected a labeling strategy that balanced
|
||||
the quirks of these screen readers.
|
||||
|
||||
:::note
|
||||
The best way to explore block labels is to try it yourself on the
|
||||
[Blockly playground](https://raspberrypifoundation.github.io/blockly/packages/blockly/tests/playground.html)
|
||||
with a screen reader enabled.
|
||||
:::
|
||||
|
||||
Block labels are built by combining strings. They may have the following
|
||||
information:
|
||||
- Position: the first block in a stack is labeled "begin stack".
|
||||
- Available connections: "has input", "has inputs", or no information. Both
|
||||
horizontal (value) and vertical (statement) inputs are considered.
|
||||
- Shape: generally "statement", "value", or "container". Statement blocks can
|
||||
be stacked vertically; value blocks can be connected horizontally; container
|
||||
blocks can contain statement blocks.
|
||||
- Block and field text: The contents of the block and selected children, generally read
|
||||
from left to right. The label is derived from the text displayed on the block,
|
||||
meaning that it is automatically internationalized.
|
||||
|
||||
### Extended descriptions
|
||||
|
||||
Screen reader users can replay the block label with **I** or play an extended
|
||||
description with **shift + I**. The extended description contains information
|
||||
about parent blocks. This information is disruptive when reading code linearly
|
||||
but helpful when debugging or reorienting within a program.
|
||||
|
||||
## Fields
|
||||
|
||||
### Built-in fields
|
||||
|
||||
Most editable fields in Blockly have an `aria-role` of `"button"` to indicate
|
||||
that pressing **enter** will open a field editor. Blockly sets more specific
|
||||
ARIA roles for built-in fields when appropriate (e.g. text inputs and
|
||||
checkboxes).
|
||||
|
||||
Blockly's number fields have an HTML input type of `text` rather than `number`.
|
||||
Developers are encouraged to add additional labels and validation about the
|
||||
type of number expected. See the [number field documentation](/guides/create-custom-blocks/fields/built-in-fields/number#accessibility)
|
||||
for more information.
|
||||
|
||||
### Custom fields
|
||||
|
||||
Blockly allows developers to create arbitrarily complex custom fields.
|
||||
Developers are responsible for the accessibility of their custom field editors.
|
||||
|
||||
## Dragging
|
||||
|
||||
During drags Blockly uses an [ARIA live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions)
|
||||
to provide updates on the location of the dragging block. This describes where
|
||||
the block will connect if the drag is immediately confirmed. Updates are
|
||||
generated by both mouse and keyboard drags.
|
||||
|
||||
## Screen reader optimizations
|
||||
|
||||
During testing we found cases where the preferences of screen reader users
|
||||
strongly diverged from the preferences of sighted users. Blockly exposes a
|
||||
"screen reader mode" that enables settings that were preferred by screen reader
|
||||
users. There is no way for Blockly to detect if a screen reader is in use, so
|
||||
users need to explicitly toggle this mode with **control + alt + z** (Windows)
|
||||
or **command + option + z** (Mac). Developers may also expose these options as
|
||||
user preferences for more granular control.
|
||||
|
||||
### Navigation looping
|
||||
|
||||
By default navigating **down** from the last item on a workspace moves the
|
||||
cursor back up to the top of the workspace. This is called "looping". Screen
|
||||
reader users preferred a hard stop, while sighted users preferred looping. In
|
||||
screen reader mode looping is disabled.
|
||||
|
||||
### Audio cues
|
||||
|
||||
By default Blockly does not play sounds when the cursor moves up and down. In
|
||||
screen reader mode tones play when the cursor moves to a new level of
|
||||
indentation.
|
||||
@@ -818,6 +818,11 @@ const sidebars = {
|
||||
label: 'Keyboard navigation',
|
||||
id: 'guides/configure/web/keyboard-nav',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Screen reader',
|
||||
id: 'guides/configure/web/screen-reader',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Colour and accessibility',
|
||||
@@ -1280,7 +1285,12 @@ const sidebars = {
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Compliance',
|
||||
id: 'guides/app-integration/compliance',
|
||||
id: 'guides/app-integration/accessibility/compliance',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Best practices',
|
||||
id: 'guides/app-integration/accessibility/best-practices',
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user