How to add new icons

Every once in a while, we need a new icon. Luckily, it's pretty straight forward to do so, and in this guide, we will show you how.

First, get the set of new icons from your favorite designer as SVGs. There will typically be 6 SVGs per icon – a custom version for the 18, 24 and 30px version of each icon, and each of those in an outlined and a filled version.

Your typical .zip file will include something like this:

# Chapter Fill 18x18.svg
# Chapter Fill 24x24.svg
# Chapter Fill 30x30.svg
# Chapter Outline 18x18.svg
# Chapter Outline 24x24.svg
# Chapter Outline 30x30.svg

In order for us to create correct component names for our icons, we use a naming standard for our icon files. It looks like this:

# {icon name}-{variant}-{size}.svg

The icon name can have spaces, the variant is outline or fill (not outlined or filled), and the size is typically nxn (so 30x30). Everything is lowercase.

Here are some examples:

# chapter-fill-24x24.svg
# phone signal-outline-30x30.svg
# chevron right-outline-18x18.svg

Make sure to rename all of your icons correctly. If you've gotten several icons at a time (it's been known to happen), make sure you finish one at a time, to ensure everything is up to spec.

The icon assets live in the packages/spor-icon/svg folder. If you venture into that folder, you'll see something like this:

❯ ls
communication   map             onboard-service transportation
feedback        misc            payment         travel
layout          navigation      social-media

These are the categories for your icons. Ask your designer where they should be put, if that wasn't a part of the file structure you received them in.

Next, drop your newly named icons into the correct folder.

To make sure everything is as it should, return to the spor root folder and run npm run build. This will create the spor-icon-react and spor-icon-react-native components that will be used in our applications.

You can verify that your icons are built correctly by going into each of packages/spor-icon-react/tmp and packages/spor-icon-react-native/tmp folders, and finding your correctly named component as one of the files there.

The final step you want to do is to release new versions of the @vygruppen/por-icon-react and @vygruppen/spor-icon-react-native packages. You do this by running the npx changeset command. This will prompt you for what packages you want to release. In this case, you want to release a new version of @vygruppen/spor-icon, @vygruppen/spor-icon-react and @vygruppen/spor-icon-react-native. Only the first of those three will be pre-selected, so make sure to include all three.

If you've removed or renamed an icon, it's a major release.
If you've added an icon, it's a minor release.
If you've updated an icon without updating its name, it's a patch release.

You can read more about changesets here.

With all of this done, you're ready to push your branch and create a pull request. You don't have to include screenshots, as those show up automatically. But we love it if you explain why the icons are necessary, so we don't end up adding icons to our common icon package that could've been one-offs in a single project.

If you've reached this far, you're done with your job. Now the Spor team has to verify your changes, and deploy a new version. That typically happens within minutes if you ping us on Slack.

If you're stumbling into some issues that aren't covered by this guide, please make sure to tell us, so we can help improve the guide for future readers. Now, get on with publishing those new icons!