Tech Agnostic Design Tokens

[jcklpe]

USWDS currently has design tokens. Well sorta. USWDS is built to be as neutral and themable as possible, but the design tokens aren't actually included in the SASS files, from what I understand. They seem to more like key variables intended to be used to theme on top of the USWDS after the fact.

I think it would be worthwhile considering actually building out the design tokens in a more tech agnostic fashion, as the true root of the USWDS and not merely an optional utility.

When I say as a "true root" and tech agnostic I mean like this:

https://specifyapp.com/blog/introduction-to-design-tokens

I've been doing a lot of work trying to get USWDS as a standard adopted within my organization under USCIS, and I think that pulling out design tokens in a more abstracted and robust way would do a lot for making it easier for orgs to organize this stuff.

As it exists currently, the USWDS is a design system with a very specific implementation in a Component Library. And the devs pay attention to the Component Library and nothing else, confusing the two. Some companies have done very basic ports of the styles from that Component Library to React implementations etc, but all this is pretty hacky. With truly tech agnostic design tokens this would be much easier to handle and the foundation of design decisions -> design tokens -> implementation would be much cleaner.

[thescientist13]

Great idea!

Did this at my last company wherein we managed our tokens in a JSON file then had a build script that would generate CSS classes, CSS variables, and SASS variables and published that all to our internal NPM registry.

As a building block, this allowed lots of teams to opt in across the organization and across tech stacks:

1. Those already using our official component library based on Angular Material could just keep using the SASS output. In fact, we just made it a dependency of our main theming system so for most teams, they never really had to interact / feel this change at all.
2. Marketing sites using a CMS could just grab the CSS variables / classes for brand colors, fonts, etc, and not the components (though that was also something they could work up to as we explored Web Components). If they had a build pipeline or not, no worries they could pick the right integration for their needs, including just copy / pasting raw CSS.
3. For our company, mergers and acquisitions were a thing and not everyone was on the same tech stack as you would expect. As one of the first tasks for any of these new products was to adopt the company branding ASAP, this approach allowed these teams to adopt our company branding without having to go through a bunch of hoops or convert to Angular or SASS, etc.

Anyway, just wanted to share some anecdotal experience on this topic.

[mejiaj]

These are all great points! Currently, only colors are available as JSON and that's used for internal development. You can view that here.

This is something we'd like to offer in the future. Are there any tools that you found useful when converting tokens to JSON and then generating CSS/SASS?

[thescientist13]

Just NodeJS and a couple of for loops. 😃

[jcklpe]

We haven't yet got design tokens fully pulled into our development pipeline. Right now we're just using them as a version controlled reference spec. But I've done similar things in the past using nodejs.

[sawyerh]

@mejiaj Two tools that come to mind, that I think touch on what you're asking:

• https://github.com/amzn/style-dictionary
• https://github.com/salesforce-ux/theo

For uswds-theme.dev, I created a script using PostCSS to pull the USWDS design tokens out of the Sass files

[mejiaj]

Thanks for these resources! Also, wow that USWDS theme project looks great 😻.

[jcklpe]

@mejiaj : just read a quick article lauding style dictionary: https://www.bekk.christmas/post/2021/21/why-i-love-style-dictionary-and-why-you-should-too

It looks pretty good and flexible!

[jcklpe]

I thought this article was useful in outlining why distinguishing between a Design System and Component Library is helpful:
https://engineering.udacity.com/choosing-the-right-component-library-for-your-design-system-mui-vs-chakra-45c4c949d150

[mgifford]

Love the "New hotness" category. Surely someone has looked at building digital assets for XR in the .gov space and wondered how they would align.

Makes sense to try to be technology agnostic.

[jcklpe]

This tool might be useful for this work:
https://tokencss.com/

I've also previously posted here about Style Dictionary which has a similar function I believe:
https://www.bekk.christmas/post/2021/21/why-i-love-style-dictionary-and-why-you-should-too

[mejiaj]

Thanks for providing those links! We've definitely discussed this as a future task so getting more information is always helpful.