Summary

• Fixed configuration errors with disabled color settings. All disabled color settings should now be configurable and accept hex color values.
• Updated disabled settings names to match other state colors. Updated default disabled color settings values and added $theme-color-disabled-lighter and $theme-color-disabled-darker.
• Added "disabled-lighter" and "disabled-darker" color tokens. Also updated the default values for all disabled tokens.

Breaking change

⚠️ This is a breaking change. The names and values of disabled settings and tokens have changed and will need to be updated according to the table below if they are used in your project. All disabled states must meet minimum color contrast requirements for text (4.5:1).

Related issue

Closes #5334

Related pull requests

Changelog PR

Preview link

Disabled form elements page

Problem statement

1. $theme-color-disabled-text, $theme-color-disabled-text-reverse, and $theme-color-text-on-disabled settings return a module loop error for any custom configuration.

$theme-color-disabled-light: "magenta-10", //compiles
$theme-color-disabled: "magenta-10", //compiles
$theme-color-disabled-dark: "magenta-10", //compiles
$theme-color-disabled-text: "magenta-10", //module loop error
$theme-color-disabled-text-reverse: "magenta-10", //module loop error
$theme-color-text-on-disabled: "magenta-10", //module loop error

2. Unlike other state color settings like $theme-color-success and $theme-color-error, the disabled color settings do not accept hex values.

$theme-color-disabled-light: #fffff, //compiles (but not currently used in the system)
$theme-color-disabled: #333333, //error: not a token
$theme-color-disabled-dark: #333333, //compiles (but not currently used in the system)
$theme-color-disabled-text: #333333, //error: not a token
$theme-color-disabled-text-reverse: #333333, //error: not a token
$theme-color-text-on-disabled: #333333, //error: not a token

Solution

1. Added the !default flag to these settings to make them configurable in projects.
2. Created new disabled color shortcodes and used them to replace the $theme-color-disabled- references in the Sass. Using shortcodes enables the system to accept hex code values for these settings.
3. Renamed the disabled color settings to match the convention in other state colors ("lighter", "light", "dark", etc). This adds flexibility to the use of these settings.

Settings updates

Warning
The settings do not create a warning when color combinations do not meet contrast standards. Recommend we open a new issue to address this.
Update: I've opened issue #5427 to address this.

Testing and review

• Confirm that all disabled settings are configurable
• Confirm that all disabled settings accept hex code values
• Confirm that the updated settings names make sense and match convention
• Confirm that all $theme-color-disabled- references in Sass have been updated to shortcodes
• Confirm that all new tokens work in the color function
• Confirm no visual regressions

To test configuration:

1. In a test project, install this branch
2. In your project, configure USWDS by adding hex values to the following settings. Example:

@use "uswds-core" with (
    $theme-color-disabled-lighter: #999999, 
    $theme-color-disabled-light: #888888, 
    $theme-color-disabled: #777777,
    $theme-color-disabled-dark: #555555,
    $theme-color-disabled-darker: #444444,
);

3. Confirm that Sass compiles without errors.