fix(button): accessible disabled button (VIV-2798) (#2517)

* chore: accessible disabled button

* chore: adds new pending state tests

* chore: update button disabled selector in styles

* chore: update button disabled selector in styles

* chore: updates guidelines with more info on disabled

* chore: updates split-button and fab with a11y fix for disabled

* chore: update select a11y test results

* chore: updates dismiss class functionality

* chore: linting

* chore: moves click handlers to component class

* Update metadata

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: TaylorJ76

libs/components/metadata.json

@@ -1408,6 +1408,12 @@
 					"args": [],
 					"returnType": "boolean"
 				},
+				{
+					"name": "clickHandler",
+					"description": "Handles click events.\nPrevents interaction when disabled or pending.",
+					"args": [{ "name": "event", "type": "Event" }],
+					"returnType": "unknown"
+				},
 				{
 					"name": "reportValidity",
 					"description": "Return the current validity of the element.\nIf false, fires an invalid event at the element.",
@@ -3979,6 +3985,12 @@
 					"args": [],
 					"returnType": "boolean"
 				},
+				{
+					"name": "clickHandler",
+					"description": "Handles click events.\nPrevents interaction when disabled.",
+					"args": [{ "name": "event", "type": "Event" }],
+					"returnType": "unknown"
+				},
 				{
 					"name": "reportValidity",
 					"description": "Return the current validity of the element.\nIf false, fires an invalid event at the element.",
@@ -7740,7 +7752,20 @@
 				}
 			],
 			"vueModels": [],
