-
Notifications
You must be signed in to change notification settings - Fork 76
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 encapsulate essential visual elements such as colors, typography, spacing and more. They provide a powerful solution to standardizing, documenting, and reusing shared design decisions and providing those visual interface elements as data exported for each unique supported context, also called a platform.
In the ever-expanding global digital ecosystem, designing and maintaining user interfaces that resonate across diverse geographical, technological, and spacial contexts is a formidable task. Design systems grapple with the ever more complex need for consistency and documentation of design patterns.
- 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
globalToken-->transformer
subgraph transformer
tokenTransformer{{ Token Transformer }}
cssToken1("--calcite-color-foreground-1: ffffff;")
cssToken2("--calcite-button-background-color: var(--calcite-color-foreground-1);")
tokenTransformer -- global.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 globalToken[Global]
value2("value: {calcite.core.color.neutral.blk.000}")
system2(system: calcite)
tier2(tier: global)
type2(type: color)
group2(group: foreground)
scale2(scale: 1)
end
flowchart LR
componentToken(COMPONENT TOKEN)
globalToken(GLOBAL TOKEN)
coreToken(CORE TOKEN)
raw(RAW VALUE)
componentToken --> globalToken
globalToken --> 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.
Global 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.