Form Inputs: Normalize disabled forms styles #5063

mahoneycm · 2022-12-06T16:27:58Z

Resolves #5051
Includes work from:
#5004
#5128
#5146

Description

Creates and normalizes disabled styles across USWDS forms.

Breaking change

⚠️ This is potentially a breaking change.

Existing usa-combo-box, usa-date-picker, usa-file-input components with aria-disabled="true" may be affected now that the javascript for each component looks for that attribute during initialization

While we advise against using the usa-button--disabled class, this would break markdown for devs who have implemented it

Related PRs

USWDS Site change log PR →

The Problem

Currently, Chrome and Edge support disabled styles for forms. Both implement a pretty minimal opacity shift to disabled elements to help users understand an element is disabled. The shift is pretty minor:

Enabled vs disabled in Chrome

Safari & Firefox do not offer any visual queues an element is disabled at this time. This can cause

The solution

Create USWDS styles for disabled forms to add visual context for users.

Text Input Disabled

Affected components

All components within the Forms Inputs category on Storybook as well as Button

Updates made

All form controls and buttons have matching disabled and aria-disabled states
- Every disabled element and its overlaid text meets WCAG AA contrast:
  - Disabled backgrounds are defined with $theme-color-disabled ("gray-20")
  - Text on default backgrounds are defined with the new variable: $theme-color-disabled-text (”gray-50”)
  - Text on reverse backgrounds are defined with the new variable: $theme-color-disabled-text-reverse ("gray-40")
  - Text on disabled backgrounds are defined with the new variable: $theme-color-text-on-disabled ("gray-70")
