Importing Tokens

Step 1 — Upload your file

Drag a file onto the upload area or click to browse. ReframeUI accepts JSON, CSS, and JS config files depending on the format.

The format selector defaults to "Auto-detect (recommended)." Auto-detect reads the file structure and picks the closest match. If it selects the wrong format, choose the correct one from the dropdown before proceeding. See Import Formats for the full list of supported formats and what a valid input looks like for each.

Step 2 — Review the token map

After upload, ReframeUI parses your file and shows a preview of every token it found. The table lists each token's path, type, target section, and resolved value.

If one or more tokens could not be confidently assigned to a section, a badge appears showing the count. Those tokens require manual review before the import can proceed. Click "Next" to move to the mapping step. If every token was categorized automatically, no badge appears and you move directly to applying the import.

Step 3 — Resolving ambiguous tokens

This step appears only when one or more tokens could not be automatically categorized. For each row, you see the token path, the inferred type, and a suggested section when one exists.

For each token, pick one of three actions:

• –Choose a section from the dropdown.
• –Leave the suggested section as-is and continue.
• –Check Skip to exclude the token from this import entirely.

Skipped tokens do not appear in your project. They are counted in the final summary so you know what was left out.

Reviewing changes before applying

Before the import writes anything to your project, ReframeUI shows you a diff. Three categories are listed:

• –Added: token paths not currently in your project.
• –Modified: existing paths whose values differ from what is already there.
• –Conflicting: paths where both the import file and your existing token have changed.

If there are no conflicts, this step is skipped and the import applies immediately.

For conflicting tokens, a resolution table lets you decide what happens to each one. Three options are available per token:

• –Overwrite (default): the incoming value replaces the existing one.
• –Skip: the existing token is left as-is and the incoming value is discarded.
• –Rename: the incoming token is written under a new path. Selecting this option reveals a text input for the new name. The Apply button stays blocked until every rename input has a value.

Review your resolutions before clicking Apply. Overwritten tokens cannot be recovered unless you re-import.

Alias breakage warning

This step appears after conflict resolution when the import would remove or rename a token path that an existing alias token references. If no aliases are affected, this step is skipped.

The table shows each affected alias, its current reference path, and why it will break. You have two options: re-point each alias to a different token before confirming, or proceed and fix the broken aliases manually after the import completes.

Confirmation and summary

The final step shows a summary: how many tokens were imported, how many were skipped (either during the ambiguous step or via a conflict skip), and a close button. Imported tokens appear in the token table immediately. The import is saved automatically; no publish step is required.

What happens to existing tokens

Import is additive. Tokens not present in your import file are not changed or removed.

Only the token paths that appear in your file are touched, according to the resolutions you chose in the diff step. If you want to replace your entire token set, delete the existing tokens first, then import.