Version Management

Introduction

The Version Management feature in Grails lets you track structural and visual changes to your Figma components over time. Grails acts as a bridge between the design environment and code, using a semantic Diff Engine to analyze every sync and automatically generate a new version when meaningful changes are detected.

Every time a component is synced, Grails computes a precise diff and immediately applies the result — no manual approval step required.

Sync Mechanisms (Push vs Pull)

Grails maintains synchronization with your Figma components using two distinct integration paths. Both paths require an active Figma Personal Access Token (PAT) configured in your Team Settings.

1. Push Sync (Figma Plugin → Grails): Initiated directly by designers using the Grails Figma Plugin. Changes are pushed explicitly when working on active files.
2. Pull Sync (Figma Library Publish Webhook → Grails): Initiated automatically when a library is published natively via Figma. The webhook instructs Grails to query the Figma REST API and pull the latest specs into a new version.

The Diff Engine

When Grails detects changes — either pushed from the plugin or pulled from the webhook — it runs a semantic diff comparing the incoming spec against the current stable version. The Diff Engine classifies every change by severity:

• Major Changes: Breaking changes such as renaming an existing property, removing a previously supported variant, or changing the data type of an input.
• Minor Changes: Safe modifications such as purely visual token updates, adding new variants without affecting existing ones, or updating default values.

Direct-Merge Model

Grails uses a Direct-Merge approach: all syncs — whether Major or Minor — are immediately applied as a new version. There is no intermediate candidate state or manual approval queue.

This means:

• Every plugin sync is instantly reflected in the vault.
• The Diff Engine result is recorded in the version history for audit purposes, even when the changes are breaking.
• Editors and Admins can always review the diff detail of any version after the fact via the Version History Drawer.

Note

If your team previously relied on the Pending Review state as a gating mechanism, the recommended approach is now to use version history to audit and annotate breaking changes after they land. Commit messages left during sync provide the audit trail.

Component Diff Drawer

To inspect what changed between two versions, open the Component Diff Drawer from the Version History panel. It provides a detailed breakdown of the diff:

Inside the Diff Drawer you will find:

• User-Friendly Summaries: A “TL;DR” translating technical changes into human-readable sentences (e.g., ”✓ Renamed property from Icon to Leading Icon”).
• Visual Previews: A side-by-side or carousel comparison of component thumbnails.
• Structural Tree: A detailed comparison of Anatomy, Properties, Variants, and Design Tokens — showing exactly what lines were added, removed, or modified.

Version History Drawer

To review past changes of a component over time, click the History button in the top-right corner of the Component Drawer.

History Details

Each entry in the timeline represents a specific snapshot and includes:

• Version Number: An incremental badge (v1, v2, v3, etc.) identifying the snapshot.
• Author & Time: Who initiated the sync (or if it was triggered by the Figma webhook).
• Commit Message: A custom description optionally provided during sync (“Sync with comment”).
• Change Classification: Whether the version carried Major or Minor changes, as evaluated by the Diff Engine.
• Diff Summary: A human-readable and structural breakdown of exactly what changed in that update.

To investigate a previous state in detail, click View Version Details on any historical entry to open the Component Diff Drawer for that snapshot.

Available Actions

Action	Roles	Description
Sync Component	Admin, Editor	Push a new version via the Figma Plugin. Changes are applied immediately.
Sync with Comment	Admin, Editor	Attach a custom changelog message before syncing, visible in version history.
View Version Details	Admin, Editor, Viewer	Open the Diff Drawer for any historical version to inspect structural changes.
Clear History	Admin, Editor	Delete all historical snapshots except the current active version (found in the Danger Zone of the Component Drawer).

Permission Notes

All roles (Admin, Editor, Viewer) can view the version timeline and browse historical snapshots. Only Admins and Editors can execute syncs or clear a component’s history. Sync functionality requires a valid Figma PAT configured at the team level.