USWDS - Disabled mixin: Test for color contrast #5455

mahoneycm · 2023-08-21T19:19:46Z

Summary

Added color contrast checks for disabled tokens. On compilation, USWDS will test disabled element color contrast and provide a fallback color if minimum contrast is not met. If the fallback does not meet minimum requirements, a warning will be provided.

Breaking change

This is not a breaking change.

Related issue

Closes #5427

Related pull requests

Changelog PR →

Preview link

Disabled form elements →

Button outline →

Button outline inverse →

Problem statement

#5402 normalized disabled tokens for users. Users could unintentionally set the tokens to colors with poor contrast, causing disabled elements to lose the necessary context.

Solution

Utilize set-bg-and-color() mixin which includes a contrast check, fallback colors, and warning message if fallback colors are unable to resolve contrast issue.

Important

These tests can only be conducted when background color is known. Elements with disabled colors without a defined background color are still at risk for breaking color contrast.

More information in Further Considerations below

Testing and review

Color contrast failsafe testing:

By default, u-disabled is set to the following:

@mixin u-disabled($bg-color: "disabled-lighter", $text-color: "disabled-dark")

To test, we can update these values to have non-compliant color contrast

Visit _settings-color.scss
Update $theme-color-disabled-dark to match $theme-color-disabled-lighter
- gray-40
Inspect disabled elements in Disabled Forms pattern (http://localhost:6006/?path=/story/patterns-forms--disabled-form-elements).
Color should revert to ink fallback
Update $theme-disabled-lighter to a darker color than $theme-disabled-lighter
- gray-60
Inspect warning in terminal

Testing checklist

Code matches USWDS standard
Disabled styles are tested properly for color contrast
- Fallbacks to ink token
- Displays a warning when fallback fails color contrast
No visual regression

Further Considerations

Toggle

Unknown background colors

For elements with an undefined background color, we could use set-text-from-bg and assume $theme-body-background-color as the color to test against

This would work for (potentially) most cases but is a big assumption.

It could benefit components like checkbox labels or outline buttons, but if those elements are placed in an area with a different background color, we would be testing against the wrong color.

Food for thought. Maybe we can discuss ways to enhance these color contrast tests further down the line.

No mixin parameters used

Now that we've removed the u-disabled parameters from _usa-button, no styles use the optional parameters and the default is used across the board. Its probably fine to maintain the current functionality of the parameters, but flagging in case we want to remove.

Secondary fallback value

I’d like to investigate a secondary fallback for contrast checks.

Currently, if the $preferred-color-token fails contrast checks, it uses the $preferred-fallback-token which is ink by default.

When that token fails the contrast check, we still use the token but provide a warning in the build pipeline.

I’d like to further investigate adding a secondary fallback to test white against the background color. In my mind, if black still fails color contrast, the next reasonable test would be to use white rather than leave black on a dark background.

We do something similar specifically when the background grade is 45

// When $bg-color = 45, serve alternate tokens with color grades of 0 and 100
  // This provides sufficient contrast to pass WCAG AA standards
  @if $bg-grade == 45 and $wcag-target == "AA" {
    $preferred-text-token: "white";
    $fallback-text-token: "black";
  }

This will probably be a second issue/enhancement

…trast

mahoneycm · 2023-08-21T19:23:45Z

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

@@ -68,7 +68,6 @@ $close: map-merge(
    // Placeholder overrides to ensure color contrast compliance accross browsers
    &::placeholder {
      opacity: 1;
-      color: color("disabled-dark");


Browsers set the color for the placeholder via the -webkit-text-fill-color above. Removing this color definition because it seems unnecessary.

…or-contrast

mahoneycm · 2023-08-25T16:34:28Z

@amyleadem Pulled in the latest and it should be ready for review!

mejiaj

Code looks good. I updated the summary to match the changelog statement.

I was able to test:

Colors are set using disable-lighter (background) and disable-dark (text).
Warning appears on compile when contrast is not met.

Assigning PR to @amyleadem for review.

…or-contrast

amyleadem

Thanks for taking this on! Generally this looks good but I’ve flagged some issues in the list below. I consider some of these items to be out of scope and have added a note when I think they don’t need to be blockers for this PR. Curious to hear if you disagree!

…st check

mahoneycm

Thanks @amyleadem ! Here are my thoughts for each of your concerns:

Button outline

Outline buttons can be set to failing contrast ratios (For example, set $theme-color-disabled: “gray-20” and $theme-body-background-color: "white”)

This is related to my note about this only working for components with defined background colors. There’s no way for us to calculate the background color behind transparent element/

Important

These tests can only be conducted when background color is known. Elements with disabled colors without a defined background color are still at risk for breaking color contrast.

We could only assume the background color is the $theme-body-background-color but if the button is placed in a different element/section with a different background, then the check would be invalid.

Consider our Sign In page examples where the background color is set to base-lightest.

What do you think about setting a warning to check the color contrast when it would otherwise fail against $theme-body-background-color?

Checkbox/radio labels

Checkbox and radio can be set to failing contrast ratios (For example, set $theme-color-disabled: “gray-20” and $theme-body-background-color: "white”)

Resolved in 9bb417c and 96a1c21

Additional notes in file comments.

Input mask

.usa-input-mask--content is hard-coded to “gray-50”. Is it possible to run this through our contrast mixins as well?

I believe this is possible using :has(). Since the input and the span are siblings, we need some sort of check to see if the input is disabled. We could consider this as a progressive enhancement as Firefox has begun to support it.

.usa-input-mask {
  display: block;
  position: relative;

  &:has(input:disabled) {
    .usa-input-mask--content {
      @include u-disabled;

      // Needed to maintain input border. Bg color set by input.
      background-color: transparent;
    }
  }
}

Alternatively, we could add a disabled class for usa-input-mask or add styles via JS.

Component icons

Most of the icons are set via add-background-svg which doesn’t check for color contrast.

We could consider replacing this function with add-color-icon which can take an optional $contrast-bg value and can swap the icon for its white variant.

Since these icons are not updated via the mixin or disabled theme colors, maybe we could consider this a potential enhancement beyond the scope of this PR.

What do you think?

mahoneycm · 2023-12-26T17:04:12Z

packages/usa-radio/src/styles/_usa-radio.scss

-  &:disabled,
-  &[aria-disabled="true"] {
-    @include format-input {
-      cursor: not-allowed;
-    }
-    @include format-label {
-      cursor: not-allowed;
-    }
-  }
-


Duplicate styles found in _usa-checkbox.scss.

Moved styles to checkbox-and-radio-colors.scss

Note
It looks like format-input styles were not carried over, but I confirmed that there are no visual regressions after this consolidation.

mahoneycm · 2023-12-26T17:04:28Z

packages/usa-checkbox/src/styles/_usa-checkbox.scss

-  &:disabled,
-  &[aria-disabled="true"] {
-    @include format-input {
-      cursor: not-allowed;
-    }
-    @include format-label {
-      color: color("disabled");
-      cursor: not-allowed;
-
-      @media (forced-colors: active) {
-        color: color(GrayText);
-      }
-    }
-  }
-


Duplicate styles found in _usa-radio.scss.

Moved styles to checkbox-and-radio-colors.scss

Note
It looks like format-input styles were not carried over, but I confirmed that there are no visual regressions after this consolidation.

packages/uswds-core/src/styles/mixins/helpers/checkbox-and-radio-colors.scss

amyleadem

This is looking good! Thanks for the thoughtful responses, @mahoneycm. I had one question about some checkbox/radio styles. I think my other concerns have been addressed. Here are my thoughts:

Button outline - That explanation makes sense. With the transparent background color, I don’t see a way to automate this check. I think we’ll just have to move forward without a contrast check here.
Checkbox/radio - This fix looks good. I confirmed the following:
- There are no visual regressions after consolidating duplicate styles
- I receive a warning when neither “disabled” nor “gray-50” meet contrast requirements
Input mask - To keep things moving, I think we can consider this out of scope.
Component icons - To keep things moving, I think we can consider this out of scope. I vote we open a follow-up issue to consider later.

I'd like to have @mejiaj confirm that the recent changes and discussions.

packages/uswds-core/src/styles/mixins/helpers/checkbox-and-radio-colors.scss

amyleadem · 2024-01-04T20:45:22Z

packages/usa-radio/src/styles/_usa-radio.scss

-  &:disabled,
-  &[aria-disabled="true"] {
-    @include format-input {
-      cursor: not-allowed;
-    }
-    @include format-label {
-      cursor: not-allowed;
-    }
-  }
-


Note
It looks like format-input styles were not carried over, but I confirmed that there are no visual regressions after this consolidation.

amyleadem · 2024-01-04T20:47:07Z

packages/usa-checkbox/src/styles/_usa-checkbox.scss

-  &:disabled,
-  &[aria-disabled="true"] {
-    @include format-input {
-      cursor: not-allowed;
-    }
-    @include format-label {
-      color: color("disabled");
-      cursor: not-allowed;
-
-      @media (forced-colors: active) {
-        color: color(GrayText);
-      }
-    }
-  }
-


Note
It looks like format-input styles were not carried over, but I confirmed that there are no visual regressions after this consolidation.

mejiaj

No visual regressions found with disabled styles. No issues with code.

Added suggestions for improving documentation.

packages/usa-button/src/styles/_usa-button.scss

packages/uswds-core/src/styles/mixins/utilities/_disabled.scss

amyleadem

Looks good to me!

mejiaj

I was able to test different values in following settings:

$theme-color-disabled-family
$theme-color-disabled-lighter
$theme-color-disabled-light
$theme-color-disabled
$theme-color-disabled-dark
$theme-color-disabled-darker

Got a warning on colors that weren't meeting contrast.

Warning: Neither the specified preferred color token (`disabled-dark`) nor the fallback color token (`ink`) have AA contrast on a `disabled-lighter` background. Using `ink`. Please check your source code and project settings.
    packages/uswds-core/src/styles/functions/color/get-color-token-from-bg.scss 65:7  get-color-token-from-bg()
    packages/uswds-core/src/styles/mixins/helpers/set-text-from-bg.scss 14:28         set-text-from-bg()
    uswds-core/src/styles/mixins/helpers/set-text-and-bg.scss 16:3                    set-text-and-bg()
    packages/uswds-core/src/styles/mixins/utilities/_disabled.scss 28:5               u-disabled()
    packages/usa-textarea/src/styles/_usa-textarea.scss 9:5                           @forward
    packages/usa-textarea/src/styles/_index.scss 4:1                                  @forward
    _index.scss 5:1                                                                   @forward
    _index.scss 22:1                                                                  @forward
    packages/uswds/_index.scss 51:1                                                   @forward
    src/stylesheets/uswds.scss 3:1                                                    root stylesheet

Re: input mask

I noticed that issue too and confirmed the value is hardcoded. We should look into ways to improve this in a follow-up issue.

Miskeyceh94 · 2024-02-15T12:09:36Z

#5372

mahoneycm · 2024-02-15T20:50:24Z

Hey there, @Miskeyceh94

Did you mean to leave that comment tagging #5372 ? Was there any additional context you wanted to leave?

Thanks!

Miskeyceh94 · 2024-02-27T00:16:40Z

🥴 Pada Sel, 27 Feb 2024 07.47, Dan O. Williams ***@***.***> menulis:

…

Merged #5455 <#5455> into develop. — Reply to this email directly, view it on GitHub <#5455 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BA3DLOASI3DLPFOTQX4I7RDYVUNJJAVCNFSM6AAAAAA3Y2TR4SVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJRHEZDSMBXGUZTCMA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

mahoneycm added 5 commits August 21, 2023 12:50

Utilize set-text-and-bg mixin within u-disabled to test for color con…

329c61b

…trast

Manually set disabled outline buttons background and color

b7e8307

Add color contrast check for disabled file input

f71a138

Remove unused combobox placeholder color definition

32120ba

Run prettier

950759f

mahoneycm commented Aug 21, 2023

View reviewed changes

mahoneycm mentioned this pull request Aug 21, 2023

USWDS-Site - Disabled color contrast changelog uswds/uswds-site#2254

Merged

mahoneycm requested a review from amyleadem August 21, 2023 20:12

mahoneycm marked this pull request as ready for review August 21, 2023 20:12

mahoneycm marked this pull request as draft August 21, 2023 20:33

mahoneycm added 3 commits August 25, 2023 10:06

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

b584b12

…or-contrast

Add comma to trigger rebuild

4f96471

Remove comma to trigger rebuild

a53a6d4

mahoneycm marked this pull request as ready for review August 25, 2023 16:33

mahoneycm requested a review from mejiaj September 5, 2023 16:11

mejiaj approved these changes Nov 28, 2023

View reviewed changes

mejiaj assigned amyleadem Nov 28, 2023

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

90d6e6e

…or-contrast

amyleadem suggested changes Dec 20, 2023

View reviewed changes

mahoneycm added 2 commits December 26, 2023 11:59

Remove duplicate disabled checkbox and radio styles; add color contra…

9bb417c

…st check

Enhance checkbox + radio contrast check logic

96a1c21

mahoneycm commented Dec 26, 2023

View reviewed changes

Run prettier

379e3f9

mahoneycm requested a review from amyleadem January 2, 2024 15:10

amyleadem suggested changes Jan 4, 2024

View reviewed changes

Replace radio + checkbox 'disabled' colors with -text-color-disabled

264b36b

mahoneycm requested review from mejiaj and amyleadem January 5, 2024 14:40

mejiaj suggested changes Jan 8, 2024

View reviewed changes

packages/usa-button/src/styles/_usa-button.scss Show resolved Hide resolved

packages/uswds-core/src/styles/mixins/utilities/_disabled.scss Outdated Show resolved Hide resolved

Add scss comments

987177b

mahoneycm requested a review from mejiaj January 11, 2024 15:54

amyleadem approved these changes Jan 26, 2024

View reviewed changes

mahoneycm mentioned this pull request Feb 1, 2024

USWDS-Site: Documentation updates for release 3.8.0 uswds/uswds-site#2477

Closed

5 tasks

Format sassdoc comments

a937d98

mejiaj approved these changes Feb 6, 2024

View reviewed changes

mejiaj requested a review from thisisdano February 6, 2024 18:02

thisisdano approved these changes Feb 26, 2024

View reviewed changes

thisisdano merged commit e74ca0b into develop Feb 26, 2024

thisisdano deleted the cm-disabled-color-contrast branch February 26, 2024 23:47

This was referenced Feb 28, 2024

USWDS-Site: Documentation updates for release 3.8.0 uswds/uswds-site#2509

Merged

USWDS: Release 3.8.0 tasks #5797

Closed

thisisdano mentioned this pull request Mar 11, 2024

USWDS 3.8.0 #5812

Merged

SherfeyInv mentioned this pull request Jun 7, 2024

[Snyk] Upgrade @uswds/uswds from 3.7.1 to 3.8.0 SherfeyInv/digitalgov.gov#4

Closed

lane-formio mentioned this pull request Jun 22, 2024

[Snyk] Upgrade @uswds/uswds from 3.8.0 to 3.8.1 formio/uswds-viewer#21

Closed

sennhann29 mentioned this pull request Jul 26, 2024

[Snyk] Upgrade @uswds/uswds from 3.4.1 to 3.8.1 sennhann29/digitalgov.gov#4

Open

lane-formio mentioned this pull request Aug 31, 2024

[Snyk] Upgrade @uswds/uswds from 3.8.0 to 3.8.2 formio/uswds-viewer#25

Merged

FuhuXia mentioned this pull request Sep 26, 2024

[Snyk] Upgrade @uswds/uswds from 3.8.0 to 3.8.2 GSA/datagov-harvester#101

Merged

USWDS - Disabled mixin: Test for color contrast #5455

USWDS - Disabled mixin: Test for color contrast #5455

Uh oh!

Conversation

mahoneycm commented Aug 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Related issue

Related pull requests

Preview link

Problem statement

Solution

Testing and review

Color contrast failsafe testing:

Testing checklist

Further Considerations

Unknown background colors

No mixin parameters used

Secondary fallback value

Uh oh!

mahoneycm Aug 21, 2023

Choose a reason for hiding this comment

Uh oh!

mahoneycm commented Aug 25, 2023

Uh oh!

mejiaj left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

mahoneycm left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Button outline

Checkbox/radio labels

Input mask

Component icons

Uh oh!

mahoneycm Dec 26, 2023

Choose a reason for hiding this comment

Uh oh!

amyleadem Jan 4, 2024

Choose a reason for hiding this comment

Uh oh!

mahoneycm Dec 26, 2023

Choose a reason for hiding this comment

Uh oh!

amyleadem Jan 4, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

amyleadem Jan 4, 2024

Choose a reason for hiding this comment

Uh oh!

amyleadem Jan 4, 2024

Choose a reason for hiding this comment

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Re: input mask

Uh oh!

Miskeyceh94 commented Feb 15, 2024

Uh oh!

mahoneycm commented Feb 15, 2024

mahoneycm commented Aug 21, 2023 •

edited

Loading

mejiaj left a comment •

edited

Loading

mahoneycm left a comment •

edited

Loading