Design tokens

What are design tokens?

Design tokens are abstractions of visual properties – such as color, font, width, etc –- agnostic of platforms and programming languages. Generated as:

• Sass/SCSS for web
• CSS Custom Properties for web
• JSON for iOS/Sketch
• XML for Android

This allows for a sharing of a centralized system of specifications across all platforms. Just include the variables or data file in your build and replace any specs with the properly named token.

Other companies that use design tokens

• Salesforce
• Amazon
• AirBNB
• Adobe
• Shopify
• Github
• OpenTable
• Spotify
• Mozilla
• Etsy
• CVS Health

Base values vs. global settings vs. pattern-specific tokens

Base values

Base values are the bottom-line values that feed all others. These are the core specs that feed the very foundations that all other patterns and specifications are built upon. These are usually not accessible as tokens, but are rather set by the Design System team and feed into the tokens library as aliases. Exceptions apply in come cases for legacy code. Examples include:

• COLOR_BRAND The primary brand color (accessible as a token as SDS_COLOR_BRAND).
• GLOBAL_BORDER_COLOR Provides the color used globally for all borders, unless overridden at the pattern level.
• COLOR_BACKGROUND_BANDING Sets the global color for page-section banding.

Global settings

Use global tokens when setting site-wide values that should not change from page-to-page. For example, specs like font-family, default text color, page-section margin and padding values, and brand colors. Examples include:

• SDS_GLOBAL_FONT_FAMILY_DEFAULT (currently set to "Inter var", Helvetica, Arial, sans-serif) for the global default font stack.
• SDS_GLOBAL_TEXT_COLOR (currently set to #212121) for the global default text color.
• SDS_COLOR_BRAND (currently set to #532380) for the global default primary brand color.

Pattern-specific tokens

Use pattern-specific tokens when applying specs to a base pattern. These values map to global values and can be safely overridden at the pattern, module or page level as needed without affecting the global values. Examples for when a token value could be changed would include contextual styling (on light and dark backgrounds), extending patterns for testing, and any new situation where the global value breaks the experience or doesn’t fit. Examples:

• SDS_ACCORDION_HEADER_BACKGROUND_COLOR (currently set to #e6e6e6) for the background color of an active accordion area header.
• SDS_NOTIFICATION_ICON_MARGIN (currently set to 0 16px 0 0) for the margin around an alert icon.
• SDS_MODAL_OVERLAY_OPACITY (currently set to 0.65) for the opacity of a modal overlay background.

Token hierarchy

As an example of token hierarchy, let’s look at a Button. The following aliases and tokens apply to a button’s background-color:

• STRONG_MAGENTA (alias) This alias is the literal name of this color. This allows us to maintain a list of color names that remain unassociated or tied to specific usage. If a new color comes in as part of a brand refresh, we just add it to the list.
• COLOR_BRAND_LIGHTER (alias) This alias allows us to assign a color from the master list as a brand color. As of this writing, the value is set to “STRONG_MAGENTA”. For the brand refresh scenario, we just update this token value with the new color.
• SDS_BUTTON_BACKGROUND_COLOR (token) This token is available to designers and developers, and should be used in all references. Its assigned value (as of this writing) is “COLOR_BRAND_LIGHTER” for the default pattern, set by the Design System team at the brand level. This can be overwritten if needed, but should not be to maintain consistency.

Available design token list

These tokens names have been converted to their Sass/SCSS equivalents. Individual Components list their respective tokens in the Specs area.

Global

Global typography

$sds-global-font-family-default

"Inter var", Helvetica, Arial, sans-serif

$sds-global-font-family-default-alt

"Inter var alt", Helvetica, Arial, sans-serif

$sds-global-font-family-heading

"Sharp Sans Display 1", Helvetica, Arial, sans-serif

$sds-global-font-size

16px

$sds-global-font-size-larger

18px

$sds-global-font-size-small

14px

$sds-global-font-size-smaller

12px

$sds-global-font-weight-bold

700

$sds-global-font-weight-light

300

$sds-global-font-weight-normal

400

$sds-global-font-weight-semi-bold

600

$sds-global-text-color

#212121

$sds-global-text-color-disabled

#767676

$sds-global-text-color-inverse

#ffffff

$sds-global-text-color-inverse-weak

#959595

$sds-global-text-color-weak

#555555

$sds-global-text-line-height

1.5

Global colors

$black Deprecated

#212121

$darker-gray Deprecated

#555555

$dark-gray Deprecated

#767676

$gray Deprecated

#959595

$lighter-gray Deprecated

#e6e6e6

$light-gray Deprecated

#bdbdbd

$sds-alert-color-error

#cc1100

$sds-alert-color-notification

#5c707c

$sds-alert-color-success

#93a533

$sds-alert-color-warning

#dfa20b

$sds-color-brand

#532380

$sds-color-brand-accent

#00BFDE

$sds-color-brand-dark

#250858

$sds-color-brand-lighter

#bb00cc

$sds-color-shade-black

#212121

$sds-color-shade-darker-gray

#555555

$sds-color-shade-dark-gray

#767676

$sds-color-shade-gray

#959595

$sds-color-shade-lighter-gray

#e6e6e6

$sds-color-shade-light-gray

#bdbdbd

$sds-color-shade-true-black

#000000

$sds-color-shade-very-light-gray

#f2f2f2

$sds-color-shade-white

#ffffff

$sds-color-theme-pricing

#aed622

$sds-color-theme-sponsored

#212121

$sds-global-icon-color

#212121

$sds-global-icon-color-inverse

#ffffff

$sds-social-color-facebook

#1778F2

$sds-social-color-google

#bd081c

$sds-social-color-pinterest

#dc4e41

$sds-social-color-twitter

#55acee

$true-black Deprecated

#000000

$very-light-gray Deprecated

#f2f2f2

$white Deprecated

#ffffff

Global base values

$sds-global-breakpoint-desktop

980px

$sds-global-breakpoint-desktop-plus

1170px

$sds-global-breakpoint-modern

375px

$sds-global-breakpoint-phablet

504px

$sds-global-breakpoint-tablet

768px

$sds-global-gutter-size

16px

$sds-global-spacing-break

56px

$sds-global-spacing-large

24px

$sds-global-spacing-medium

16px

$sds-global-spacing-micro

8px

$sds-global-spacing-small

14px

$sds-global-spacing-xlarge

32px

Pattern-specific

Accordions

$sds-accordion-content-padding

16px

$sds-accordion-header-background-color

#e6e6e6

$sds-accordion-header-height-min

48px

$sds-accordion-header-padding

16px 56px 16px 16px

$sds-accordion-section-border-color

#e6e6e6

$sds-accordion-section-border-size

1px

$sds-accordion-section-border-style

solid

Author

$sds-author-border-color

#e6e6e6

$sds-author-border-style

solid

$sds-author-border-width

1px

$sds-author-caption-margin

16px

$sds-author-caption-max-width

85ch

$sds-author-caption-max-width-tablet

35em

$sds-author-font-size

14px

$sds-author-padding

24px 16px

$sds-author-padding-desktop

24px 0

Badge

$sds-badge-background-color

#e6e6e6

$sds-badge-background-color-sponsored

#ffffff

$sds-badge-background-color-sponsored-ga

#212121

$sds-badge-border-radius

4px

$sds-badge-height

24px

$sds-badge-icon-background-color

#250858

$sds-badge-icon-block-height

24px

$sds-badge-icon-block-scale

scale(1.5)

$sds-badge-icon-block-width

24px

$sds-badge-icon-border-radius

4px 0 0 4px

$sds-badge-icon-fill

#ffffff

$sds-badge-icon-margin

0 6px 0 0

$sds-badge-icon-padding

0 6px 0 0

$sds-badge-icon-width

10px

$sds-badge-label-color

#250858

$sds-badge-label-color-inverse

#ffffff

$sds-badge-label-font-size

12px

$sds-badge-label-font-weight

700

$sds-badge-margin

8px

$sds-badge-padding

0 6px

Breadcrumb

$sds-breadcrumb-font-size

14px

$sds-breadcrumb-icon-color

#000000

$sds-breadcrumb-icon-color-inverse

#ffffff

$sds-breadcrumb-icon-size

1em

$sds-breadcrumb-link-color

#555555

$sds-breadcrumb-separator-color

#555555

Button-list

$sds-button-list-arrow-size

12px

$sds-button-list-drawer-background-color

#ffffff

$sds-button-list-drawer-border-color

#e6e6e6

$sds-button-list-drawer-border-size

1px

$sds-button-list-drawer-border-style

solid

$sds-button-list-drawer-close-color

#555555

$sds-button-list-drawer-close-position

8px

$sds-button-list-drawer-close-size

12px

$sds-button-list-drawer-padding

32px 16px 16px

$sds-button-list-icon-fill

#ffffff

$sds-button-list-icon-fill-facebook

#1778F2

$sds-button-list-icon-fill-pinterest

#dc4e41

$sds-button-list-icon-fill-twitter

#55acee

$sds-button-list-item-margin

8px

$sds-button-list-label-color

#212121

$sds-button-list-label-size

16px

$sds-button-list-label-weight

400

$sds-button-list-zindex

9999

Buttons

$sds-button-background-color

#532380

$sds-button-background-color-disabled

#e6e6e6

$sds-button-background-color-hover

#250858

$sds-button-background-color-inverse-hover

#ffffff

$sds-button-background-color-secondary

#ffffff

$sds-button-background-color-secondary-hover

#250858

$sds-button-border-color-inverse-hover

#ffffff

$sds-button-border-color-secondary

#532380

$sds-button-border-color-secondary-hover

#532380

$sds-button-border-radius

6px

$sds-button-border-size-secondary

2px

$sds-button-border-style-secondary

solid

$sds-button-color

#ffffff

$sds-button-color-disabled

#ffffff

$sds-button-color-hover

#ffffff

$sds-button-color-inverse

#212121

$sds-button-color-secondary

#532380

$sds-button-color-secondary-disabled

#e6e6e6

$sds-button-color-secondary-hover

#ffffff

$sds-button-font-size

16px

$sds-button-font-size-dense

14px

$sds-button-font-size-medium

14px

$sds-button-font-weight

700

$sds-button-height

56px

$sds-button-height-dense

32px

$sds-button-height-medium

40px

$sds-button-icon-svg-width

50%

$sds-button-line-height

16px

$sds-button-margin

0 auto

$sds-button-max-width

250px

$sds-button-max-width-fluid

503px

$sds-button-padding

0 32px

$sds-button-padding-dense

8px 16px

$sds-button-text-align

center

$sds-button-width

80%

$sds-button-width-dense

auto

$sds-button-width-fluid

100%

$sds-button-width-icon

40px

$sds-button-width-tablet

auto

Caption

$sds-caption-color

#212121

$sds-caption-credit-border-color

#e6e6e6

$sds-caption-credit-border-style

solid

$sds-caption-credit-border-width

1px

$sds-caption-credit-color

#959595

$sds-caption-credit-font-size

12px

$sds-caption-credit-font-size-tablet

12px

$sds-caption-credit-font-style

normal

$sds-caption-credit-font-weight

400

$sds-caption-credit-line-height

1.13

$sds-caption-credit-margin

8px 0 0

$sds-caption-credit-padding

8px 0 0

$sds-caption-font-size

14px

$sds-caption-font-style

italic

$sds-caption-font-weight

400

$sds-caption-line-height

1.25

$sds-caption-margin

24px 0 0

$sds-caption-padding

0

Checkbox

$sds-checkbox-background-color

#ffffff

$sds-checkbox-background-color-active

#212121

$sds-checkbox-background-size

65%

$sds-checkbox-border-color

#bdbdbd

$sds-checkbox-border-color-active

#212121

$sds-checkbox-border-color-disabled

#e6e6e6

$sds-checkbox-border-color-error

#cc1100

$sds-checkbox-border-radius

4px

$sds-checkbox-border-style

solid

$sds-checkbox-border-width

1px

$sds-checkbox-height

20px

$sds-checkbox-label-color

#212121

$sds-checkbox-label-color-disabled

#767676

$sds-checkbox-label-color-error

#cc1100

$sds-checkbox-label-font-size

16px

$sds-checkbox-label-line-height

1.25

$sds-checkbox-label-padding

0 0 0 32px

$sds-checkbox-margin

16px

$sds-checkbox-width

20px

Container

$sds-container-card-background-color

#ffffff

$sds-container-card-border-color

#e6e6e6

$sds-container-card-border-style

solid

$sds-container-card-border-width

1px

$sds-container-card-margin

24px

$sds-container-card-padding

16px

$sds-container-card-shadow-blur

0

$sds-container-card-shadow-color

#f2f2f2

$sds-container-card-shadow-offset-x

0

$sds-container-card-shadow-offset-y

2px

$sds-container-card-shadow-spread

0

$sds-container-card-text-color

#212121

Disclaimer

$sds-disclaimer-color

#555555

$sds-disclaimer-color-inverse

#959595

$sds-disclaimer-font-size

11px

$sds-disclaimer-line-height

1.25

$sds-disclaimer-link-color

#bb00cc

$sds-disclaimer-link-text-decoration-inverse

underline

$sds-disclaimer-max-width

85ch

$sds-disclaimer-max-width-tablet

35em

Dropdown

$sds-dropdown-icon-fill

#212121

$sds-dropdown-icon-height

16px

$sds-dropdown-icon-position-right

16px

$sds-dropdown-icon-width

16px

Filter

$sds-filter-background-color

#e6e6e6

$sds-filter-background-color-hover

#555555

$sds-filter-border-radius

4px

$sds-filter-color

#212121

$sds-filter-color-hover

#ffffff

$sds-filter-font-size

14px

$sds-filter-height

32px

$sds-filter-icon-fill

#212121

$sds-filter-icon-fill-hover

#ffffff

$sds-filter-icon-height

8px

$sds-filter-icon-margin

0 8px 0 0

$sds-filter-icon-width

8px

$sds-filter-margin

0 12px 0 0

$sds-filter-padding

0 8px

$sds-filter-sort-background-color-active

#555555

$sds-filter-sort-color-active

#ffffff

$sds-filter-sort-color-active-hover

#ffffff

$sds-filter-sort-icon-fill-active

#ffffff

Headshot

$sds-headshot-border-radius

50%

$sds-headshot-height

64px

$sds-headshot-margin

16px

$sds-headshot-max-width

176px

$sds-headshot-width

64px

Helper-text

$sds-helper-text-color

#555555

$sds-helper-text-color-error

#cc1100

$sds-helper-text-color-inverse

currentColor

$sds-helper-text-font-size

14px

$sds-helper-text-margin

8px 0 0

Label

$sds-label-color

#555555

$sds-label-color-error

#cc1100

$sds-label-font-size

16px

$sds-label-font-size-focus

12px

$sds-label-font-size-optional

14px

$sds-label-margin-optional

0 0 0 8px

$sds-label-position-left

16px

$sds-label-position-top

16px

$sds-label-transform-focus

translate3d(0, -10px, 0)

Link

$sds-link-color

#bb00cc

$sds-link-color-active

#532380

$sds-link-color-hover

#532380

$sds-link-color-hover-active

#532380

$sds-link-color-inverse

#ffffff

$sds-link-color-inverse-hover

#ffffff

$sds-link-color-inverse-hover-active

#ffffff

$sds-link-color-inverse-visited

#ffffff

$sds-link-color-visited

#532380

$sds-link-icon-margin

0 0.5em 0 0

$sds-link-outline-focus

1px dotted #767676

$sds-link-text-decoration

none

$sds-link-text-decoration-hover

underline

$sds-link-text-decoration-hover-inverse

underline

$sds-link-text-decoration-inverse

underline

Lists

$sds-list-bullet-color-unordered

#00BFDE

$sds-list-item-bullet-line-height

1rem

$sds-list-item-bullet-position

-16px

$sds-list-item-bullet-size

21px

$sds-list-item-margin

16px 0 0

$sds-list-line-height

1.25

$sds-list-padding-bulleted

0 0 0 24px

$sds-list-style-ordered

decimal

Modal

$sds-modal-content-background-color

#ffffff

$sds-modal-content-body-color

#212121

$sds-modal-content-body-desc-margin

0 0 16px

$sds-modal-content-body-height-min

208px

$sds-modal-content-body-margin

0 0 16px

$sds-modal-content-body-padding

0 32px

$sds-modal-content-border-color

#e6e6e6

$sds-modal-content-border-size

1px

$sds-modal-content-border-style

solid

$sds-modal-content-header-icon-color

#959595

$sds-modal-content-header-icon-height

24px

$sds-modal-content-header-icon-hover-background-color

#f2f2f2

$sds-modal-content-header-icon-hover-color

#555555

$sds-modal-content-header-icon-target-height

40px

$sds-modal-content-header-icon-target-padding

8px

$sds-modal-content-header-icon-target-width

40px

$sds-modal-content-header-icon-width

24px

$sds-modal-content-header-icon-z-index

50

$sds-modal-content-header-padding

0 32px

$sds-modal-content-height

100vh

$sds-modal-content-height-max

85vh

$sds-modal-content-height-min

214px

$sds-modal-content-height-tablet

auto

$sds-modal-content-padding

0 0 32px

$sds-modal-content-title-font-weight

400

$sds-modal-content-width

100%

$sds-modal-content-width-max

676px

$sds-modal-content-width-tablet

70%

$sds-modal-content-z-index

9999

$sds-modal-overlay-color

#000000

$sds-modal-overlay-opacity

0.65

$sds-modal-overlay-z-index

9998

$sds-modal-small-content-font-size

14px

$sds-modal-small-content-height

auto

$sds-modal-small-content-height-max

85vh

$sds-modal-small-content-height-min

212px

$sds-modal-small-content-height-min-tablet

208px

$sds-modal-small-content-line-height

1.25

$sds-modal-small-content-padding

0 0 16px

$sds-modal-small-content-width

70vw

$sds-modal-small-content-width-max

300px

$sds-modal-title-margin

0 0 24px

Notification

$sds-notification-background-color

#ffffff

$sds-notification-border-radius

0

$sds-notification-color-error

#cc1100

$sds-notification-color-information

#5c707c

$sds-notification-color-success

#93a533

$sds-notification-color-warning

#dfa20b

$sds-notification-content-link-color

#bb00cc

$sds-notification-content-margin

8px 0 0

$sds-notification-icon-layout-left

16px

$sds-notification-icon-layout-top

24px

$sds-notification-icon-margin

0 16px 0 0

$sds-notification-icon-size

24px

$sds-notification-padding

24px 16px

$sds-notification-text-align

left

$sds-notification-title-font-weight

700

Pagination

$sds-pagination-button-margin

0 0 0 16px

$sds-pagination-list-active-font-weight

600

$sds-pagination-list-color

#5c707c

$sds-pagination-list-link-color

#bb00cc

$sds-pagination-list-link-color-hover

#532380

$sds-pagination-list-link-padding

0 12px

$sds-pagination-list-margin

24px 0

$sds-pagination-text-align

center

Radio

$sds-radio-background-active

inset 0 0 0 5px #212121

$sds-radio-background-active-disabled

inset 0 0 0 4px #e6e6e6

$sds-radio-background-color

#ffffff

$sds-radio-border-color

#bdbdbd

$sds-radio-border-color-active

#212121

$sds-radio-border-color-disabled

#e6e6e6

$sds-radio-border-color-error

#cc1100

$sds-radio-border-radius

50%

$sds-radio-border-style

solid

$sds-radio-border-width

1px

$sds-radio-height

20px

$sds-radio-label-color

#212121

$sds-radio-label-color-disabled

#767676

$sds-radio-label-color-error

#cc1100

$sds-radio-label-font-size

16px

$sds-radio-label-line-height

1.25

$sds-radio-label-padding

0 0 0 24px

$sds-radio-margin

16px

$sds-radio-width

20px

Rating

$sds-rating-breakdown-bar-background-color

#e6e6e6

$sds-rating-breakdown-bar-background-color-full

#532380

$sds-rating-breakdown-bar-background-color-half

linear-gradient(90deg, #532380 50%, #e6e6e6 50%)

$sds-rating-breakdown-bar-height

6px

$sds-rating-breakdown-bar-margin

0 2px 0 0

$sds-rating-breakdown-bar-width

28px

$sds-rating-breakdown-height

auto

$sds-rating-breakdown-label-font-size

14px

$sds-rating-breakdown-label-font-weight

600

$sds-rating-breakdown-label-line-height

1

$sds-rating-breakdown-label-margin

0 0 0 16px

$sds-rating-breakdown-width

auto

$sds-rating-count-color

#555555

$sds-rating-count-margin

0 0 0 4px

$sds-rating-height

16px

$sds-rating-item-background-size

16px

$sds-rating-item-fill

#532380

$sds-rating-item-font-size

0

$sds-rating-item-height

16px

$sds-rating-item-line-height

1

$sds-rating-item-margin

0

$sds-rating-item-width

16px

$sds-rating-link-color

#bb00cc

$sds-rating-width

96px

Reveal

$sds-reveal-content-padding

0 16px 0 0

$sds-reveal-icon-margin

0 0 0 8px

$sds-reveal-summary-color

#bb00cc

$sds-reveal-summary-focus-border-size

0

$sds-reveal-summary-icon-fill

#bb00cc

$sds-reveal-summary-icon-fill-inverse

#ffffff

$sds-reveal-summary-icon-margin

0 0 0 8px

$sds-reveal-summary-margin

0 0 16px

$sds-reveal-summary-padding

0 16px 0 0

Separator

$sds-separator-border-color

#e6e6e6

$sds-separator-border-size

1px

$sds-separator-border-style

solid

$sds-separator-margin

20px 0

Tabs

$sds-tabs-border-color

#e6e6e6

$sds-tabs-border-size

1px

$sds-tabs-border-style

solid

$sds-tabs-list-align

flex-start

$sds-tabs-list-color

#555555

$sds-tabs-list-color-active

#212121

$sds-tabs-list-font-size

16px

$sds-tabs-list-font-weight

400

$sds-tabs-list-font-weight-active

700

$sds-tabs-list-height

40px

$sds-tabs-list-item-box-shadow-active

inset 0 -4px 0 #bb00cc

$sds-tabs-list-item-margin

0 0 0 16px

$sds-tabs-list-item-padding

0 20px

$sds-tabs-list-line-height

1

$sds-tabs-list-margin

0 0 16px

Tag

$sds-tag-border-color

#e6e6e6

$sds-tag-border-radius

4px

$sds-tag-border-style

solid

$sds-tag-border-width

1px

$sds-tag-font-size

14px

$sds-tag-height

32px

$sds-tag-margin

0 8px 0 0

$sds-tag-padding

0 8px

$sds-tag-target-height

44px

$sds-tag-text-decoration

none

Text-field

$sds-color-form-focus

#00bfde

$sds-text-field-background-color

#ffffff

$sds-text-field-border-color

#bdbdbd

$sds-text-field-border-color-active

#bdbdbd

$sds-text-field-border-color-disabled

#e6e6e6

$sds-text-field-border-color-error

#cc1100

$sds-text-field-border-radius

6px

$sds-text-field-border-style

solid

$sds-text-field-border-width

1px

$sds-text-field-color

#212121

$sds-text-field-font-size

16px

$sds-text-field-height

56px

$sds-text-field-line-height

1.5

$sds-text-field-margin-textarea-focus

24px

$sds-text-field-min-height-textarea

100px

$sds-text-field-opacity-disabled

0.4

$sds-text-field-padding

16px

$sds-text-field-width

100%

$sds-text-field-width-max

503px

Toggle

$sds-toggle-icon-height

32px

$sds-toggle-icon-svg-fill

#767676

$sds-toggle-icon-svg-fill-save

#bb00cc

$sds-toggle-icon-svg-height

50%

$sds-toggle-icon-svg-width

50%

$sds-toggle-icon-width

32px

$sds-toggle-label-color

#767676

$sds-toggle-label-font-size

14px

Tooltip

$sds-tooltip-arrow-size

24px

$sds-tooltip-background-color

#ffffff

$sds-tooltip-border-color

#e6e6e6

$sds-tooltip-border-radius

6px

$sds-tooltip-border-size

1px

$sds-tooltip-border-style

solid

$sds-tooltip-box-shadow

2px 2px 6px 0 rgba(0,0,0,0.08)

$sds-tooltip-color

#555555

$sds-tooltip-content-font-size

14px

$sds-tooltip-content-line-height

1.25

$sds-tooltip-icon-background-color

transparent

$sds-tooltip-icon-background-color-hover

#f2f2f2

$sds-tooltip-icon-border-radius

0

$sds-tooltip-icon-size

32px

$sds-tooltip-margin

0 0 32px

$sds-tooltip-padding

16px

$sds-tooltip-spacer-margin

-13px -5px 0 0

$sds-tooltip-width

200px