Skip to main content
Design Tokens Explorer supports four token file formats. This guide covers the exact syntax expected by each parser, edge cases, and how token names are derived.

​
CSS custom properties

The CSS parser extracts tokens from CSS custom properties declared inside a :root {} block.

​
Syntax

tokens.css
:root {
  --color-primary: #7c3aed;
  --color-primary-light: #a78bfa;
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --radius-sm: 0.25rem;
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

​
Name derivation

The -- prefix is stripped. The token name in the panel is the CSS custom property name without dashes: color-primary, space-1, etc.

​
Rules and limitations

  • Only :root {} is scanned. Tokens declared in other selectors (:host, [data-theme], media queries) are not loaded.
  • Values can be any valid CSS value string — colors, lengths, shadows, easing functions, etc.
  • Multi-value properties are supported: --shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -2px rgba(0,0,0,0.05).
  • Comments inside :root are ignored.
  • Variables that reference other variables (e.g. --color-bg: var(--color-neutral-50)) are loaded with the raw reference value.

​
Multiple :root blocks

Only the first :root {} block in the file is parsed. Tokens in a second :root {} block will not be loaded.

​
SCSS

SCSS files (.scss) are parsed with the same engine as CSS. The file must declare tokens as CSS custom properties inside a :root {} block. SCSS-specific syntax like variables ($var), nesting, and mixins is ignored — only CSS custom properties inside :root are extracted.

​
Syntax

tokens.scss
:root {
  // Primary palette
  --color-primary: #7c3aed;
  --color-primary-light: #a78bfa;

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

  // Radius
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
}
SCSS line comments (//) inside :root are handled correctly — they do not interfere with token extraction.

​
Rules and limitations

  • The same constraints as CSS apply: only the first :root {} block is parsed.
  • SCSS-only features (variables, @mixin, @include, nesting) are not interpreted. Only CSS custom property lines (--name: value;) are extracted.
  • Remote .scss sources are supported with the same constraints as remote CSS sources.

​
JSON

The JSON parser supports both flat and deeply nested objects. All values are flattened into a single token list.

​
Flat JSON

tokens.json
{
  "color-primary": "#7C3AED",
  "color-surface": "#FAFAFA",
  "space-4": "1rem",
  "radius-md": "0.5rem"
}
Token names match the JSON keys directly.

​
Nested JSON

tokens.json
{
  "color": {
    "primary": "#7C3AED",
    "neutral": {
      "100": "#F5F5F5",
      "500": "#737373",
      "900": "#171717"
    }
  },
  "space": {
    "1": "0.25rem",
    "2": "0.5rem",
    "4": "1rem",
    "8": "2rem"
  }
}
Nested keys are joined with -. The above produces:
  • color-primary
  • color-neutral-100
  • color-neutral-500
  • color-neutral-900
  • space-1, space-2, space-4, space-8

​
Design Tokens format (W3C / Style Dictionary)

Many design tools export tokens in a nested format with a $value key. This is flattened like any other nested structure. The path segments (excluding $value) become the token name: 
{
  "color": {
    "primary": {
      "$value": "#7C3AED",
      "$type": "color"
    }
  }
}
This produces: color-primary-$value (with value #7C3AED) and color-primary-$type (with value color). If you use this format, consider naming conventions that avoid $value in the token name — or configure a group to filter by prefix.

​
Rules and limitations

  • Values must be strings or numbers. Arrays and booleans are skipped.
  • Maximum nesting depth: 20 levels.
  • Numbers are converted to strings (e.g. 400 becomes "400").
  • Parsing errors result in an empty token set with an error notification.

​
JavaScript / TypeScript (local files only)

The JS/TS parser uses regex to extract string and number variable assignments without executing any code.

​
Syntax

tokens.ts
export const colorPrimary = "#7C3AED";
export const colorPrimaryLight = "#A78BFA";
export const spaceSm = "0.5rem";
export const fontWeightBold = 700;

// Works with const/let/var and optional type annotations
export const radiusMd: string = "0.5rem";
export let shadowBase = "0 2px 4px rgba(0,0,0,0.1)";

​
Name derivation

Variable names are used as-is (they are not converted to kebab-case). The token name in the panel matches the variable name: colorPrimary, spaceSm, fontWeightBold.

​
Rules and limitations

  • Only single-line assignments are matched. Multi-line values are not supported.
  • Values must be string literals (single quotes, double quotes, or backticks) or number literals.
  • Complex expressions, function calls, template literals with interpolations, and object/array assignments are all ignored.
  • TypeScript type annotations between : and = are tolerated and stripped.
  • Remote JS/TS files are not supported. Only local workspace files can be loaded. This is a deliberate security constraint.
  • Destructuring assignments and shorthand exports are not matched.

​
When to use JS/TS format

JS/TS loading is best for simple constant files that export primitive token values. If your token file is complex (uses imports, computed values, or factories), consider exporting a plain JSON file instead.

​
Choosing a format

ConsiderationCSSSCSSJSONJS/TS
Nesting support——Deep nesting—
Remote loading✓✓✓—
Native CSS usage✓✓——
Tool compatibility (Figma, Tokens Studio)——✓—
Code-defined tokens———✓
No build step required✓✓✓✓
SCSS comments inside :root—✓——
For most design systems, CSS custom properties are the recommended format — they can be used directly in the browser, work with all CSS preprocessors, and are natively understood by browsers. SCSS is the right choice when your token file already lives in a .scss context or uses SCSS-style comments. JSON is ideal when tokens come from a design tool export. JS/TS is useful for component library packages that expose token constants.