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

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

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

<Warning>
  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`.

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

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

<Tip>
  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.
</Tip>

## Supported file formats

### CSS custom properties

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

```css tokens/brand.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;
  --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.

```scss tokens/brand.scss theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
:root {
  // Colors
  --color-primary: #7c3aed;
  --color-primary-light: #a78bfa;

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

<Tip>
  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.
</Tip>

### JSON

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

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

```ts tokens/tokens.ts theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
export const colorPrimary = '#7C3AED';
export const spaceSm = '0.5rem';
export const fontWeightBold = 700;
```

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

## Remote sources

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

```json theme={"theme":{"light":"material-theme-ocean","dark":"material-theme-ocean"}}
{
  "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](/docs/guides/multiple-sources) for practical examples.