Add descriptions to tokens in Figma

[mkernohanbc]

Currently, we don't use the description field for Figma variables in the design tokens library. Tokens Studio does support a description field for each token, meaning we can create and manage variable descriptions at source.

A user has identified this as a refinement that would make it easier to understand the intended usage and scope of a given token, increasing their confidence level that they're using tokens 'correctly'.

This is likely to be a moderate lift, but is not a breaking change. Earmarking for a potential 3.0.1 or 3.1 release.

[mkernohanbc]

@Philip-Cheung I'm happy to take this on, adding you for visibility.

[Philip-Cheung]

Currently blocked from accessing TS (same issue of TS asking me for credentials to continue). Will need @ty2k to remove the access token for me to access TS

CC @mkernohanbc

[ty2k]

Philip was blocked by the "Couldn't load tokens stored on GitHub" error as seen in the screenshot below after opening Tokens Studio:

Couldn't load tokens stored on GitHub
Unable to fetch tokens from remote storage, if you haven't added credentials yet add them in the next step. Otherwise make sure the file exists and you have access to it.
(Enter credentials)

How we resolved this

1. Working in the "Tokens 3.0.1" branch in Tokens Studio plugin in Figma, I set up a new Sync Provider that points to bcgov/design-system using a new GitHub fine-grained personal access token (PAT) that I generated. The GitHub PAT only has access to read from this repo. This means it can read the existing JSON tokens data stored in the repo, which should be sufficient to unblock Philip's work. When it comes to adding changes to the JSON tokens data in the repo, I intend to do it by either:
   • Making a new branch in bcgov/design-system where I will manually commit the new JSON data (copy/paste from the TS plugin).
   • Making a new branch on a forked personal repo ty2k/design-system where my GitHub PAT has write access (the plugin itself will push a commit to a branch in my personal repo, no copy/paste)

This is what the sync provider settings look like:

• Name can be anything
• Personal Access Token is one generated by me that has at least read access to bcgov/design-system
• Repository (owner/repo) is bcgov/design-system
• Branch needs to refer to an existing branch, which in this case I cut from main and pushed just before this
• File Path needs to point to packages/design-tokens/input/tokens.json which needs to exist (though it doesn't need existing data in it - if the target file path does have valid tokens JSON, that will over-write any changes in the Figma file as we have experienced in the past)
• Base URL should be left blank

2. After the sync provider details are entered, hitting "Save" brings up a new dialog asking if we would like to pull the existing tokens data from GitHub:

Pull from GitHub?
Your repo already contains tokens, do you want to pull these now?
(Cancel) (Yes)

Note that this is a destructive action! If you select "Yes", you will be overwriting any existing token data in the file with the JSON data that's at your File Path in your sync provider.

I answered "Yes" since our File Path target contains the most recent tokens data (v3.0.0 right now) and that is what I would like to start with.

3. Now the Settings screen in the Tokens Studio plugin looks like the screenshot below. Note the addition of the "bcgov/design-system" sync provider.

At this point, Philip still has no access. I click the "Apply" button next to "Local document" in an effort to apply the data from the File Path target to the local file.

4. Another modal pops up asking if we want to "set to document storage":

Set to document storage?
You can always go back to remote storage.
(Cancel) (Yes, set to local)

I click "Yes, set to local".

5. At this point, our sync provider is set to "Local document" using the data from our File Path target. This is the point where Philip has access again:

[mkernohanbc]

Completed with 3.1.1 update, rolling out today/tomorrow.