docs: explain how to make disabled buttons accessible (#4077)

Co-authored-by: Russell J.T. Dyer <6652767+russelljtdyer@users.noreply.github.com>

Author: vursen

articles/components/button/index.adoc

@@ -2,9 +2,9 @@
 tab-title: Usage
 layout: tabbed-page
 title: Button
-page-title: Button component | Vaadin components
-description: The Button component allows users to perform actions. It comes in several different style variants and supports icons as well as text labels.
-meta-description: The Vaadin component Button allows users to perform actions. It comes in several different style variants and supports icons as well as text labels.
+page-title: Button Component | Vaadin Components
+description: The Button component allows users to perform actions. It comes in several different style variants and supports icons, as well as text labels.
+meta-description: The Vaadin component Button allows users to perform actions. It comes in several different style variants and supports icons, as well as text labels.
 page-links:
   - 'API: https://cdn.vaadin.com/vaadin-web-components/{moduleNpmVersion:@vaadin/button}/#/elements/vaadin-button[TypeScript] / https://vaadin.com/api/platform/{moduleMavenVersion:com.vaadin:vaadin}/com/vaadin/flow/component/button/Button.html[Java]'
   - 'Source: https://github.com/vaadin/web-components/tree/v{moduleNpmVersion:@vaadin/button}/packages/button[TypeScript] / https://github.com/vaadin/flow-components/tree/{moduleMavenVersion:com.vaadin:vaadin}/vaadin-button-flow-parent[Java]'
@@ -120,6 +120,7 @@ endif::[]
 
 Primary danger buttons should only be used when a dangerous action is the most likely action. An example of this would be the affirmative *Delete* action in a deletion confirmation dialog. Secondary and Tertiary variants can be used for actions related to current errors, such as resolving them or viewing their details.
 
+
 [role="since:com.vaadin:vaadin@V24.5"]
 === Warning Variant
 
@@ -150,6 +151,7 @@ include::{root}/frontend/demo/component/button/react/button-warning.tsx[render,t
 endif::[]
 --
 
+
 === Size Variants
 
 The following size variants are available for Button instances whose size needs to be different from the default:
@@ -291,7 +293,6 @@ The *Tertiary + Contrast* combination should be avoided because of similarity to
 The standard Button colors can be adjusted using <<{articles}/styling/lumo/lumo-style-properties/color#,the Lumo color properties>>. Therefore, these variants shouldn't be used to replace standard buttons only to achieve a different color.
 
 
-
 == Buttons with Icons
 
 Buttons can have icons instead of text, or they can have icons along with text.
@@ -332,7 +333,6 @@ Additionally, [since:com.vaadin:vaadin@V23.3]##<<../tooltip#,tooltips>>## can be
 Use the `icon` / `LUMO_ICON` theme variant on icon-only buttons to reduce the white space on either side of the icon. The Flow `Button` component automatically applies the `icon` variant if the icon is the only child of the component.
 
 
-
 == Buttons with Images
 
 Images on buttons can be used like icons. See the icon usage recommendations for more information.
@@ -365,7 +365,7 @@ endif::[]
 
 == Disabled
 
-Buttons representing actions that aren't currently available to the user should be either hidden or disabled. A disabled button is rendered as "dimmed", and is excluded from the focus order. This may be useful when you don't want interactive UI elements to receive the focus using the tab key.
+Buttons representing actions that aren't currently available to the user should be either hidden or disabled. A disabled button is rendered as "dimmed".
 
 [.example]
 --
@@ -393,14 +393,33 @@ endif::[]
 --
 
 
-=== Hidden vs. Disabled
+=== Focus & Hover
 
-Hiding entirely an unavailable action is often preferable to a disabled button, as this reduces UI clutter. However, in certain situations, this can be problematic. If the user expects a button to be present -- such as at the end of a form -- hiding the button can cause confusion, even if the form clearly shows the presence of one or more invalid fields. Also, since a hidden button doesn't occupy any space in the UI, toggling its visibility can cause unwanted changes in the layout of other elements.
+By default, disabled buttons are not focusable and cannot react to hover events. This can cause accessibility issues by making them entirely invisible to assistive technologies, and prevents the use of Tooltips to explain why the action is not available. This can be addressed by enabling the feature flag `accessibleDisabledButtons`, which allows you to focus and hover on disabled buttons, while preventing them from being triggered:
 
+[.example]
+--
+.`Flow`
+[source,properties]
+----
+# Add this line to src/main/resources/vaadin-featureflags.properties
+com.vaadin.experimental.accessibleDisabledButtons=true
+----
 
-=== Show Error on Click
+.`Lit & React`
+[source,js]
+----
+// Set before any button is added to the DOM
+window.Vaadin.featureFlags.accessibleDisabledButtons = true;
+----
+--
+
+
+=== Alternatives to Disabling
 
-As an alternative to hiding or disabling buttons, configure instead unavailable actions to show an error message when the button is clicked by using a <<../notification/index#,Notification>> or an adjacent inline text element. This approach is the most accessible option, but may be frustrating to users who expect unavailable actions to be distinguished somehow from available actions.
+The most obvious alternative to disabling a button is to hide it. This reduces UI clutter, but can cause confusion since the user won't know where to watch for the button once the action it represents becomes available. There's also a risk of undesired layout shifts in the UI when the button appears.
+
+Another option is to keep the button visible and enabled, but show an error, e.g. using a Notification, when it's clicked. This option is best combined with some custom styling of the button to give the user a hint that the action is unavailable.
 
 
 === Prevent Multiple Clicks
@@ -433,7 +452,6 @@ endif::[]
 --
 
 
-
 == Focus
 
 As with other components, the focus ring is only rendered when the button is focused by keyboard or programmatically.
@@ -456,6 +474,7 @@ include::{root}/frontend/demo/component/button/react/button-focus.tsx[render,tag
 endif::[]
 --
 
+
 === Auto Focus
 
 Buttons can receive keyboard focus automatically when the UI in which they appear is rendered.
@@ -544,6 +563,7 @@ include::{root}/frontend/demo/component/button/react/button-labels.tsx[render,ta
 endif::[]
 --
 
+
 === Buttons in Forms
 
 Buttons in forms should be placed below the form with which they're associated. They should be aligned left, with the primary action first, followed by other actions, in order of importance.

articles/components/menu-bar/index.adoc

@@ -2,9 +2,9 @@
 tab-title: Usage
 layout: tabbed-page
 title: Menu Bar
-page-title: Menu Bar component | Vaadin components
+page-title: Menu Bar Component | Vaadin Components
 description: Menu Bar is a horizontal button bar with hierarchical drop-down menus.
-meta-description: Learn how to implement the Vaadin Menu Bar component in your Vaadin applications and how you can customize it for a better user experience.
+meta-description: Learn how to implement the Vaadin Menu Bar component in Vaadin applications and how you can customize it for a better user experience.
 page-links:
   - 'API: https://cdn.vaadin.com/vaadin-web-components/{moduleNpmVersion:@vaadin/menu-bar}/#/elements/vaadin-menu-bar[TypeScript] / https://vaadin.com/api/platform/{moduleMavenVersion:com.vaadin:vaadin}/com/vaadin/flow/component/menubar/MenuBar.html[Java]'
   - 'Source: https://github.com/vaadin/web-components/tree/v{moduleNpmVersion:@vaadin/menu-bar}/packages/menu-bar[TypeScript] / https://github.com/vaadin/flow-components/tree/{moduleMavenVersion:com.vaadin:vaadin}/vaadin-menu-bar-flow-parent[Java]'
@@ -160,6 +160,7 @@ endif::[]
 [NOTE]
 In versions prior to 24.3, theme names must be used instead  of class names (`theme` property / `addThemeNames` Java method). The CSS syntax for targeting a theme name is `[theme~="custom-theme"]`
 
+
 [role="since:com.vaadin:vaadin@V24.5"]
 === Drop-down Indicators
 
@@ -254,7 +255,6 @@ include::{root}/src/main/java/com/vaadin/demo/component/menubar/MenuBarIcons.jav
 ----
 endif::[]
 
-
 ifdef::react[]
 [source,tsx]
 ----
@@ -331,6 +331,25 @@ include::{root}/frontend/demo/component/menubar/react/menu-bar-disabled.tsx[rend
 endif::[]
 --
 
+By default, disabled buttons (i.e., root-level items) are not focusable and cannot react to hover events. This can cause accessibility issues by making them entirely invisible to assistive technologies, and prevents the use of Tooltips to explain why the action is not available. This can be addressed by enabling the feature flag `accessibleDisabledButtons`, which allows focusing and hovering on disabled buttons, while preventing them from being triggered:
+
+[.example]
+--
+.`Flow`
+[source,properties]
+----
+# Add this line to src/main/resources/vaadin-featureflags.properties
+com.vaadin.experimental.accessibleDisabledButtons=true
+----
+
+.`Lit & React`
+[source,js]
+----
+// Set before any button is added to the DOM
+window.Vaadin.featureFlags.accessibleDisabledButtons = true;
+----
+--
+
 
 === Checkable Menu Items