Design tokens

Design tokens store visual design attributes. They help us make our UI more consistent and we support custom themes. We use them instead of static values like HEX codes for color or sizing units.

1. Installation

First thing you will need to do is install the package into your project.

Run npm to add the package to your project

npm install --save @kiwicom/orbit-design-tokens

or do so with Yarn:

yarn add @kiwicom/orbit-design-tokens

2. How to use

Now that you have installed the latest version of the package, you will need to add an import directly into the file where you want to use the design tokens.

You will simply need to add this line of code to the top of the file:

import { defaultTokens } from '@kiwicom/orbit-design-tokens'

Now you can use tokens by typing defaultTokens and just continue with the dot-notation by typing the appropriate token name you want to use f.e. defaultTokens.colorTextPrimary. More advanced text editors should suggest which tokens are available to you in the token object, so you can find tokens quicker than by typing the entire token name.

3. Formats

The main structure of the package is written in JavaScript for better usage in JavaScript projects. We are also able to generate a JSON file which will allow us to transform this type of file into different ones. It should be possible to transform JSON into SASSLESSStylusXML or others.

4. Naming conventions

Every design token in the package has a name suggested according to the Orbit naming conventions. These conventions should be systematic, and work according to the following template:

property_usage-type--state

💡

Every token name starts with its related CSS property, like color, background or fontSize. This should help to use them more naturally.

More information about adding new tokens is described in How to add a new token

5. Full list of design tokens

Colors

Use these tokens for text or icon colors. Don't use these for borders and background colors.

