From 413bc13cc444260dedcf4d00d80dfad868dacee8 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 2 Mar 2026 16:10:06 +1000 Subject: [PATCH] Docs: DOC-2621 - Accessibility page improvements - Add How to use the editor section with keyboard navigation shortcuts - Document Ctrl+F9 for focusing contextual toolbar (e.g. editing image alt-text) - Explain menus vs toolbars and when to use each - Add screen reader guidance (VoiceOver, JAWS, NVDA) and Help plugin link - Add keywords metadata and intro paragraph - Fix help_accessibility heading format and HTML capitalization in examples --- modules/ROOT/pages/accessibility.adoc | 5 +++ .../accessibility-keyboard-navigation.adoc | 41 +++++++++++++++++++ .../configuration/help_accessibility.adoc | 6 +-- .../configuration/iframe_aria_text.adoc | 2 +- 4 files changed, 50 insertions(+), 4 deletions(-) create mode 100644 modules/ROOT/partials/configuration/accessibility-keyboard-navigation.adoc diff --git a/modules/ROOT/pages/accessibility.adoc b/modules/ROOT/pages/accessibility.adoc index b330dba244..2bdd180e96 100644 --- a/modules/ROOT/pages/accessibility.adoc +++ b/modules/ROOT/pages/accessibility.adoc @@ -2,6 +2,11 @@ :navtitle: Accessibility :description_short: Configure the accessibility of TinyMCE. :description: Configure the accessibility of TinyMCE. +:keywords: accessibility, keyboard navigation, screen reader, a11y + +This page describes configuration options that affect how {productname} supports keyboard users and screen readers. For guidance on using the editor with the keyboard, see the xref:accessibility.adoc#how-to-use-the-editor[How to use the editor] section that follows. + +include::partial$configuration/accessibility-keyboard-navigation.adoc[] include::partial$configuration/a11y_advanced_options.adoc[] diff --git a/modules/ROOT/partials/configuration/accessibility-keyboard-navigation.adoc b/modules/ROOT/partials/configuration/accessibility-keyboard-navigation.adoc new file mode 100644 index 0000000000..7298e4371d --- /dev/null +++ b/modules/ROOT/partials/configuration/accessibility-keyboard-navigation.adoc @@ -0,0 +1,41 @@ +[[how-to-use-the-editor]] +== How to use the editor + +{productname} supports full keyboard navigation. Users can access the menu bar, toolbars, and contextual toolbars without using a mouse. + +=== Menus and toolbars + +The editor provides two main ways to access formatting and editing features: + +* **Menu bar**: Use the menu bar when the desired command is known. Menus group related actions and can be faster to navigate for experienced users. +* **Toolbars**: Use the main toolbar for frequently used actions. Toolbar buttons are visible by default and provide quick access to common formatting options. +* **Contextual toolbars**: Some actions are available only from contextual toolbars that appear when the cursor is on specific content, such as images, links, or tables. + +[TIP] +==== +When a feature appears only in a contextual toolbar (for example, editing alternative text for an image), use the keyboard shortcut to focus the contextual toolbar. See the table below. +==== + +=== Keyboard shortcuts for editor navigation + +[cols="1,2,2",options="header"] +|=== +|Action |Windows or Linux |macOS +|Focus the menu bar |Alt+F9 |⌥+F9 +|Focus the toolbar |Alt+F10 |⌥+F10 +|Focus the element path (footer) |Alt+F11 |⌥+F11 +|Focus notifications |Alt+F12 |⌥+F12 +|Focus the contextual toolbar |Ctrl+F9 |Ctrl+F9 +|Open the Help dialog |Alt+0 |⌥+0 +|=== + +The contextual toolbar appears when the cursor is on content that has context-specific actions, such as an image or a link. For example, to edit alternative text for an image using only the keyboard: + +. Place the cursor on the image. +. Press Ctrl+F9 (Windows, Linux, or macOS) to focus the contextual toolbar. +. Use the arrow keys to move to the desired button (for example, *Image options* or *Alternative description*). +. Press Enter or Space to activate the button. + +=== Screen readers + +{productname} works with common screen readers, including VoiceOver (macOS and iOS), JAWS, and NVDA. The xref:help.adoc[Help] plugin provides a Keyboard Navigation tab that documents the full keyboard navigation model. When the Help plugin is loaded, the shortcut to open the Help dialog (Alt+0 or ⌥+0) appears in the status bar by default. diff --git a/modules/ROOT/partials/configuration/help_accessibility.adoc b/modules/ROOT/partials/configuration/help_accessibility.adoc index 12c6e2017e..3d49359b78 100644 --- a/modules/ROOT/partials/configuration/help_accessibility.adoc +++ b/modules/ROOT/partials/configuration/help_accessibility.adoc @@ -1,5 +1,5 @@ [[help_accessibility]] -== `help_accessibility` +== `+help_accessibility+` When the xref:help.adoc[Help] plugin is loaded, the {productname} editor displays the keyboard shortcut for accessing the Help dialog in the {productname} status bar by default. @@ -16,7 +16,7 @@ The `help_accessibility` option allows for this display to be turned off. [source,js] ---- tinymce.init({ - selector: "textarea", // change this value according to your html + selector: "textarea", // change this value according to your HTML plugins: "help", help_accessibility: false, }); @@ -31,7 +31,7 @@ It is not necessary, but may be useful, to explicitly set the option to `true`. [source,js] ---- tinymce.init({ - selector: "textarea", // change this value according to your html + selector: "textarea", // change this value according to your HTML plugins: "help", help_accessibility: true, }); diff --git a/modules/ROOT/partials/configuration/iframe_aria_text.adoc b/modules/ROOT/partials/configuration/iframe_aria_text.adoc index 44bfd64e5a..330013f17e 100644 --- a/modules/ROOT/partials/configuration/iframe_aria_text.adoc +++ b/modules/ROOT/partials/configuration/iframe_aria_text.adoc @@ -19,7 +19,7 @@ The `+title+` attribute is read by screen-readers to help users identify the edi [source,js] ---- tinymce.init({ - selector: 'textarea', // change this value according to your html + selector: 'textarea', // change this value according to your HTML iframe_aria_text: 'Text Editor' }); ----