> ## Documentation Index
> Fetch the complete documentation index at: https://dtexplorer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Token File Formats

> Detailed guide to CSS, SCSS, JSON, and JavaScript/TypeScript token file formats — syntax, examples, and parsing rules.

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 `:root {}`, `:where(html) {}`, and `@theme {}` blocks.

### Syntax

```css tokens.css theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
: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);
}
```

Tailwind-style theme blocks are also supported:

```css tokens.css theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
@theme {
  --color-primary: #7c3aed;
  --space-2: 0.5rem;
}
```

### 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

* All `:root {}`, `:where(html) {}`, and `@theme {}` blocks in the file are 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 supported blocks are ignored.
* Variables that reference other variables (e.g. `--color-bg: var(--color-neutral-50)`) are loaded with the raw reference value.

### Multiple blocks

All supported blocks are parsed. You can split tokens across multiple `:root {}`, `:where(html) {}`, and/or `@theme {}` blocks in the same file.

***

## SCSS

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

### Syntax

```scss tokens.scss theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
: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 supported blocks are handled correctly — they do not interfere with token extraction.

### Rules and limitations

* The same constraints as CSS apply: all supported blocks (`:root`, `:where(html)`, `@theme`) are 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

```json tokens.json theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
{
  "color-primary": "#7C3AED",
  "color-surface": "#FAFAFA",
  "space-4": "1rem",
  "radius-md": "0.5rem"
}
```

Token names match the JSON keys directly.

### Nested JSON

```json tokens.json theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
{
  "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:

```json theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
{
  "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

```ts tokens.ts theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
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

| Consideration                             | CSS | SCSS | JSON         | JS/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 supported blocks     | —   | ✓    | —            | —     |

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.