Working with tokens

Tokens are named values for color, type, spacing, radius, shadow and breakpoints. Components use tokens for every style, and brand themes change them. Use the same tokens in your own CSS and designs, and your work follows the brand the same way the components do.

Three tiers

Tokens come in three tiers. Each tier refers to the one below it: component tokens point to semantic tokens, and semantic tokens point to base values.

How a brand changes everything at once

A brand theme changes a few tokens, and everything that points to them follows. The primary button’s background is a chain of tokens:

--nbhd-action-primary-backgroundColor        the button reads this
  → --nbhd-color-action-primary-background   the purpose: primary action
    → --nbhd-color-brand-primary             the brand's main color
      → --nbhd-moen-color-deepBlue           Moen's Deep Blue, #1b365d

The Moen theme points --nbhd-color-brand-primary at Deep Blue. Every primary button on a Moen site turns Deep Blue, along with anything else that uses the brand’s main color, and no component needs Moen-specific CSS.

This is also why tokens matter when you design. Name the token in a spec, such as “text primary” or “space 6”, rather than the value it has today. Values change from brand to brand; token names don’t.

Choose the right token

• Color: start with a semantic token. --nbhd-color-text-primary says what the color is for, and each brand can give it the right value. Use a base color only when no semantic token describes what you need. For text inside a section with a surface, use the context tokens described in Surfaces and color, which change with the surface.
• Spacing: use the semantic space scale, --nbhd-space-0 to --nbhd-space-40. Each step points to the matching base step (--nbhd-space-4 → --nbhd-base-space-4), and brands set their own step size: --nbhd-space-4 is 16px by default and 20px on Moen, which uses a 5px step. Your spacing stays in proportion on every brand. Components use the same semantic scale.
• Sizing: use the semantic size tokens, such as --nbhd-size-icon-sm or --nbhd-size-control-lg, for the dimensions of icons, controls and media. Unlike spacing, sizes stay the same on every brand. See Sizing.
• Stacking: use the semantic z-index scale, such as --nbhd-z-100, instead of a fixed z-index number, so your layers sit in the right order relative to headers, menus and dialogs. See Z-Index.
• Shadows: use the semantic shadow tokens, such as --nbhd-shadow-md, so cards, menus and dialogs lift off the page by the same amount everywhere. See Shadows.
• Motion: use the semantic duration and easing tokens, such as --nbhd-motion-duration-normal and --nbhd-motion-easing-standard, for transitions and animations, so hovers and other state changes move at the same speed and with the same feel as the components. See Motion.
• Opacity: use the semantic opacity tokens, such as --nbhd-opacity-disabled or --nbhd-opacity-overlay-backdrop, for disabled states and overlays, so they fade by the same amount as the components. See Opacity.
• Focus: use the focus tokens, such as --nbhd-focus-outlineWidth and --nbhd-context-color-focus-outline, for keyboard focus outlines, so your elements show the same outline as the components. See Focus.
• Breakpoints: change layouts at the same widths as the components. Media queries can’t read custom properties, so write the width from Breakpoints in @media, and read breakpoint.* from the token package in JavaScript.
• Type: use the typography tokens, such as --nbhd-typography-body-fontSize, so text matches the brand’s type scale.
• Never use fixed values for anything a token covers. A hex color or pixel value stays the same when the brand changes.

/* Avoid: fixed values ignore the brand theme */
.promo {
  color: #1c1d1f;
  padding: 16px;
  border: 1px solid #1b5e20;
}

/* Use: tokens follow the brand theme */
.promo {
  color: var(--nbhd-color-text-primary);
  padding: var(--nbhd-space-4);
  border: var(--nbhd-border-width-subtle) solid var(--nbhd-color-accent-primary);
}

Naming

Every token is a CSS custom property that starts with --nbhd-. The rest of the name is built from segments, most general first:

--nbhd-{component}-{subcomponent}-{variant}-{property}-{state}-{breakpoint}

Only the component and property are always there; the other segments appear when they apply.

Segments are separated by hyphens, and each segment is camelCase inside. Some examples:

--nbhd-card-borderRadius                     component + property
--nbhd-card-title-fontSize                   + subcomponent
--nbhd-action-primary-backgroundColor        + variant
--nbhd-productCard-title-color-hover         + state
--nbhd-typography-headline-fontSize-bpLg     + breakpoint
--nbhd-color-text-primary                    semantic token
--nbhd-moen-color-deepBlue                   brand color

The breakpoints match the Breakpoints foundation: bpSm is 544px, bpMd 768px, bpLg 1024px and bpXl 1200px.

Some color tokens still use an older --nbhd-color- prefix, such as --nbhd-color-surface-primary. They’re safe to use. Each component page lists the exact names it reads.

A name with an underscore after --nbhd-, such as --nbhd-_card-overlay-display, is internal to a component, not a token. Don’t use these.

Where to find tokens

• Foundations: the base scales for color, type, spacing, borders, shadows and more.
• Brands: each brand’s colors, fonts and spacing.
• Components: each component page lists its tokens under CSS Properties.
• In code: @fbin-web/neighborhood-tokens includes every token as JSON (dist/neighborhood.tokens.json) and JavaScript (dist/neighborhood.tokens.js) as well as CSS.