Skip to main content

Design Tokens

We capture all of our design elements as discrete entities called design tokens.

Design tokens have a static name and a variable value, allowing you to theme the entire design of an application with design tokens alone. Most design tokens have a default value assigned, which effectively represents the default theme of the Norton Design System. But since token values can be changed, you can simply reassign the value to begin creating a theme for a Norton Design System application.

Types of Design Tokens

The Norton Design System contains three types of design tokens: system, role, and component tokens, which are used in conjunction to capture the entire design of an application.

System Tokens

A system token is associated with one of our various subsystems, such as the color, motion, spacing, or typography systems.

  • System tokens are immutable—their values cannot be changed—because they are intended to act as a value store rather than part of the theming system.
  • System token names don't give hints as to how they should be used. This is because they are simply property values and could be used in a variety of ways.
  • System tokens should rarely be used directly.

Role Tokens

A role token has a semantic purpose in an application's design.

  • Role tokens are customizable and together constitute the primary way to theme a Norton Design System application.
  • Role token names do give hints about how they should be used.
  • Role tokens are the primary interface for theming and should therefore be used directly whenever possible.

Component Tokens

A component token is scoped to a specific component.

  • Component tokens are customizable but changing their values may result in inconsistency across components.
  • Component token names generally follow the pattern of {component}-{property}, where component is the name of the component and property captures the CSS property where the token is used.
    • Examples: button-border-width or tooltip-offset-y.
  • Component tokens can and should be used directly when creating custom components based on a Norton Design System component.

Token Conventions

In addition to the system of inheritance that our design tokens use, we follow a few key conventions that help you to better understand how to use them in your application.

Base Tokens

Base tokens always have the -base suffix, denoting that they are used as the default value for the corresponding property across the application. Customizing these will have the most wide-ranging impact on the design language of your application.

Example: custom base border-radius
@use '@wwnds/core' as nds with (
$radius-base: var(--nds-radius-lg),
);

// buttons, text fields, and other inline components will all have more rounded corners

T-Shirt Sizing

For tokens that fall on a linear scale such as font size, we sometimes use t-shirt sizing suffixes of -xs, -sm, -md, and -lg to capture a normalized subset of values. Customizing these will allow you to change the sense of scale across your application.