Figma Plugin

The Grails Figma Plugin is the interface that connects your Figma file to the platform. From here you can scan and sync your variables, text and color styles, components, and screens directly to the Grails Vault — no manual exporting or copying required.

The plugin lives inside Figma and has full access to your file: it reads the document’s content, detects what changed since the last sync, and gives you precise control over what to sync and when.

Note

The plugin is available on Figma Community. Once installed, you’ll find it in the Plugins menu of any Figma file.

---

Initial Connection

Before syncing, the plugin needs to know which Grails team it should communicate with. This process is done once per team.

Step 1 — Enter Your Sync Token

When you open the plugin for the first time in a file, you’ll see the connection screen:

• Token field: A password field (hidden by default) where you enter your personal Sync Token.
• Eye button: Toggles between showing and hiding the token as you type.
• “Connect” button: Validates the token against the Grails API.

Note

Your personal Sync Token is found in Grails → Team Settings → Integrations tab → Plugin Token. The Copy button copies it to your clipboard in one click. Every team member has their own token — do not share yours.

If the token is invalid or the connection fails, an error message with details will appear below the field.

Step 2 — Select a Project (if you have more than one)

If your team has more than one project in Grails, a project selection screen appears after connecting:

• Project list: Each project shows a folder icon, the project name, and the team name in smaller text.
• Selected item: Marked with a checkmark on the right.
• “Start syncing” button: Confirms the selection and opens the full plugin.
• “Back” button: Returns to the token screen if you need to switch accounts.

Note

If your team has only one project, this screen is skipped automatically and the plugin opens directly in the main view.

The project selection is saved per Figma file. Each file can sync to a different project, and the selection persists between sessions.

---

Main Interface

Once connected, the plugin shows the full interface divided into three zones:

Header

• “Grails” title on the left.
• Team badge in the center: shows the active team name. Hovering reveals a tooltip in the format {team name} · {project name}.
• Disconnect button (unplugged cable icon) on the right: unlinks the plugin from your account. Asks for confirmation before proceeding.

Navigation Sidebar

Four vertical tabs on the left side of the plugin, each with its icon:

Tab	Icon	What it syncs
Variables	{} (braces)	Variable collections and design tokens
Styles	Palette	Text, color, effect, and grid styles
Components	Diamond	Components and component sets
Screens & Flows	Branch (git)	Frames/screens to Vault flows

At the bottom of the sidebar: Settings button (gear icon) to access plugin configuration.

---

Sync Status Badge System

All items in the Variables, Styles, and Components tabs display a badge indicating their sync status with Grails. Understanding these badges is key to knowing what needs to be synced.

Sync Status Badges

Badge	Color	Meaning
Synced	Green	The item is in sync with Grails. The content in Figma matches exactly what’s in Grails. No action needed.
Outdated	Yellow	The item was published to the Figma library (changes confirmed) but hasn’t been synced to Grails yet. The change is ready — just needs to be synced.
WIP	Yellow	The item has local changes in Figma that haven’t been published to the library yet. Work is in progress. It’s recommended to wait for the designer to publish the changes before syncing.
Unsynced	Gray	The item exists in Figma but was never synced to Grails.
New	Blue	Newly detected item in the scan with no previous history in the plugin.

The difference between Outdated and WIP

This is the most important distinction in the plugin:

• Outdated → Changes in Figma are already published to the team library. The component/variable/style is “done” from a design perspective — just needs to be brought into Grails. ✅ Safe to sync.

• WIP (Work in Progress) → Changes exist in Figma but haven’t been published to the library yet. The designer is still working on it. If you sync now, you’ll capture an intermediate state of the design. ⚠️ Evaluate whether you want to sync before it’s published.

Version Badge (Components only)

Already-synced components also show a version badge alongside the status badge:

• v1, v2, v3… — Indicates how many saved versions this component has in Grails. The badge color matches the status (green for Synced, yellow for Outdated or WIP).

---

Tab: Variables

The Variables tab lets you sync all variable collections defined in your Figma file to the Grails Vault.

Main View

Action Bar

At the top of the list:

• Counter: “X collections · Y selected” — shows total collections and how many are selected.
• Status filters: Buttons to filter the list: All, Synced, Outdated, Unsynced.
• Quick-select buttons: All (selects all) and None (deselects all).

Collection List

Collections appear in two groups:

• SYNCED COLLECTIONS (dark header) — Collections that already have history in Grails (any sync status).
• UNSYNCED COLLECTIONS (light header) — Collections never synced before.

Each collection item shows:

• Checkbox on the left to select.
• Collection name.
• Status badge (Synced, Outdated, WIP, Unsynced, New).
• Count badge: “X vars” — how many variables the collection has.
• Token Role badge (if one is assigned): the semantic group name (e.g., “Brand Colors”). Clicking the tag icon opens the Token Role manager.
• Unlink icon (red, only if synced): unsyncs the collection from Grails.

