Token names
An explanation of Primer's design token naming convention
Primer Design System
Site navigation
On this page
On this page
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-4base-color-green-5brand-base-color-lime-5base-fontWeight-semibold
Functional
Functional tokens represent global UI patterns.
Example functional tokens
bgColor-insetborderColor-defaultbrand-borderWidth-thinboxShadow-inset-thick
Component/pattern
Component/pattern tokens should only be used in component CSS.
Example component/pattern tokens
control-danger-borderColor-restbutton-primary-bgColor-hoverbrand-overlay-bgColortext-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-defaultmuted- The secondary color variant for a given token. Example:fgColor-mutedemphasis- 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