Skip to content
Adobe Commerce Storefront
Docs Playgrounds Videos

Design tokens

Branding with design tokens is the quickest way to customize your storefront. The goal of branding is to replace the storefront design token values with the values of your brand’s colors, typography, spacing, and shapes. Let’s dive in.

Big picture

The following diagram shows a small branding change. When we override the default value of a single shape token, we override the default border-radius of the Button library component, which changes the look and feel of dropins that use it.

Diagram for how to brand dropins

How to override the dropin-design tokens.

Vocabulary

design tokens

CSS variables with default values. Our design tokens provide a standard set of CSS properties and default values for colors, typography, spacing, shapes, and layout grids. We use them in all of our component CSS classes to avoid hard-coded values that cannot be easily changed. With this strategy, you can restyle our dropins to match your brand simply by changing the default token values.

css All default design tokens
.dropin-design {
  --color-brand-500: #454545; /* Brand buttons default - AAA */
  --color-brand-600: #383838; /* Brand buttons on hover - AAA */
  --color-brand-700: #2b2b2b; /* Brand buttons selected */
  --color-neutral-50: #ffffff; /* Lightest surface / Text & components On Dark surface - AAA */
  --color-neutral-100: #fafafa; /* Light surface - AAA */
  --color-neutral-200: #f5f5f5; /* Light surface - AAA */
  --color-neutral-300: #e8e8e8; /* Disabled surfaces - AAA */
  --color-neutral-400: #d6d6d6; /* Ornamental elements (ie. Divider) */
  --color-neutral-500: #b8b8b8; /* Disabled text */
  --color-neutral-600: #8f8f8f; /* Component borders (ie. Text field border) - AA Large text */
  --color-neutral-700: #666666; /* Secondary text - AAA */
  --color-neutral-800: #3d3d3d; /* Default text - AAA */
  --color-neutral-900: #292929; /* Default text on hover - AAA */
  --color-positive-200: #eff5ef; /* Semantic positive surface - AA Large text */
  --color-positive-500: #7fb078; /* Semantic positive surface */
  --color-positive-800: #53824c; /* Semantic Positive text - On Light AA */
  --color-informational-200: #eeeffb; /* Semantic informational surface - AA Large text */
  --color-informational-500: #6978d9; /* Semantic informational surface */
  --color-informational-800: #5d6dd6; /* Semantic informational text, Highlights - On Light AA */
  --color-warning-200: #fdf3e9; /* Semantic warning surface - AA Large text */
  --color-warning-500: #e79f5c; /* Semantic warning surface */
  --color-warning-800: #cc7a2e; /* Semantic warning text - On Light AA */
  --color-alert-200: #ffebeb; /* Semantic alert surface - AA Large text */
  --color-alert-500: #db7070; /* Semantic alert surface */
  --color-alert-800: #c35050; /* Semantic alert text - On light AA */
  --color-opacity-16: rgba(255, 255, 255, 0.16);
  --color-opacity-24: rgba(255, 255, 255, 0.24);
  --color-action-button-active: #ffffff; /* Defaults to var(--color-neutral-50) */
  --color-action-button-hover: #e8e8e8; /* Defaults to var(--color-neutral-300) */
  --color-button-active: #2b2b2b; /* Defaults to var(--color-brand-700) */
  --color-button-focus: #d6d6d6; /* Defaults to var(--color-neutral-400) */
  --color-button-hover: #383838; /* Defaults to var(--color-brand-600) */
  --grid-1-columns: 4;
  --grid-1-margins: 0;
  --grid-1-gutters: 16px;
  --grid-2-columns: 12;
  --grid-2-margins: 0;
  --grid-2-gutters: 16px;
  --grid-3-columns: 12;
  --grid-3-margins: 0;
  --grid-3-gutters: 24px;
  --grid-4-columns: 12;
  --grid-4-margins: 0;
  --grid-4-gutters: 24px;
  --grid-5-columns: 12;
  --grid-5-margins: 0;
  --grid-5-gutters: 24px;
  --shape-border-radius-1: 3px;
  --shape-border-radius-2: 8px;
  --shape-border-radius-3: 24px;
  --shape-border-width-1: 1px;
  --shape-border-width-2: 1.5px;
  --shape-border-width-3: 2px;
  --shape-border-width-4: 4px;
  --shape-shadow-1: 0 0 16px 0 rgba(0, 0, 0, 0.16); /* Elevated panels (ie. Page side panel, Mobile bottom bar) */
  --shape-shadow-2: 0 2px 16px 0 rgba(0, 0, 0, 0.16); /* Elevated dialogs (ie. Modal) */
  --shape-shadow-3: 0 2px 3px 0 rgba(0, 0, 0, 0.16); /* Elevated container (ie. Card) */
  --shape-icon-stroke-1: 1px;
  --shape-icon-stroke-2: 1.5px;
  --shape-icon-stroke-3: 2px;
  --shape-icon-stroke-4: 4px;
  --spacing-xxsmall: 4px;
  --spacing-xsmall: 8px;
  --spacing-small: 16px;
  --spacing-medium: 24px;
  --spacing-big: 32px;
  --spacing-xbig: 40px;
  --spacing-xxbig: 48px;
  --spacing-large: 64px;
  --spacing-xlarge: 72px;
  --spacing-xxlarge: 96px;
  --spacing-huge: 120px;
  --spacing-xhuge: 144px;
  --spacing-xxhuge: 192px;
  --type-base-font-family: system-ui, sans-serif;
  --type-display-1-font: normal normal 300 60px/72px var(--type-base-font-family); /* Hero title */
  --type-display-1-letter-spacing: 0.04em;
  --type-display-2-font: normal normal 300 48px/56px var(--type-base-font-family); /* Banner title */
  --type-display-2-letter-spacing: 0.04em;
  --type-display-3-font: normal normal 300 34px/40px var(--type-base-font-family); /* Desktop & tablet section title */
  --type-display-3-letter-spacing: 0.04em;
  --type-headline-1-font: normal normal 400 24px/32px var(--type-base-font-family); /* Desktop & tablet page title */
  --type-headline-1-letter-spacing: 0.04em;
  --type-headline-2-default-font: normal normal 300 20px/24px var(--type-base-font-family); /* Rail title */
  --type-headline-2-default-letter-spacing: 0.04em;
  --type-headline-2-strong-font: normal normal 400 20px/24px var(--type-base-font-family); /* Mobile page and section title */
  --type-headline-2-strong-letter-spacing: 0.04em;
  --type-body-1-default-font: normal normal 300 16px/24px var(--type-base-font-family); /* Normal text paragraph */
  --type-body-1-default-letter-spacing: 0.04em;
  --type-body-1-strong-font: normal normal 400 16px/24px var(--type-base-font-family);
  --type-body-1-strong-letter-spacing: 0.04em;
  --type-body-1-emphasized-font: normal normal 700 16px/24px var(--type-base-font-family);
  --type-body-1-emphasized-letter-spacing: 0.04em;
  --type-body-2-default-font: normal normal 300 14px/20px var(--type-base-font-family);
  --type-body-2-default-letter-spacing: 0.04em;
  --type-body-2-strong-font: normal normal 400 14px/20px var(--type-base-font-family);
  --type-body-2-strong-letter-spacing: 0.04em;
  --type-body-2-emphasized-font: normal normal 700 14px/20px var(--type-base-font-family);
  --type-body-2-emphasized-letter-spacing: 0.04em;
  --type-button-1-font: normal normal 400 20px/26px var(--type-base-font-family); /* Primary button text */
  --type-button-1-letter-spacing: 0.08em;
  --type-button-2-font: normal normal 400 16px/24px var(--type-base-font-family); /* Small buttons */
  --type-button-2-letter-spacing: 0.08em;
  --type-details-caption-1-font: normal normal 400 12px/16px var(--type-base-font-family);
  --type-details-caption-1-letter-spacing: 0.08em;
  --type-details-caption-2-font: normal normal 300 12px/16px var(--type-base-font-family);
  --type-details-caption-2-letter-spacing: 0.08em;
  --type-details-overline-font: normal normal 700 12px/20px var(--type-base-font-family);
  --type-details-overline-letter-spacing: 0.16em;
}

