Pending matches in Tokens

Grails looks for tokens and collections that are the same one kept in two places:

• a Figma variable and a code token with the same name, or with a name the code shortens;
• a Figma variable and a code token with the same value;
• two collections whose tokens mostly pair up.

It never joins them on its own. A person decides.

Where to find them

Admins and editors see a callout over the table on the Design side: N possible matches to review. Review opens the Pending matches panel with each pair. Viewers do not see the callout.

What the panel shows

Each pair is one card with its two sides, side by side:

• A token shows its collection, its type and its value: the Figma value in the collection’s default mode, and the code value as the code writes it.
• A collection shows how many tokens it holds.

Only a side with a panel of its own is a button. A Figma variable opens its token panel. A code token and a collection do not open anything.

The pairs are grouped by the reason they were proposed. The largest group comes first, and each group has a heading with its count. The reasons are:

• Match by Name: the same name.
• Match by Name ending: the code name ends the way the Figma name does.
• Match by Values: the same value, with different names.
• Match by Tokens: for collections, most of their tokens pair up.

Hover a reason to read it in a sentence. When there is more than one reason in the list, a row of chips at the top shows one reason at a time; All shows everything.

Deciding

Each card has two decisions in its footer:

• Match joins the two sides. You can undo it later (see Unmatch). Once matched, the Figma variable’s token panel names its code token and the repository it comes from, at the foot: for example Code: color.ink · @acme/ui.
• Not the same dismisses the pair. Grails will not propose it again.

Both ask for a confirmation first.

Match all appears when two or more pairs are tokens with the same name and the same value. It matches only those pairs, in one go, after a confirmation that says how many there are. Every other pair is matched one at a time.

If someone already decided a pair somewhere else, it leaves the list with a notice. If Grails cannot join a pair, it stays in the list, with the reason under it. The count in the callout follows each decision.

The panel for a component pair is the same panel, described in Components.

Unmatch

The panel’s Matched tab lists the token and collection pairs already matched, newest first, by a person or by Grails on its own, with who matched each one and when. Admins and editors see Unmatch at the foot of each card; a matched Figma variable’s token panel has it too, in the ⋯ menu beside its Code: line. After a confirmation the two become separate again, each with its own documentation, and Grails will not propose the pair again. Anything that changed after the match stays where it is now.

A match made before Grails kept a record of matches, or one whose token was matched with something else since, cannot be undone here, and its card says why.