Design tokenValue
$colorTextPrimary Connecting the unconnected
#46515e
$colorTextSecondary Connecting the unconnected
#7f91a8
$colorTextAttention Connecting the unconnected
#171b1e
$colorTextError Connecting the unconnected
#d21c1c
$colorTextInfo Connecting the unconnected
#0176D2
$colorTextSuccess Connecting the unconnected
#46B655
$colorTextWarning Connecting the unconnected
#f9971e
$colorTextCritical Connecting the unconnected
#d21c1c
$colorTextWhite Connecting the unconnected
#fff
$colorIconPrimary
#46515e
$colorIconSecondary
#7f91a8
$colorIconAttention
#171b1e
$colorIconTertiary
#bac7d5
$colorIconInfo
#0176D2
$colorIconSuccess
#46B655
$colorIconWarning
#f9971e
$colorIconCritical
#d21c1c
$colorHeading Connecting the unconnected
#171b1e
$colorHeadingInverted Connecting the unconnected
#fff
$colorTextLinkPrimary Connecting the unconnected
#00a991
$colorTextLinkPrimaryHover Connecting the unconnected
#00a991
$colorTextLinkSecondary Connecting the unconnected
#171b1e
$colorTextLinkSecondaryHover Connecting the unconnected
#00a991
$colorAlertIconSuccess
#46B655
$colorTextAlertSuccess Connecting the unconnected
#065d12
$colorAlertIconInfo
#0176D2
$colorTextAlertInfo Connecting the unconnected
#07405c
$colorAlertIconWarning
#f9971e
$colorTextAlertWarning Connecting the unconnected
#a93610
$colorAlertIconCritical
#d21c1c
$colorTextAlertCritical Connecting the unconnected
#650808
$colorTextAlertLink Connecting the unconnected
#171b1e
$colorTextButtonFilled Connecting the unconnected
#fff
$colorTextButtonFilledHover Connecting the unconnected
#fff
$colorTextButtonFilledActive Connecting the unconnected
#fff
$colorTextButtonPrimary Connecting the unconnected
#fff
$colorTextButtonPrimaryHover Connecting the unconnected
#fff
$colorTextButtonPrimaryActive Connecting the unconnected
#fff
$colorTextButtonSecondary Connecting the unconnected
#46515e
$colorTextButtonSecondaryHover Connecting the unconnected
#3f4854
$colorTextButtonSecondaryActive Connecting the unconnected
#38404b
$colorTextButtonInfo Connecting the unconnected
#fff
$colorTextButtonInfoHover Connecting the unconnected
#fff
$colorTextButtonInfoActive Connecting the unconnected
#fff
$colorTextButtonSuccess Connecting the unconnected
#fff
$colorTextButtonSuccessHover Connecting the unconnected
#fff
$colorTextButtonSuccessActive Connecting the unconnected
#fff
$colorTextButtonWarning Connecting the unconnected
#fff
$colorTextButtonWarningHover Connecting the unconnected
#fff
$colorTextButtonWarningActive Connecting the unconnected
#fff
$colorTextButtonCritical Connecting the unconnected
#fff
$colorTextButtonCriticalHover Connecting the unconnected
#fff
$colorTextButtonCriticalActive Connecting the unconnected
#fff
$colorTextButtonFacebook Connecting the unconnected
#fff
$colorTextButtonFacebookHover Connecting the unconnected
#fff
$colorTextButtonFacebookActive Connecting the unconnected
#fff
$colorTextButtonGoogle Connecting the unconnected
#46515e
$colorTextButtonGoogleHover Connecting the unconnected
#3f4854
$colorTextButtonGoogleActive Connecting the unconnected
#38404b
$colorTextButtonPrimaryBordered Connecting the unconnected
#00a991
$colorTextButtonPrimaryBorderedHover Connecting the unconnected
#009882
$colorTextButtonPrimaryBorderedActive Connecting the unconnected
#008f7b
$colorTextButtonSecondaryBordered Connecting the unconnected
#46515e
$colorTextButtonSecondaryBorderedHover Connecting the unconnected
#3f4854
$colorTextButtonSecondaryBorderedActive Connecting the unconnected
#38404b
$colorTextButtonInfoBordered Connecting the unconnected
#0176D2
$colorTextButtonInfoBorderedHover Connecting the unconnected
#006abd
$colorTextButtonInfoBorderedActive Connecting the unconnected
#0064b2
$colorTextButtonSuccessBordered Connecting the unconnected
#46B655
$colorTextButtonSuccessBorderedHover Connecting the unconnected
#42ac50
$colorTextButtonSuccessBorderedActive Connecting the unconnected
#3fa34c
$colorTextButtonWarningBordered Connecting the unconnected
#f9971e
$colorTextButtonWarningBorderedHover Connecting the unconnected
#f48a06
$colorTextButtonWarningBorderedActive Connecting the unconnected
#e68206
$colorTextButtonCriticalBordered Connecting the unconnected
#d21c1c
$colorTextButtonCriticalBorderedHover Connecting the unconnected
#bd1919
$colorTextButtonCriticalBorderedActive Connecting the unconnected
#b21717
$colorTextButtonFacebookBordered Connecting the unconnected
#3b5998
$colorTextButtonFacebookBorderedHover Connecting the unconnected
#385490
$colorTextButtonFacebookBorderedActive Connecting the unconnected
#354f88
$colorTextButtonGoogleBordered Connecting the unconnected
#46515e
$colorTextButtonGoogleBorderedHover Connecting the unconnected
#3f4854
$colorTextButtonGoogleBorderedActive Connecting the unconnected
#38404b
$colorTextButtonLinkPrimary Connecting the unconnected
#00a991
$colorTextButtonLinkPrimaryHover Connecting the unconnected
#009882
$colorTextButtonLinkPrimaryActive Connecting the unconnected
#008f7b
$colorTextButtonLinkSecondary Connecting the unconnected
#46515e
$colorTextButtonLinkSecondaryHover Connecting the unconnected
#3f4854
$colorTextButtonLinkSecondaryActive Connecting the unconnected
#38404b
$colorTextInput Connecting the unconnected
#46515e
$colorTextInputPrefix Connecting the unconnected
#7f91a8
$colorTextInputDisabled Connecting the unconnected
#bac7d5
$colorTextBadgeNeutral Connecting the unconnected
#171b1e
$colorTextBadgeInfo Connecting the unconnected
#0176D2
$colorTextBadgeSuccess Connecting the unconnected
#46B655
$colorTextBadgeWarning Connecting the unconnected
#f9971e
$colorTextBadgeCritical Connecting the unconnected
#d21c1c
$colorTextBadgeDark Connecting the unconnected
#fff
$colorIconInput
#bac7d5
$colorPlaceholderInput Connecting the unconnected
#bac7d5
$colorPlaceholderInputError Connecting the unconnected
#d21c1c
$colorPlaceholderInputFile Connecting the unconnected
#7f91a8
$colorPlaceholderInputFileError Connecting the unconnected
#d21c1c
$colorFormLabel Connecting the unconnected
#46515e
$colorFormLabelFilled Connecting the unconnected
#7f91a8
$colorInfoCheckBoxRadio Connecting the unconnected
#7f91a8
$colorIconCheckboxRadio
#00a991
$colorIconCheckboxRadioDisabled
#bac7d5
$colorIconRadioButton
#00a991
$colorIconRadioButtonDisabled
#bac7d5

