Figma Plugin
The Grails Figma Plugin runs inside Figma and lets you scan the current file to detect all design system entities — components, variables (collections), paint styles, and text styles — then evaluate their sync status with Grails and push changes with a single click.
Screens Overview
The plugin is a single-panel UI with multiple screens. Navigation between screens is handled by the plugin itself — there are no browser tabs or separate windows.
| Screen | When it appears |
|---|---|
| Login | First time the plugin runs, or after disconnect |
| Welcome / Welcome Back | After a successful login, before the first scan |
| Scanning | While the file is being scanned |
| Scan Results | After the first scan on a new file (first-time users) |
| Dashboard | Main hub — shows sync status summary and action banners |
| Entity List | When drilling into Components, Variables, Paint Styles, or Text Styles |
| Review & Sync | Pre-sync staging area to select what to sync |
| Review Removed | When removed entities are detected in Figma |
| Sync Progress | While a sync is running |
| Sync Complete | After a successful sync |
| Settings | Account info and plugin options |
Login Screen
When the plugin runs for the first time (or after being disconnected), you’ll see the Login screen.
- API Token field — Paste your personal Grails API Token here. The field is type
password— the value is never visible. - “What is a token?” link — Opens the Token Help screen with instructions on where to find your token in Grails.
- Connect button — Validates the token against the Grails API.
Your API Token is found in Grails → Team Settings → Integrations → Plugin Token. Each team member has their own token — do not share it.
If the token is invalid, an error message appears inline below the field.
Welcome / Welcome Back Screen
After a successful connection, the plugin determines whether you are a new user (no prior entities synced) or a returning user (at least one entity previously synced).
New user:
“Welcome to Grails. Grails keeps your design system in sync between Figma and your codebase. We’ll scan your file to detect all components, variables, and styles.” Button: Scan My File
Returning user:
“Welcome back, [Name]! We’ll scan your Figma file to check the current sync status of your design system.” Button: Scan & Check Status
Scanning Screen
A progress bar with a label (e.g., “Detecting components…”) shows while the plugin reads the file. Scanning analyzes all components, variable collections, paint styles, and text styles in the document.
Scan Results Screen (First-Time Only)
After the first scan on a file that has never been synced to Grails, you see the Scan Results screen:
- Four Summary Cards — Components, Variables, Paint Styles, Text Styles — each showing the detected count.
- “Sync All” button — Syncs all detected entities to Grails in one operation.
- “Review” button — Opens the Review & Sync screen to cherry-pick what gets synced first.
After clicking either button, the plugin proceeds to the Review & Sync screen so you can confirm the selection before the sync runs. This screen only appears once per file — after the first sync, the plugin goes directly to the Dashboard on subsequent opens.
Dashboard Screen
The Dashboard is the main hub of the plugin. It appears automatically after every subsequent file open (once a sync has been performed). The dashboard loads the current sync status by calling the evaluate-all backend endpoint.
Header
- User avatar — Two-letter initials of the connected user’s name.
- Team name — The Grails team name this file is linked to.
- Settings icon (⚙) — Opens the Settings screen.
Status Bar
The top of the body area shows one of:
| State | What it shows |
|---|---|
| Loading | A spinner with “Loading sync status…” |
| All synced | A green checkmark with “Everything is up to date.” |
| Interrupted sync | Amber banner (see below) |
| Action required | Red or amber banners (see below) |
Summary Cards
Four clickable cards show the count and status breakdown for each entity type:
| Card | Icon | Color | Shows |
|---|---|---|---|
| Components | Diamond | Purple | Top-level components + component sets only (variants are not counted separately) |
| Variables | Braces {} | Blue | Variable collections |
| Paint Styles | Paintbrush | Orange | Paint/fill styles |
| Text Styles | T | Teal | Text/typography styles |
Each card shows the number of entities currently synced to Grails, along with a sub-label showing the total detected in Figma (e.g., “of 42 total”). Badge counts indicate status drift:
| Badge | Color | Meaning |
|---|---|---|
| Green dot | Green | All synced entities are perfectly in sync — no drift, no deleted items |
| Modified count | Amber | Number of entities with a hash mismatch (changed in Figma since last sync) |
| Removed count | Red | Number of entities in Grails that no longer exist in Figma |
Clicking a card navigates to the Entity List for that type.
Action Banners
Banners appear on the dashboard when action is needed. Priority order (only the highest priority is shown for conflicting states):
🔴 Interrupted Sync (Amber)
Appears when a previous sync was started but not completed (e.g., Figma was closed mid-sync).
- Shows: who started the sync, when, and how many items remain.
- Actions: Resume sync (continues from where it left off) | Finalize (marks it as complete without re-running).
🔴 Published Library Changes (Red)
Appears when entities were published to the Figma library after the last sync to Grails.
- Title: “Published library changes pending sync”
- Detail: count of published items.
- Action: Review Published Changes → opens Review & Sync pre-filtered to only the published items.
🟡 Removed Entities Detected (Red)
Appears when entities previously synced to Grails no longer exist in Figma.
- Title: ”⚠ Removed entities detected”
- Action: Review Removed → opens the Review Removed screen.
🟡 Changes Detected (Amber)
Appears only when entities that were previously synced to Grails now have a hash mismatch — meaning they changed in Figma since the last sync. This alert is not triggered by entities that have never been synced.
- Title: “Changes detected in synced entities”
- Detail: count of modified entities (e.g., “3 modified”).
- Action: Review Changes → opens Review & Sync pre-filtered to Modified entities only, showing exactly what drifted.
🔵 Variables Require Plugin Re-sync (Amber)
Appears when variables were changed on the server but your plan requires re-syncing from the plugin (vs. auto-sync).
- Detail: “Variables were updated but can’t be auto-synced on your plan.”
Footer
- Re-scan File button — Triggers a new full scan of the current Figma file without navigating away from the Dashboard.
Entity List Screens
Clicking any Summary Card on the Dashboard opens the Entity List for that type (Components, Variables, Paint Styles, or Text Styles). All four lists share the same layout.
Layout
- Top bar — Back arrow + title + Settings icon.
- Search bar — Filters entities by name in real time.
- Segment filter bar — Tabs to filter by status.
- List — One row per entity with a status badge and a checkbox.
- Selection bar (appears when items are checked) — Actions for the selection.
Segment Filters
| Filter | What it shows |
|---|---|
| All | Every entity detected in Figma |
| Synced | Entities already in sync with Grails (status = synced, no unpublished changes) |
| Modified | Entities that changed since the last sync (outdated) OR have unpublished Figma changes (publishStatus = CHANGED) |
| Not Synced | Entities that exist in Figma but were never synced to Grails (unsynced, excluding those with Figma publish changes) |
| Removed | Entities synced to Grails but no longer found in the Figma file |
Status Badges
Each row in the list shows a badge reflecting the entity’s evaluation result:
| Badge | Color | Meaning |
|---|---|---|
| Synced | Green | Entity is identical in Figma and Grails. |
| Outdated | Yellow/Amber | Hash mismatch — the entity changed in Figma since the last sync. Grails is behind. |
| New | Blue | Entity exists in Figma but has never been synced to Grails. |
| Removed | Red | Entity was previously synced but is no longer found in the Figma file. Its name appears with strikethrough. |
Selection Actions
When one or more items are checked, a bottom bar appears with context-sensitive actions:
| State | Available actions |
|---|---|
| Modified or New items selected | Sync Selected → opens Review & Sync pre-loaded with this selection |
| Fully synced items selected | Re-sync · Unsync |
| Removed items selected | Remove from Grails → opens Review Removed |
Review & Sync Screen
The staging area before any sync operation. You can arrive here from:
- The “Review Changes” / “Review Published Changes” banner on the Dashboard
- The “Review” button on the Scan Results screen
- The “Sync Selected” action on any Entity List
Layout
- Title: “Review & Sync” + “N selected” count in the header.
- Search bar — Filter entities by name.
- Filter tabs:
All (N)|Modified (N)|New (N) - Collapsible groups: Components, Variable Collections, Paint Styles, Text Styles — each with a group-level checkbox and a
N/Mcounter. - Footer — Sync note field + Sync Now button.
Filter Tabs (Review & Sync)
Filter tabs appear when there are Modified entities in the current view, or when the screen was opened from the Dashboard with a pre-applied filter.
| Filter | What it shows |
|---|---|
| All | All entities with outstanding changes (modified + never-synced) |
| Modified | Entities that changed since the last sync (hash mismatch) |
| Unsynced | Entities that exist in Figma but were never synced to Grails |
Item Badges in Review & Sync
Each item shows a version/status badge indicating the sync state:
| Badge color | Meaning |
|---|---|
Green v3 | Entity is in sync with Grails. Number shows the version count. |
Amber v3 | Entity changed since the last sync (hash mismatch). Number shows the version count in Grails. |
Red v3 | Entity exists in Grails but was deleted or unpublished in Figma. |
For variables and styles (which don’t have version counts), the badge shows a status symbol: ✓ (synced), ~ (modified), or ✕ (removed).
Sync Note
An optional textarea for a short commit message. The text is saved with the sync record in Grails (visible in the entity’s history).
Sync Now
Disabled if 0 items selected. Clicking triggers the sync pipeline for all selected items across all entity types in a single operation.
Review Removed Screen
Reached from the “Review Removed” banner on the Dashboard. Shows entities that are in Grails but no longer found in Figma.
- Red warning banner: “These entities no longer exist in Figma. They may have been deleted or unpublished. Removing them from Grails is permanent.”
- Collapsible groups: Components, Variable Collections, Paint Styles, Text Styles.
- All removed items are pre-selected and shown with strikethrough names and Removed badges.
- Sync note — optional comment for the audit trail.
- Remove from Grails — Permanently deletes the selected entities from Grails. This cannot be undone.
Settings Screen
Accessible from the ⚙ icon in the top bar of any screen.
Connected Account
Shows the connected user’s name, email, team name, and plan badge.
Settings
| Option | Default | What it does |
|---|---|---|
| Sync images | On | Exports and uploads component thumbnails during sync |
| Sync variant thumbnails | On | Exports a separate thumbnail per variant (vs. one per set) |
| Include hidden assets | Off | Includes components/variables whose names start with . or _ |
Disconnect
Removes the stored API Token from the plugin. The plugin returns to the Login screen. The next user to open the plugin must enter a new token.
You can switch accounts by disconnecting and reconnecting with a different token. No data in Grails is deleted by disconnecting the plugin.
Sync Workflows
The plugin handles four distinct real-world sync scenarios. Each has a dedicated guide: