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 — Scan My File

   After a successful connection, the Welcome screen appears with a brief explanation of what Grails does.

   Click Scan My File.

   The scan reads the entire Figma file — components, variable collections, paint styles, and text styles. Nothing is modified or sent anywhere at this point.

4. Review Scan Results

   The Scan Results screen shows four Summary Cards with the count of detected entities:

   • Components — top-level components and component sets
   • Variables — variable collections
   • Paint Styles — fill and stroke color styles
   • Text Styles — typographic styles

   All items show a New badge (blue dot) because none have ever been synced.

5. Choose how to proceed

   Option	When to use
   Sync All	You want to push everything at once and curate later in Grails.
   Review	You want to pick exactly which entities go into Grails on the first sync.

6. If you clicked Review — Review & Sync screen

   All entities are pre-selected. Use the Modified / New tabs to explore what’s included, or uncheck anything you don’t want in this first sync.

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

   Click Sync Now.

7. Sync Progress → Sync Complete

   A progress screen shows while the sync pipeline runs. When finished, the Sync Complete screen confirms success.

8. 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 evaluate-all to check 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.