Font family

Design tokenValue
$fontFamily"Roboto", -apple-system, ".SFNSText-Regular", "San Francisco", "Segoe UI", "Helvetica Neue", "Lucida Grande", sans-serif

Background colors

Use these tokens for background colors only. Do not use these for border colors or text theme.palette.

Design tokenValue
$backgroundBody
#f5f7f9
$backgroundModal
#fff
$backgroundCard
#fff
transparent
$backgroundCountryFlagtransparent
$backgroundButtonPrimary
#00a991
$backgroundButtonPrimaryHover
#009882
$backgroundButtonPrimaryActive
#008f7b
$backgroundButtonSecondary
#e8edf1
$backgroundButtonSecondaryHover
#d9e1e8
$backgroundButtonSecondaryActive
#cad5df
$backgroundButtonFacebook
#3b5998
$backgroundButtonFacebookHover
#385490
$backgroundButtonFacebookActive
#354f88
$backgroundButtonGoogle
#f5f7f9
$backgroundButtonGoogleHover
#e5eaef
$backgroundButtonGoogleActive
#d6dee6
$backgroundButtonInfo
#0176D2
$backgroundButtonInfoHover
#006abd
$backgroundButtonInfoActive
#0064b2
$backgroundButtonSuccess
#46B655
$backgroundButtonSuccessHover
#42ac50
$backgroundButtonSuccessActive
#3fa34c
$backgroundButtonWarning
#f9971e
$backgroundButtonWarningHover
#f48a06
$backgroundButtonWarningActive
#e68206
$backgroundButtonCritical
#d21c1c
$backgroundButtonCriticalHover
#bd1919
$backgroundButtonCriticalActive
#b21717
$backgroundButtonBorderedtransparent
$backgroundButtonBorderedHover
#f5f7f9
$backgroundButtonBorderedActive
#fff
$backgroundButtonLinkPrimarytransparent
$backgroundButtonLinkPrimaryHover
#e5eaef
$backgroundButtonLinkPrimaryActive
#d6dee6
$backgroundButtonLinkSecondarytransparent
$backgroundButtonLinkSecondaryHover
#e5eaef
$backgroundButtonLinkSecondaryActive
#d6dee6
$backgroundInput
#fff
$backgroundInputDisabled
#e8edf1
$backgroundAlertSuccess
#e7f3e8
$backgroundAlertInfo
#e0f6ff
$backgroundAlertWarning
#fcf1cd
$backgroundAlertCritical
#fae8e8
$backgroundBadgeNeutral
#f5f7f9
$backgroundBadgeInfo
#e0f6ff
$backgroundBadgeSuccess
#e7f3e8
$backgroundBadgeWarning
#fcf1cd
$backgroundBadgeCritical
#fae8e8
$backgroundBadgeDark
#46515e
transparent
$backgroundIllustrationtransparent
$backgroundSeparator
#e8edf1

Font size

Use these sizing tokens for font sizes.

Design tokenValue
$fontSizeHeadingDisplay Preview
40px
$fontSizeHeadingTitle1 Preview
28px
$fontSizeHeadingTitle2 Preview
22px
$fontSizeHeadingTitle3 Preview
16px
$fontSizeTextNormal Preview
14px
$fontSizeTextLarge Preview
16px
$fontSizeTextSmall Preview
12px
$fontSizeMessage Preview
14px
$fontSizeButtonLarge Preview
16px
$fontSizeButtonNormal Preview
14px
$fontSizeButtonSmall Preview
12px
$fontSizeInputNormal Preview
16px
$fontSizeInputSmall Preview
14px
$fontSizeFormLabel Preview
14px
$fontSizeFormFeedback Preview
12px

Border radius

Use radius tokens to change the border-radius size (rounded corners).

Design tokenValue
$borderRadiusCircle
use only for square

50%
$borderRadiusNormal
use for all basic elements like buttons, inputs, content containers

3px
$borderRadiusLarge
use for big elements like modal and large buttons

6px
$borderRadiusSmall
use for smaller elements like tags

2px
$borderRadiusBadge
12px

Z Index

Use layers to show depth of page.

Design tokenValue
$zIndexDefault1
$zIndexSticky100
$zIndexModalOverlay800
$zIndexModal825
$zIndexOnTheTop900

Size (width, height)

