2. Design Application
Overview
Applying your branding and corporate design to kickstartDS is itself done in roughly two steps:
- Use a reduced set of Branding Token to generate your initial Design Token set
- Fine tune the resulting Design Token set to closely fit your corporate identity
Apply branding
Initialization
We start by creating a file branding-token.json, inside a new directory src/token... for everything to do with Design Token going forward:
_10mkdir -p src/token_10touch src/token/branding-token.json
This file will hold all of our Branding Token. Those are used to initialize you first Design Token set, and especially ease first-time setup.
Get the most up-to-date version of its content from here, and paste it into the file you just created:
Use a current version
Be sure to actually copy the file linked above, entering the values yourself. This way you'll be sure not to miss any recently updated token in your set up, in case this guide gets outdated!
Select Branding Token
For a more in-depth overview of those token, have a look at our foundations page about Branding Token, detailing all values in use.
But to get a first feel for working with the file, and to add some flavour to our Design System, we'll change some select values around. And feel free to replace everything with values that seem more appropriate for you, or that fit your particular brand (maybe even because you opted to follow the more detailed guide above). If you're wondering which values we selected for this guide... we're mostly matching our own brand for this guide:
| Preview | Name | Value |
|---|---|---|
primary | #05566a | |
primary-inverted | #ecff00 | |
background | #fff | |
foreground | #050505 | |
link | #5D5DD5 | |
link-inverted | #C6C6FF | |
informative | #05566a | |
informative-inverted | #ecff00 | |
font-family | -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol' | |
scale-ratio | 1.35 | |
bp-ratio | 1.15 |
Apply Branding Token
So let's get right into it, customizing step by step:
Start with copied branding-token.json
This is the file you've copied before, we'll start updating it piecemeal to show off common ways of design application.
Customize primary color
Most brands have such a primary color as part of their corporate design guidelines. This will be used to highlight elements, and give them more importance.
Next to primary itself, we'll also define its counter part primary-inverted as #ecff00 (#fff / white works for most uses otherwise, read about the finer details here).
Customize foreground and link colors
For this guide we'll have just change the foreground color, but this will influence how elements and text are rendered in components. So it is quite an influential choice.
Additionally we'll define some slightly different colors for our link and link-inverted (they always come in pairs!), to make it unique.
Customize tonal colors
There are a bunch of tokens that, for lack of a better explanation, relate to the tone of voice the element using it should have. Most commonly this would be something like a notice shown to the user (which might be successful = positive, neutral = informative, etc).
Because it seems to fit our branding, and doesn't interfere with user expectations otherwise, we'll change informative (and you guessed it, informative-inverted) to our primary color.
Add a fitting font
In this guide we'll opt for a native system font stack for our display and copy fonts. We'll leave interface and mono and all size values untouched for now. If you have other requirements (for example a self-hosted font, or one by Google Fonts), we'll add a guide for that soon!
Adjust spacing behaviour
As we have a pretty dense layout in mind, we reduce spacing > scale-ratio and bp-ratio a bit. This will result in spacing in general scaling a bit less.
We keep the general spacing of 8px, though. We'll also leave the rest of the values untouched as they'll work just fine for this guide!
Start with copied branding-token.json
This is the file you've copied before, we'll start updating it piecemeal to show off common ways of design application.
Customize primary color
Most brands have such a primary color as part of their corporate design guidelines. This will be used to highlight elements, and give them more importance.
Next to primary itself, we'll also define its counter part primary-inverted as #ecff00 (#fff / white works for most uses otherwise, read about the finer details here).
Customize foreground and link colors
For this guide we'll have just change the foreground color, but this will influence how elements and text are rendered in components. So it is quite an influential choice.
Additionally we'll define some slightly different colors for our link and link-inverted (they always come in pairs!), to make it unique.
Customize tonal colors
There are a bunch of tokens that, for lack of a better explanation, relate to the tone of voice the element using it should have. Most commonly this would be something like a notice shown to the user (which might be successful = positive, neutral = informative, etc).
Because it seems to fit our branding, and doesn't interfere with user expectations otherwise, we'll change informative (and you guessed it, informative-inverted) to our primary color.
Add a fitting font
In this guide we'll opt for a native system font stack for our display and copy fonts. We'll leave interface and mono and all size values untouched for now. If you have other requirements (for example a self-hosted font, or one by Google Fonts), we'll add a guide for that soon!
Adjust spacing behaviour
As we have a pretty dense layout in mind, we reduce spacing > scale-ratio and bp-ratio a bit. This will result in spacing in general scaling a bit less.
We keep the general spacing of 8px, though. We'll also leave the rest of the values untouched as they'll work just fine for this guide!
Now that we have a slightly modified, up-to-date version of our Branding Token in place, we can start hooking everything up.
kickstartDS Integration
First, add the kickstartDS CLI to your project:
_10yarn add kickstartds
Read more about our CLI here
Then add the following two additional lines to your package.json scripts block:
init-tokens is used to convert your Branding Token (branding-token.json) into a Style Dictionary compatible Design Token set (a bunch of JSON files), whereas build-tokens takes your Design Token set, and converts it to the outputs needed to use and display your Design System. But more about this later!
Generate first Design Token set
Generate your first full set of Design Token now, by calling:
_10yarn init-tokens
Your output should look roughly like this:
_35yarn run v1.22.18_35$ kickstartDS tokens init_35 _ _ _ _ _ ____ _____35 | | _(_) ___| | _____| |_ __ _ _ __| |_| _ \/ ___|_35 | |/ / |/ __| |/ / __| __/ _` | '__| __| | | \___ \_35 | <| | (__| <\__ \ || (_| | | | |_| |_| |___) |_35 |_|\_\_|\___|_|\_\___/\__\__,_|_| \__|____/|____/_35_35______________/\\\\\\\\\__/\\\______________/\\\\\\\\\\\________35 ___________/\\\////////__\/\\\_____________\/////\\\///_________35 _________/\\\/___________\/\\\_________________\/\\\____________35 ________/\\\_____________\/\\\_________________\/\\\____________35 _______\/\\\_____________\/\\\_________________\/\\\____________35 _______\//\\\____________\/\\\_________________\/\\\____________35 ________\///\\\__________\/\\\_________________\/\\\____________35 __/\\\____\////\\\\\\\\\_\/\\\\\\\\\\\\\\\__/\\\\\\\\\\\__/\\\__35 _\///________\/////////__\///////////////__\///////////__\///___35_35Version: 1.0.0_35For more information visit:_35https://www.kickstartDS.com/docs/intro/cli_35_35Starting..._35[kickstartDS: general] info: welcome to the kickstartDS CLI_35[kickstartDS: tokens/init] starting: init command with init variable init-task_35[1/1] [init: check] info: checking prerequesites before starting_35[1/1] [init: check] info: prerequesites met, starting_35[init: cleanup] info: cleaning up temp dir /tmp/tokens-init-init-task before starting command_35[init: cleanup] info: finished cleaning up temp dir /tmp/tokens-init-init-task before starting command_35[1/1] [init: init] info: running the init subtask_35[info] generating your token set from primitives tokens file /tmp/tokens-init-init-task/token-primitives.json_35[info] successfully generated primitives tokens and wrote them to folder /tmp/tokens-init-init-task/./src/token/dictionary_35[1/1] [init: init] info: finished running the init subtask successfully_35[kickstartDS: tokens/init] finished: init command with init variable init-task_35Done in 1.19s.
It uses your branding-token.json as an input, and generates a folder src/token/dictionary for you. That folder holds JSON files defining your Design Token by category:
_17$ tree src/token/dictionary_17_17> src/token/dictionary_17> ├── background-color.json_17> ├── border-color.json_17> ├── border.json_17> ├── box-shadow.json_17> ├── breakpoints.json_17> ├── color.json_17> ├── deprecated.json_17> ├── depth.json_17> ├── spacing.json_17> ├── text-color.json_17> ├── transition.json_17> └── typo.json_17>_17> 0 directories, 12 files
You'll only use this mechanism when first setting up your tokens. It's meant to specifically ease this workflow. Running it again will overwrite changes you manually did to your Design Token set, which is probably not intended!
To learn more about the categories represented by those generated files, have a look at our foundations page about them.
Compile Design Token set
Finally, to test the integration works as expected, we'll first want to create one additional file: sd.config.cjs at our projects root. As the name may imply, this is further configuration for our Design Token, to convert them into different outputs (more specifically the Style Dictionary that gets used under the hood):
And, as this is based on Style Dictionary, it generally follows their configuration scheme.
Let's detail some lines:
Import dependencies
Import style-dictionary to use their native StyleDictionary.extend, and get our pre-made, kickstartDS compatible, configuration from @kickstartds/style-dictionary.
Extend configuration
Our pre-made configuration gets extended by our local project setup. That way we can reuse stuff for easier configuration, if needed.
Design Token location
We configure the default Design Token location, which is tokens as a glob src/token/dictionary/**/*.json...
Default SVG icons
... and tell Style Dictionary where to look for our default icons. These are used by kickstartDS components, and need to be present in different formats later on (depending on the use case).
Platforms
To test that our integration works as expected, we'll add the CSS platform for now, which will result in our Design Token being converted to CSS custom properties, as src/token/tokens.css.
Using correct file extension
It's important to actually use cjs as the file extension here.
You can build your Design Token set into different outputs using Style Dictionary and kickstartDS. So far we've mainly configured how token are ingested, but we'll build on our single test platform CSS in the process of this guide. Adding integrations for Storybook, the use in kickstartDS components, and so on! By re-using our pre-made configurations we only have to define a buildPath to activate a platform. Optionally you can define file names with files, too.
With all of that in place, for the first time compile your Design Token set into CSS Custom Properties now:
_10yarn build-tokens
If everything worked as expected, you should end up with a long src/token/tokens.css file and the following output on your terminal:
_52yarn run v1.22.19_52$ kickstartDS tokens compile_52 _ _ _ _ _ ____ _____52 | | _(_) ___| | _____| |_ __ _ _ __| |_| _ \/ ___|_52 | |/ / |/ __| |/ / __| __/ _` | '__| __| | | \___ \_52 | <| | (__| <\__ \ || (_| | | | |_| |_| |___) |_52 |_|\_\_|\___|_|\_\___/\__\__,_|_| \__|____/|____/_52_52______________/\\\\\\\\\__/\\\______________/\\\\\\\\\\\________52 ___________/\\\////////__\/\\\_____________\/////\\\///_________52 _________/\\\/___________\/\\\_________________\/\\\____________52 ________/\\\_____________\/\\\_________________\/\\\____________52 _______\/\\\_____________\/\\\_________________\/\\\____________52 _______\//\\\____________\/\\\_________________\/\\\____________52 ________\///\\\__________\/\\\_________________\/\\\____________52 __/\\\____\////\\\\\\\\\_\/\\\\\\\\\\\\\\\__/\\\\\\\\\\\__/\\\__52 _\///________\/////////__\///////////////__\///////////__\///___52_52Version: 1.0.4_52For more information visit:_52https://www.kickstartds.com/docs/intro/cli/_52_52Starting..._52[kickstartDS: general] [info]: welcome to the kickstartDS CLI_52[kickstartDS: tokens/compile] starting: compile command with compile variable compile-task_52[1/1] [compile: check] [info]: checking prerequesites before starting_52[1/1] [compile: check] [info]: prerequesites met, starting_52[compile: cleanup] [info]: cleaning up temp dir /tmp/tokens-compile-compile-task before starting command_52[compile: cleanup] [info]: finished cleaning up temp dir /tmp/tokens-compile-compile-task before starting command_52[1/1] [compile: compile] [info]: running the compile subtask_52[1/1] [compile: compile] [info]: getting Style Dictionary from token files_52[1/1] [compile: compile] [info]: compiling Style Dictionary to needed CSS and assets_52_52css_52✔︎ src/token/tokens.css_52_52html_52✔︎ src/token/icons/icon-sprite.html_52_52jsx_52✔︎ src/token/icons/IconSprite.js_52_52storybook_52✔︎ src/token/storybook/tokens.css_52✔︎ src/token/storybook/icons.svg_52_52js_52✔︎ src/token/storybook/tokens.js_52[1/1] [compile: compile] [info]: copying generated CSS and assets to local folder_52[1/1] [compile: compile] [info]: finished running the compile subtask successfully_52[kickstartDS: tokens/compile] finished: compile command with compile variable compile-task_52Done in 2.41s.
To commit, or not to commit...
It's up to personal / team preference if the generated src/token/token.css file should be added to your repository... or your .gitignore.
There are valid arguments to make for both sides, so you should just follow what feels right for you!
We'll add it to our .gitignore:
Fine tune the design
Once the Design Token are generated, the Design System will already have the broad look & feel of your Corporate Design!
However you probably still have to tweak it a little to make it match up perfecly with your CD requirements.
This can be done by configuring the various .json files found within the dictionary folder.
Adjustments in background-color.json
Common adjutments are made in the background-color.json file.
Note that the same can be applied to text-color.json and border-color.json.
Set hover / active
We are going to be adjusting various states of primary, as they are entireley dependant on the selected color.
What might initially work on certain colors might not work at all on others.
Adjustments in typo.json
The typo.json often needs touching up as there are a lot of variying factors, such as the line-heights and font-sizes.
Set bp-factor
We want to go real big with our desktop font-size, however to have a more nuanced scaling of the font-size we need additional breakpoint-factors.
line-height
If you have a hugely variying font size it makes sense to adjust the line-height.
Adjustments in background-color.json
Common adjutments are made in the background-color.json file.
Note that the same can be applied to text-color.json and border-color.json.
Set hover / active
We are going to be adjusting various states of primary, as they are entireley dependant on the selected color.
What might initially work on certain colors might not work at all on others.
Adjustments in typo.json
The typo.json often needs touching up as there are a lot of variying factors, such as the line-heights and font-sizes.
Set bp-factor
We want to go real big with our desktop font-size, however to have a more nuanced scaling of the font-size we need additional breakpoint-factors.
line-height
If you have a hugely variying font size it makes sense to adjust the line-height.
Result
With this we have completed our Design Token setup, and our branding should be successfully applied to kickstartDS!
Next Step
In the next step we'll set up Storybook. This connects nicely, as we'll add the Storybook integration for Design Token there, to make them viewable in the browser. We'll also make preparations for the step after, where we'll add components.
It's probably a good idea to commit everything again, now!
Code Sandbox
See the result of this step in the Code Sandbox below. It's showing specifically the result after this step. You can also view this on Github directly in the ds-guide repository, there's a branch for every step... and we're currently on the branch step/2 in the guide:
Toggle the file browser with the hamburger icon at the top left, or open it directly in your browser.