Preparing your GitHub repo to work with Ficus

What you need

Let’s make sure you have everything you need:

• A repo on GitHub.com
• Optionally, some token JSON files in that repo in the W3C Design Token Community Group draft format (or, Ficus can just create them from scratch)
• Links to the Figma files that contain the variables you want to use
• A Figma enterprise plan (standard plans can’t access these features)
• An understanding of how your Figma variables relate to your tokens

Setting up the project file

You’ll need to add a file to your repo that tells Ficus how to interact with it. I recommend naming it ficus.json but anything will work. All of the token JSON files that you want Ficus to update should be in the same folder or subfolders. This Ficus project file links a variable collection in Figma with one or more token JSON files.

Create a new JSON file in your repo either through the GitHub UI or your favorite text editor. You can start with this text:

{
	"name": "My design system",
	"figma": {
		"files": [
			{
				"key": "https://www.figma.com/file/abcdefg1234567890/My-variables-file",
				"collections": {
					"Global tokens": {
						"modes": {
							"Value": [ "global.json" ]
						}
					}
				}
			}
		]
	}
}

The above example assumes that you have a single Figma file called "My variables file" that has a single variable collection called "Global tokens" with a single mode called "Value". The tokens in the Value collection should be saved to global.json. Of course, you’ll need to adjust it to match how your tokens are organized. Here’s what you can change:

• name: This just helps you keep multiple Ficus configurations separate. It can be whatever you want.
• figma.files This is an array so you can include multiple Figma files at once: for example, you might have your global variables in one file and your alias variables in another.
  • key: This is either a link to a Figma file, or just the file’s "key" (the path segment after file in the URL).
  • collections: A list of the variable collections that you want Ficus to use. Each key in the object should exactly match the name of a variable collection in this Figma file, "Global tokens" in this example.
    • modes: A list of the modes in this variable collection. Each key in the object should exactly match the name of a mode in the variable collection, "Value" in this example. The value of each mode is an array of one string for each file connected to that mode. (Normally you would have a single token file for each mode, but you can split your tokens across multiple files and Ficus will try its best to add tokens to a reasonable place.)

Once you’ve created your Ficus project file, make sure that you commit and push. Everyone who uses Ficus with this GitHub repo will need the GitHub URL of that project file. It will look something like this:

https://github.com/TravisSpomer/MyTokens/blob/main/src/ficus.json

What’s next

Ficus is now set up! The next thing you should do is perform a test run before inviting designers to make their first pull requests.

• Optionally, create a new fork or branch of your repo that you can use for your testing.
• Each branch or fork will have its own project file URL, so make sure you get the correct one.
• Read through the steps to Setting up Ficus and making your first pull request.
• Once you’ve verified that things are working properly, share the GitHub URL of your project file (ficus.json) with your designer. Now they can make their first pull request with Ficus!

How do I turn these design tokens into CSS?

Ficus doesn’t do anything like that, but there are lots of tools that can. Or, you can write your own: the design token format is pretty simple.

What if my token names don’t match between Figma and code?

By default, a token named "Color/Red" in Figma will be saved in JSON as Color.Red. If that’s not what you need, find the variable in Figma and click Edit variable, and then scroll down to Code Syntax. Click the plus sign (+) and then Web, and then type the name of the token as it appears in JSON there, such as Global.Color.Red0. Do that for each token that’s named differently.

Security

Ficus has no special access to your repo: only people who already have access to your repo will be able to use Ficus to open pull requests.