From 83a976a8df7842f7bddac9e47a37c002cfa04f26 Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Fri, 1 May 2026 13:52:07 -0700 Subject: [PATCH 1/3] chore: add accessibility section for extending a built-in field --- .../fields/customizing-fields/extending.mdx | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx index f7557c30d2a..0657d771ff2 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx @@ -72,3 +72,28 @@ static fromJson(options) { For more information about registering a field see the [JSON and registration](/guides/create-custom-blocks/fields/customizing-fields/creating#json-and-registration) section in Creating a Custom Field. + +## Accessibility + +You are responsible for ensuring that your custom fields are WCAG compliant and +correctly implement `IFocusableNode`. That includes having an appropriate +[ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) +for your on-block display and making your field editor WCAG compliant. + +When the on-block display is focused, its focusable DOM element will have the +`blocklyActiveFocus` or `blocklyPassiveFocus` CSS class added. Blockly defaults +to showing a yellow outline around the focused field. You may override this +behaviour as long as you show [visible focus](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html). + +All fields must have an ARIA type and value, which are used to construct the +[ARIA label](/guides/create-custom-blocks/fields/anatomy-of-a-field#aria-label). +The ARIA label is generally of the form `: `. The ARIA +value defaults to the result of calling `getText` on the field. You must ensure +that the result is meaningful when read with a screen reader. To this end, if +`getAriaValue` returns an invalid representation (i.e. `null` or empty string) +then it should be instead represented using a localization of the text +`empty string` to convey this to the user. + +When extending a built-in field you will inherit its ARIA type and value logic. +You can override the inherited ARIA logic by overriding any of `getAriaTypeName`, +`getAriaValue`, and `computeAriaLabel`. From 89c49ce28a7a5438df28913c7524f3d54cca6203 Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Fri, 1 May 2026 15:54:07 -0700 Subject: [PATCH 2/3] chore: add information about accessibility to the creating a custom field page --- .../fields/customizing-fields/creating.mdx | 55 +++++++++++++++---- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx index e79c4409cbd..8b88f01b480 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx @@ -23,7 +23,7 @@ To create a new field, do the following: 1. [Handle disposal of event listeners](#disposing) (UI disposal is handled for you). 1. [Implement value handling](#value-handling). -1. [Add a text-representation of your field's value, for accessibility](#text). +1. [Add a text-representation of your field's value](#text). 1. Add additional functionality such as: - [An editor](#creating-an-editor). - [On-block display updates](#updating-the-on-block-display). @@ -166,6 +166,25 @@ The requirements of a field's on-block display are: - All DOM elements must be children of the field's `fieldGroup_`. The field group is created automatically. - All DOM elements must stay inside the reported dimensions of the field. +- The root DOM element has an appropriate +[ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques). + + +### Accessibility + +You are responsible for ensuring that your custom fields are WCAG compliant and +correctly implement `IFocusableNode`. That includes having an appropriate ARIA +role for your on-block display and making your field editor WCAG compliant. + +In general, the on-block display for a clickable field should have the ARIA +role `button` to indicate that an action will take place when it is clicked or +activated. + +When the on-block display is focused, its focusable DOM element will have the +`blocklyActiveFocus` or `blocklyPassiveFocus` CSS class added. Blockly defaults +to showing a yellow outline around the focused field. You may override this +behaviour as long as you show [visible focus](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html). + See the [Rendering](/guides/create-custom-blocks/fields/customizing-fields/creating#updating-the-on-block-display) @@ -180,11 +199,13 @@ field's degree symbol) you can append the symbol element (usually contained in a ### Input events -By default fields register tooltip events, and mousedown events (to be used for -showing -[editors](/guides/create-custom-blocks/fields/customizing-fields/creating#creating-an-editor)). -If you want to listen for other kinds of events (e.g. if you want to handle -dragging on a field) you should override the field's `bindEvents_` function. +By default fields register tooltip events, mousedown events, and some keyboard +events. Users can open the field +[editor](/guides/create-custom-blocks/fields/customizing-fields/creating#creating-an-editor) +by tapping or clicking on the field, or by navigating to the field with the +keyboard and pressing `Enter`. If you want to listen for other kinds of events +(e.g. if you want to handle dragging on a field) you should override the field's +`bindEvents_` function. ```js bindEvents_() { @@ -424,12 +445,26 @@ getText() { } ``` +All fields must have an ARIA type and value, which are used to construct the +ARIA label. The ARIA label is generally of the form `: `. +The ARIA value defaults to the result of calling `getText` on the field. You +must ensure that the result is meaningful when read with a screen reader. To +this end, if getAriaValue returns an invalid representation (i.e. `null` or +empty string) then it should be instead represented using a localization of the +text empty string to convey this to the user. + ## Creating an editor -If you define the `showEditor_` function, Blockly will automatically listen for -clicks and call `showEditor_` at the appropriate time. You can display any HTML -in your editor by wrapping it one of two special `div`s, called the -`DropDownDiv` and `WidgetDiv`, which float above the rest of Blockly's UI. +If you define the `showEditor_` function, Blockly will automatically call +`showEditor_` and move focus into the editor when the field is activated. +You can display any HTML in your editor by wrapping it one of two special +`div`s, called the `DropDownDiv` and `WidgetDiv`, which float above the rest of +Blockly's UI. + +You are responsible for the accessibility of your field editor, including +setting [ARIA roles and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques). +When possible you should use [semantic HTML](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Accessibility/HTML) +inside the `WidgetDiv` or `DropdownDiv`. :::info Updates to an editor's display should be handled during From 33ce4c7c9233e046e821122e0258ce7e5ba496d1 Mon Sep 17 00:00:00 2001 From: Rachel Fenichel Date: Mon, 4 May 2026 13:11:31 -0700 Subject: [PATCH 3/3] chore(docs): better phrasing about getAriaValue --- .../fields/customizing-fields/creating.mdx | 22 ++++++++++++++----- .../fields/customizing-fields/extending.mdx | 21 +++++++++++------- 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx index 8b88f01b480..d2b00e7b238 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx @@ -445,13 +445,23 @@ getText() { } ``` +### ARIA value + All fields must have an ARIA type and value, which are used to construct the -ARIA label. The ARIA label is generally of the form `: `. -The ARIA value defaults to the result of calling `getText` on the field. You -must ensure that the result is meaningful when read with a screen reader. To -this end, if getAriaValue returns an invalid representation (i.e. `null` or -empty string) then it should be instead represented using a localization of the -text empty string to convey this to the user. +[ARIA label](/guides/create-custom-blocks/fields/anatomy-of-a-field#aria-label). +The ARIA label is generally of the form `: `. When +extending a built-in field you will inherit its ARIA type and value logic. +You can override the inherited ARIA logic by overriding any of `getAriaTypeName`, +`getAriaValue`, and `computeAriaLabel`. + +`getAriaValue` must return a human-readable, screen reader–appropriate +representation of the field’s current value. By default, it returns the result +of `getText`, which is not guaranteed to be informative for assistive +technologies. You must override `getAriaValue` when `getText` might not produce +a meaningful spoken representation (for example, when possible values include +symbols, abbreviations, or non-textual representations such as icons or colors). +If `getAriaValue` would return an empty or non-informative value, it must +instead return a localized string indicating that the value is empty. ## Creating an editor diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx index 0657d771ff2..a99759381c9 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/extending.mdx @@ -87,13 +87,18 @@ behaviour as long as you show [visible focus](https://www.w3.org/WAI/WCAG22/Unde All fields must have an ARIA type and value, which are used to construct the [ARIA label](/guides/create-custom-blocks/fields/anatomy-of-a-field#aria-label). -The ARIA label is generally of the form `: `. The ARIA -value defaults to the result of calling `getText` on the field. You must ensure -that the result is meaningful when read with a screen reader. To this end, if -`getAriaValue` returns an invalid representation (i.e. `null` or empty string) -then it should be instead represented using a localization of the text -`empty string` to convey this to the user. - -When extending a built-in field you will inherit its ARIA type and value logic. +The ARIA label is generally of the form `: `. When +extending a built-in field you will inherit its ARIA type and value logic. You can override the inherited ARIA logic by overriding any of `getAriaTypeName`, `getAriaValue`, and `computeAriaLabel`. + +### ARIA value vs text + +`getAriaValue` must return a human-readable, screen reader–appropriate +representation of the field’s current value. By default, it returns the result +of `getText`, which is not guaranteed to be informative for assistive +technologies. You must override `getAriaValue` when `getText` might not produce +a meaningful spoken representation (for example, when possible values include +symbols, abbreviations, or non-textual representations such as icons or colors). +If `getAriaValue` would return an empty or non-informative value, it must +instead return a localized string indicating that the value is empty.