Footer Button

• No items: “Scan variables” (primary) — starts the scan.
• Items present, nothing selected: “Rescan variables” (secondary) — rescans the file.
• Items selected: “Sync X collection(s)” (primary) — syncs the selected collections.

Progress Bar

During scanning or syncing, a progress bar appears with:

• Descriptive text: “Scanning variables…” or “Syncing…”
• Counter: “X / Y”

Assigning a Token Role to a Collection

From the tag icon next to each collection you can assign a Token Role — a semantic name that groups the collection in the Grails Vault (e.g., “Brand Colors”, “Spacing Scale”).

The Token Role side panel shows:

• Header: “Token Group — {collection name}” with a back button.
• List of existing roles: Each role with its name and a delete button (trash icon).
• Create new role: Text field with placeholder “e.g. Brand Colors” and a “Create” button.

The Token Role is saved in the Figma file and sent to Grails when the collection is synced.

Unlinking a Collection

The red unlink icon next to each synced collection opens a confirmation to remove that collection from Grails. The collection still exists in Figma — only the Grails data is deleted.

Caution

Unlinking a collection deletes all its variables from Grails. This action cannot be undone from the plugin. To see it again you’ll need to re-sync it.

---

Tab: Styles

The Styles tab lets you sync the local styles from your Figma file: text (typography), color, effect, and grid styles.

Main View

Action Bar

• Counter: “X styles · Y selected.”
• Filters: All, Synced, Outdated, Unsynced.
• Quick-select: All and None.

Style List

Styles are organized by type with section headers:

• TEXT — Typographic styles (fonts, sizes, weights).
• COLOR — Color and fill styles (PAINT).
• EFFECT — Effect styles (shadows, blur).
• GRID — Layout grid styles.

Within each type, styles are sub-grouped into:

• SYNCED STYLES — Those with history in Grails.
• UNSYNCED STYLES — Those never synced.

Each style item shows:

• Checkbox on the left.
• Style name (e.g., “Body / Large”).
• Description (small gray text, if available).
• Status badge (Synced, Outdated, WIP, Unsynced).
• Unlink icon (red, if synced).

Footer Button

• No items: “Scan styles” (primary).
• Items present, nothing selected: “Rescan styles” (secondary).
• Items selected: “Sync X style(s)” (primary).

---

Tab: Components

The Components tab lets you sync components and component sets from your Figma file. This is the tab with the most options, including the ability to create versioned snapshots with commit messages.

Main View

Action Bar

• Counter: “X components · Y selected.”
• Filters: All, Synced, Outdated, Unsynced.
• Quick-select: All and None.

Component List

Components are organized in two groups:

• SYNCED COMPONENTS — Components with history in Grails, sorted alphabetically.
• UNSYNCED COMPONENTS — New or never-synced components.

Each component item shows:

• Checkbox on the left.
• Component name, prefixed with the page name: “Page Name / Component Name”.
• Type badge: “Set” if it’s a Component Set (a family of variants).
• Status badge: Synced, Outdated, WIP, or Unsynced.
• Version badge: “v1”, “v2”, etc. — only on already-synced components. Color matches status.

Footer Buttons (change based on selection)

Situation	Available buttons
No items	”Scan components” (primary)
Items present, nothing selected	”Rescan components” (secondary)
1 component selected (not yet synced)	“Sync selected” (primary)
1 component selected (already synced)	“Sync selected” (primary) · “Sync as New Version” (secondary)
2 or more components selected	”Sync X components” (primary)

Standard Sync (“Sync selected” / “Sync X components”)

Standard sync updates the current state of the component in Grails. If the component was already in Grails, it overwrites the data with the latest version from Figma. No additional history is created.

Version Sync (“Sync as New Version”)

Available only when exactly 1 already-synced component is selected. Opens a version modal with:

• Component name and its metrics:
  • “[X PROPS]” badge — how many properties it has.
  • “[Y VARIANTS]” badge — how many variants it has (if it’s a Set).
  • “[Z SUBCOMPS]” badge — how many sub-components it uses.
• Message field (required): “What changed in this version?” — describes the changes for the history log.
• “Cancel” button: Closes the modal without syncing.
• “Sync version” button: Disabled until the message field has content. On confirmation, creates a new entry in the component’s version history in Grails.

Note

A component’s version history is accessible from the Grails Vault by clicking the component → History button in the detail panel. Each version shows the commit message, date, and “v{N}” badge.

Progress Bar

During scanning:

• “Found N components…” — shows components as they’re discovered.

During sync:

• “N / M” — counter of processed components.

---

Tab: Screens & Flows

The Screens & Flows tab lets you sync Figma frames (screens) directly into visual flows in the Grails Vault.

How it works

Unlike the other tabs, this tab works with your active selection in Figma. First you select one or more frames (or a full section) on the Figma canvas, then scan them from the plugin.

