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
#252A31
colorTextSecondary Connecting the unconnected
#5F738C
colorTextAttention Connecting the unconnected
#171b1e
colorTextError Connecting the unconnected
#D21C1C
colorTextInfo Connecting the unconnected
#0172CB
colorTextSuccess Connecting the unconnected
#28A138
colorTextWarning Connecting the unconnected
#F9971E
colorTextCritical Connecting the unconnected
#D21C1C
colorTextWhite Connecting the unconnected
#fff
colorIconPrimary
#252A31
colorIconSecondary
#5F738C
colorIconAttention
#171b1e
colorIconTertiary
#bac7d5
colorIconInfo
#0172CB
colorIconSuccess
#28A138
colorIconWarning
#F9971E
colorIconCritical
#D21C1C
colorHeading Connecting the unconnected
#171b1e
colorHeadingInverted Connecting the unconnected
#fff
colorTextLinkPrimary Connecting the unconnected
#007F6D
colorTextLinkPrimaryHover Connecting the unconnected
#00a991
colorTextLinkSecondary Connecting the unconnected
#171b1e
colorTextLinkSecondaryHover Connecting the unconnected
#00a991
colorAlertIconSuccess
#28A138
colorTextAlertSuccess Connecting the unconnected
#235C2B
colorAlertIconInfo
#0172CB
colorTextAlertInfo Connecting the unconnected
#004680
colorAlertIconWarning
#F9971E
colorTextAlertWarning Connecting the unconnected
#8E2A06
colorAlertIconCritical
#D21C1C
colorTextAlertCritical Connecting the unconnected
#760909
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
#252A31
colorTextButtonSecondaryHover Connecting the unconnected
#181B20
colorTextButtonSecondaryActive Connecting the unconnected
#0B0C0F
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
#252A31
colorTextButtonGoogleHover Connecting the unconnected
#181B20
colorTextButtonGoogleActive Connecting the unconnected
#0B0C0F
colorTextButtonWhite Connecting the unconnected
#252A31
colorTextButtonWhiteHover Connecting the unconnected
#181B20
colorTextButtonWhiteActive Connecting the unconnected
#0B0C0F
colorTextButtonPrimaryBordered Connecting the unconnected
#00a991
colorTextButtonPrimaryBorderedHover Connecting the unconnected
#009882
colorTextButtonPrimaryBorderedActive Connecting the unconnected
#008f7b
colorTextButtonSecondaryBordered Connecting the unconnected
#252A31
colorTextButtonSecondaryBorderedHover Connecting the unconnected
#181B20
colorTextButtonSecondaryBorderedActive Connecting the unconnected
#0B0C0F
colorTextButtonInfoBordered Connecting the unconnected
#0172CB
colorTextButtonInfoBorderedHover Connecting the unconnected
#0161AC
colorTextButtonInfoBorderedActive Connecting the unconnected
#01508E
colorTextButtonSuccessBordered Connecting the unconnected
#28A138
colorTextButtonSuccessBorderedHover Connecting the unconnected
#238B31
colorTextButtonSuccessBorderedActive Connecting the unconnected
#1D7228
colorTextButtonWarningBordered Connecting the unconnected
#F9971E
colorTextButtonWarningBorderedHover Connecting the unconnected
#F38906
colorTextButtonWarningBorderedActive Connecting the unconnected
#D67906
colorTextButtonCriticalBordered Connecting the unconnected
#D21C1C
colorTextButtonCriticalBorderedHover Connecting the unconnected
#B91919
colorTextButtonCriticalBorderedActive Connecting the unconnected
#9D1515
colorTextButtonFacebookBordered Connecting the unconnected
#3b5998
colorTextButtonFacebookBorderedHover Connecting the unconnected
#385490
colorTextButtonFacebookBorderedActive Connecting the unconnected
#354f88
colorTextButtonGoogleBordered Connecting the unconnected
#252A31
colorTextButtonGoogleBorderedHover Connecting the unconnected
#181B20
colorTextButtonGoogleBorderedActive Connecting the unconnected
#0B0C0F
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
#252A31
colorTextButtonLinkSecondaryHover Connecting the unconnected
#181B20
colorTextButtonLinkSecondaryActive Connecting the unconnected
#0B0C0F
colorTextInput Connecting the unconnected
#252A31
colorTextInputPrefix Connecting the unconnected
#5F738C
colorTextInputDisabled Connecting the unconnected
#bac7d5
colorTextBadgeNeutral Connecting the unconnected
#171b1e
colorTextBadgeInfo Connecting the unconnected
#0172CB
colorTextBadgeSuccess Connecting the unconnected
#28A138
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
#5F738C
colorTextTag Connecting the unconnected
#252A31
colorTextTagSelected Connecting the unconnected
#e8edf1
colorIconInput
#bac7d5
colorPlaceholderInput Connecting the unconnected
#bac7d5
colorPlaceholderInputError Connecting the unconnected
#D21C1C
colorPlaceholderInputFile Connecting the unconnected
#5F738C
colorPlaceholderInputFileError Connecting the unconnected
#D21C1C
colorFormLabel Connecting the unconnected
#252A31
colorFormLabelFilled Connecting the unconnected
#5F738C
colorInfoCheckBoxRadio Connecting the unconnected
#5F738C
colorIconCheckboxRadio
#00a991
colorIconCheckboxRadioDisabled
#bac7d5
colorIconRadioButton
#00a991
colorIconRadioButtonDisabled
#bac7d5
colorStopoverArrow Connecting the unconnected
#5F738C

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
#0172CB
backgroundButtonInfoHover
#0161AC
backgroundButtonInfoActive
#01508E
backgroundButtonSuccess
#28A138
backgroundButtonSuccessHover
#238B31
backgroundButtonSuccessActive
#1D7228
backgroundButtonWarning
#F9971E
backgroundButtonWarningHover
#F38906
backgroundButtonWarningActive
#D67906
backgroundButtonCritical
#D21C1C
backgroundButtonCriticalHover
#B91919
backgroundButtonCriticalActive
#9D1515
backgroundButtonWhite
#fff
backgroundButtonWhiteHover
#f5f7f9
backgroundButtonWhiteActive
#e5eaef
backgroundButtonBorderedtransparent
backgroundButtonBorderedHover
#f5f7f9
backgroundButtonBorderedActive
#f5f7f9
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
#EBF4EC
backgroundAlertInfo
#E5F7FF
backgroundAlertWarning
#FDF0E3
backgroundAlertCritical
#FAEAEA
backgroundBadgeNeutral
#f5f7f9
backgroundBadgeInfo
#E5F7FF
backgroundBadgeSuccess
#EBF4EC
backgroundBadgeWarning
#FDF0E3
backgroundBadgeCritical
#FAEAEA
backgroundBadgeDark
#252A31
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
#252A31
backgroundTagHover
#e5eaef
backgroundTagSelectedHover
#181B20
backgroundTagActive
#d6dee6
backgroundTagSelectedActive
#0B0C0F

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
#0172CB
borderColorInputError
#D21C1C
borderColorInputErrorHover
#B91919
borderColorInputErrorFocus
#D21C1C
borderColorTableCell
#bac7d5
borderColorCard
#e8edf1
borderColorModal
#e8edf1
borderColorButtonPrimaryBordered
#00a991
borderColorButtonPrimaryBorderedHover
#009882
borderColorButtonPrimaryBorderedActive
#008f7b
borderColorButtonSecondaryBordered
#252A31
borderColorButtonSecondaryBorderedHover
#181B20
borderColorButtonSecondaryBorderedActive
#0B0C0F
borderColorButtonFacebookBordered
#3b5998
borderColorButtonFacebookBorderedHover
#385490
borderColorButtonFacebookBorderedActive
#354f88
borderColorButtonGoogleBordered
#252A31
borderColorButtonGoogleBorderedHover
#181B20
borderColorButtonGoogleBorderedActive
#0B0C0F
borderColorButtonInfoBordered
#0172CB
borderColorButtonInfoBorderedHover
#0161AC
borderColorButtonInfoBorderedActive
#01508E
borderColorButtonSuccessBordered
#28A138
borderColorButtonSuccessBorderedHover
#238B31
borderColorButtonSuccessBorderedActive
#1D7228
borderColorButtonWarningBordered
#F9971E
borderColorButtonWarningBorderedHover
#F38906
borderColorButtonWarningBorderedActive
#D67906
borderColorButtonCriticalBordered
#D21C1C
borderColorButtonCriticalBorderedHover
#B91919
borderColorButtonCriticalBorderedActive
#9D1515
borderColorButtonWhiteBordered
#fff
borderColorButtonWhiteBorderedHover
#fff
borderColorButtonWhiteBorderedActive
#fff
borderColorCheckboxRadio
#bac7d5
borderColorCheckboxRadioError
#D21C1C
borderColorCheckboxRadioHover
#5F738C
borderColorCheckboxRadioActive
#252A31
borderColorCheckboxRadioFocus
#0172CB
borderColorTable
#e8edf1
borderColorTableHead
#bac7d5
borderColorTag
#e8edf1
borderColorTagFocus
#0172CB

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
textDecorationTextLinkPrimaryHovernone
textDecorationTextLinkSecondaryunderline
textDecorationTextLinkSecondaryHovernone

