Adding Design Tokens

This styleguide uses Design Tokens to generate styles as well as a documentation.
It uses Style Dictionary under the hood.
All tokens are defined in JSON files.

Adding and generating new design tokens is done as follows:

  • Find the design token files inside their respective folders in config/design-tokens/.
  • You can either add a new object or just a new property to the JSON file.
  • To add a new token file, add a folder named after the token you wish to create and add a base.json file inside of it as its sole content.
    The main token object will be referenced by a property that has the exact same name as its parent folder.
    So, if you add a new token file, its folder parent folder will be named "example-token" and the outermost property of the JSON object will have to be named "example-token" as well.
  • Run the generate:tokens npm script to generate any new tokens.
  • Tokens get generated in two locations, in a different format for each, detailed in the usage section below.

Usage

SCSS

You'll find them in assets/css/base-styles/design-tokens/generated-files/, in an SCSS format.
If a new token file was added, go to the folder, find the _index.scss SASS partial and add the new token file to the list by importing it.
If you merely added a new token to an existing file, you can just run generate:tokens npm script and be done wit it.
These files are used to define SASS maps that will be used for every single value definition in our SCSS.

Go to /framework/settings/_custom-variables.scss and define a new map for each parent key in the base token map found in the generated design token files.

Use the map-deep-get function to get to the child-map inside the base token map.

Please add a reference to a new SCSS child-map if a nested object was added to the original JSON token file.

Token values are to be rendered using these maps only.


// custom map definition
// in assets/css/base-styles/design-tokens/generated-files/_color.scss
// find the $token-color map

$token-color: (
  'color': (
	'brand': (
	  'primary': (
		'10': $color-brand-primary-10,
		'30': $color-brand-primary-30,
		'60': $color-brand-primary-60,
		...
	  ),
	  'secondary': (
		...

	  )
	),
	'products': (
		...
	),
	'gray': (
		...
	)
  )
);

// usage example

// reassign the $token-color map to a custom map like below
// the custom map name ALWAYS starts with "$token" and ends in "-map"
$token-color-brand-map: map-deep-get($token-color,"color","brand");

// this lets you access data more easily without having to type out every child-map key.
// use it like so:
.element {
	background-color: map-deep-get($token-color-brand-map, "secondary", "10");
}

JSON

You'll find them in config/design-tokens-generated-config, in a JSON format.
If a new token file was added, go to ./docs/docs.config.js and reference it in the docs config context object. If a new token file was added OR child-map was added, go to docs/design-tokens/ and add the necessary loops to display token data in dedicated file.

These generated JSON token files are used for the documentation instead of the original ones because they contain all a lot more meta data. You can for instance have access to the resolved alias (referenced) values as well as the original value for any given token.


Docs config usage: 


// aliases are added for convenience
// only add if necessary
const PATHS = {
	DESIGN_TOKENS_GENERATED_PATH: path.join(config.paths.configFolder,config.paths.generatedTokensFolder),
	...
}

// add token map reference
const spacingTokens = require(path.join('..',PATHS.DESIGN_TOKENS_GENERATED_PATH,'spacing.json'));
...

// add to doc context config to be able to reference data throughout doc files
module.exports = {
	context: {
		paths: PATHS,
		namespace: namespace,
		colorTokens : colorTokens,
		...
	}
}

Token documentation page generation: 


// if new token, create page with token name inside docs/design-tokens
// if new child-map, add loop to existing token documentation page

// spacer example


<h2>Unit</h2>
<table>
	<tr>
		<th>Variable name</th>
		<th>Value</th>
	</tr>
	// accolades were replaced by parentheses to prevent loop from generating HTML
	(% for key, spacing in spacingTokens.unit %)
		<tr>
			<td style="font-weight: bold">
				$spacer-unit-(( key ))
			</td>
			<td>
				(( spacing.value ))
			</td>
		</tr>
	(% endfor %)
</table>