The following set of principles guide our team when naming things in the system. These principles are loosely based on the guidelines from Brad Frost’s CSS Architecture for Design Systems.
Modularity reduces complexity and improves our system’s reusability. This applies to our naming as well. Different parts of the design system need to be clearly separated.
Consistency enhances clarity and makes our design system more predictable and easy to use. We use the same language and naming wherever possible.
Developers and designers should be able to understand the system at a glance and understand the structure and purpose of any given part.
It’s critical to ensure that the design system’s naming doesn’t conflict with other libraries and systems. This is accomplished by the provided namespacing.
The system may seem verbose, but it delivers clarity and resilience in exchange. Keeping naming legible and scalable sometimes means sacrificing a shorter syntax.
Semantic colors carry meaning and imply how and where they should be used. Each semantic color name contains a role, a modifier, and a theme mode. This accommodates needs such as state, interactivity, and emphasis for different Kesko brands. For example, a component may require color variations for :hover and :focus states.
k-color-{role}-{modifier}-{theme}accent, border, text, status, or bg.weak, strong, active, hover, or success.light or dark.k-color-text-accentk-color-text-on-accentk-color-bg-accentk-color-bg-highlightk-color-status-errork-color-status-infoFor the Kesko primitive palette, we use numeric scales (100, 200, 300, ..). This provides clear ordering and makes it easy to add values between the existing tokens when necessary.
k-color-{name}-{variant}a-z) and hyphens (-). Do not use uppercase characters, symbols, underscores (_), dots (.), or digits (0-9).k-color-orange-100k-color-orange-200k-color-red-100k-color-red-200k-color-blue-100k-color-blue-200100200300400500600700800900100011001200Kesko Design System uses a simple naming structure for component naming based on {prefix}-{name} format.
{prefix}-{name}.k-button or k-input. “K” stands for “Kesko”. Prefixing is critical to ensure that our naming doesn’t conflict with other systems.<k-animation> instead of <k-animating>.-), such as k-element.a-z) and hyphens (-). Do not use uppercase characters, symbols, underscores (_), dots (.), or digits (0-9).k- prefix.annotation-xmlcolor-profilefont-facefont-face-srcfont-face-urifont-face-formatfont-face-namemissing-glyph<k-alert><k-badge><k-button><k-icon><k-input><k-visually-hidden>var(--k-{component}-{property}) for public properties.var(--_k-{component}-{property}) for private properties.--k- prefixes a public custom property, meaning developers can use it to fine tune components. --_k- prefixes a private custom property, which is reserved for internal design system use.var(--k-button-border-radius)var(--k-button-font-size)var(--k-button-background)var(--k-button-border-radius)Designers and developers should be able to understand the purpose of a design token at a glance. To make sure naming stays consistent and legible, we follow these guidelines for design tokens:
{prefix}-{category}-{name}-{variant}{prefix}-{category}-{subcategory}-{name}-{variant}k-color-accent or k-font-size-xl. “K” stands for “Kesko”. Prefixing is critical to ensure that our naming doesn’t conflict with other systems.k-color-success instead of k-color-succeed.a-z) and hyphens (-). Do not use uppercase characters, symbols, underscores (_), dots (.), or digits (0-9).{prefix}-{category}-{name}-md is always the default value.color,font, or similar. If it makes sense, you can also include a subcategory, for example k-font-size-xl or k-color-status-error.k-color-textk-color-text-accentk-color-text-on-accentk-color-bgk-color-bg-surfacek-color-bg-accentk-color-status-errork-color-status-successk-font-size-xlk-font-weight-boldk-font-family-sansk-font-leading-mdblackboldmediumregularlightKesko Design System defines semantic sizes using the t-shirt metaphor. 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.
sm, md, lg, xl) when naming things. This makes it quicker for developers and designers to reference the sizes.md is always the default or the base value.lg, xl, 2xl, 3xl.sm, xs, 2xs, 3xs.k-font-size-2xlk-font-size-xlk-font-size-lgk-font-size-mdk-font-size-smOur design system styles follow a simple naming structure based on .{prefix}-{name}-{modifier} format.
.{prefix}-{name}-{modifier}..k-button or .k-input. “K” stands for “Kesko”. Prefixing is critical to ensure that our naming doesn’t conflict with other systems..k-button-primary or .k-button-outline..k-is-{status}. For example: .k-is-loading..k-button.k-input.k-button-outline.k-is-loadingWhen naming Custom Element and Figma attributes, it’s important to pay attention to the consistency between the different components so that API stays as predictable as possible. Our shared conventions include:
size and follow our sizes guideline for naming.disabled.variant for style variants such as success, error and such.aligntitlelangtranslatedirdatasethiddentabIndexaccessKeydraggablespellcheckautocapitalizecontentEditableisContentEditableinputModeoffsetParentoffsetTopoffsetLeftoffsetWidthoffsetHeightstyleinnerTextouterTextoncopyoncutonpasteonabortonbluroncanceloncanplayoncanplaythroughonchangeonclickoncloseoncontextmenuoncuechangeondblclickondragondragendondragenterondragleaveondragoverondragstartondropondurationchangeonemptiedonendedonerroronfocusonfocusinonfocusoutoninputoninvalidonkeydownonkeypressonkeyuponloadonloadeddataonloadedmetadataonloadstartonmousedownonmouseenteronmouseleaveonmousemoveonmouseoutonmouseoveronmouseuponmousewheelonpauseonplayonplayingonprogressonratechangeonresetonresizeonscrollonseekedonseekingonselectonstalledonsubmitonsuspendontimeupdateontoggleonvolumechangeonwaitingonwheelonauxclickongotpointercaptureonlostpointercaptureonpointerdownonpointermoveonpointeruponpointercancelonpointeroveronpointeroutonpointerenteronpointerleaveonselectstartonselectionchangenonceclickfocusblurnamespaceURIprefixlocalNametagNameidclassNameclassListslotattributesshadowRootassignedSlotinnerHTMLouterHTMLscrollTopscrollLeftscrollWidthscrollHeightclientTopclientLeftclientWidthclientHeightattributeStyleMaponbeforecopyonbeforecutonbeforepasteonsearchpreviousElementSiblingnextElementSiblingchildrenfirstElementChildlastElementChildchildElementCountonfullscreenchangeonfullscreenerroronwebkitfullscreenchangeonwebkitfullscreenerrorsetPointerCapturereleasePointerCapturehasPointerCapturehasAttributesgetAttributeNamesgetAttributegetAttributeNSsetAttributesetAttributeNSremoveAttributeremoveAttributeNShasAttributehasAttributeNStoggleAttributegetAttributeNodegetAttributeNodeNSsetAttributeNodesetAttributeNodeNSremoveAttributeNodeclosestmatcheswebkitMatchesSelectorattachShadowgetElementsByTagNamegetElementsByTagNameNSgetElementsByClassNameinsertAdjacentElementinsertAdjacentTextinsertAdjacentHTMLrequestPointerLockgetClientRectsgetBoundingClientRectscrollIntoViewscrollscrollToscrollByscrollIntoViewIfNeededanimatecomputedStyleMapbeforeafterreplaceWithremoveprependappendquerySelectorquerySelectorAllrequestFullscreenwebkitRequestFullScreenwebkitRequestFullscreenpartcreateShadowRootgetDestinationInsertionPointsnodeTypenodeNamebaseURIisConnectedownerDocumentparentNodeparentElementchildNodesfirstChildlastChildpreviousSiblingnextSiblingnodeValuetextContenthasChildNodesgetRootNodenormalizecloneNodeisEqualNodeisSameNodecompareDocumentPositioncontainslookupPrefixlookupNamespaceURIisDefaultNamespaceinsertBeforeappendChildreplaceChildremoveChild