CSS Library: Which USWDS color tokens should be added

[jamigibbs]

Description

This could be worked on in tandem with:

• CSS Library: How to import/pass-through specific USWDS tokens? #1967

This purpose of this work is to begin identifying which USWDS color tokens we would like to offer from the CSS Library:

• https://github.com/uswds/uswds/tree/develop/packages/uswds-tokens/colors
• https://designsystem.digital.gov/utilities/color/

Tasks

• Review the USWDS color tokens and determine which ones we want to offer from the CSS Library

Acceptance Criteria

• We understand which USWDS color tokens we would like added to the CSS Library token file(s)

[humancompanion-usds]

Short answer is: None.

CSS Library should only offer the VA namespaced tokens. Teams will continue to not have direct access to the 1,000+ USWDS color palette. That said, in v3, all of our color tokens should point to USWDS primitive token values. But the CSS library shouldn't get access to those directly. As we define more semantic tokens we'll grow the color palette available to teams. Also, teams will be able to request that we bring a USWDS value into our system. But both of those will be done slowly and with great care.

I think we can close this? Let me know if you have questions.

[micahchiang]

Here is my understanding of what this ticket is trying to ask: What USWDS color token values should be added?

The css-library currently has a color.json token file with primitive values mapped to VA brand colors. For example:

    "primary": {
      "*": { "value": "#0071bb"},
      "darker": { "value": "#003e73"},
      "darkest": { "value": "#112e51"},
      "alt": {
        "*": { "value": "#02bfe7"},
        "dark": { "value": "#00a6d2"},
        "darkest": { "value": "#046b99"},
        "light": { "value": "#9bdaf1"},
        "lightest": { "value": "#e1f3f8"}
      }
    },

These tokens are used to build VA namespaced sass variables, many of which are used throughout Formation and vets-website:

$color-primary: #0071bb;
$color-primary-darker: #003e73;
$color-primary-darkest: #112e51;
$color-primary-alt: #02bfe7;
$color-primary-alt-dark: #00a6d2;
$color-primary-alt-darkest: #046b99;
$color-primary-alt-light: #9bdaf1;
$color-primary-alt-lightest: #e1f3f8;

Using the USWDS3 theme tokens page as a reference for this example, in the instance where all of our primary blues are updated to align with USWDS3, we would theoretically want to pull in these tokens using whatever method is implemented in #1967, and use their primitive values instead of what's in our color.json token file:

Private Zenhub Image

A potential process might look like:

1. Query USWDS for primary blues tokens
2. Run them through some intermediary step which uses the USWDS3 color function to retreive their primitive values. Edit: Or we may not even need this helper function 🤷
3. Assign the primitives to our VA namespaced sass variables

Note: we'd have to determine which of the USWDS blues align most with our namespacing, on first pass it looks like we use at least a couple more blues

So, USWDS tokens are never directly used or available to teams, but their values are as assignments to our existing sass variables. vets-website scss would still use VA namespaced variables ($color-primary, $color-primary-darker, etc.) but the hex values would come from USWDS3:

 // uswds3 'primary' hex value
$color-primary: #005ea2;
// uswds3 'primary-dark' hex value
$color-primary-darker: #1a4480;
// uswds3 'primary-darker' hex value
$color-primary-darkest: #162e51;

With this, I feel like the answer to this ticket is: we want the primary blues from uswds3, and just to throw another potential set out there, maybe we'd want some greens? I know chunk of things on VA.gov use $color-green or its corresponding utility class: vads-u-color--green

[humancompanion-usds]

Ah, okay, I follow now. I'm defining the tokens in issue #1973. The VA tokens will point to USWDS token values and I'll define them all for you to add. My goal is to have the color tokens done today. The spacing tokens are there.

[caw310]

closing as we will reference #1973 mentioned above.