Design tokenValue
$widthIconSmall
16px
$heightIconSmall ⇦ 16px
$widthIconMedium
24px
$heightIconMedium ⇦ 24px
$widthIconLarge
32px
$heightIconLarge ⇦ 32px
$heightInputNormal ⇦ 44px
$heightInputLarge ⇦ 52px
$heightInputSmall ⇦ 32px
$heightButtonNormal ⇦ 44px
$heightButtonLarge ⇦ 52px
$heightButtonSmall ⇦ 32px
$heightRadioButton ⇦ 20px
$widthRadioButton
20px
$heightCheckbox ⇦ 20px
$widthCheckbox
20px
$heightCountryFlag ⇦ auto
$widthCountryFlag
24px
$heightBadge ⇦ 24px
$widthBadgeCircled
24px
$heightIllustrationSmall ⇦ 90px
$heightIllustrationMedium ⇦ 200px
$heightServiceLogoSmall ⇦ 12px
$heightServiceLogoMedium ⇦ 24px
$heightServiceLogoLarge ⇦ 48px
$heightSeparator ⇦ 1px
$heightInputGroupSeparatorSmall ⇦ 16px
$heightInputGroupSeparatorNormal ⇦ 24px

Border color

Design tokenValue
$borderColorInput
#bac7d5
$borderColorInputHover
#a6b6c8
$borderColorInputActive
#94a8be
$borderColorInputFocus
#0176D2
$borderColorInputError
#d21c1c
$borderColorInputErrorHover
#bd1919
$borderColorInputErrorFocus
#d21c1c
$borderColorTableCell
#bac7d5
$borderColorCard
#e8edf1
$borderColorModal
#e8edf1
$borderColorButtonPrimaryBordered
#00a991
$borderColorButtonPrimaryBorderedHover
#009882
$borderColorButtonPrimaryBorderedActive
#008f7b
$borderColorButtonSecondaryBordered
#46515e
$borderColorButtonSecondaryBorderedHover
#3f4854
$borderColorButtonSecondaryBorderedActive
#38404b
$borderColorButtonFacebookBordered
#3b5998
$borderColorButtonFacebookBorderedHover
#385490
$borderColorButtonFacebookBorderedActive
#354f88
$borderColorButtonGoogleBordered
#46515e
$borderColorButtonGoogleBorderedHover
#3f4854
$borderColorButtonGoogleBorderedActive
#38404b
$borderColorButtonInfoBordered
#0176D2
$borderColorButtonInfoBorderedHover
#006abd
$borderColorButtonInfoBorderedActive
#0064b2
$borderColorButtonSuccessBordered
#46B655
$borderColorButtonSuccessBorderedHover
#42ac50
$borderColorButtonSuccessBorderedActive
#3fa34c
$borderColorButtonWarningBordered
#f9971e
$borderColorButtonWarningBorderedHover
#f48a06
$borderColorButtonWarningBorderedActive
#e68206
$borderColorButtonCriticalBordered
#d21c1c
$borderColorButtonCriticalBorderedHover
#bd1919
$borderColorButtonCriticalBorderedActive
#b21717
$borderColorCheckboxRadio
#bac7d5
$borderColorCheckboxRadioError
#d21c1c
$borderColorCheckboxRadioHover
#7f91a8
$borderColorCheckboxRadioActive
#46515e
$borderColorCheckboxRadioFocus
#0176D2

Border style

Design tokenValue
$borderStyleCardsolid
$borderWidthCard1px
$borderStyleInputsolid
$borderWidthInput1px
$borderWidthInputFocus2px

Opacity

Design tokenValue
$opacityOverlay0.8
$opacityButtonDisabled0.3
$opacityRadioButtonDisabled0.5
$opacityCheckboxDisabled0.5

Font weight

Use this for setting basic font weights.

Design tokenValue
$fontWeightNormal400
$fontWeightMedium500
$fontWeightBold700
$fontWeightLinks500
$fontWeightHeadingDisplay700
$fontWeightHeadingTitle1700
$fontWeightHeadingTitle2500
$fontWeightHeadingTitle3500

Spacing

Use this for setting spacings for elements.