library components

Basic components (like Button, Checkbox, and Carousel) used to build dropins. Design tokens are embedded in the CSS classes of these components to ensure fast, flexible styling to match your brand.

Adobe Commerce design system

The collection of design tokens, library components, and conventions we use to style our dropins.

brand

To override the built-in design token default values to match your brand’s colors, typography, spacing, shapes, and grids.

style

To change existing dropin CSS classes or add new CSS classes to the dropin elements. Styling provides a deeper level of customization than branding.

Examples

This example shows six design tokens with new values for three color and three shape tokens from the boilerplate’s styles/styles.css file.

styles/styles.css
:root, .dropin-design {
  /* Commerce design tokens */
  --color-brand-500: #512d6d; /* Branded Button color - AAA */
  --color-brand-600: #7434db; /* Branded Button color on hover - AAA */
  --color-brand-700: #6023c0; /* Branded Button color when selected */
  --shape-border-radius-1: 0;
  --shape-border-radius-2: 2px;
  --shape-border-radius-3: 4px; /* Default border radius for Buttons */
}

Step-by-step

The following steps show how to override the default design token values to match your brand colors, typography, spacing, shapes, and layouts (grids).

For example, start with typography, then move on to spacing, shapes, grids, and finally colors (because they are typically the hardest to map to design tokens). Using this process ensures each brand category is completed and reviewed before moving on to the next. :::

