diff --git a/packages/button/src/vaadin-button.d.ts b/packages/button/src/vaadin-button.d.ts index 09d1479308..fb1ae0aeb6 100644 --- a/packages/button/src/vaadin-button.d.ts +++ b/packages/button/src/vaadin-button.d.ts @@ -38,16 +38,16 @@ import { ButtonMixin } from './vaadin-button-mixin.js'; */ declare class Button extends ButtonMixin(ElementMixin(ThemableMixin(ControllerMixin(HTMLElement)))) { /** - * When set to true, prevents all user interactions with the button such as - * clicking or hovering, and removes the button from the tab order, which - * makes it unreachable via the keyboard navigation. + * When disabled, the button is rendered as "dimmed" and prevents all + * user interactions (mouse and keyboard). * - * While the default behavior effectively prevents accidental interactions, - * it has an accessibility drawback: screen readers skip disabled buttons - * entirely, and users can't see tooltips that might explain why the button - * is disabled. To address this, an experimental enhancement allows disabled - * buttons to receive focus and show tooltips, while still preventing other - * interactions. This feature can be enabled with the following feature flag: + * Since disabled buttons are not focusable and cannot react to hover + * events by default, it 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 makes disabled buttons focusable and hoverable, while still + * preventing them from being triggered: * * ``` * // Set before any button is attached to the DOM. diff --git a/packages/button/src/vaadin-button.js b/packages/button/src/vaadin-button.js index f13ed5edec..6789bb0bb1 100644 --- a/packages/button/src/vaadin-button.js +++ b/packages/button/src/vaadin-button.js @@ -53,16 +53,16 @@ class Button extends ButtonMixin(ElementMixin(ThemableMixin(ControllerMixin(Poly static get properties() { return { /** - * When set to true, prevents all user interactions with the button such as - * clicking or hovering, and removes the button from the tab order, which - * makes it unreachable via the keyboard navigation. + * When disabled, the button is rendered as "dimmed" and prevents all + * user interactions (mouse and keyboard). * - * While the default behavior effectively prevents accidental interactions, - * it has an accessibility drawback: screen readers skip disabled buttons - * entirely, and users can't see tooltips that might explain why the button - * is disabled. To address this, an experimental enhancement allows disabled - * buttons to receive focus and show tooltips, while still preventing other - * interactions. This feature can be enabled with the following feature flag: + * Since disabled buttons are not focusable and cannot react to hover + * events by default, it 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 makes disabled buttons focusable and hoverable, while still + * preventing them from being triggered: * * ``` * // Set before any button is attached to the DOM. diff --git a/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts b/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts index 2b878936aa..a870609c43 100644 --- a/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts +++ b/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts @@ -102,18 +102,16 @@ export declare class MenuBarMixinClass { * * #### Disabled buttons * - * When a root-level item (menu bar button) is disabled, it prevents all user - * interactions with it, such as focusing, clicking, opening a sub-menu, etc. - * The button is also removed from tab order, which makes it unreachable via - * the keyboard navigation. + * When disabled, menu bar buttons (root-level items) are rendered + * as "dimmed" and prevent all user interactions (mouse and keyboard). * - * While the default behavior effectively prevents accidental interactions, - * it has an accessibility drawback: screen readers skip disabled buttons - * entirely, and users can't see tooltips that might explain why the button - * is disabled. To address this, an experimental enhancement allows disabled - * menu bar buttons to receive focus and show tooltips, while still preventing - * other interactions. This feature can be enabled with the following feature - * flag: + * Since disabled buttons are not focusable and cannot react to hover + * events by default, it 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 makes disabled buttons focusable and hoverable, while still + * preventing them from being triggered: * * ``` * // Set before any menu bar is attached to the DOM. diff --git a/packages/menu-bar/src/vaadin-menu-bar-mixin.js b/packages/menu-bar/src/vaadin-menu-bar-mixin.js index 652fee7339..f3f2d60af5 100644 --- a/packages/menu-bar/src/vaadin-menu-bar-mixin.js +++ b/packages/menu-bar/src/vaadin-menu-bar-mixin.js @@ -80,18 +80,21 @@ export const MenuBarMixin = (superClass) => * * #### Disabled buttons * - * When a root-level item (menu bar button) is disabled, it prevents all user - * interactions with it, such as focusing, clicking, opening a sub-menu, etc. - * The button is also removed from tab order, which makes it unreachable via - * the keyboard navigation. + * When disabled, menu bar buttons (root-level items) are rendered + * as "dimmed" and prevent all user interactions (mouse and keyboard). * - * While the default behavior effectively prevents accidental interactions, - * it has an accessibility drawback: screen readers skip disabled buttons - * entirely, and users can't see tooltips that might explain why the button - * is disabled. To address this, an experimental enhancement allows disabled - * menu bar buttons to receive focus and show tooltips, while still preventing - * other interactions. This feature can be enabled with the following feature - * flag: + * Since disabled buttons are not focusable and cannot react to hover + * events by default, it 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 makes disabled buttons focusable and hoverable, while still + * preventing them from being triggered: + * + * ``` + * // Set before any menu bar is attached to the DOM. + * window.Vaadin.featureFlags.accessibleDisabledButtons = true; + * ``` * * ``` * // Set before any menu bar is attached to the DOM.