What does not work yet, and what to do instead. It describes the current release. For a quick overview see Feature status.
Can overwrite your work
Read these first.
| Limitation |
Do instead |
| Every import replaces the whole project. There is no merge |
Export first. Undo restores the previous project while the plugin stays open |
| A pull replaces the project in the file, after a review |
Review the list of removed tokens before you confirm |
| After a cancelled review, a refused file or an undone pull, the remote still counts as reviewed, so the next push can replace it without the overwrite dialog |
Do not push until a pull has been imported, or work on a separate branch. See Sync |
| A token path changed in the JSON editor creates a new token, and layers lose their binding |
Rename in the token dialog |
| A token renamed directly in Git arrives as a new token, and the old one is removed |
Rename in the plugin or through an AI app, then push. This keeps the bindings in that Figma file only. Another Figma file that pulls the rename gets a new token, and its layers need it applied again |
A push in a project folder deletes any .tokens.json file in its tokens folder that is not a set of the project |
Keep hand-made token files outside that folder |
| Editing one field of a border or shadow saves literal colors as sRGB hex, so wide-gamut values are lost |
Change these tokens in the JSON editor |
| A sync to Figma variables removes variables whose tokens were deleted. Layers keep their last values but lose the variable binding |
Check the list in the preview before you choose sync variables. See Figma variables |
Authoring
| Limitation |
Do instead |
| A rename or move that would break a reference is refused and cannot be forced |
Create a token under the new name, point each dependant at it (view dependencies finds them), then delete the old token. Layers bound to the old token need the new one applied |
| The token dialog cannot move a token to another set |
Copy it into the other set’s JSON view, then delete the original. The copy is a new token, so layers bound to the original need it applied |
| Folders and groups cannot be renamed |
Rename the sets in a folder, or the tokens in a group, one by one |
| Undo covers 50 steps, is lost when the plugin closes, and does not cover layers |
Use Figma’s own undo for layers |
| Formulas and color changes cannot be edited in the token dialog |
Use the JSON editor |
| Search covers the selected set only |
Select the other set, then search |
| There is no reset command |
Delete the sets or folders in the sidebar |
Token dialog
| Limitation |
Do instead |
| Cubic bezier: references offered for single points are refused on save |
Enter four numbers |
| Transition: the timing function takes four numbers only |
Reference a curve in the JSON editor |
| Gradient: the reference field on a stop cannot resolve |
Leave it empty. Use references in color and position |
| Shadow: a layer reference to a token with several layers cannot resolve |
Reference a token with one layer, or write the layers out |
| Font weight: the reference list also offers number tokens, which give a type mismatch |
Choose a font weight token |
| Border: a dash pattern written inline cannot be edited |
Use the JSON editor, or reference a stroke style token |
Import
| Limitation |
Do instead |
| A folder of DTCG files with no Resolver file is refused |
Add design-tokens.resolver.json. See Themes in files |
| One invalid or unreferenced file stops a whole package |
Fix or remove that file |
A single file with an extra dot in its name, such as tokens.v2.json, is refused |
Rename the file |
Sync
| Limitation |
Do instead |
| The plugin does not merge |
Pull, then redo your edits. Or export and merge the files in Git |
A pull reads every .json file in a project folder and stops if one is not part of the project |
Use a folder that holds only token files |
| Once a project has been pulled or pushed, any new commit on the branch stops a push, even a README change |
Choose pull latest, or point the connection at a branch used only for tokens |
| Self-hosted Git servers cannot be reached |
Export and commit the files yourself |
| The access token is stored unencrypted by the plugin, in Figma’s client storage |
Use a token limited to one repository, with an expiry date |
Applying to Figma
| Limitation |
Do instead |
| Duration, cubic bezier, transition, gradient and string tokens cannot be applied to layers |
Use them in code from the DTCG files |
Stroke keywords double, groove, ridge, outset and inset cannot be applied |
Use solid, dashed, dotted or a dash pattern |
| sync to: current page and document are disabled |
Select the top-level frames, then sync to: selection |
| Editing a token does not change layers that use it |
Select the layers and choose sync to: selection |
| Padding and gap on a frame without auto layout are stored but show no effect |
Turn on auto layout |
Figma variables
| Limitation |
Do instead |
| By design, mapping runs from tokens to variables. Figma is a consumer, so styles and variables are not read into tokens |
Author tokens in the plugin, or import DTCG files or a Tokens Studio export |
Left out of the mapping: rem dimensions, font family lists, string, duration, cubic bezier and all composite types |
Use px values and single names where a variable is needed. show what is left out names each token and the reason |
Syntope MCP
| Limitation |
Do instead |
| Needs the plugin open in Figma Desktop |
Keep it open while the app works. A mode without Figma is planned |
| macOS only, Windows is not supported yet |
Work in the plugin directly |
| The Mac app is not signed by Apple |
Allow it under System Settings → Privacy & Security |
| Does not read Figma variables |
Ask the app to work with saved tokens and layers |
syntope_import_tokens works in an empty project only |
Use syntope_change_tokens, or the import tokens dialog |
| Applying uses the default option of every theme group |
Switch the theme in the plugin first |
| With read and change tokens, the app does not ask before each change |
Start with read tokens. Grant change access per file. Changes can be undone |
See Troubleshooting Syntope MCP for connection problems.
Syntope Engine
| Limitation |
Do instead |
| Not on npm |
Build it from source |
| No API reference, and the API can change |
Pin the version you build. The two entry points are described in Use the engine in code |
| Generates no CSS, JavaScript or platform code |
Pass the DTCG files to a build tool that reads them |
A calculated token has one $value in files, for one theme |
Read other themes through the engine, or give the token a plain value in each theme’s set |