Design tokenValue
$paddingAlert16px
$paddingAlertWithIcon12px
$paddingButtonSmall12px
$paddingButtonNormal16px
$paddingButtonLarge28px
$paddingTextareaSmall8px 12px
$paddingTextareaNormal12px
$paddingInputSmall0 12px
$paddingInputNormal0 12px
$paddingButtonSmallWithIcon8px
$paddingButtonNormalWithIcon8px
$paddingButtonLargeWithIcon12px
$marginButtonIconSmall8px
$marginButtonIconNormal12px
$marginButtonIconLarge16px
$marginRightButtonGroup1px
$marginTopFormFeedback2px
$marginBottomSelectSuffix2px
$paddingLeftInputFile6px
$paddingLeftSelectPrefix48px
$marginRightBadgeIcon4px
$spaceXXXSmall2px
$spaceXXSmall4px
$spaceXSmall8px
$spaceSmall12px
$spaceMedium16px
$spaceLarge24px
$spaceXLarge32px
$spaceXXLarge40px
$spaceXXXLarge52px

Duration

Use this for setting the speed of animation or transition.

Design tokenValue
$durationFast0.15s
$durationNormal0.3s
$durationSlow0.4s

Modifier

Use this for values for transform property, etc.

Design tokenValue
$modifierScaleButtonActive0.95
$modifierScaleCheckboxRadioActive0.95

Line height

Design tokenValue
$lineHeightText1.4
$lineHeightHeading1.2

Text decoration

Design tokenValue
$textDecorationTextLinkPrimarynone
$textDecorationTextLinkPrimaryHoverunderline
$textDecorationTextLinkSecondaryunderline
$textDecorationTextLinkSecondaryHoverunderline

Box shadow

Design tokenValue
$boxShadowButtonFocus0 0 4px 1px rgba(1, 118, 210, 0.3)
$boxShadowActionable0 2px 4px 0 rgba(23, 27, 30, 0.1)
$boxShadowElevatedLevel10 4px 12px 0 rgba(23, 27, 30, 0.15)
$boxShadowModal0 20px 60px 0 rgba(23, 27, 30, 0.4)

Color palette

Use these tokens as a fallback when you need specific color. It's always preferred to use less abstract design tokens. Don't use Hover and Active shades as base theme.palette.

Design tokenValue
$paletteProductLight#9ae5da
$paletteProductLightHover#7fded0
$paletteProductLightActive#64d7c6
$paletteProductNormal#00a991
$paletteProductNormalHover#009882
$paletteProductNormalActive#008f7b
$paletteProductDark#005448
$paletteWhite#fff
$paletteWhiteHover#f5f7f9
$paletteWhiteActive#e5eaef
$paletteCloudLight#f5f7f9
$paletteCloudLightHover#e5eaef
$paletteCloudLightActive#d6dee6
$paletteCloudNormal#e8edf1
$paletteCloudNormalHover#d9e1e8
$paletteCloudNormalActive#cad5df
$paletteInkLighter#bac7d5
$paletteInkLighterHover#a6b6c8
$paletteInkLighterActive#94a8be
$paletteInkLight#7f91a8
$paletteInkLightHover#6d819c
$paletteInkLightActive#5f738c
$paletteInkNormal#46515e
$paletteInkNormalHover#3f4854
$paletteInkNormalActive#38404b
$paletteInkDark#171b1e
$paletteOrangeLight#fcf1cd
$paletteOrangeLightHover#faeab7
$paletteOrangeLightActive#f9e4a1
$paletteOrangeNormal#f9971e
$paletteOrangeNormalHover#f48a06
$paletteOrangeNormalActive#e68206
$paletteOrangeDark#a93610
$paletteRedLight#fae8e8
$paletteRedLightHover#f5d4d4
$paletteRedLightActive#f1c0c0
$paletteRedNormal#d21c1c
$paletteRedNormalHover#bd1919
$paletteRedNormalActive#b21717
$paletteRedDark#650808
$paletteGreenLight#e7f3e8
$paletteGreenLightHover#d7ebd8
$paletteGreenLightActive#c7e3c9
$paletteGreenNormal#46B655
$paletteGreenNormalHover#42ac50
$paletteGreenNormalActive#3fa34c
$paletteGreenDark#065d12
$paletteBlueLight#e0f6ff
$paletteBlueLightHover#c8effe
$paletteBlueLightActive#b0e8fe
$paletteBlueNormal#0176D2
$paletteBlueNormalHover#006abd
$paletteBlueNormalActive#0064b2
$paletteBlueDark#07405c
$paletteSocialFacebook#3b5998
$paletteSocialFacebookHover#385490
$paletteSocialFacebookActive#354f88

6. How to add a new token

Check our design tokens repository on Github for more information.