First-Time Sync

This guide covers the full flow for a designer opening the Grails plugin for the first time in a Figma file that has not yet been linked to Grails.

Prerequisites

• The Grails Figma Plugin must be installed in your Figma account.
• You need a Grails API Token for your team. Find it in: Grails → Team Settings → Integrations → Plugin Token.
• You must be a member of the Grails team you want to sync to (Admin or Editor role).

Step-by-Step

1. Open the plugin in Figma

   Go to Plugins → Grails. The Login screen appears.

2. Enter your API Token

   Paste your personal Grails API Token into the field and click Connect.

   The plugin validates the token against the Grails API. If the token is incorrect, an error message appears below the field.

3. Welcome screen — Continue and scan this file

   After a successful connection, the Welcome screen shows who is signed in, with which team, and the project the file will sync to.

   Click Continue and scan this file.

   The scan only reads your Figma file — components, variable collections, paint styles, and text styles. Nothing is synced until you choose what to sync.

4. Review & Sync opens with everything selected

   When nothing in the file has been synced yet, the plugin opens Review & Sync directly. The entities are listed in four groups — Components, Variable Collections, Visual Styles and Text Styles — and every one is selected.

   Rows in this list show no badge for entities that were never synced. In the entity lists you open from the Dashboard, the same entities carry a gray Not synced badge.

   If Grails cannot determine the sync status, the plugin shows Scan Results instead, with Sync All to sync everything. Review stays disabled there until the status can be read.

5. Choose what goes into the first sync

   Uncheck anything you don’t want in this first sync. The checkbox of a group selects or clears all of its entities, and the search bar filters the list by name.

   Add an optional Sync note (e.g., “Initial import — complete design system”) for your audit trail.

   Click Sync Now.

6. Sync Progress → Sync Result

   A progress screen shows while the sync runs. When it finishes, the result screen reports Sync Complete if everything arrived, or Sync Finished With Gaps if part of the selection did not — listing what is missing and what to do about it. A first sync of a large file is the most likely place to hit your plan’s entity limit; if that happens, the skipped entities are listed separately and un-syncing is what frees room.

7. Dashboard — everything synced

   The plugin lands on the Dashboard. All four cards now show their counts, and the status bar reads “Everything is up to date.”

   From here, the plugin is in maintenance mode — it checks the sync status on every file open and alerts you only when something needs attention.

After the First Sync

On every subsequent file open, the plugin will:

1. Load the Dashboard.
2. Automatically run the sync status check to see whether anything changed since the last sync.
3. Show the appropriate banner if action is needed, or the green “Everything is up to date” bar if not.

You no longer need to trigger scans manually — the plugin handles status checking automatically.