Token Sources

Configure where Design Tokens Explorer loads your tokens from — local files, remote URLs, and multiple sources.

The sources setting

designTokensExplorer.sources is an array of source objects. Each source loads tokens from a local file path or remote URL and appears as a separate panel in the sidebar.

settings.json

"designTokensExplorer.sources": [
  {
    "name": "Brand Tokens",
    "path": "./tokens/brand.css",
    "groups": [
      { "name": "color", "type": "color" },
      { "name": "radius", "type": "radius" },
      { "name": "space", "type": "size" }
    ]
  }
]

Source properties

Property	Type	Required	Description
name	string	Yes	Display name shown in the sidebar panel header
path	string	Yes	Local path (relative to workspace root) or HTTPS URL
groups	array	No	List of token groups with optional preview type assignment

Groups

Groups control how tokens are organized in the sidebar and which visual preview renderer is applied. Each group matches tokens by name prefix.

"groups": [
  { "name": "color", "type": "color" },
  { "name": "space", "type": "size" },
  { "name": "radius", "type": "radius" }
]

A token is assigned to the group whose name matches the beginning of the token name. The type then controls the preview renderer shown next to the value.

The group name must match the exact prefix used in your token names. If your tokens are named brandColor-500, brandColor-400, etc., the group name must be brandColor — not color.

// tokens: brandColor-500, brandColor-400, brandRadius-md
"groups": [
  { "name": "brandColor", "type": "color" },
  { "name": "brandRadius", "type": "radius" }
]

A mismatch means those tokens won’t be grouped and will fall into the Other category.

Group type reference

Type	Preview rendered	Example values
color	Color swatch	#7C3AED, rgb(124, 58, 237), hsl(263, 70%, 58%)
size	Visual width bar (rem→px converted)	1rem, 16px, 0.5rem
radius	Rounded corner demo	0.5rem, 4px, 50%
font-size	Scaled text sample	0.875rem, 1.25rem
font-weight	Weight demo text	400, 700, bold
line-height	Multi-line spacing demo	1.5, 1.75, 2
shadow	Shadowed element	0 2px 4px rgba(0,0,0,0.1)
easing	SVG cubic-bezier curve	cubic-bezier(0.4, 0, 0.2, 1)
time	Duration text	150ms, 0.3s
filter	No preview	blur(4px)

Tokens that don’t match any group are placed in an Other group without a preview.

The type field is optional. If omitted, DTE tries to infer the type from the group name (e.g. a group named color is treated as type color). Explicit type values are recommended for reliable previews.

Supported file formats

CSS custom properties

The file must declare tokens inside a :root {}, :where(html) {}, or @theme {} block:

tokens/brand.css

:root {
  --color-primary: #7c3aed;
  --color-primary-light: #a78bfa;
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
}

Token names are extracted without the -- prefix (color-primary, space-1, etc.).

SCSS

.scss files are loaded with the same parser as CSS. The file must declare tokens as CSS custom properties inside a :root {}, :where(html) {}, or @theme {} block. SCSS line comments (//) are supported inside those blocks. SCSS-specific syntax outside of custom property declarations is ignored.

tokens/brand.scss

:root {
  // Colors
  --color-primary: #7c3aed;
  --color-primary-light: #a78bfa;

  // Spacing
  --space-1: 0.25rem;
  --space-2: 0.5rem;
}

Use SCSS files when your token file already lives in a .scss context or you prefer SCSS-style (//) comments. The parsed output is identical to a CSS file with the same custom properties.

JSON

Flat or nested JSON objects are both supported. Nested keys are joined with -:

tokens/tokens.json

{
  "color": {
    "primary": "#7C3AED",
    "neutral": {
      "100": "#f5f5f5",
      "900": "#171717"
    }
  },
  "space": {
    "1": "0.25rem",
    "2": "0.5rem"
  }
}

This produces tokens: color-primary, color-neutral-100, color-neutral-900, space-1, space-2.

Nesting depth is limited to 20 levels.

JavaScript / TypeScript (local only)

String and number exports are parsed via regex — no code is executed:

tokens/tokens.ts

export const colorPrimary = '#7C3AED';
export const spaceSm = '0.5rem';
export const fontWeightBold = 700;

Remote .js / .ts files are not supported for security reasons. JS/TS loading only works for local files.

Remote sources

Any path starting with https:// is fetched as a remote source. The format is inferred from the file extension in the URL.

{
  "name": "Figma Tokens",
  "path": "https://tokens.example.com/tokens.json"
}

Remote source constraints:

• Timeout: 10 seconds
• Maximum response size: 2 MB
• Private IPs, localhost, and loopback addresses are blocked (SSRF protection)
• .js / .ts remote sources are not supported

Remote sources are fetched once on activation and re-fetched when you run Refresh Sources. They are not watched for changes automatically.

File watching

Local sources are watched for changes. When the file is saved, tokens are automatically reloaded after a 400 ms debounce and the sidebar refreshes. The usage audit also re-runs in the background.

Multiple sources

You can configure any number of sources. Each appears as a separate, switchable panel in the sidebar. See Multiple Sources for practical examples.