Token System
The token system keeps design decisions centralized, explicit, and overridable. Global tokens define the shared design language, component manifests declare which inputs are allowed, and component-scoped aliases provide the safe runtime override surface.
Why the token system exists
- Tokens replace one-off visual values with named system inputs, which keeps the design language consistent.
- Global tokens define the shared runtime surface, while components only consume the tokens they explicitly declare.
- Theme authors override the global layer, and local implementations should override component aliases rather than editing component Sass.
How the token system works
The implementation is intentionally explicit. Global tokens are defined once, compiled into CSS variables, mapped into component scope, and then consumed through helper functions. That keeps the customization surface stable and makes inheritance rules easier to reason about.
Define global tokens
System tokens live in JSON so the source of truth stays explicit, reviewable, and schema-validated.source/data/design-tokens.json
Generate runtime variables
The token compiler turns JSON entries into CSS custom properties that are published at the global layer.source/sass/setting/_design-tokens.scss
Declare allowed component inputs
Each component must opt in to the tokens it is allowed to consume. Nothing is mapped implicitly.source/components/<component>/component.json
Map to component scope
The token mixin creates component-local aliases such as --c-card--color--surface from the approved global tokens.source/sass/mixin/_tokens.scss
Override safely at runtime
Themes change the global token surface, while local instances override component-scoped aliases without forking component Sass.:root or .c-component
Base token reference
These are the foundational system tokens that the component layer builds on. Direct tokens are the intended customization inputs. Derived tokens are published for consumption, but their upstream inputs are the place to make supported changes.
Base
The baseline units everything else scales from.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--base
|
Foundation unit for spacing, size, and radius calculations across the system. | Locked system baseline. Defaults to calc(1rem / 2) and is usually changed only indirectly. | No |
|
--base-font-size
|
Root type size that drives the entire font-size scale. | Direct token. The computed font-size tokens derive from this value. | Yes |
Layout
Controls the container widths used by the page structure.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--container-width-multiplier
|
Controls the main content width scale. | Direct numeric input used to compute the standard container width. | Yes |
|
--container-width
|
Final container width used by layouts. | Derived from --container-width-multiplier and --base. | No |
|
--container-width-wide-multiplier
|
Controls how much wider the wide container is than the default container. | Direct numeric input applied on top of the standard container width. | Yes |
|
--container-width-wide
|
Final wide-container width token. | Derived from --container-width and --container-width-wide-multiplier. | No |
Radius
Defines how rounded corners behave throughout the system.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--border-radius
|
Radius scale input used by components for rounded corners. | Direct numeric token that components usually multiply by --base. | Yes |
|
--corner-shape
|
Controls the corner rendering mode where corner-shape is supported. | Direct select token, typically switching between corner styles such as round. | Yes |
Typography
Sets the system-level inputs for font families, weights, and rhythm.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--font-family-base
|
Default body font family. | Direct font token used by the base text layer. | Yes |
|
--font-family-heading
|
Heading font family. | Defaults to the base font family until explicitly changed. | Yes |
|
--font-family-code
|
Monospace stack for code-oriented UI and documentation. | Locked direct token with a fixed default stack. | No |
|
--font-size-scale-ratio
|
Ratio used to generate the full font-size scale. | Direct select token consumed by the derived font-size tokens. | Yes |
|
--font-weight-normal
|
Default text weight. | Direct token for body text emphasis baseline. | Yes |
|
--font-weight-medium
|
Medium emphasis font weight. | Direct token for moderate emphasis states. | Yes |
|
--font-weight-bold
|
Strong emphasis font weight. | Direct token for bold emphasis. | Yes |
|
--font-weight-heading
|
Default heading weight. | Direct token applied to heading styles. | Yes |
|
--line-height-base
|
Default body line height. | Direct numeric token for readable body copy rhythm. | Yes |
|
--line-height-heading
|
Default heading line height. | Direct numeric token for tighter heading rhythm. | Yes |
|
--letter-spacing-base
|
Default text letter spacing. | Direct numeric token for overall body text tracking. | Yes |
Derived font sizes
Computed size tokens generated from the type baseline and scale ratio.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--font-size-80
|
Two steps below the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-90
|
One step below the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-100
|
Base type size token. | Derived directly from --base-font-size. | No |
|
--font-size-200
|
One step above the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-300
|
Two steps above the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-400
|
Three steps above the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-500
|
Four steps above the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-600
|
Five steps above the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-700
|
Six steps above the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
|
--font-size-800
|
Seven steps above the base type size. | Derived from --base-font-size and --font-size-scale-ratio. | No |
Borders
Controls line weight and companion-border generation.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--border-width
|
Base border width token for UI elements. | Direct numeric token used across components with outlines or dividers. | Yes |
|
--color--border-mix-amount
|
Mix ratio used when generating derived border companion colors. | Direct percentage token that influences border contrast from upstream colors. | Yes |
Spacing
Defines inner and outer rhythm values used by components and layouts.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--space
|
Standard internal spacing token for paddings and margins inside components. | Direct numeric token commonly multiplied with --base. | Yes |
|
--outer-space
|
Spacing token for gaps between components or for outer layout rhythm. | Direct numeric token used for larger structural separation. | Yes |
Shadows
Provides the global inputs used by component shadow formulas.
| Token | Purpose | How it works | Editable |
|---|---|---|---|
|
--shadow-color
|
Base color used by shadow formulas. | Direct RGBA token that controls the hue and transparency of elevation. | Yes |
|
--shadow-amount
|
Global multiplier for shadow intensity. | Direct numeric token that components combine with --base in shadow calculations. | Yes |