Different disciplines use names defined in the design system to communicate about tokens, components and similar. Hence, names must be modular, meaningful and pronounceable.

The following set of principles guide our team when naming things and help us do better and more informed decisions. These principles are adapted from Brad Frost’s CSS Architecture for Design Systems.

Make it modular #

Nord consists of independent modules which applies to our naming as well. Different parts of the system need to be clearly separated.

Make it legible #

Developers should be able to understand code at a glance and understand the purpose of any given part. Same is true for design components.

Avoid conflicts #

Since Nord’s components will be used on many platforms, it’s critical to ensure that its naming doesn’t conflict with other systems.

Design Tokens #

Users should be able understand the purpose of any given token at a glance. To make sure naming stays consistent and straightforward, we follow these guidelines:

Sizes #

We define sizing using T-shirt sizes. This makes it possible for anyone, technical or non-technical person, to understand the differences and how they relate to each other.

Colors #

Each color name contains a role, modifier and theme. This accommodate needs such as state, interactivity, and emphasis for different products. For example, a component may require color variations for hover, active, selected, focused, and disabled states.

Roles in color names are used to indicate how color is applied. By defining roles instead of specific values, we can ensure the correct use of each color, allow for modifiers, and support theming.

Each color follows the same naming convention so that they are understandable at a glance:

Components #

Different disciplines use component names to communicate about them. Hence, they must be short, meaningful, and pronounceable.

Icons #

HTML Classes #

Component Props #

When naming Web Component properties we need to be careful that the names we use do not conflict with existing standardized prototype members. Reserved names include:

align, title, lang, translate, dir, dataset, hidden, tabIndex, accessKey, draggable, spellcheck, autocapitalize, contentEditable, isContentEditable, inputMode, offsetParent, offsetTop, offsetLeft, offsetWidth, offsetHeight, style, innerText, outerText, oncopy, oncut, onpaste, onabort, onblur, oncancel, oncanplay, oncanplaythrough, onchange, onclick, onclose, oncontextmenu, oncuechange, ondblclick, ondrag, ondragend, ondragenter, ondragleave, ondragover, ondragstart, ondrop, ondurationchange, onemptied, onended, onerror, onfocus, onfocusin, onfocusout, oninput, oninvalid, onkeydown, onkeypress, onkeyup, onload, onloadeddata, onloadedmetadata, onloadstart, onmousedown, onmouseenter, onmouseleave, onmousemove, onmouseout, onmouseover, onmouseup, onmousewheel, onpause, onplay, onplaying, onprogress, onratechange, onreset, onresize, onscroll, onseeked, onseeking, onselect, onstalled, onsubmit, onsuspend, ontimeupdate, ontoggle, onvolumechange, onwaiting, onwheel, onauxclick, ongotpointercapture, onlostpointercapture, onpointerdown, onpointermove, onpointerup, onpointercancel, onpointerover, onpointerout, onpointerenter, onpointerleave, onselectstart, onselectionchange, nonce, click, focus, blur, namespaceURI, prefix, localName, tagName, id, className, classList, slot, attributes, shadowRoot, assignedSlot, innerHTML, outerHTML, scrollTop, scrollLeft, scrollWidth, scrollHeight, clientTop, clientLeft, clientWidth, clientHeight, attributeStyleMap, onbeforecopy, onbeforecut, onbeforepaste, onsearch, previousElementSibling, nextElementSibling, children, firstElementChild, lastElementChild, childElementCount, onfullscreenchange, onfullscreenerror, onwebkitfullscreenchange, onwebkitfullscreenerror, setPointerCapture, releasePointerCapture, hasPointerCapture, hasAttributes, getAttributeNames, getAttribute, getAttributeNS, setAttribute, setAttributeNS, removeAttribute, removeAttributeNS, hasAttribute, hasAttributeNS, toggleAttribute, getAttributeNode, getAttributeNodeNS, setAttributeNode, setAttributeNodeNS, removeAttributeNode, closest, matches, webkitMatchesSelector, attachShadow, getElementsByTagName, getElementsByTagNameNS, getElementsByClassName, insertAdjacentElement, insertAdjacentText, insertAdjacentHTML, requestPointerLock, getClientRects, getBoundingClientRect, scrollIntoView, scroll, scrollTo, scrollBy, scrollIntoViewIfNeeded, animate, computedStyleMap, before, after, replaceWith, remove, prepend, append, querySelector, querySelectorAll, requestFullscreen, webkitRequestFullScreen, webkitRequestFullscreen, part, createShadowRoot, getDestinationInsertionPoints, nodeType, nodeName, baseURI, isConnected, ownerDocument, parentNode, parentElement, childNodes, firstChild, lastChild, previousSibling, nextSibling, nodeValue, textContent, hasChildNodes, getRootNode, normalize, cloneNode, isEqualNode, isSameNode, compareDocumentPosition, contains, lookupPrefix, lookupNamespaceURI, isDefaultNamespace, insertBefore, appendChild, replaceChild, and removeChild.

CSS Custom Properties #

All CSS custom properties should be created as a private custom property on the :host selector, but can be adjusted with other selectors. If the custom property needs to be opened up for public use, then the value of the private property should be set as its public custom property counterpart with a fallback. Here’s an example of both a public and private custom property:

:host {
  /* Public properties */
  --_n-banner-border-radius: var(--n-banner-border-radius, var(--n-border-radius));

  /* Private properties */
  --_n-banner-background: var(--n-color-status-info-weak);

Repositories #

While we don’t follow a strict naming format on repositories, there’re a few rules we follow to make sure naming stays consistent and straightforward to follow:

Getting support #

Have questions about naming? Please head over to the Support page for more guidelines and ways to contact us.

Was this page helpful?

Send feedback

We use this feedback to improve our documentation.

Edit page