Discovery: Style Dictionary

[caw310]

Description

Do discovery work on a style dictionary to define design tokens that allows you to export them to be used in other tools and to use code right out of component library. Should be able to use the design tokens in Sketch, UXPin and Figma.

Details

Tasks

• Research style dictionary to define design tokens that allows you to export them to be used in other tools. use code right out of component library.
• Share findings with DST (designers, developers and PO)
• Make a recommendation and write any necessary follow up tickets

Acceptance Criteria

• Make a recommendation on next steps
• Write any necessary follow up tickets

[humancompanion-usds]

Being able to support react-native has emerged as a requirement for the Mobile app team. I was able to generate a react-native variables file for them (I have the transform on a branch but haven't pushed it up yet). Their feedback was:

Generally speaking, that format is fine, but we can’t use the unit-base spacing like export const unitsNeg1p5 = "-1.2rem"; The React Native version of that would be -19.2 (if my math is correct and they’re using a base of 16), but totally fine, I understand why it’s generated like that (for the Web). The biggest thing for us in there is the color hexcodes anyway.

They can also just output a JSON format for us to consume, we’ll ultimately remap the variables anyway. With the JSON format we can also try and worm it into Figma to sharing at that level.

I did provide a pointer to our JSON token files. Tim on the mobile team is the person to talk to (I'll get his details and add it here).

[jamigibbs]

Hi @timwright12! I've started to do some discovery work for generating different token formats. Style Dictionary does provide some pre-made transforms to help us generate one for React Native but reading Matt's comment above, it sounds like it might need some additional work?

Here is an example of what that pre-made transform outputs for our tokens to react-native.

export const colorBase = "#212121";
export const colorWhite = "#ffffff";
export const colorBlack = "#000000";
export const colorOrange = "#eb7f29";
export const colorLinkDefault = "#004795";
export const colorWarningMessage = "#fac922";
export const colorGibillAccent = "#fff1d2";
export const colorPrimary = "#0071bb";
....etc

And this is an example they've provided on how to use that in a react-native project: https://github.com/amzn/style-dictionary/blob/main/examples/advanced/create-react-native-app/src/App.js#L4

import * as variables from "./style-dictionary-dist/variables";

export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Testing! Testing!</Text>
      <Text style={styles.p}>All done!</Text>
      <StatusBar style="auto" />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: variables.colorBrand01,
    alignItems: "center",
    justifyContent: "center",
  },
  title: {
    fontSize: PixelRatio.getFontScale() * variables.sizeFontMd.scale,
    color: variables.colorBrand02,
  },
  p: {
    fontSize: PixelRatio.getFontScale() * variables.sizeFontSm.number,
    color: variables.colorBrand02,
  },
});

If the tokens don't look exactly right for your needs, we should be able to do custom filtering or even create our own custom transforms but I wanted to check in with you first to see if that was even necessary based on the output we're receiving above.

[timwright12]

Hey @jamigibbs! In chatting with Matt the React Native output was great, but we also wanted to request that the JSON format be available just for flexibility of use.

For the individual tokens, hexcodes will work. For font sizing a spacing are you all able to use the same format as the example? {"original":"16px","number":16,"decimal":0.16,"scale":256}; If so, that's great. When I was looking through the VADS tokens it looked like there were unit values on the sizing (rem, px, etc). That's the part we can't use. If 1rem is listed in the tokens, we would need 16 to use it in React Native.

This: export const fontSizeH3 = "2rem";
would need to be: export const fontSizeH3 = "32";

For us, just being able to use the colors is awesome, so if we can also use the sizing that'd be a bonus.

[jamigibbs]

Thanks @timwright12! I think it would be a pretty straightforward effort for us to make those modifications. Here's a quick POC with a couple of custom transforms that will convert rem and remove px from matching values.

And we can output that as either json or js formats (or both!):

• react-native/tokens.js
• react-native/tokens.json

I think that's gets you everything you need?

[timwright12]

JSON + React Native should do it. Transforms look good too! Thank you!

[jamigibbs]

Discovery Notes

CSS Library Quick Overview

The CSS Library has two types of resources available:

1. Design tokens (css/scss/json/js)
2. Utility classes (stylesheets)

The design tokens are what this discovery has focused on.

Can we generate different token formats for React Native, UXPin, Sketch, etc?

With style-dictionary, we should be able to generate any format that we need. They provide a number of pre-defined formats, transform groups, and transforms. And if those pre-defined formats don't get us exactly what we want, we can create our own custom formats or custom transforms.

React Native

The mobile team are a good example of needing something more custom than what style-dictionary can provide. They need rem values converted to pixel and no units appended to the value (ie. fontSize: 1rem would be fontSize: 16). They also are requesting the tokens in js and json formats (see convo above).

