[NO-JIRA] Track Figma metadata for token release labels

[IrinaWei]

Summary

This PR upgrades the Figma token sync release-label classifier from a token-path-based diff to a Figma-key-based diff, so renames in Figma show up as renames (one event) rather than as a delete + add (two events). It also splits the auto-generated PR summary into separate sections for renamed, changed, deleted, and added tokens so reviewers can scan the impact at a glance.

Why

Today the classifier compares two snapshots of token-sync/tokens/*.json by token path (the /-joined position in the JSON tree).

That's fine for value changes, but it has two real problems:

1. Renames look like delete + add. If a designer renames a Figma variable from core/primary to core/brand-primary, the classifier sees the old path disappear and a new path appear. The release is correctly labelled major — but the PR body says "deleted/renamed: core/primary" and "added: core/brand-primary" with no link between the two. Reviewers have to manually figure out it's the same token.
2. Group-level renames look like mass deletes. Renaming a Figma group (e.g. semantic → semantic-color) currently shows up as N deletes + N adds, which buries any actually deleted token in the noise.

The fix is to track the Figma-side identity of each variable (id + key, both stable across renames) inside the emitted DTCG token, and key the diff off that identity instead of the path.

Changes

1. Emit Figma metadata into the DTCG output

token-sync/src/dtcg-transformer.ts and types.ts now write a $extensions.figma block on every emitted leaf:

{
  "$value": "#0770e3",
  "$type": "color",
  "$extensions": {
    "figma": {
      "id": "VariableID:1234:5678",
      "key": "abc123def456..."
    }
  }
}

key is the persistent published key Figma assigns to a variable; it does not change when the variable is renamed or moved between groups. id is included for traceability back to the Figma file.

2. Classify by Figma key, fall back to token path

classify-release-label.ts now has two diff paths:

• figma-key mode — used when every leaf in both snapshots carries $extensions.figma. Builds an identity map keyed by ${fileName}:${figmaKey} and produces:
  • renamedTokens — same key, different tokenPath
  • changedTokens — same key, same path, different value fingerprint
  • deletedTokens — key in previous, missing in current
  • addedTokens — key in current, missing in previous
  • Each token lands in exactly one bucket — no double-counting.
• token-path mode (fallback) — preserves the existing path-based behaviour for older generated JSON that hasn't been re-fetched yet.

The chosen mode is exposed as summary.classificationMethod so callers/tests can assert on it.

The major vs minor rule is unchanged in spirit: any rename, value change, or deletion → major; pure additions → minor.

3. Value fingerprint ignores $extensions

tokenFingerprint strips $extensions before serialising the leaf for comparison. This means a metadata-only churn (e.g. Figma reassigns an internal id but the variable's value is unchanged) is not flagged as a value change.

4. Separate PR body sections

Previously the auto-generated PR body had a single "Deleted or renamed tokens" section. It now renders four distinct sections in this order:

1. Renamed tokens — with before → after paths
2. Changed token values
3. Deleted tokens
4. Added tokens

Each token appears in only one section. Empty sections are omitted.

5. Workflow + docs

• sync-figma-variables.yml: updated the in-PR-body release-label rules text to refer to "Figma variable keys" instead of "token paths". Also switches actions/checkout to use ${{ github.ref }} so the workflow can be tested from a feature branch via workflow_dispatch.
• token-sync/README.md and RUNBOOK.md: describe the key-based classification and the new PR body sections.

Backwards compatibility

• Old generated tokens without $extensions.figma continue to work — the classifier falls back to path-based diffing for that file set. The first run after this PR merges will write the metadata, and from then on key-based diffing applies.
• summary.deletedOrRenamedTokens is retained as a derived field (concat of deletedTokens + previous paths from renamedTokens) for any existing consumers.

Out of scope

• The classifier still flags $description-only changes as changed. That can be tightened later if it proves noisy in practice.
• No change to the major/minor boundary itself — only to how each bucket is computed and presented.

[skyscanner-backpack-bot]

Visit https://backpack.github.io/storybook-prs/4538 to see this build running in a browser.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[skyscanner-backpack-bot]

Visit https://backpack.github.io/storybook-prs/4538 to see this build running in a browser.