v0.4.0GitHub—

docs / guides / tokens

Design tokens

Show the real token names behind typography, colors, spacing, and corners.

##Enable inspection

javascript
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.

css
: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

FieldDefaultMeaning
sourceNoneExtra token object, flat or in the supported DTCG-like structure.
csstrueRead root CSS custom properties; set false for an external-only source.
max2Maximum token names in a label.
javascript
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

javascript
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.