Naming #

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

With every piece of content we name, we aim to follow this simple set of rules adapted from Brad Frost’s CSS Architecture for Design Systems.

Make it modular #

Duet consists of independent modules and this 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 Duet’s parts will be used on many platforms, it’s critical to ensure that its naming doesn’t conflict with other systems.

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 at a glance.

• Keep it consistent and pronounceable: Always use the long form version (small, medium, large, x-large) when naming components, tokens, and symbols instead of the short form version (s, m, l, xl).
• Default size: “medium” is always the default or the base value.
• Larger than default: When you want to define a size larger than medium we use large, x-large, xx-large and so on. If it’s a component, make it possible to pass the size via a “size” property.
• Smaller than default: When you want to define a size smaller than medium, we use small, x-small, xx-small and so on. If it’s a component, make it possible to pass the size via a “size” property.
• Examples: size-large, size-medium, size-small, size-x-small.

Colors #

These are our generic color naming guidelines. Color names must be:

• Meaningful: Not over specific, not overly abstract.
• Short: Maximum of 1 to 2 words.
• Pronounceable: We want to be able talk about them.
• Not a “color”: Since our system has multiple brands & themes we can’t use terms like red or blue in the name, but instead have to think about the function of the color and define the name based on that. Examples: color-primary, color-secondary, color-warning, color-text, etc.
• Darker than default: When you want to define a shade, use either color-{name}-dark, color-{name}-darker or color-{name}-darkest.
• Lighter than default: When you want to define a tint, use color-{name}-light, color-{name}-lighter, color-{name}-lightest and so on.

Icons #

When naming icons, we use the below defined conventions and categories to group them:

• Prefixing icon names: Icon names always start with a category name and a hyphen. For example action-{name} or messaging-{name}. If you have subcategories, include them in the naming as well and separate with hyphen. Example: action-arrow-{name}.
• Grouping icons: All Duet’s icons are grouped under these categories: action-, category-, claim-, damage-, expression-, file-, form-, messaging-, navigation- and profile-.

Design Tokens #

Please discuss with the design system team before creating a new global token. We want to make sure all global tokens are as reusable as possible and that there’s also a real need to make it global intead of local.

• Prefixing design tokens: Token names always start with a category name and a hyphen. For example color-{name} or space-{unit} or size-{unit}. If you have subcategories, include them in the naming as well and separate with hyphen, Example: color-primary-{name} or color-secondary-{name}.
• Suffix for Turva: Theme related rules and differences should be tokenized with -turva suffix. Example: {category}-{name}-turva or color-primary-turva.

Components #

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

• Noun rather than verb: Components are not actions, they are conceptually “things.” It is better to use nouns instead of verbs, such as “animation” instead of “animating.” “input,” “tab,” “navigation,” and “menu” are some examples.
• Meaningful: Not over specific, not overly abstract.
• Short: Maximum of 2 or 3 words.
• Pronounceable: We want to be able talk about them.
• Custom element spec compliant: Don’t use reserved names. Reserved names include: annotation-xml, font-face, font-face-src, font-face-uri, font-face-format, font-face-name, missing-glyph, color-profile.
• Examples: <duet-button>, <duet-date-picker>, <duet-header>.

Component Props #

When naming component properties we need to be extra careful that the names we use do not conflict with existing standardized prototype members. Reserved names that we can’t use include:

title, lang, translate, dir, tabIndex, accessKey, draggable, contentEditable, isContentEditable, 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, 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

Abstract #

We name all Sketch files in Abstract following the below naming convention:

<Project> - <Feature Name>

Example 1: “Toivo - Pet Insurance Purchase”
Example 2: “Toivo - Sign Up Flow”

Branches in Abstract follow the below naming convention:

<Feature/Fix> - <Feature Name/Fix Name>

Example 1: “Feature - Sign Up Flow”
Example 2: “Fix - Symbol Alignment Issues”

GitHub #

We name all repositories in GitHub following the below naming conventions:

• Repository names should be short and descriptive.
• Starts with a product name and a hyphen. For example toivo-{feature-name}.
• Always use lowercase characters only in a repository name.
• Use hyphens to separate words.

Example 1: “toivo-pet-insurance-purchase”
Example 2: “toivo-sign-up-flow”