From 1627e43c0d34895508acf94e208f90b0892e1250 Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Tue, 19 May 2026 18:18:45 -0700 Subject: [PATCH 1/4] chore(docs): add accessibility section under app integration --- .../app-integration/{ => accessibility}/compliance.mdx | 6 +++--- packages/docs/sidebars.js | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) rename packages/docs/docs/guides/app-integration/{ => accessibility}/compliance.mdx (98%) diff --git a/packages/docs/docs/guides/app-integration/compliance.mdx b/packages/docs/docs/guides/app-integration/accessibility/compliance.mdx similarity index 98% rename from packages/docs/docs/guides/app-integration/compliance.mdx rename to packages/docs/docs/guides/app-integration/accessibility/compliance.mdx index 399d3d92e11..a312823d1fc 100644 --- a/packages/docs/docs/guides/app-integration/compliance.mdx +++ b/packages/docs/docs/guides/app-integration/accessibility/compliance.mdx @@ -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. diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index 627ab67dc45..84192c3b288 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -1280,7 +1280,7 @@ const sidebars = { { type: 'doc', label: 'Compliance', - id: 'guides/app-integration/compliance', + id: 'guides/app-integration/accessibility/compliance', }, ], }, From 821c741c863118c735207cf393dcbcbf5b5069af Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Wed, 20 May 2026 17:48:13 -0700 Subject: [PATCH 2/4] chore(docs): add information about accessibility best practices and screen reader usage --- .../accessibility/best-practices.mdx | 141 ++++++++++++++++++ .../accessibility/compliance.mdx | 20 +-- .../guides/configure/web/keyboard-nav.mdx | 33 +++- .../guides/configure/web/screen-reader.mdx | 115 ++++++++++++++ packages/docs/sidebars.js | 10 ++ 5 files changed, 307 insertions(+), 12 deletions(-) create mode 100644 packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx create mode 100644 packages/docs/docs/guides/configure/web/screen-reader.mdx diff --git a/packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx b/packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx new file mode 100644 index 00000000000..0bbb28c6fcc --- /dev/null +++ b/packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx @@ -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 os 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. \ No newline at end of file diff --git a/packages/docs/docs/guides/app-integration/accessibility/compliance.mdx b/packages/docs/docs/guides/app-integration/accessibility/compliance.mdx index a312823d1fc..6d1ceb82604 100644 --- a/packages/docs/docs/guides/app-integration/accessibility/compliance.mdx +++ b/packages/docs/docs/guides/app-integration/accessibility/compliance.mdx @@ -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. diff --git a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx index 51b3805326a..c3d881ecd9a 100644 --- a/packages/docs/docs/guides/configure/web/keyboard-nav.mdx +++ b/packages/docs/docs/guides/configure/web/keyboard-nav.mdx @@ -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) diff --git a/packages/docs/docs/guides/configure/web/screen-reader.mdx b/packages/docs/docs/guides/configure/web/screen-reader.mdx new file mode 100644 index 00000000000..e5b59d40e8b --- /dev/null +++ b/packages/docs/docs/guides/configure/web/screen-reader.mdx @@ -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. \ No newline at end of file diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index 84192c3b288..87ba07b7a3d 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -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', @@ -1282,6 +1287,11 @@ const sidebars = { label: 'Compliance', id: 'guides/app-integration/accessibility/compliance', }, + { + type: 'doc', + label: 'Best practices', + id: 'guides/app-integration/accessibility/best-practices', + } ], }, { From e5ca0a53b52f9885f373c3c8bace5e4a71cd977c Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Thu, 21 May 2026 08:34:17 -0700 Subject: [PATCH 3/4] chore(docs): fix formatting --- packages/docs/sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index 87ba07b7a3d..6107783557a 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -1291,7 +1291,7 @@ const sidebars = { type: 'doc', label: 'Best practices', id: 'guides/app-integration/accessibility/best-practices', - } + }, ], }, { From a06eb079eab8d28ad3008eca5b0f2daa778ac6c7 Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Thu, 21 May 2026 13:10:14 -0700 Subject: [PATCH 4/4] chore(docs): fix typo --- .../guides/app-integration/accessibility/best-practices.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx b/packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx index 0bbb28c6fcc..422f5ee42a3 100644 --- a/packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx +++ b/packages/docs/docs/guides/app-integration/accessibility/best-practices.mdx @@ -130,7 +130,7 @@ An intermediate approach is to prompt users to use the 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 os users don't have to set it on every +account system, save this information so users don't have to set it on every visit. ## Documentation