Token Reference
This page distinguishes the public token surfaces you should build against from the engine variables that exist for implementation, diagnostics, and advanced interop.
Most applications should prefer:
- Semantic classes (e.g.
surface-card,text-subtle,hue-brand) - Exported tokens (for example from
axiomatic export --format typescript)
If you directly depend on --axm-* CSS variables, treat them as an advanced escape hatch rather than the default integration surface.
Public surfaces
Section titled “Public surfaces”Semantic classes
Section titled “Semantic classes”The primary “token surface” is the set of semantic classes generated and shipped by the system.
- Surfaces:
surface-page,surface-card,surface-action, … - Text:
text-strong,text-subtle, … - Hue modifiers:
hue-brand,hue-danger, …
Exported tokens (recommended for libraries)
Section titled “Exported tokens (recommended for libraries)”If you are building custom primitives or a component library, prefer consuming exported tokens (TypeScript/DTCG/Tailwind) rather than reading engine CSS variables.
Internals / interop (engine CSS variables)
Section titled “Internals / interop (engine CSS variables)”These variables are scoped to the current surface context (e.g., inside .surface-card) and change as nesting/context changes. They are useful for diagnostics and advanced interop, but are not the preferred day-to-day surface.
| Token | Description |
|---|---|
--axm-surface-token | The background color of the current surface. |
--axm-text-high-token | High-contrast text color (e.g., Black on Light, White on Dark). |
--axm-text-subtle-token | Lower-contrast text color for secondary information. |
--axm-text-subtlest-token | Lowest-contrast text color for placeholders or disabled text. |
--axm-border-dec-token | Decorative border color (low contrast). |
--axm-border-int-token | Interactive border color (higher contrast). |
Prefer using the utility classes (like .text-strong, .surface-card) instead of accessing these tokens directly. This ensures your UI remains consistent with the system’s composition model.
Utility Classes
Section titled “Utility Classes”These utility classes provide a semantic layer over the raw tokens.
Context Accessors
Section titled “Context Accessors”These utilities allow elements to “read” the current surface context and apply it to specific properties. Use these when you need an element to match the current surface (e.g., for masking or blending) without creating a new surface context.
| Class | Description |
|---|---|
.bg-surface | Sets background-color to the surface token. |
.border-surface | Sets border-color to the surface token. |
.stroke-surface | Sets SVG stroke to the surface token. |
Interaction States
Section titled “Interaction States”These utilities apply system-wide interaction styles, ensuring consistency for focus and selection states.
| Class | Description |
|---|---|
.ring-focus | Applies a static focus ring. |
.ring-focus-visible | Applies a focus ring only on :focus-visible. |
.border-highlight | Sets border-color to the highlight ring color. |
Composition
Section titled “Composition”You can compose surface classes with hue utilities to create colored surfaces.
<!-- A button with the highlight color --><button class="surface-action hue-highlight">Click Me</button>Global Tokens
Section titled “Global Tokens”These tokens are defined on :root and are available everywhere.
Elevation (Shadows)
Section titled “Elevation (Shadows)”| Token | Description |
|---|---|
--axm-shadow-sm | Small shadow for subtle depth. |
--axm-shadow-md | Medium shadow for cards and dropdowns. |
--axm-shadow-lg | Large shadow for modals and floating actions. |
--axm-shadow-xl | Extra large shadow for major overlays. |
| Token | Description |
|---|---|
--axm-focus-ring-color | The brand-aware color used for focus rings. |
Data Visualization
Section titled “Data Visualization”If you have configured a palette in color-config.json, these tokens will be available.
| Token | Description |
|---|---|
--axm-chart-1 | First color in the categorical palette. |
--axm-chart-2 | Second color… |
| … | … |
--axm-chart-N | Nth color. |
Internal Tokens
Section titled “Internal Tokens”You may see these tokens in the generated CSS, but they are generally intended for internal use by the engine.
--axm-chroma-brand: The base chroma value derived from your key colors.--axm-hue-brand: The base hue value derived from your key colors.