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 the Grails evaluate-all endpoint.
3. Grails compares the incoming hashes against the stored hashes for each entity.
4. Returns an evaluation result with a status per entity: synced, outdated, unsynced, 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, pre-filtered to Modified — showing only the entities that drifted 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.

   The Modified filter is pre-applied when arriving from the Dashboard banner. Use the tabs to switch:

   • All — everything pending (modified + never-synced)
   • Modified — drifted entities only (pre-applied from Dashboard)
   • Unsynced — entities never synced to Grails before

   Use the search bar to find a specific entity by name.

5. Adjust the selection

   All modified and new entities are 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 Complete

   After a successful sync, the plugin returns to the Dashboard showing “Everything is up to date.”

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.

WIP Warning

If any selected component has unpublished local changes in Figma (publishStatus = CHANGED), a warning banner appears at the bottom of Review & Sync:

“WIP components included — some selected components have unpublished changes in Figma.”

This means the changes haven’t been published to the Figma library yet. You can still proceed — the warning is informational. However, consumers of your Grails Vault will receive in-progress work. Consider whether that is intentional before clicking Sync Now.

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 Re-scan File at the bottom of the Dashboard. This re-runs the full scan and evaluation without closing the plugin.