[1]: Work on one category at a time

Open the styles/styles.css file.

From the root of your project, open the styles/styles.css file.

  • Directoryscripts/
    • …
  • Directorystyles/ CSS files for dropin design tokens, fonts, deferred styles
    • fonts.css — Default font styles
    • lazy-styles.css — Global styles loaded after LCP
    • styles.css — Global design tokens and CSS classes for site
  • Directorytools/
    • …

Override typography tokens.

We suggest starting with typography overrides. Mapping a brand’s typography to the available design tokens is typically straightforward. For example, NASA’s Brand Guidelines for typography specifies three font families:

  • Inter for large display and heading text
  • Public Sans for interfaces and body text
  • DM Mono for numbers and small labels

After installing the fonts, you can map them to the storefront design tokens. The following example shows how you might override the default typography design tokens to match NASA’s brand guidelines.

:root,
.dropin-design {
  --type-body-font-family: 'Public Sans', sans-serif;
  --type-display-font-family: 'Inter', sans-serif;
  --type-details-font-family: 'DM Mono', monospace;


  --type-display-1-font: normal normal 300 60px/72px var(--type-display-font-family); /* Hero title */
  --type-display-1-letter-spacing: 0.04em;
  --type-display-2-font: normal normal 300 48px/56px var(--type-display-font-family); /* Banner title */
  --type-display-2-letter-spacing: 0.04em;
  --type-display-3-font: normal normal 300 34px/40px var(--type-display-font-family); /* Desktop & tablet section title */
  --type-display-3-letter-spacing: 0.04em;


  --type-headline-1-font: normal normal 400 24px/32px var(--type-display-font-family); /* Desktop & tablet page title */
  --type-headline-1-letter-spacing: 0.04em;
  --type-headline-2-default-font: normal normal 300 20px/24px var(--type-display-font-family); /* Rail title */
  --type-headline-2-default-letter-spacing: 0.04em;
  --type-headline-2-strong-font: normal normal 400 20px/24px var(--type-display-font-family); /* Mobile page and section title */
  --type-headline-2-strong-letter-spacing: 0.04em;


  --type-body-1-default-font: normal normal 300 16px/24px var(--type-body-font-family); /* Normal text paragraph */
  --type-body-1-default-letter-spacing: 0.04em;
  --type-body-1-strong-font: normal normal 400 16px/24px var(--type-body-font-family);
  --type-body-1-strong-letter-spacing: 0.04em;
  --type-body-1-emphasized-font: normal normal 700 16px/24px var(--type-body-font-family);
  --type-body-1-emphasized-letter-spacing: 0.04em;
  --type-body-2-default-font: normal normal 300 14px/20px var(--type-body-font-family);
  --type-body-2-default-letter-spacing: 0.04em;
  --type-body-2-strong-font: normal normal 400 14px/20px var(--type-body-font-family);
  --type-body-2-strong-letter-spacing: 0.04em;
  --type-body-2-emphasized-font: normal normal 700 14px/20px var(--type-body-font-family);
  --type-body-2-emphasized-letter-spacing: 0.04em;


  --type-button-1-font: normal normal 400 20px/26px var(--type-body-font-family); /* Primary button text */
  --type-button-1-letter-spacing: 0.08em;
  --type-button-2-font: normal normal 400 16px/24px var(--type-body-font-family); /* Small buttons */
  --type-button-2-letter-spacing: 0.08em;


  --type-details-caption-1-font: normal normal 400 12px/16px var(--type-details-font-family);
  --type-details-caption-1-letter-spacing: 0.08em;
  --type-details-caption-2-font: normal normal 300 12px/16px var(--type-details-font-family);
  --type-details-caption-2-letter-spacing: 0.08em;
  --type-details-overline-font: normal normal 700 12px/20px var(--type-details-font-family);
  --type-details-overline-letter-spacing: 0.16em;
}

Continue with spacing, shapes, layouts, and colors.

Use the same process for overriding the spacing, shapes, grids, and color token values. With a company’s brand guidelines, you can start discovering how to map brand categories to the design-token values you need to override. But it’s not always straightforward. Mapping brand colors to the color token options can be challenging. This is when you will need to work closely with the design team to make decisions about which design tokens to override and how to map your brand colors to the available options.

Video

Playground

Summary

The process of branding dropins is typically fast and easy. Focus on one brand category at a time and work with your designers to solve the less obvious brand-to-token overrides.