Box shadow

Design tokenValue
boxShadowButtonFocus0 0 4px 1px rgba(1, 114, 203, 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#ECF8F7
paletteProductLightHover#D6F0EE
paletteProductLightActive#C0E8E4
paletteProductNormal#00a991
paletteProductNormalHover#009882
paletteProductNormalActive#008f7b
paletteProductDark#007F6D
paletteProductDarkHover#007060
paletteProductDarkActive#006657
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#5F738C
paletteInkLightHover#52647A
paletteInkLightActive#465567
paletteInkNormal#252A31
paletteInkNormalHover#181B20
paletteInkNormalActive#0B0C0F
paletteInkDark#171b1e
paletteOrangeLight#FDF0E3
paletteOrangeLightHover#FAE2C7
paletteOrangeLightActive#F8D3AB
paletteOrangeNormal#F9971E
paletteOrangeNormalHover#F38906
paletteOrangeNormalActive#D67906
paletteOrangeDark#8E2A06
paletteOrangeDarkHover#712105
paletteOrangeDarkActive#531904
paletteRedLight#FAEAEA
paletteRedLightHover#F4D2D2
paletteRedLightActive#EEB9B9
paletteRedNormal#D21C1C
paletteRedNormalHover#B91919
paletteRedNormalActive#9D1515
paletteRedDark#760909
paletteRedDarkHover#5A0707
paletteRedDarkActive#3E0505
paletteGreenLight#EBF4EC
paletteGreenLightHover#D7EAD9
paletteGreenLightActive#C3DFC7
paletteGreenNormal#28A138
paletteGreenNormalHover#238B31
paletteGreenNormalActive#1D7228
paletteGreenDark#235C2B
paletteGreenDarkHover#1B4621
paletteGreenDarkActive#123016
paletteBlueLight#E5F7FF
paletteBlueLightHover#C7EEFF
paletteBlueLightActive#A8E5FF
paletteBlueNormal#0172CB
paletteBlueNormalHover#0161AC
paletteBlueNormalActive#01508E
paletteBlueDark#004680
paletteBlueDarkHover#003561
paletteBlueDarkActive#002442
paletteSocialFacebook#3b5998
paletteSocialFacebookHover#385490
paletteSocialFacebookActive#354f88

6. How to add a new token

Check our design tokens repository on Github for more information.