@sps-woodland/tokens

SPS Woodland Design System design tokens

1. What are design tokens?
2. How this package works
3. Available Formats
   1. JavaScript/TypeScript
   2. CSS
   3. vanilla-extract
   4. Sass

What are design tokens?

Design tokens are the primitives of a design system. They are a record of design decisions - font sizes, spacing values, border radii, etc. - in a format that is both human and machine readable. They are the single source of truth from which consumable artifacts can be generated, such as CSS classes, palettes for design tools, or XML files for mobile app development.

How this package works

The token source files are located in the src/tokens directory. To generate consumables from them, we use a tool called Style Dictionary, developed by Amazon. The Style Dictionary configuration is at the package root, config.js. Style Dictionary comes with a number of built-in formats that can be generated, and it's also easy to add your own. In src/formats you will find the custom formats we've created.

Style Dictionary also has a concept of "transforms" which apply to the token values. For example, you might want to define your colors using hex in the source files, but output hsla format in the generated consumables. Each format comes with a default group of transforms. In our case, we are modifying the transform groups we're using with a custom one treat size values in the source as pixels and convert that to rem in the output. (The default is to treat size tokens' values as rem and simply append "rem" to them for the output.)

Additionally, we have vanilla-extract sprinkles where the file that defines them is not generated, but that file imports a file that is generated that contains the tokens in an object whose shape is tailored to what the sprinkle definitions need.

This means that the build process follows a series of stages in a particular order:

1. Run style-dictionary build to generate files from the token source files. Non-TypeScript outputs go into lib which is excluded from git, TS outputs go into src and are committed.
2. Run vite build to build the TypeScript exports provided by src/index.ts into lib.
3. Run tsc with the flag to only emit declarations to generate .d.ts files in lib for consumers that are using TypeScript.

Formats

JavaScript/TypeScript

For JS/TS code, we export a simple object of the token values, along with TypeScript typing for it.

import { tokens } from "@sps-woodland/tokens";

console.log(tokens.size.spacing.lg); // "2rem"

CSS

Two CSS files are provided: one that declares our tokens as CSS custom properties, and one that defines utility classes to apply them. The utility classes are defined using the custom properties, so if you want to use those, you must include both files.

// in index.tsx or App.tsx for your application
import "@sps-woodland/tokens/lib/css/tokens.css";
import "@sps-woodland/tokens/lib/css/utils.css";

/* usage in CSS */
.some-element {
  color: var(--color-blue-medium);
}

// usage in JSX
<div className="mt-sm type-body-md">...</div>

Available utility classes

• Colors, as .COLOR-VARIANT, e.g. .purple-dark or .grey-medium-light
• Background colors, as .bg-COLOR-VARIANT, e.g. .bg-blue-light
• Bootstrap-esque margin and spacing classes, as .PREFIX-SIZE, where PREFIX is either m for margin or p for padding, optionally followed by t/b/l/r for top/bottom/left/right or x/y for x (left + right)/y (top + bottom). E.g.:
  • .my-sm = margin y, small (small spacing for margin-top and margin-bottom)
  • .p-md = padding medium (medium spacing for padding all the way around)
  • .ml-xs = margin left, extra small
• Font weights (.fw-normal and .fw-bold)
• Typography font size + line height combinations, e.g. .type-body-md for medium body type, .type-title-lg for large title type, etc.
• Font sizes and line heights individually, e.g. .fs-body-sm for the small body font size, .lh-title-sm for the small title line height, etc.

vanilla-extract

The tool of the future for UI styles at SPS is vanilla-extract, and as such we are providing our design tokens as sprinkles.

For these to work you will need to import the CSS file that goes along with them in your index or main App component:

import "@sps-woodland/tokens/lib/vanilla-extract/style.css";

Then, in your .css.ts files, you can import our sprinkles and use them per the sprinkles documentation linked above.

import { style } from "@vanilla-extract/css";
import { sprinkles, rem } from "@sps-woodland/tokens";

export const fooClass = sprinkles({
  color: "blue-medium",
  marginTop: "md",
});

// or with additional custom styles - again, see the vanilla-extract docs
export const barClass = style([
  sprinkles({
    color: "red-dark",
    type: "title-xl",
  }),
  /* We also export this utility function for your custom style
   * definitions in vanilla-extract. It will find all the pixel values
   * within and convert them to rem. */
  rem({
    maxWidth: "200px",
  }),
]);

Sass

The consumables for Sass are essentially the same as for CSS. There is a file of Sass variables for our tokens and a file of utility classes defined using those variables.

// in your root scss file
@import "@sps-woodland/tokens/lib/scss/tokens";
@import "@sps-woodland/tokens/lib/scss/utils";