SPS Woodland Design System 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.
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:
- Run
style-dictionary build
to generate files from the token source files. Non-TypeScript outputs go intolib
which is excluded from git, TS outputs go intosrc
and are committed. - Run
vite build
to build the TypeScript exports provided bysrc/index.ts
intolib
. - Run
tsc
with the flag to only emit declarations to generate.d.ts
files inlib
for consumers that are using 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"
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>
- 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
, wherePREFIX
is eitherm
for margin orp
for padding, optionally followed byt
/b
/l
/r
for top/bottom/left/right orx
/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.
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",
}),
]);
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";