-
Notifications
You must be signed in to change notification settings - Fork 76
tokens naming schema
Using the token naming schema we can define individual design decisions and catalogue them for consistency across team(s) or business(es).
Calcite tokens extend the W3C Design Token Working Group model and each token always has the following properties.
timeline
title Naming Schema
section Namespace
System : calcite
Tier : core : global : web-platform
Domain : internal
section Object
Component : button : action : dropdown
Element : heading : description : content
Type : color : corner-radius : space : size
section Base
Group : brand : status
Kind : info : success : danger
Appearance : transparent : outline : round : start : end
section Modifier
Scale : lg : md : sm : 1 : 2 : 3
State : hover : focus : active : selected
Context : color
Mode : light : dark
The Calcite Design System was designed for Esri teams and our customers to support the use of Esri apps and tools.
The categories of the design system that group tokens by their usage patterns.
Core tier tokens (also known as foundation or base tokens). Their main role in the system are to store all raw values. This is the level that state all options available first and with it build the ground base options of the design system. This tier is responsible for the look of the final product by defining all the values that can be used across the whole tokens ecosystem. Tokens in this tier are intended to be used as references on semantic and component tier tokens.
Global tier tokens help associate meaning, context, and/or intent to the design tokens across an entire domain. Tokens in this tier do not use raw values like “16px” or “8%”, and so on. They should always reference a Core token instead. Their name represents the decisions the design system team made in regards to when to their intended use.
Component tokens are platform specific. They may have string and compound values but should not use raw values like “16px” or “#fff” but instead should reference other tier tokens - core and global. Component tokens represent component level visual pattern decisions. The names should be clearly understandable and be as specific as possible in order to be applied in component development. Component tokens may be considered by customer request to provide better theme customization. Current component level tokens may be applied to the following CSS properties on the web.
-
border-color: should reference acolortoken. -
color: should reference acolor.texttoken. -
background-color: should reference acolortoken. -
border-radius: should reference acorner.radiustoken. -
box-shadow: should reference ashadowtoken unless a component token is only provided for thebox-shadow-color, in which case it can reference anycolortoken.
Tokens on this tier may be specific to a component's variants and/or states.
The sets of tokens under a team name. Calcite reserves 'internal' for internal team tokens. Domain tokens should within the system should still follow Calcite Design System best practices.
A specific custom component the token is applied to.
Element(s) within the component with it’s own internal state.
A predefined categorization applied to the token’s value which defines the purpose of the token.
Tokens which define the container breakpoints on various devices. Not used in Figma.
Tokens are used across all the system and can be found in all of the token tiers for multiple purposes. You can use color tokens to create new color styles, update color styles across the system or apply them to a fill or stroke.
Defines the "roundness" of a components edges. Can be applied to all corners, or to a specific corner like “top-right”, “top-left”, “bottom-right”, “bottom-left”.
Names used in the application to define font families. This is just a name reference, the appropriate asset files will need to be loaded separately. Not used in Figma.
Typographic ordinal naming for weight scales which may be converted to numeric values for certain platforms. Not used in Figma.
Only found in the semantic tier. These are set as static values but will be exported as relative values for the web platform.
These are set as static values which may be exported as relative values for certain platform.
tokens which define set opacity percentages used across the design system. Not used in Figma.
Defines an effect style either simple with one single level of shadow or an array of multiple shadows. These can be used combined with other tokens like colors or dimensions to create references and stay updated along the evolution of the design system.
Used to create tokens that define the width, height, or both. They can also be used to set min-widths or max-widths depending on the need and to set specific breakpoint sizes.
Spacing tokens define values like paddings, margins, and gutters. They can be used to define space all-around, to a gap, or to a specific side of the element or component to build.
Sets the stacking layer for UI elements. Not used in figma.
A set of tokens belonging to a specific category.
A variant of tokens belonging to a specific group.
A variant of tokens belonging to s specific visual group.
Regarding scales, we can use numeric, ordinal (especially helpful for small scales with around five items), or customized scales according to the needs.
Use for scales with a large number of tokens. Example -0, 1, 2, 3 ... [list tokens where scale is numerical]
Used for scales of five tokens or less. Example - lg, md, sm, ... [list tokens where scale is ordinal]
50, 60, 70, 100, ... 900
level-1, level-2, level-3
thin, light, regular ... snug, tight
Mutually exclusive user interaction inaction variations. This might include web specific pseudo classes like :hover, :focus, and :active but also include disabled and more generalized interaction states like highlight and selected.
Mutually exclusive variations within a specific type.