-
Notifications
You must be signed in to change notification settings - Fork 89
tokens intro
Why are you reading this introduction? You're likely on this page because you are trying to solve an immediate problem. You need to use, update, or add Calcite tokens or need to understand how to use tokens in your project. It likely feels overwhelming. You want to do this one little thing and get back to what you were doing. However, Design Tokens are more than a variable, they are a methodology for storing and sharing distinct design decisions in an enterprise design system.
Design tokens are the building blocks of design - they represent decisions like color, spacing, shadow, and opacity. Design tokens encourage consistency across experiences, reinforce accessibility within components, and support rich theming and customization.
- Communication and collaboration of shared design decisions across teams and modalities
- Management and documentation of the Calcite Design System
- Unique source of truth to improve better communication and collaboration from design to development
- Design consistency across any product UI
- Improved management of the design system
- Easier management of themes and white-labelling features
In Calcite’s Design Token names must be unique, meaningful, easy-to understand, modular, and consistent. We have simple rules that allows the team to keep creating design tokens consistently and we provide template token sets to move work forward ensuring consistency and scalability. Read more about the Calcite Design Tokens naming schema..
When the TokenTransformer is run, each token's unique identifier in the naming schema is parsed and converted to a variable name for the appropriate platform context. Read more about platform output. Component tokens currently only exist in Calcite Components because that was the domain they were built for but will be moved to the Calcite Design Tokens package in a future update.
flowchart LR
value2-->coreToken
cssToken1-->cssToken2
semanticToken-->transformer
subgraph transformer
tokenTransformer{{ Token Transformer }}
cssToken1("--calcite-color-foreground-1: ffffff;")
cssToken2("--calcite-button-background-color: var(--calcite-color-foreground-1);")
tokenTransformer -- semantic.css --> cssToken1
end
subgraph coreToken[Core]
value1("value: #FFFFFF")
system1(system: calcite)
tier1(tier: core)
type1(type: color)
group1(group: neutral)
variant1(variant: blk)
scale1(scale: 000)
end
subgraph semanticToken[Semantic]
value2("value: {calcite.core.color.neutral.blk.000}")
system2(system: calcite)
tier2(tier: semantic)
type2(type: color)
group2(group: foreground)
scale2(scale: 1)
end
flowchart LR
componentToken(COMPONENT TOKEN)
semanticToken(SEMANTIC TOKEN)
coreToken(CORE TOKEN)
raw(RAW VALUE)
componentToken --> semanticToken
semanticToken --> coreToken
coreToken --> raw
Core tier tokens are always strings representing a raw value. All other token tiers should be string references to higher tier tokens.
A composite token is a map of string values representing a complex token like Shadow. read more about composite tokens from the W3C Community Group. These are currently used by tokens in the core tier and are converted to a string by the TokenTransformer when generating CSS output. Learn more about web-platform support.
Semantic and core token documentation is generated via the TokenTransformer for the Esri Developer Docs. Component tokens are documented via JSDocs style comments in the SCSS file for each relevant component. This is to support the existing component variables documentation process but will be moved to use the Calcite Design Tokens Transformer in the future. Read more on the tokens documentation page.