Token names

Intro

Primer design tokens are named using a consistent convention to make it easier to understand what they do and how they should be used at a glance.

Categories

This naming convention is broken down into three categories: base, component/pattern, functional. Each category is a subset of the over-arching convention.

Across all categories, the property value is always required. This value specifies exactly how a token is indended to be applied to a UI.

Base

Base tokens are the lowest level tokens and map directly to a raw value.

Example base tokens

base-size-4
base-color-green-5
brand-base-color-lime-5
base-fontWeight-semibold

Functional

Functional tokens represent global UI patterns.

Example functional tokens

bgColor-inset
borderColor-default
brand-borderWidth-thin
boxShadow-inset-thick

Component/pattern

Component/pattern tokens should only be used in component CSS.

Example component/pattern tokens

control-danger-borderColor-rest
button-primary-bgColor-hover
brand-overlay-bgColor
text-codeInline-fontSize

Convention breakdown

Prefix

Prefix provides top-level encapsulation of a particular flavor of Primer, such as Primer Brand. It can be used for protected base tokens like Brand color scales, or value overrides for traditional Primer tokens in order to avoid collisions.

brand: used for marketing/brand specific tokens.

Namespace

Namespace creates a scope used to identify how a token may be used. For example, base tokens are the lowest level and are generally used as a reference for functional tokens (the next step above).

base: represents global, constant values. These are the lowest level tokens and map directly to a raw value.

Pattern

Pattern represents a group of design decisions, or a specific Primer component. Whenever possible, aim to use a name that is generic enough to influence related components. For example, the pattern control can be used for multiple types of controls like buttons, inputs, or interactive action list items.

For pattern and component names that are multi-word, use camelCase to separate each word.

Variant

Variant can be used to either modify the pattern or property. Only one variant is allowed per token. It typically represents a stylistic variant of a token such as color (danger) or size (small).

Property (required)

Property is used to represent an item’s style. It usually matches a CSS property, but it can also store other conceptual definitions such as size, minTarget, etc. Use camelCase for multi-word properties.

Scale

Scale represents ordinals to describe things like state, density, thickness, range, and speed. Scale names strive to follow our size naming convention standards.

Token name block delimiters

Individual name blocks for each token should be separated with a single character that is relevant to each Primer framework. For example, use the - dash character for CSS variables and . dot character for JavaScript.

Do

Use dashes to separate words.

Don’t

Don't use other characters to separate words.

Color modifiers

We use the following values to modify the color variant:

• default - The default color variant for a given token. Example: fgColor-default
• muted - The secondary color variant for a given token. Example: fgColor-muted
• emphasis - The opposite of "muted", emphasis is a stronger color variant. Example: bgColor-accent-emphasis

Size modifiers

Size modifiers are often found as part of the scale block. The following describes how we name size modifiers for each category.

General-purpose t-shirt sizes

xsmall | small | medium | large | xlarge | xxlarge

Density

Use normal as the default size

condensed | normal | spacious

Thickness names

Use thin as the default size

thin | thick | thicker

Viewport ranges names

narrow | regular | wide