token-names

17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Design token naming convention structure

Primer design tokens follow a consistent naming convention with components: prefix, namespace, pattern, variant, property, variant, and scale. Each token name is broken down into blocks separated by single dashes for CSS variables. The property value is always required and specifies exactly how a token is intended to be applied to a UI.

Three token categories in Primer

Primer design tokens are organized into three categories: base (lowest level tokens that map directly to raw values), component/pattern (tokens used only in component CSS), and functional (tokens representing global UI patterns).

Base token structure and examples

Base tokens are the lowest level tokens and map directly to a raw value. They include prefix (optional), namespace 'base', pattern (optional), property, variant (optional), and scale (optional). Examples include: base-size-4, base-color-green-5, brand-base-color-lime-5, base-fontWeight-semibold.

Functional token structure and examples

Functional tokens represent global UI patterns and include prefix (optional), property, and scale (optional), but exclude namespace, pattern, and variant. Examples include: bgColor-inset, borderColor-default, brand-borderWidth-thin, boxShadow-inset-thick.

Component/pattern token structure and examples

Component/pattern tokens should only be used in component CSS and include prefix (optional), pattern, variant (optional), property, and scale (optional), but exclude namespace. Examples include: control-danger-borderColor-rest, button-primary-bgColor-hover, brand-overlay-bgColor, text-codeInline-fontSize.

Prefix in token names

Prefix provides top-level encapsulation of a particular flavor of Primer. The 'brand' prefix is used for marketing/brand specific tokens and can protect base tokens like Brand color scales or provide value overrides for traditional Primer tokens to avoid collisions.

Namespace in token names

Namespace creates a scope to identify how a token may be used. The 'base' namespace represents global, constant values and is used for the lowest level tokens that map directly to raw values. Functional tokens generally use base tokens as a reference.

Pattern in token names

Pattern represents a group of design decisions or a specific Primer component. Names should be generic enough to influence related components when possible. For example, 'control' can be used for multiple types of controls like buttons, inputs, or interactive action list items. Multi-word pattern names use camelCase.

Variant in token names

Variant can modify either the pattern or property, with only one variant allowed per token. It typically represents a stylistic variant such as color (danger) or size (small).

Property in token names (required)

Property is required for all tokens and represents an item's style, usually matching a CSS property. It can also store other conceptual definitions such as size, minTarget, and similar. Multi-word properties use camelCase.

Scale in token names

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

Color modifier values

Color modifiers for the variant block use three values: 'default' for the default color variant (example: fgColor-default), 'muted' for the secondary color variant (example: fgColor-muted), and 'emphasis' for a stronger color variant opposite of muted (example: bgColor-accent-emphasis).

General-purpose t-shirt size modifiers

General-purpose size modifiers for tokens follow the scale: xsmall, small, medium, large, xlarge, xxlarge.

Density size modifiers

Density size modifiers use the scale: condensed, normal, spacious. The 'normal' value is used as the default size.

Thickness name modifiers

Thickness name modifiers use the scale: thin, thick, thicker. The 'thin' value is used as the default size.

Viewport range name modifiers

Viewport range name modifiers use the scale: narrow, regular, wide.

Token name block separator characters

Individual name blocks for each token should be separated with a single character relevant to each Primer framework. Use the dash (-) character for CSS variables and dot (.) character for JavaScript.

Give your agent this brain