When we started building the Figma plugin, the architecture felt obvious: UISqueezy Studio is the source of truth, the plugin reads from it, designers work in Figma, the plugin pushes changes back. One source, one direction, everything synced. We built it this way. It was wrong within a month.
The wrong mental model
"Push to Figma" implies that Figma is downstream — a consumer of tokens, not a participant in their authorship. This is not how design teams actually work. Designers don't just consume tokens; they discover new needs for tokens while they're designing. The right spacing value for a new component often gets refined in Figma before it ever reaches Studio.
The one-way model created a workflow tax: every token idea that originated in Figma had to be manually created in Studio, then pushed to Figma, then manually applied to the component that inspired it in the first place. Teams started bypassing the token layer entirely, applying raw values in Figma and "syncing later" — which meant never.
"Push to Figma" is a deployment metaphor. Design doesn't work like deployment.— Architecture retrospective, August 2025
CRDTs in brief
The solution space for two-way sync is well-studied in distributed systems. Conflict-free Replicated Data Types (CRDTs) are data structures that can be updated concurrently by multiple actors and merged deterministically without coordination. They're used in collaborative editors, offline-first apps, and now, apparently, design token systems.
The key property of a CRDT is that merges are commutative and associative: the order in which you apply concurrent changes doesn't affect the final state. For tokens, this means a designer can update a value in Figma while an engineer updates the same token's description in Studio, and when the two systems sync, both changes survive without either side knowing about the other during the edit.
Conflict resolution
Not every conflict can be resolved automatically. If a designer changes color.brand.500 to red in Figma at the same time an engineer changes it to blue in Studio, no algorithm can determine which is correct — that's a design decision. CRDTs don't solve this class of conflict; they just make it explicit.
Our conflict UI surfaces in both Studio and the Figma plugin simultaneously. The conflicting token is flagged with a diff view showing both values, who changed each, and when. One side must explicitly accept or reject the other's change. The token remains in a "conflicted" state — still functional, using the last agreed value — until the conflict is resolved.
- Same-field edits within 60 seconds of each other: flagged as likely conflict, require resolution
- Same-field edits more than 60 seconds apart: last-write wins with a change log entry
- Different-field edits (value vs. description): always auto-merged
- Structural changes (rename, delete): always require explicit resolution
The authority question
Even with CRDTs handling concurrent edits, there remains the question of authority: who is allowed to change what? Our permission model assigns every token to a primary owner — a team or individual — and every change from a non-owner goes through a lightweight review step.
This turned out to be the most important design decision in the whole system. Teams that skipped the authority model found that two-way sync introduced new chaos: anyone could change anything, and nobody knew who to blame when the brand colors drifted. Authority makes sync legible — every change has an owner, every owner has a reason.
What we gave up
Honest accounting: two-way sync is more complex to explain, more complex to debug, and more complex to build than one-way sync. We have a conflict UI that most users will never see, a permission system that requires upfront configuration, and a sync log that grows indefinitely and needs pruning.
What we gained: designers actually use the token system because it meets them in Figma. Token adoption on teams using two-way sync is 40% higher than on teams using the one-way plugin. The complexity cost is real. The workflow tax of one-way sync was higher.