chore(docs): add accessibility best practices and screen reader docs

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 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.

packages/docs/docs/guides/app-integration/compliance.mdx → 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.
@@ -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.

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)

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. 

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',
@@ -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',
             },
           ],
         },