docs / guides / tokens
Design tokens
Show the real token names behind typography, colors, spacing, and corners.
##Enable inspection
create({
root: 'main', auto: true, inspect: true,
plugins: ['tokens'],
});After a finished element is hovered, the plugin compares its computed style with known tokens. Without inspect: true or construction labels, installing the plugin alone does not make labels visible.
##CSS custom properties
The plugin reads declarations on :root and html, including adopted stylesheets and inline root properties. It infers categories from token names and resolves values through the browser, so CSS aliases, rem, clamp(), and supported color syntax can match actual rendered values.
:root {
--color-text-primary: #181b20;
--font-size-title: 2rem;
--space-card: 1.5rem;
--radius-card: 0.75rem;
}
.card { padding: var(--space-card); border-radius: var(--radius-card); }
h2 { color: var(--color-text-primary); font-size: var(--font-size-title); }Cross-origin stylesheets that the browser refuses to expose through CSSOM are skipped. Component-only declarations are not an independent token source. Use the explicit source option when your tokens live elsewhere.
##TokensOptions
| Field | Default | Meaning |
|---|---|---|
source | None | Extra token object, flat or in the supported DTCG-like structure. |
css | true | Read root CSS custom properties; set false for an external-only source. |
max | 2 | Maximum token names in a label. |
import { create, tokens } from 'swarmtroopers';
create({
root: 'main', auto: true, inspect: true,
plugins: [tokens({
max: 3,
source: {
'color.text.primary': '#181b20',
'font-size.title': '32px',
'space.card': '24px',
'radius.card': '12px',
},
})],
});##Structured sources and aliases
const source = {
color: {
$type: 'color',
base: { $value: '#4f7bff' },
action: { $value: '{color.base}' },
},
space: {
card: { $type: 'dimension', $value: { value: 24, unit: 'px' } },
},
};
const plugin = tokens({ css: false, source });The parser recognizes $value, inherited $type, string references such as {color.base}, numeric values interpreted as pixels, { value, unit } dimensions, and color objects with a hex field. Alias resolution follows at most eight reference hops. It is not a general validator or full converter for every DTCG color-space representation; provide CSS color strings or supported values.
##What labels report
Typing tasks match font size and text color. Rules match background or border color. Frames match the top-left corner radius, background, top padding, and top border. Semantic color names are preferred when several names share a value. A missing match falls back to Swarm Troopers’ ordinary size label.
The token index is cached, then invalidated when Swarm Troopers invalidates layout, such as after resize, fonts, or refresh(). Inspection explains computed values; it does not edit your token system.