Syncing DS Changes

This guide covers the day-to-day workflow for a designer who has made changes to components, variables, or styles in Figma and needs to reflect those changes in Grails.

What triggers this workflow

Any of the following situations:

• You modified a component (renamed, added a variant, changed anatomy).
• You changed a variable value or added a new variable to a collection.
• You added, renamed, or modified a paint style or text style.
• You added an entirely new component or collection that was never synced before.

How the plugin detects changes

The plugin uses a hash-based evaluation system. On each file open, it:

1. Reads all entities from Figma (via the Plugin API).
2. Sends entity fingerprints (hashes) to Grails for the sync status check.
3. Grails compares the incoming hashes against the stored hashes for each entity.
4. Returns a status per entity: Synced, Modified, Not synced or Removed.

No manual scan is needed — the status check is automatic every time you open the plugin.

Step-by-Step

1. Open the plugin

   The plugin loads the Dashboard and shows “Loading sync status…” while evaluating.

2. Read the Dashboard

   Once evaluation completes, you’ll see one of:

   • 🟢 “Everything is up to date” — no action needed.
   • 🟡 Amber banner: “Changes detected in synced entities — N modified” — entities that were previously synced to Grails changed in Figma since the last sync.

   The Summary Cards also show amber badge counts for modified entities per type, and a green dot when a card’s entities are all in sync.

   Note

   The amber banner only appears for drifted entities (hash mismatch after a prior sync). Entities that have never been synced do not trigger the banner — they appear in their entity list under the Unsynced filter.

3. Click “Review Changes” on the amber banner

   This opens the Review & Sync screen, listing only the entities that changed since your last sync.

4. Review what will be synced

   Entities are grouped by type: Components, Variable Collections, Paint Styles, Text Styles. Each item shows a colored version badge:

   Badge color	Meaning
   Amber v3	Entity changed since last sync (hash mismatch). Grails has an older version.
   Green v3	Entity is in sync with Grails.

   Arriving from the Dashboard banner, the screen lists only the changed entities, so it shows no filter tabs. Use the search bar to find a specific entity by name.

5. Adjust the selection

   Every listed entity is pre-selected. You can:

   • Uncheck any item you don’t want to include in this sync.
   • Uncheck a group header to deselect the entire group.
   • The header shows N/M — checked count / total in group.

6. Add a Sync note (optional)

   Type a brief description of the changes in the Sync note field. This note is saved in the entity’s history log and is useful for audit purposes.

   Example: “Updated button variants after design review”

7. Click Sync Now

   The sync pipeline processes all selected entities. Progress is shown on the Sync Progress screen.

8. Sync Result

   When everything in the selection arrived, the result screen reads Sync Complete and the Dashboard returns to “Everything is up to date.”

   If part of it did not arrive, the screen reads Sync Finished With Gaps and lists what is missing. The sync stays open in that case, and the Dashboard shows the interrupted-sync banner with Resume sync until the rest is delivered.

Note

Entities skipped because your plan’s limit was reached are listed separately from the ones a retry can still deliver — retrying those specific entities will not help. See Sync Result.

Syncing from the Entity List

You can also sync individual entities without going through the Dashboard banner:

1. Click a Summary Card on the Dashboard (e.g., Components).
2. On the Entity List, use the Modified filter to see only changed items.
3. Check the ones you want to sync.
4. Click Sync Selected in the bottom bar.

This opens Review & Sync pre-loaded with only your selection.

Re-scanning the file

If you made changes in Figma while the plugin was already open and the Dashboard still shows the old status, click Update Sync Status at the bottom of the Dashboard. This scans the file again and refreshes the status without closing the plugin.