[a11y-defect-2]: VA Button disabled prop must be true or undefined | null for Voice Access to work correctly

[1Copenut]

Point of contact

@1Copenut

Severity level

2, Serious. Should be fixed in 1-2 sprints post-launch.

Details

I discovered several <VaButton> components would not honor the MS Voice Access command to "Click button name" during an audit of VA Benefit Letters. I root caused the issue to how the disabled prop is being updated in the component.

Right now, VA Button takes in a Boolean prop disabled with a default value of false. This prop is used to set the correct aria-disabled state of true | false.

Where this becomes a problem is in how Microsoft Voice Access understands the web component's declaration disabled=false. According to the HTML 5 spec, disabled is a Boolean attribute. Its only acceptable values are to exist (true) or not (null, undefined). When we set disabled to false, browsers are able to overcome the issue, but assistive technologies are not always. In this case, the confusion is causing Microsoft Voice Control to ignore click commands entirely.

Reproduction steps

1. These steps assume Windows 11, using Microsoft Voice Access
2. Add an example <VaButton> component to a test page
3. Set prop disabled={false} in a hard-coded value for easy testing
4. Add a custom click handler that logs something simple like "Clicked me!"
5. Open the page in a web browser and turn on MS Voice Access
6. Say "Click BUTTON_TEXT" and verify the button is not clicked
7. Comment out the disabled prop in code and reload the page
8. Repeat steps 5 and 6. Verify the button was clicked as expected.

Proposed solution or next steps

The default value false needs to be updated to undefined for this component. Users should only be adding the disabled prop when they need to disable a button and use logic to ensure the only values it can receive are true | null | undefined.

// Product team implementation

const isDisabled = myCustomLogic ? true : undefined;

<VaButton
  disabled={isDisabled}
  text={buttonText}
  onClick={this.downloadLetter}
/>

! VA Button, lines 48-51

/**
  * If `true`, the click event will not fire.
  */
- @Prop({ reflect: true }) disabled?: boolean = false;
+ @Prop({ reflect: true }) disabled?: (true | undefined | null) = undefined;

References, articles, or WCAG support

1. HTML 5 spec for Boolean attributes
2. StackOverflow: disabled={true} HTML button attribute does not work right in JavaScript...
3. PR #92357 local prop override

Type of issue

• Axe-core
• Screenreader | assistive tech & device support
• Keyboard
• Zoom
• Color, typography, & visual elements
• Components and pattern standards
• Content organization
• Focus
• Headings
• Content style guide
• Link and button labels
• Semantic HTML
• Markup and metadata
• Non-text content and media
• Overall user experience
• Cognitive | user flows & navigating
• URL standards
• Something else