Variables & Tokens

The Variables section is the central repository for all design values — also called tokens — that form the visual foundation of your design system. Here you’ll find every color, spacing value, typography setting, or boolean flag that has been defined and synced from your Figma variable collections.

This section serves two primary use cases: exploring the entire set of variables in your system (organized by collection and type), and browsing Token Roles — semantic groupings that make it easy to find tokens that serve a specific purpose, such as “Brand Colors” or “Spacing Scale.”

Overview

The Variables section presents an interface split into two main zones:

• Left Sidebar: Contains the navigation tree with all synced collections and Team-defined Token Roles. Allows you to jump directly to a specific collection.
• Main Content Area: Shows variables in table format or the token cards for the selected role, depending on context.
• Toolbar: At the top of the content area, includes a search field and a counter showing how many variables are displayed.

Note

If no collections have been synced yet, the section will show an empty state with instructions for starting synchronization from the Figma plugin.

Variables Sidebar

The sidebar organizes your content into two main sections:

Variable Collections

Shows all collections synced from Figma. Each collection can be expanded to reveal its variables. Clicking a collection filters the main area to show only that collection’s variables.

Status badges next to collections indicate:

• Red badge: This collection was deleted in Figma but still exists in Grails.
• Yellow badge: This collection has outdated variables that changed in Figma.

Token Roles

Below the collections is the Token Roles section. A Token Role is a semantic grouping you define in Grails to organize tokens that share a common purpose (e.g., “Semantic Colors” or “Text Sizes”).

• Clicking a Token Role switches the main area to the Tokens View — a visual grid of token cards.
• Admins and Editors can create new Token Roles using the ”+” button next to the section title.

All Variables View (Table)

When no Token Role is selected, the main area shows the variables table with all variables in your system.

Information shown

Variables are grouped by collection and listed in a table with the following columns:

• Name: The full name of the variable including its grouping path (e.g., Colors/Primary/Blue-500). Displayed in a monospace font for readability.
• Type: A badge indicating the variable’s data type.
• Values per mode: One column per mode in the collection (e.g., Light, Dark, Desktop, Mobile). Shows the resolved value in that mode — a color, a number, or a reference to another variable.

Variable Types (Badges)

Badge	Type	What it contains
COLOR	Color	A color value (hex, RGBA) or a reference (alias) to another color. Shows a color swatch.
FLOAT	Numeric	A numeric value: spacing, font size, border radius, opacity, etc.
BOOLEAN	Boolean	A true or false value. Usually used to enable/disable visual behaviors.
STRING	Text	A text value: font family, URL, label, etc.

Aliased Values

When a variable’s value is an alias (reference to another variable), the values column shows the referenced variable’s name instead of a direct value. You can click that name to navigate directly to that variable and see its resolved value.

Caution

If an alias is broken (the referenced variable no longer exists or there’s a circular reference), a warning icon will appear next to the value.

Token Role View (Token Grid)

Selecting a Token Role in the sidebar switches the main area to the grid view. This view shows visual cards for each token in the selected role.

Information in each card

• Visual preview: For color tokens, a rectangle showing the actual token color. For other types, a visual representation of the value.
• Token name: The full name including its path.
• Resolved value: The final value of the token in the active mode.

Mode Selector

When the Token Role’s collection has multiple modes (e.g., Light / Dark, or Desktop / Mobile), a mode selector appears in the toolbar. Switching the mode lets you see how token values vary across contexts.

Variable Detail Panel

Clicking any variable in the table opens the Detail Panel from the right side of the screen. This panel shows comprehensive information about the selected variable.

Panel header

• Name and path: The full variable name with its categorization path (e.g., Colors / Primary / Blue-500).
• Type badge: Indicates whether it’s COLOR, FLOAT, BOOLEAN, or STRING.
• Token Role badge (optional): If the variable belongs to a Token Role, a blue badge with the role name appears. Clicking it navigates directly to that role.

Values and Aliases per Mode

The main section of the panel shows the variable’s values for each mode in its collection. For each mode you’ll see:

• Visualized alias chain: If the variable is an alias pointing to another variable (which may in turn point to another), a visual representation of connected nodes shows the full chain of references, from the variable name to the final resolved value.
• Final resolved value: The actual value applied at the end of the chain — for example, the hex #1A73E8 for a color, or 16 for a number.
• Color swatch: For COLOR-type variables, a square showing the actual color is displayed next to the hex value. You can click the value to copy it to the clipboard.

Broken references

Danger

If a variable has an alias configured but the reference is broken, the panel will show a red X icon with one of these messages:

• “Circular Reference” — The alias chain forms a loop (A → B → A).
• “Reference not found” — The referenced variable was deleted.

Stacked Panels

Clicking the name of a referenced variable inside the detail panel opens a second panel stacked over the first, showing that referenced variable’s details. You can navigate the full alias chain this way without losing your original context.

Collection Management

From the sidebar, Admins can disconnect a collection from Grails:

Caution

Unsyncing a Collection removes the collection and all its variables from Grails, but does not delete them from your Figma file. This action requires confirmation and cannot be undone from the interface. To see it again, you’ll need to re-sync it from the plugin.

Available Actions

Action	Roles	Description
Search variables	All	Typing in the search bar filters variables by name in real time.
Select collection	All	Clicking a collection in the sidebar filters the main area to show only its variables.
Switch mode	All	The mode selector (if present) lets you switch between Light/Dark, Desktop/Mobile, etc.
View variable detail	All	Clicking a variable opens the Detail Panel with its full value, type, and alias chain.
Copy color value	All	In the Detail Panel, clicking a color value copies the hex code to the clipboard.
Navigate aliases	All	Clicking a referenced variable opens its Detail Panel in a stacked panel.
Create Token Role	Admin, Editor	”+” button next to the “Token Roles” title in the sidebar. Creates a new semantic group.
Delete Token Role	Admin	Delete a Token Role (requires confirmation). Does not delete the variables it contained.
Unsync Collection	Admin	Remove a collection and all its variables from Grails (requires confirmation).

Role Permissions

• Admin: Full access. Can create and delete Token Roles, and unsync collections.
• Editor: Can create Token Roles. Can explore and search all information.
• Viewer: Read-only access. Can browse collections, view variables, explore aliases, and check values, but cannot make any changes.