-			"methods": [],
+			"methods": [
+				{
+					"name": "handleActionClick",
+					"description": "Handles action click events.\nPrevents interaction when disabled or pending.",
+					"args": [{ "name": "event", "type": "Event" }],
+					"returnType": "unknown"
+				},
+				{
+					"name": "handleIndicatorClick",
+					"description": "Handles indicator click events.\nPrevents interaction when disabled or pending.",
+					"args": [{ "name": "event", "type": "Event" }],
+					"returnType": "unknown"
+				}
+			],
 			"slots": [
 				{ "name": "default", "description": "Default slot." },
 				{

libs/components/src/lib/button/ACCESSIBILITY.md

@@ -10,9 +10,13 @@
 - Always provide an `aria-label` for buttons that contain only an icon.
 - The label is announced by screen readers and communicates the button’s purpose.
 
+### Disabled Buttons
+
+When you set the `disabled` attribute on the Button component, the `aria-disabled` attribute on the button element. This allows the button to receive focus so that it can be announced (as a disabled button) by a screen reader.
+
 ## Best Practices
 
-### Avoid Disabling Buttons
+### Never Put Tooltips/Toggletips on Disabled Buttons
 
 - Disabled buttons cannot receive focus and don’t explain why they can’t be used.
 - Instead, consider keeping the button active and use validation or error messages to guide the user.

libs/components/src/lib/button/GUIDELINES.md

@@ -582,7 +582,7 @@ The smaller size buttons (`condensed` and `super-condensed`) are useful when use
 </docs-do>
 </docs-do-dont>
 
-## Ghost buttons
+## Ghost Buttons
 
 <docs-do-dont>
 <docs-do slot="description" headline="Use ghost buttons inside a container">
@@ -634,16 +634,26 @@ The smaller size buttons (`condensed` and `super-condensed`) are useful when use
 </docs-do>
 </docs-do-dont>
 
-## Disabled
+## Disabled Buttons
 
-<vwc-note connotation="warning" headline="Disabled buttons should be used with caution">
-	<vwc-icon slot="icon" name="warning-line" label="Warning:"></vwc-icon>
+### Why Disabled Buttons Are Problematic
 
-Try to use [progressive disclosure](https://www.nngroup.com/articles/progressive-disclosure/) instead of disabled buttons.
+1. **Cause deception**<br />The call to action text draws users to click, but nothing happens. This causes confusion, leading users to think that the interface is broken.
+2. **Insufficient contrast**<br />Even if the button is disabled, the button label is still crucial for understanding the interface.
+3. **No feedback**<br />Without feedback, users don't know what has gone wrong or how to fix the error.
+4. **System complexity**<br />Disabled buttons are often used to prevent wasteful clicks, but this puts pressure on the design / implementation to provide robust inline validation. The reality is, inline validation systems can fail, leaving the user stuck with a disabled button and no way to complete the form.
 
-</vwc-note>
+### When Disabled Buttons Can Be Useful
+
+While disabled buttons often create more problems than they solve, there are limited scenarios where they can improve the user experience if designed carefully:
+
+1. **Preventing duplicate submissions**<br />After a critical action such as submitting a payment, booking, or form, the button can be temporarily disabled to avoid multiple clicks and duplicate transactions. This should always be paired with visible feedback (e.g., changing the label to “Processing…” and showing a spinner). We have the [`pending` feature](/components/button/#pending) for this situation.
+2. **Communicating temporary unavailability**<br/>Buttons may be disabled while content is loading or while a dependent process finishes (eg. waiting for a verification SMS). This should be short-lived, and the button state must be updated as soon as the action becomes available.
+
+### Best Practices
 
-Ensure that the user is able to understand why the action is disabled and what they need to do to enable it.
+- Always provide visible and accessible feedback when a button is disabled (e.g., helper text, inline validation, or an explanatory tooltip).
+- Prefer inline error messages and contextual feedback over disabling buttons—this often gives a clearer and more usable experience.
 
 ## Related Components
 

libs/components/src/lib/button/VARIATIONS.md

@@ -333,6 +333,13 @@ The spinner is not displayed when using the `super-condensed` size.
 
 The `disabled` attribute disables the buttons and indicates that the action is not available.
 
+<vwc-note connotation="warning">
+	<vwc-icon slot="icon" name="warning-line"></vwc-icon>
+	
+Disabled buttons should be used with caution. Read our [guidelines for when to disabled buttons](/components/button/guidelines/#disabled).
+
+</vwc-note>
+
 ```html preview 72px
 <div class="container">
 	<vwc-button appearance="filled" label="Disabled" disabled></vwc-button>

libs/components/src/lib/button/button.scss

@@ -65,11 +65,11 @@
 		inline-size: 100%;
 	}
 
-	&:not(:disabled) {
+	&:not(.disabled) {
 		cursor: pointer;
 	}
 
-	&:disabled {
+	&.disabled {
 		cursor: not-allowed;
 	}
 

libs/components/src/lib/button/button.spec.ts

@@ -118,6 +118,54 @@ describe('vwc-button', () => {
 			const icon = element.shadowRoot?.querySelector(ICON_SELECTOR) as Icon;
 			expect(icon).toBeInstanceOf(Icon);
 		});
+
+		it('should not emit click when pending', async () => {
+			const listener = vi.fn();
+			element.addEventListener('click', listener);
+
+			element.pending = true;
+			await elementUpdated(element);
+
+			const control = getControlElement(element);
+			control?.click();
+
+			expect(listener).not.toHaveBeenCalled();
+		});
+
+		it('should not emit keyboard activation when disabled (Enter)', async () => {
+			const listener = vi.fn();
+			element.addEventListener('click', listener);
+
+			element.pending = true;
+			await elementUpdated(element);
+
+			const control = getControlElement(element);
+			const event = new KeyboardEvent('keydown', {
+				key: 'Enter',
+				bubbles: true,
+			});
+			control?.dispatchEvent(event);
+
+			expect(listener).not.toHaveBeenCalled();
+		});
+
+		it('should not emit keyboard activation when disabled (Space)', async () => {
+			const listener = vi.fn();
+			element.addEventListener('click', listener);
+
+			element.pending = true;
+			await elementUpdated(element);
+
+			const control = getControlElement(element);
+			const event = new KeyboardEvent('keydown', {
+				key: ' ',
+				code: 'Space',
+				bubbles: true,
+			});
+			control?.dispatchEvent(event);
+
+			expect(listener).not.toHaveBeenCalled();
+		});
 	});
 
 	describe('dropdown-indicator', () => {
@@ -336,7 +384,29 @@ describe('vwc-button', () => {
 			);
 			expect(control).toBeInstanceOf(Element);
 		});
+
+		it('should set aria-disabled on <button> when disabled', async () => {
+			element.disabled = true;
+			await elementUpdated(element);
+
+			const control = getControlElement(element);
+			expect(control?.getAttribute('aria-disabled')).toBe('true');
+		});
+
+		it('should not emit click when disabled', async () => {
+			const listener = vi.fn();
+			element.addEventListener('click', listener);
+
+			element.disabled = true;
+			await elementUpdated(element);
+
+			const control = getControlElement(element);
+			control?.click();
+
+			expect(listener).not.toHaveBeenCalled();
+		});
 	});
+
 	describe('title', function () {
 		it('should set title on the button if set', async () => {
 			const titleText = 'close';
@@ -364,7 +434,6 @@ describe('vwc-button', () => {
 					'ariaAtomic',
 					'ariaBusy',
 					'ariaCurrent',
-					'ariaDisabled',
 					'ariaExpanded',
 					'ariaHasPopup',
 					'ariaHidden',

libs/components/src/lib/button/button.template.ts

@@ -9,16 +9,7 @@ import {
 import { chevronTemplateFactory } from '../../shared/patterns/chevron';
 import type { VividElementDefinitionContext } from '../../shared/design-system/defineVividComponent';
 import { delegateAria } from '../../shared/aria/delegates-aria';
-import type { Button, ButtonAppearance, ButtonSize } from './button';
-
-const getAppearanceClassName = (
-	appearance: ButtonAppearance,
-	disabled: boolean
-) => {
-	let className = `appearance-${appearance}`;
-	disabled && (className += ' disabled');
-	return className;
-};
+import type { Button, ButtonSize } from './button';
 
 const getClasses = ({
 	connotation,
@@ -28,6 +19,7 @@ const getClasses = ({
 	icon,
 	label,
 	disabled,
+	pending,
 	stacked,
 	size,
 	iconSlottedContent,
@@ -38,10 +30,8 @@ const getClasses = ({
 	classNames(
 		'control',
 		[`connotation-${connotation}`, Boolean(connotation)],
-		[
-			getAppearanceClassName(appearance as ButtonAppearance, disabled),
-			Boolean(appearance),
-		],
+		[`appearance-${appearance}`, Boolean(appearance)],
+		['disabled', disabled || pending],
 		[`shape-${shape}`, Boolean(shape)],
 		[`size-${size}`, Boolean(size)],
 		[
@@ -111,7 +101,6 @@ function renderButtonContent(context: VividElementDefinitionContext) {
 	return html` <button
 		class="${getClasses}"
 		?autofocus="${(x) => x.autofocus}"
-		?disabled="${(x) => x.disabled || x.pending}"
 		form="${(x) => x.formId}"
 		formaction="${(x) => x.formaction}"
 		formenctype="${(x) => x.formenctype}"
@@ -124,8 +113,10 @@ function renderButtonContent(context: VividElementDefinitionContext) {
 		title="${(x) => x.title}"
 		${delegateAria({
 			ariaLabel: null,
+			ariaDisabled: (x) => x.disabled || x.pending,
 		})}
 		${ref('control')}
+		@click="${(x, c) => x.clickHandler(c.event)}"
 	>
 		${buttonContent(context)}
 	</button>`;

libs/components/src/lib/button/button.ts

@@ -176,4 +176,16 @@ export class Button extends AffixIconWithTrailing(
 		super();
 		this.title = '';
 	}
+
+	/**
+	 * Handles click events.
+	 * Prevents interaction when disabled or pending.
+	 */
+	clickHandler(event: Event) {
+		if (this.disabled || this.pending) {
+			event.preventDefault();
+			event.stopImmediatePropagation();
+			return;
+		}
+	}
 }

libs/components/src/lib/fab/VARIATIONS.md

@@ -82,8 +82,15 @@ The `size` attribute controls the size of the Fab.
 
 The `disabled` attribute disables the Fab and indicates that the action is not available.
 
+<vwc-note connotation="warning">
+	<vwc-icon slot="icon" name="warning-line"></vwc-icon>
+	
+Disabled buttons should be used with caution. Read our [guidelines for when to disabled buttons](/components/button/guidelines/#disabled).
+
+</vwc-note>
+
 ```html preview
 <vwc-fab disabled>
-	<vwc-icon slot="icon" name="store-line"></vwc-icon>
+	<vwc-icon slot="icon" name="store-line" label="Home"></vwc-icon>
 </vwc-fab>
 ```

libs/components/src/lib/fab/fab.scss

@@ -110,13 +110,13 @@
 		#{variables.$icon-gap}: 10px;
 	}
 
-	&:disabled {
+	&.disabled {
 		@include elevation.elevation(none);
 
 		cursor: not-allowed;
 	}
 
-	&:not(:disabled) {
+	&:not(.disabled) {
 		@include elevation.elevation(4);
 
 		cursor: pointer;