A working example of this has been added to the discovery PR which includes two custom transforms: https://github.com/department-of-veterans-affairs/component-library/pull/766/files#diff-79ccf6c33f36bac9578b5a05b5b76e3b80ae31b308d1ee41f941bb8fd449ebb0

Figma

An NPM package exists that we could use for Figma: style-dictionary-to-figma. I connected this package and generated a tokens file with it as part of this discovery work but this will need to be verified that it's working as expected as part of the development ticket.

The Figma documentation says that you can import/use that file just by linking to its public source.

UXPin

Looking at some UXPin tutorials, I believe we can import a standard tokens CSS file directly into the service and it will automatically generate those values.

I don't have access to a UXPin dashboard to verify this though (or found any specific UXPin documentation that confirms) but with the flexibility of style-dictionary, I believe we could make adjustments as needed.

Sketch

Importing tokens into Sketch might be more complicated. There are some Sketch plugins we could leverage (colors specifically) but we might need to create our own custom Sketch plugin in order to import all tokens (color, fonts, and spacing).

The CMS Design system did build their own Sketch plugin but it seems like it's only handling color tokens so I'm not sure why they couldn't use one of the pre-made plugins.

  const colorSwatches = makeColorSwatches(tokenData.color);
  colorSwatches.forEach((swatch) => {
    doc.swatches.push(swatch);
  });

Do we need more than color tokens in sketch? If not, then I believe we can just use one of the pre-made sketch plugins.

How do we organize all of this

With so many different token file types (including some with the same file extension), I propose we organize based on the interface it's meant to be used with:

packages
└── css-library
    ├── config.js             -- style-dictionary config file
    ├── package.json          -- commands for generating CSS Library (tokens and stylesheets)
    ├── dist                  -- generated token files and stylesheets
    │   ├── css
    │   │   └── tokens.css    -- general use tokens in css format
    │   ├── figma
    │   │   └── tokens.json   -- figma tokens processed with a transform
    │   ├── json
    │   │   └── tokens.json   -- general use tokens in json format
    │   ├── react-native
    │   │   ├── tokens.json   -- react-native tokens processed with custom transforms
    │   │   └── tokens.js     -- react-native tokens processed with custom transforms
    │   └── scss
    │       └── tokens.scss   -- general use tokens in scss format
    ├── src                   -- classes for generating utility stylesheets
    └── tokens                -- the design tokens to be generated
        ├── colors.json
        ├── fonts.json
        └── spacing.json

Example usage in the component-library

We can start using the generated tokens file now in the component library if we'd like. We will just need publish the latest updates to NPM and add the package.

The existing _variables.css file should be removed and the css tokens file imported.

@import '~@department-of-veterans-affairs/css-library/dist/css/tokens.css';

When can everyone start using the CSS Library token files?

We probably first will want to figure out how the releases are going to work for the component library repo now that we have both the component-library and css-library. We are not going to want updates to the CSS Library included in the release notes for the component-library. They are two separate packages and releases.

Some discovery work was already started to explore publishing multiple packages in a monorepo which I think we need to revisit. We left off wanting to do some additional discovery work with Lerna: #1068

Follow-up tickets

1. Discovery: Re-evaluate component-library package releases (test lerna) - Figure out how to enable separate release and release notes for this package - Discovery: Publishing multiple packages from the component-library repo #1068
   • Ticket Created: Formation Deprecation - Step 1 - Discovery: Publishing multiple packages from the component-library #1954
2. Prepare css-library package run scripts. Generate css, sass, and general json token files. Reference the discovery PR.
   • Ticket Created: CSS Library: Setup and generate CSS, SCSS, and JSON token files #1955
3. Generate the react-native token files (js & json). Reference the discovery PR.
   • Ticket Created: CSS Library: Generate the react-native token files #1956
4. Generate the Figma token file. Reference the discovery PR.
   • Ticket Created: CSS Library: Generate a Figma token file #1957
5. Generate a UXPin token file (check with UXPin team for format by probably something standard)
   • Ticket Created: CSS Library: UXPin token file #1958
6. Generate a Sketch token file (might require a custom plugin)
   • Ticket Created: CSS Library: Generate token file for Sketch #1959
7. How to import/pass through specific USWDS color tokens?
   • Ticket Created: CSS Library: How to import/pass-through specific USWDS tokens? #1967
8. What tokens should we allow from USWDS in the CSS Library?
   • Ticket Created: CSS Library: Which USWDS color tokens should be added #1968

Other planning or discovery needed?

• Create a manual release of the CSS Library (until we figure out monorepo package publishing) and replace the static _variables.css/scss files in the component-library.
• Do we need to explore how or when we are introducing the utility classes?
  • Document new CSS utility classes  #1790
• We have placeholders for fonts and elements stylesheets.
  • Generating @font-face rules with style-dictionary

Other Useful Links

• Plan - Design System CSS Utility Class Library Rebuild
• Discovery for design token library