Best Practices

Naming Conventions

Consistent naming makes variables easier to find, swap, and maintain:

Use Hierarchical Names

Organize variables in groups using forward slashes

Color/Primary/500Color/Primary/600Spacing/Base

Keep Names Consistent Across Modes

Use identical names in different modes for reliable swapping

Light Mode:

Background/Primary

Dark Mode:

Background/Primary

Avoid Implementation Details in Names

Don't include values or technical details in variable names

Bad:Color-FF0000

Good:Color/Error

Don't Use Special Characters

Stick to letters, numbers, slashes, and hyphens for maximum compatibility

Collection Organization

Group by Type

Create separate collections for different variable types:

Colors

Spacing

Typography

Use Modes Effectively

Modes should represent variants of the same design system:

Good use of modes:

• Light / Dark themes
• Brand A / Brand B variants
• Desktop / Mobile spacing scales

Limit Collection Size

Keep collections focused and manageable. If a collection grows too large (100+ variables), consider splitting it into multiple themed collections.

Export Best Practices

💾 Regular Backups

Export your variables weekly (or before major changes) as a backup

Recommended: Store in a dedicated folder with date stamps

Use Version Control

Commit exported JSON to Git for full change history

git add variables-export.json
git commit -m "Update color tokens"
git push

Meaningful File Names

Rename exported files to include version or context

variables-v2.1.0.jsondesign-tokens-2024-01-15.jsonbrand-colors-production.json

Import Best Practices

Always Preview Before Executing

The preview shows exactly what will change. Review it carefully to avoid unwanted modifications.

Understand Replace vs Rename

Replace

Overwrites existing data. Use when updating from source of truth.

Rename

Creates a copy. Use when testing or keeping both versions.

Test with Sample Data First

If you're new to importing, download the sample JSON and try importing it first to understand the process.

Backup Before Large Imports

Export your current variables before importing large sets with Replace strategy. You can re-import if something goes wrong.

Swap Best Practices

Start Small, Go Big

Test swapping with these progressively larger scopes:

1️⃣

Current Selection

Test on a few selected layers

2️⃣

Current Page

Expand to the whole page

3️⃣

Entire File

Only after confirming it works as expected

Maintain Naming Consistency

For reliable swapping, use identical variable names across collections/modes:

✓ Good:

Light / Primary/500Dark / Primary/500

Always Check the Preview

The preview shows which layers will be affected and which variables couldn't be matched. Review it before executing.

💡 Remember

Swap is undo-friendly! Press Cmd/Ctrl + Z if the result isn't what you expected.

Team Collaboration

Establish a Source of Truth

Designate one file as the master source for design tokens. Team members export from master and import into their working files.

Document Your Process

Create a team guide covering:

• Naming conventions
• When to use Replace vs Rename
• Where to store exported JSONs
• How to handle conflicts

Use Shared Storage

Store exported JSONs in a shared location (Git, Dropbox, Google Drive) so the team can access the latest versions.

Performance Tips

Large Files

Files with hundreds of collections may take longer to process. Be patient during export/import operations.

Swap Scope

Swapping across entire file in large designs can be slow. Use page or selection scope when possible.

Batch Operations

Export multiple collections at once rather than one at a time for better efficiency.