How to apply design tokens to your icons
A guide for design teams to combine design tokens and icons, and make handoff a breeze with Figma Tokens and Font Awesome.
The problem
If you’re reading this, you’ve likely experienced the headaches that can come with handing over icon assets to engineering teams for implementation. Perhaps, you’ve spent weeks hand-crafting a beautiful icon set, or maybe you’ve decided to use one of the many excellent icon sets that are available via Figma Community. Usually you get a Figma library or a set of SVGs, set them up in a bounding box and then export them all. Perhaps you’ve got a workflow to upload these into Github.
Then the problems start… SVG output can be inconsistent, with additional information embedded in the SVG code, or you just need to change an icon name or its contents. And of course like so many design decisions, they keep changing and evolving as you discover new requirements and customer needs for your design system.
It’s time consuming and involves a lot of back and forth. Often we find inconsistencies between the Figma assets, and the icon component being available and used in your design system and application or website.
If this all sounds familiar read on!
Figma Tokens & Font Awesome
Figma Tokens offers a versatile and robust way of documenting your design decisions and managing the design tokens that represent them, all from within Figma. The plugin offers both free and paid tiers, and what we describe here is available on both. We’ll use Figma Tokens to define our tokens for the icons and push them to Github ready for the engineering team. Nice!
Font Awesome has been around for what feels like forever! But they’ve not sat still and continue to improve and extend their icon library. At the time of writing, v6.1.1 offers 16,083 icons in a variety of “weights” (styles) that cover many common use cases. Font Awesome is used through its font files and font-face, and by passing specific text strings to it, the font will render an icon on screen. This can be done locally via downloadable font files, self-hosted web fonts or through an API.
A note
Font Awesome is just that, awesome! However like most icon sets it’s not perfect. It’s fantastic that you can pass typographic properties to it, such as allowing you to align your icon sizes with your text and apply scale calculations for responsive icons (again, awesome!), but you can run into some issues that also face typography. Baselining can be a problem, and being able to scale the font size does mean that your icons do not always sit well on the pixel grid. Some icons are better than others, and relative scale and weight between icons can sometimes be hit and miss. As with most decisions, it’s about understanding your requirements and your customers’ needs, and making compromises where they make sense to you.
OK, so let’s look at how these two can work together to give you a fully tokenised icon library and an easy workflow to manage them.
Part 1: Getting set up
What you’ll need
- Figma — Recommend the native app as it includes local font support natively.
- Figma Tokens plugin — Available via the Figma Community and figmatokens.com. This will work with the free version and is fine to start with this.
- Font Awesome — You’ll need to sign up (again free version is fine, though you have a more limited icon set), set up a kit and download the Font Awesome TTF files to your local machine and install these. Heaps of details available on their support site.
- JSON — A basic working knowledge of editing JSON (it’s really simple for this exercise, and can be done from within Figma Tokens. If you’re new to this, don’t worry, this will be a very minor part of the process.
Before you begin
Understanding the decisions you need to make is important. What icons do you want to use from Font Awesome’s collection? What style do you want (solid, regular, light)? What sizes do you need in your system?
How you will use the icon in your application will help inform the name you give the token. This is what is commonly referred to as a semantic token, it has specific meaning to your design system or application’s context. For example, avoid names like “chevron-down” (that simply describes the icon), instead try something functional (e.g. “select dropdown”) or something conceptual, like “down”. This follows pretty standard semantic token definitions, but we won’t go into that too much here in the interests of time and mental load! For more on naming, check out Nathan Curtis’ excellent article on token naming.
Lastly, it is recommended that you set up text styles for your Font Awesome icons. This is the same as setting up any other text style. Choose the Font Awesome family you want to use, the font size and weight, and create a text style (FYI, this can also be turned into a typography token in Figma Tokens, but we won’t go into that today).
Part 2: Creating your design tokens in Figma Tokens
Fire up Figma Tokens and head to the Other category in the main panel (if you can’t see it, make sure “Show empty groups” is enabled).
Now let’s add some icons in. For this example, we’ll set up some icons we want to use as general UI icons. Let’s use that chevron mentioned before, and let’s also setup an icon to use in our search field.
Go ahead and click the “+” next to the Other category. In the dialog, we’ll want to set a name for the token. We want to make sure the token name accurately describes what the icon is, as well as how it should be used. These might be:
icon.ui.dropdown
icon.ui.search
Note how these names are not tied to a specific component, so you can use these icons where you want, they have clear and specific meaning, but also offer flexibility. Of course, how you name these is up to you!
Figma Tokens uses periods (.) to create groups, which is really useful for collecting tokens together when they have a relationship with each other. In this case, we’ve got 2 tokens and we know they belong to both icons and also they are both in a subgroup of UI.
Next, comes a spot of magic…..️
In the value field, you want to enter the class value from the Font Awesome icon you want to use. The structure of this is “fa-{style} fa-{icon}”. For the search icon, let’s say we want to use the solid style, this would be “fa-solid fa-magnifying-glass”. For the dropdown icon we might use “fa-solid fa-chevron-down”. All of the Font Awesome class names are available for every icon via their website.
Congratulations you’ve just defined an icon token! It’s really that simple. For large icon sets, it’ll take a moment to set up, but ongoing maintenance is very easy from here on, as it adding in new icons (or even removing some… I know, right?!)
Part 3: Documenting your icons in Figma
We’re not quite done though. Great that we can pass a tokenised value over to the engineers, but what about documenting this decision for everyone? Well, don’t worry, we’ve got you covered there too.
In the token’s description field, you want to enter the icon name that Figma will recognise. To render the glyph in Figma using the local font, you need a different value than the one passed through the token’s value field.
Essentially the name of the icon is used, rather than the class value. So for the search icon, we want to simply add “magnifying-glass” into the description. For the dropdown icon, it would be “chevron-down” (without the quote marks). Again, all this is available on the Font Awesome site.
Next, we want to use Figma Token’s powerful Documentation Tokens so that we can pass this information into Figma itself and render the icon.
- Create a text layer and assign the icon text style we setup at the start. It helps to put some placeholder text in there to make selection easier. Anything will do.
- Make sure the text layer is selected, then in Figma Tokens, right click on the token you want to apply, go to the Documentation Tokens menu and choose Description
And voila! Figma Tokens has told that text layer that its content is whatever is in your description field. And with the text style using Font Awesome, this now gets translated into a glyph icon in Figma. This is just a string of text, if you change the font family, you’ll see it’s just the text. Font Awesome is being awesome and translating this into an icon.
Part 4: Handoff to Engineering
We’re so close! But there are a couple of small tasks to do before we’re done.
First, we need to make sure that the engineering team (and the transforms they use) know this is an icon token we’ve created. Currently, Figma Tokens has us set these up under the “Other” category. Obviously this is a bit generic, so let’s fix this up.
To do this, we need to edit the type of the token. Now you’ll note that this is not a field in the token dialog, so we need to switch over to JSON editing mode and do this by hand. All we have to do is change the type in each token from “other” to “icon” (this time, include the quotes). Save the JSON and then switch back to the Listing view.
More magic! The Other category is now empty and a new category called “icon” is now available. This is an important step both for organising your design tokens and to help the engineers differentiate each token and how to apply it.
And finally, we’re ready to send our 2 icons out. Figma Tokens has a range of storage and sync’ing options to meet most needs, from local storage to sync with Github, JSONbin, Gitlab and recently Azure DevOps. For this example, we’ll use Github.
You’ll need a Github repo. Unlike many tools, this can use a private repo and you can go ahead and add your credentials in to authenticate, as well as chose the location to publish your tokens to. For Pro users, you can also specify a default branch to push and pull from as Figma Tokens Pro offers multi-branching support.
With your Github repo setup, go ahead and push the tokens as a commit. If you’ve no more tokens to add at this time, you can even trigger a PR creation from this point, though a commit will save your work if you’re not ready for a PR and you can carry on working. As a rule, commit often. If you close the plugin without committing, you will lose the work done since the previous commit.
And that’s it, you’re all done! This approach is extremely powerful for rapidly creating, publishing and maintaining your icon library and brings icons into the design system methodologies that are becoming so familiar. Font Awesome continues to provide an excellent set of scalable icons with a high performing CDN and robust API (essentially, they’re a Tokens As A Service provider!).
Figma Tokens is the glue that makes all this possible, providing teams with the ability to define both engineering requirements and design decisions into a single, elegant workflow that will significantly benefit your product team’s productivity and effectiveness.
Useful links
About the author
Chris Kerr is a Principal Product Designer at Performio and a design system advocate with over 2 decades experience in product design and delivery.
Performio is a next generation Incentive Compensation Management solution that eliminates the pain of calculating sales comp, easily communicate sales comp to reps and management, and accurately report on sales performance.