- Disabled styles now receive cursor: not-allowed
- Disabled styles do not show hover states
- Removed all disabled classes (This only applies to user-added disabled styles. Dynamically-added styles are still allowed)
- Dynamically-added disabled styles are triggered for both disabled and aria-disabled
All disabled states are consistently demonstrated in Storybook
- A new Disabled Forms story has been added that shows all disabled form elements on one page
- All disabled/aria-disabled controls in storybook are consistent
- For buttons, aria-disabled is now included in the “show all states” control, which is displayed by default
Input prefix/suffix: removed need for a disabled class
- The CSS was re-written to absolutely position the icons instead of relying on disabled parent class
- Removed index.js and related test files because they were no longer needed (the JS moved focus to the disabled group, which no longer exists
Removed test pattern twig for usa-select—multiple; can rely on standard twig instead

New `disabled` utility mixin

The new u-disabled mixin overrides background-color and cursor styles of elements to display as disabled. Includes overrides for hover, active, and focus states.

Users can pass in $bg-color & $text-color parameters as necessary to add custom colors if needed.

An example of this can be found for usa-button--outline variants to ensure color compliance

@include u-disabled("transparent", $theme-color-disabled-text);

New Disabled Color Tokens

Token Name	Color
`$theme-color-disabled-text`	"gray-50"
`$theme-color-disabled-text-reverse`	"gray-40"
`$theme-color-text-on-disabled`	"gray-70"

Preview

Disabled Forms →

To Test

Visit each of the form components
View disabled variant or turn on disabled and/or aria-disabled
You may need to refreseh the page in order for the components javascript to initialize and the view to update
Confirm:
- disabled elements have a grey background and a not-allowed cursor on hover
- aria-disabled styles mimic disabled styles (Components will still be accessible if not disabled)
- Both style work together and add relative attribute to html code

Notes & Other Considerations

After discussion, we have decided to allow disabled classes that style elements that:

Do not receive the disabled attribute
Are dynamically placed
This will allow us to correctly style elements as disabled without putting the burden on the user.

Further findings from my disabled landscape analysis can be found at #5117

⚠️ We should consider adding new disabled tokens to theme color tokens and create a page for the disabled utility mixin in Utilities

Moving forward, we should also create guidance on our website about accessibility and disabled form elements to assist users in understanding when it is and is not appropriate to use these new styles and mixin

Before you hit Submit, make sure you’ve done whichever of these applies to you:

Follow the 18F Front End Coding Style Guide and Accessibility Guide.
Run npm test and make sure the tests for the files you have changed have passed.
Run your code through HTML_CodeSniffer and make sure it’s error free.
Title your pull request using this format: [Website] - [UI component]: Brief statement describing what this pull request solves.

…x-disable

…ms-styles

…o cm-disabled-forms-styles

…o other components

mejiaj

Double-checked the button and button group styles. No issues found!

amyleadem

All changes since my last approval look good!

…ms-styles

thisisdano

@mejiaj Had a couple observations that are worth addressing, especially the Combo box issue

thisisdano · 2023-05-17T20:59:56Z

packages/usa-combo-box/src/styles/_usa-combo-box.scss

+  &:disabled,
+  &[aria-disabled="true"] {
+    @include u-disabled;
+  }


@mahoneycm I think we need to address this

thisisdano · 2023-05-17T21:02:11Z

packages/usa-file-input/src/index.js

@@ -147,6 +158,11 @@ const buildFileInput = (fileInputEl) => {
    disable(fileInputEl);
  }

+  // Aria-disabled styling
+  if (ariaDisabled) {
+    ariaDisable(fileInputEl);


@mahoneycm We should probably fix this too, if it looks like a simple fix, even though I'd guess this is more of an edge case, having an error state on a disabled element

thisisdano

My comments above came from an incomplete and incorrect understanding of aria-disabled — which is, by design, responsible only for conveying disabled state to screen reader. See this MDN documentation.

Since this PR is about normalizing styles and not about JS, I think we can ignore my comments above and proceed.

mahoneycm added 27 commits October 24, 2022 10:26

Add disabled styles for usa-input and prefix/suffix

5187a92

Add disable previews for prefix/suffix

a0c0928

Update disabled suffix ID

27f837f

Fix disabled input ID

83f5d39

Add quotes to disabled color

123d806

Add disabled style to .usa-textarea:disabled

cb46d4b

Removed textarea style updates that are beyond scope of this work

b2e66b9

Merge branch 'develop' of github.com:uswds/uswds into cm-prefix-suffi…

312c981

…x-disable

Adds disabled styles to text-area and usa-select

a0f03c5

Update disabled input & prefix styles

b3a0e77

Add combo-box disabled styles

6abf1e6

Update file input disabled styles

28a888e

Create range slide disabled styles

a218bb9

Merge branch 'develop' of github.com:uswds/uswds into cm-disabled-for…

ac463d3

…ms-styles

Update date picker disabled cursor

cf18972

Character Count: Add disabled form control

11908f8

Memorable Date: Create dynamic disabled styling

9586aa6

Select: Override disabled opacity

e9ec6ba

Include aria-disabled styles & example

309d0fd

Fix aria-disabled ID's

07b8a68

Fix label for aria-disabled inputs

f62c579

Merge branch 'cm-prefix-suffix-disable' of github.com:uswds/uswds int…

392016b

…o cm-disabled-forms-styles

Include aria-disabled in disabled styles

259ea94

Normalize disabled and aria-disabled options in storybook

f03da8a

Date Picker: Update disabled & aria-disabled controls to be similar t…

58c7b57

…o other components

Memorable date: normalize disabled storybook controls

664e73c

Time Picker: Add disabled example

3d46e95

mahoneycm requested review from amyleadem and mejiaj December 8, 2022 19:53

mahoneycm marked this pull request as ready for review December 14, 2022 14:54

mahoneycm added 2 commits March 29, 2023 16:50

Disabled mixin: Remove usa-button hover & active classes from mixin

686fdd4

Button Disabled: Include hover and active classes in mixin

e7c7f10

mahoneycm requested review from amyleadem and mejiaj April 3, 2023 16:58

mejiaj approved these changes Apr 6, 2023

View reviewed changes

amyleadem approved these changes Apr 6, 2023

View reviewed changes

amyleadem requested a review from thisisdano April 6, 2023 18:50

mahoneycm mentioned this pull request Apr 19, 2023

Removing pointer events from disabled button components. #4435

Closed

brunerae linked an issue May 4, 2023 that may be closed by this pull request

USWDS - Bug: Prefix/suffix does not use disabled input styling #4913

Closed

2 tasks

mahoneycm mentioned this pull request May 5, 2023

USWDS - Site: Change log items for Disabled Forms normalization uswds/uswds-site#2089

Closed

mahoneycm and others added 2 commits May 17, 2023 14:16

Merge branch 'develop' of github.com:uswds/uswds into cm-disabled-for…

52f16cf

…ms-styles

[prettier] Fix whitespace

726d43a

thisisdano suggested changes May 17, 2023

View reviewed changes

[prettier] Remove trailing comma

799076c

thisisdano approved these changes May 17, 2023

View reviewed changes

thisisdano merged commit 70f6c0d into develop May 17, 2023

thisisdano deleted the cm-disabled-forms-styles branch May 17, 2023 22:05

amyleadem mentioned this pull request May 18, 2023

USWDS - Disabled styles: Improve consistency in high contrast mode #5295

Merged

mejiaj mentioned this pull request May 24, 2023

USWDS - Disabled styles: Phase out disabled classes #5116

Closed

thisisdano mentioned this pull request May 25, 2023

Add changelog items for USWDS 3.5.0 uswds/uswds-site#2096

Merged

24 tasks

This was referenced May 31, 2023

Removed file-input-disabled variant from component partial uswds/uswds-site#2113

Closed

Remove file-input-disabled from file-input partial uswds/uswds-site#2114

Merged

thisisdano mentioned this pull request Jun 6, 2023

USWDS 3.5.0 #5323

Merged

mejiaj mentioned this pull request Jul 17, 2023

USWDS-Site: Fix component pages from audit (Phase 1) uswds/uswds-site#2149

Merged

mahoneycm mentioned this pull request Aug 14, 2023

USWDS - Bug: Unused aria_disabled control on Button storybook preview #5436

Closed

2 tasks

amyleadem mentioned this pull request Aug 29, 2023

USWDS - Button: Remove aria_disabled control #5474

Merged

This was referenced Oct 12, 2023

New Circular page has overlapping text in InputGroups nasa-gcn/gcn.nasa.gov#1522

Closed

USWDS - Feature Request: Limited spacing of the InputPrefix results in overlapped text #5558

Open

danbrady mentioned this pull request Mar 1, 2024

Upgrade [email protected] department-of-veterans-affairs/component-library#1070

Merged

1 task

thisisdano mentioned this pull request Jun 7, 2024

USWDS - File input: Remove aria-disabled from from parent wrapper #5144

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Form Inputs: Normalize disabled forms styles #5063

Form Inputs: Normalize disabled forms styles #5063

Uh oh!

mahoneycm commented Dec 6, 2022 •

edited

Loading

Uh oh!

mejiaj left a comment

Uh oh!

amyleadem left a comment

Uh oh!

thisisdano left a comment

Uh oh!

thisisdano May 17, 2023

Uh oh!

thisisdano May 17, 2023

Uh oh!

thisisdano left a comment

Uh oh!

Uh oh!

Form Inputs: Normalize disabled forms styles #5063

Form Inputs: Normalize disabled forms styles #5063

Uh oh!

Conversation

mahoneycm commented Dec 6, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Breaking change

Related PRs

The Problem

The solution

Affected components

Updates made

New disabled utility mixin

New Disabled Color Tokens

Preview

To Test

Notes & Other Considerations

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

thisisdano left a comment

Choose a reason for hiding this comment

Uh oh!

thisisdano May 17, 2023

Choose a reason for hiding this comment

Uh oh!

thisisdano May 17, 2023

Choose a reason for hiding this comment

Uh oh!

thisisdano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mahoneycm commented Dec 6, 2022 •

edited

Loading

New `disabled` utility mixin