Main View

Top Bar

• Counter: “N frame(s) ready” when frames are scanned, or “No frames scanned” if not scanned yet.
• “Scan selection” button: Scans the frames or section currently selected in Figma. Disabled while loading.

Frame Preview List (appears after scanning)

Each scanned frame shows:

• Monitor icon.
• Frame name (truncated if too long).
• Dimensions: “W × H” in pixels (e.g., “1280 × 720”).

If the scan was of a Figma Section, additional text appears: “From section: {section name}”.

Flow Picker (“Sync to flow”)

Below the frame list, you need to choose which Vault flow to send the screens to:

• Label: “Sync to flow” with a ”+ New” button on the right to create a new flow.
• Dropdown: List of existing flows in the project, with their emoji icon as a prefix. Placeholder option “Select a flow…”.
• No flows yet: Text appears: “No flows yet. Create one to get started.”

Creating a new flow (”+ New” button):

• The area changes to a “Flow name” text field and a “Create” button (disabled if the name is empty).
• When created, the flow appears in the dropdown and is automatically selected.

Section Title (only when a Figma Section was scanned)

An additional “Section title” field appears to name the container in the Vault flow. The placeholder is the section’s name from Figma.

Success State

After a successful sync, a green checkmark icon appears with the message:

“Screens synced! Open the flow in Grails to see them.”

Footer Button

• Available when frames are scanned and sync isn’t complete yet.
• “Sync N screen(s) to flow” (primary) — disabled if no flow is selected.
• During upload: shows “Uploading N/M…” with a spinner.

---

Plugin Settings

Accessed from the gear button in the sidebar. Changes are saved per team member and persist between Figma sessions.

Section: Sync Options

Option	What it does
Show hidden assets	Includes in the scan components and variables whose names start with . or _. By default these are excluded because they’re considered internal library assets.
Sync images	Exports and uploads thumbnails for components when syncing. Active by default. Disabling it syncs components without a preview image.
Variant thumbnails	Exports a separate thumbnail for each individual variant of a Component Set. If disabled, only one thumbnail for the entire Set is exported.
Mode thumbnails	(Coming soon) Will export thumbnails for each variable mode. Currently disabled.

Section: Instance Scanning

Option	What it does
Nesting depth	Controls how deep the plugin scans nested instances inside a component to detect sub-components and dependencies. Options: Level 2 or Level 3.

Section: Connection

Field	What it shows
Token	The first 8 characters of your Sync Token followed by ”…” (read-only).
Project	The first 8 characters of the project ID followed by ”…” (read-only).

Note

To switch teams or projects, use the disconnect button (cable icon) in the plugin header and reconnect with the new team’s token. To switch projects within the same team, you need to disconnect and reconnect.

Settings footer buttons

• “Cancel” — Closes the settings screen without saving changes.
• “Save & close” — Saves the settings and returns to the previous view.

---

Recommended Workflow

The typical flow for syncing any type of content always follows the same pattern:

1. Scan → The plugin reads the Figma file and detects what exists and its current status.

2. Review statuses → Identify what’s Outdated (ready to sync), WIP (in-progress changes), or Unsynced (never synced).

3. Select → Check the items you want to sync. You can filter by status to focus on what matters most.

4. Sync → Click the sync button at the bottom. The plugin processes and sends the data to Grails.

Note

Scanning doesn’t sync anything. Scanning only reads the current state of the file. Syncing only happens when you explicitly confirm with the sync button.

---

Available Actions

Action	Where	Description
Connect with token	Initial screen	Links the plugin to your Grails team and account.
Select project	Onboarding step 2	Chooses which Grails project this Figma file syncs to.
Disconnect	Header	Unlinks the plugin from your account (requires confirmation).
Scan variables	Variables tab	Reads all variable collections in the file.
Sync collection(s)	Variables tab	Sends selected collections to Grails.
Assign Token Role	Variables tab	Assigns a semantic name to a collection (created in Grails when syncing).
Unlink collection	Variables tab	Removes the collection from Grails (requires confirmation).
Scan styles	Styles tab	Reads all local styles in the file (text, color, effect, grid).
Sync style(s)	Styles tab	Sends selected styles to Grails.
Scan components	Components tab	Reads all components and Component Sets in the file.
Sync components	Components tab	Standard sync — updates the current state in Grails.
Sync as new version	Components tab	Creates a snapshot with a commit message in the component’s history.
Scan selection	Screens & Flows tab	Reads the frames or section currently selected on the Figma canvas.
Create new flow	Screens & Flows tab	Creates a new visual flow in the Grails Vault.
Sync screens	Screens & Flows tab	Sends scanned frames to the selected flow.
Open Settings	Sidebar (gear icon)	Accesses plugin configuration options.
Save settings	Settings	Persists sync options for this team member.