Handling Removed Entities

This guide covers the scenario where entities that were previously synced to Grails can no longer be found in the Figma file. This can happen when a component is deleted, a variable collection is removed, or a style is cleared from the Figma library.

What “removed” means

When the plugin evaluates the current state of the file, it compares every entity it finds in Figma against the list of entities Grails knows about for this project. If Grails has a record of an entity that no longer appears in the Figma file, it flags that entity as removed.

Common causes:

• A designer deleted a component or component set from Figma.
• A variable collection was unlinked or deleted.
• A paint style or text style was removed from the local styles panel.
• The entity was moved to a different Figma file (not deleted, but no longer accessible to this plugin session).

Caution

Confirming removal from Grails is permanent and irreversible from the plugin. The entity’s data, version history, and linked documentation are deleted from the Vault.

What you see in the plugin

The Dashboard shows a red alert banner:

”⚠ Removed entities detected” Some entities in Grails no longer exist in your Figma file. Review them before removing. Detail: “N removed” Button: Review Removed

The Summary Cards also show a Removed badge (red dot) count for the affected entity types.

You can also see removed entities by clicking a Summary Card and selecting the Removed filter tab in the Entity List.

Step-by-Step

1. See the red banner on the Dashboard

   The banner ”⚠ Removed entities detected” appears with the count.

2. Click “Review Removed”

   The plugin navigates to the Review Removed screen.

3. Read the warning

   A red warning banner at the top reminds you:

   “These entities no longer exist in Figma. They may have been deleted or unpublished. Removing them from Grails is permanent.”

4. Review the entity list

   Entities are grouped by type (Components, Variable Collections, Paint Styles, Text Styles) in collapsible groups. Each group has:

   • A red Removed badge on the group header.
   • A strikethrough name on each item.
   • All items are pre-selected by default.

5. Decide what to remove

   • Keep all selections if all detected removals are intentional.
   • Uncheck individual items if you believe the entity was moved to another file or removed by mistake. Keeping it in Grails won’t break anything — it will appear as a “removed” entity until it’s re-synced or manually cleaned up later.

6. Add a Sync note (optional)

   Example: “Removed deprecated button variants and legacy color tokens”

7. Click “Remove from Grails”

   The selected entities are permanently deleted from the Grails Vault. The plugin returns to the Dashboard. The Removed banner disappears if all removed entities were addressed.

If you dismissed the removal by mistake

If you closed the plugin without confirming removal, the banner will reappear on the next file open. The entities remain in Grails until you explicitly confirm removal.

If you want to review removed entities without the Dashboard banner, you can:

1. Click a Summary Card (e.g., Components).
2. Select the Removed filter tab.
3. Check the item(s) you want to remove.
4. Click Remove from Grails in the selection bar.

Entity removed from Figma, but still needed in Grails?

If an entity was accidentally deleted from Figma and you want to keep its record in Grails:

1. Do not confirm removal in the plugin.
2. Restore the entity in Figma (from version history or by recreating it with the same name/key).
3. Re-sync it from the plugin to update its hash and clear the removed status.