Import and export

Moving tokens in and out as files. Both live under the footer’s Import / Export dropdown.

---

Export

Two modes.

Single JSON

Downloads design-tokens.json — one DTCG document containing the schema marker, version, and the whole token tree:

{
  "$schema": "…",
  "$version": "2025.10",
  "tokens": {
    "color": {
      "primary": {
        "500": { "$type": "color", "$value": { … } }
      }
    }
  }
}

This is exactly what the JSON editor shows.

Folder export

Downloads design-tokens.zip — one JSON file per token set, nested to match the set paths, plus $themes.json if the document has themes:

design-tokens.zip
├── global/primitives/color.json
├── global/semantic/color.json
├── comp/button.json
└── $themes.json

Inside each file the set prefix is stripped from token names, so a folder export → folder import round trip is lossless. Tokens without a set land in tokens.json.

Use folder export when the tokens are going into a repository where separate files give you meaningful diffs and review.

The dialog shows a summary of tokens, sets, and (in folder mode) file count. Download is disabled at zero tokens.

---

Import

Two modes. Both merge into the existing document rather than replacing it.

Single JSON

Pick a .json file. The dialog previews the token and set count before you commit.

Error	Cause
No tokens detected in this file.	Parsed, but no recognisable tokens
Invalid JSON file.	Did not parse

Folder import

Pick a directory. Every .json file in it is read recursively. Non-JSON and unparsable files are skipped and listed in a Skipped files warning box, so nothing is dropped silently.

---

Accepted formats

Import is deliberately permissive:

Format	Recognised by
DTCG document	A $version field plus tokens
Folder structure	Multiple files, as produced by folder export or a Git pull
Flat array	[{ name, value, type }, …]
Nested Style Dictionary / Tokens Studio	Nested objects using $value/$type or value/type, with $type inherited from parent groups

Anything else reports “Unrecognized JSON format.”; an empty folder reports “Folder import did not contain any design tokens.”

A token with no determinable type becomes other.

ZIP import is not supported — unzip a folder export before importing it.

---

Merge vs replace

This distinction matters and is not obvious in the UI:

Action	Behaviour
Import dialog (either mode)	Merge — incoming tokens and sets are added to what is there
JSON editor → save json	Replace — the whole document becomes the editor’s contents
Sync → pull	Replace — local tokens are overwritten by the remote

There is no merge-conflict resolution. Merging two documents that define the same token path means the incoming value wins.

Themes are an exception even on import: a payload containing themes replaces the current theme list.

---

Round-trip guarantees

Preserved	Not preserved
Token names, types, values, descriptions	Undo history
Token set structure (folder mode)	Layer bindings — those live on Figma layers, not in the JSON
Themes and their set states	Theme active state — imported themes arrive inactive
References, including composite slot references