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
#00826f
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
#003A69
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
colorTextButtonWhite Connecting the unconnected
#46515e
colorTextButtonWhiteHover Connecting the unconnected
#3f4854
colorTextButtonWhiteActive 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
colorTextButtonWhiteBordered Connecting the unconnected
#fff
colorTextButtonWhiteBorderedHover Connecting the unconnected
#fff
colorTextButtonWhiteBorderedActive Connecting the unconnected
#fff
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
colorTextBadgeWhite Connecting the unconnected
#171b1e
colorTextLoading Connecting the unconnected
#bac7d5
colorTextTable Connecting the unconnected
#7f91a8
colorTextTag Connecting the unconnected
#46515e
colorTextTagSelected Connecting the unconnected
#e8edf1
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
colorStopoverArrow Connecting the unconnected
#7f91a8

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
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
backgroundButtonWhite
#fff
backgroundButtonWhiteHover
#f5f7f9
backgroundButtonWhiteActive
#e5eaef
backgroundButtonBorderedtransparent
backgroundButtonBorderedHover
#f5f7f9
backgroundButtonBorderedActive
#fff
backgroundButtonWhiteBorderedtransparent
backgroundButtonWhiteBorderedHover
rgba(255, 255, 255, 0.2)
backgroundButtonWhiteBorderedActive
rgba(255, 255, 255, 0.2)
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
backgroundBadgeWhite
#fff
backgroundIllustrationtransparent
backgroundSeparator
#e8edf1
backgroundTableShadowLeftlinear-gradient(to left, transparent, rgba(186, 199, 213, 0.23))
backgroundTableShadowRightlinear-gradient(to right, transparent, rgba(186, 199, 213, 0.23))
backgroundTable
#fff
backgroundTableEven
#f5f7f9
backgroundTableHover
#e8edf1
backgroundTag
#f5f7f9
backgroundTagSelected
#46515e
backgroundTagHover
#e5eaef
backgroundTagSelectedHover
#3f4854
backgroundTagActive
#d6dee6
backgroundTagSelectedActive
#38404b

Font size

Use these sizing tokens for font sizes.

Design tokenValue
fontSizeHeadingDisplay Preview
40px
fontSizeHeadingTitle1 Preview
28px
fontSizeHeadingTitle2 Preview
22px
fontSizeHeadingTitle3 Preview
16px
fontSizeHeadingTitle4 Preview
14px
fontSizeHeadingTitle5 Preview
12px
fontSizeTextNormal Preview
14px
fontSizeTextLarge Preview
16px
fontSizeTextSmall Preview
12px
fontSizeMessage Preview
14px
fontSizeButtonLarge Preview
16px
fontSizeButtonNormal Preview
14px
fontSizeButtonSmall Preview
12px
fontSizeInputNormal Preview
14px
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
widthModalSmall
540px
widthModalNormal
740px
widthModalLarge
1280px
widthStopoverArrow
36px
heightStopoverArrow 7px

Breakpoints

Design tokenValue
widthBreakpointMediumMobile
414
widthBreakpointLargeMobile
576
widthBreakpointTablet
768
widthBreakpointDesktop
992
widthBreakpointLargeDesktop
1200

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
borderColorButtonWhiteBordered
#fff
borderColorButtonWhiteBorderedHover
#fff
borderColorButtonWhiteBorderedActive
#fff
borderColorCheckboxRadio
#bac7d5
borderColorCheckboxRadioError
#d21c1c
borderColorCheckboxRadioHover
#7f91a8
borderColorCheckboxRadioActive
#46515e
borderColorCheckboxRadioFocus
#0176D2
borderColorTable
#e8edf1
borderColorTableHead
#bac7d5
borderColorTag
#e8edf1
borderColorTagFocus
#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
fontWeightHeadingTitle4500
fontWeightHeadingTitle5700
fontWeightTableHead700

Spacing

Use this for setting spacings for elements.

Design tokenValue
paddingAlert16px
paddingAlertWithIcon12px
paddingBadge0 8px
paddingButtonWithoutText0
paddingButtonSmall0 12px
paddingButtonNormal0 16px
paddingButtonLarge0 28px
paddingButtonSmallWithIcons0 8px
paddingButtonNormalWithIcons0 12px
paddingButtonLargeWithIcons0 16px
paddingButtonSmallWithLeftIcon0 12px 0 8px
paddingButtonNormalWithLeftIcon0 16px 0 12px
paddingButtonLargeWithLeftIcon0 28px 0 16px
paddingButtonSmallWithRightIcon0 8px 0 12px
paddingButtonNormalWithRightIcon0 12px 0 16px
paddingButtonLargeWithRightIcon0 16px 0 28px
paddingTextareaSmall8px 12px
paddingTextareaNormal12px
paddingInputSmall0 12px
paddingInputNormal0 12px
marginButtonIconSmall8px
marginButtonIconNormal8px
marginButtonIconLarge12px
marginButtonGroupConnected0 1px 0 0
marginButtonGroup0 8px 0 0
marginTopFormFeedback2px
marginBottomSelectSuffix2px
paddingInputFile0 0 0 6px
paddingLeftSelectPrefix48px
paddingLoading12px
paddingTable12px 16px
paddingTableCompact8px 12px
paddingTag6px 8px
paddingTagWithIcon6px 8px 6px 6px
paddingTagRemovable6px 6px 6px 8px
paddingTagRemovableWithIcon6px
marginBadgeIcon0 4px 0 0
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
textDecorationTextLinkPrimaryunderline
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.3)
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#E1F5F2
paletteProductLightHover#bde9e2
paletteProductLightActive#9addd3
paletteProductNormal#00a991
paletteProductNormalHover#009882
paletteProductNormalActive#008f7b
paletteProductDark#00826f
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#003A69
paletteSocialFacebook#3b5998
paletteSocialFacebookHover#385490
paletteSocialFacebookActive#354f88

6. How to add a new token

Check our design tokens repository on Github for more information.