Contribute

Forking Arcticons

• Go to the GitHub page https://github.com/Arcticons-Team/Arcticons-Linux/ in a browser.

• In the top-right corner, click the Fork button. You'll get your very own clone of Arcticons! (You need a GitHub account for this).

I'd recommend using GitHub Desktop to make Git less difficult.

• Download & Install GitHub Desktop, and login with your credentials

• Click on Add > Clone repository and select your Arcticons repo. This will create a folder with the Arcticons project.

Now you have your local Arcticons project. This means you can add icons and edit the mappings.yaml.

Preparing the codebase

For generating the icons, you may need to do a git submodule update to pull the Arcticons repo, which will be pulled into the .arcticons folder.

We are using uv for the dependency management of the Python scripts. Run uv sync --dev in the Arcticons-Linux repo folder to prepare the environment.

Contributing your own icons

To contribute icons, which don't fit into the Android icon pack, you can place them into the icons_linux folder.

For matching the Arcticons style, you can follow the Android creation guide here:

Creating icons

You need to export the icon with black lines (stroke color #000) inside the icons_linux folder.

Mapping the icons

Under Linux, there is no single nomenclature for the app names, and so the icons are often needed in multiple places to account for different packaging systems etc.

For that, we have a mapping file called mapping.yaml, in which the icon names are mapped to different destinations.

Here is an example of a mapping:

browser:
  - apps/org.gnome.Epiphany
  - categories/applications-internet
  - categories/applications-network

The browser icon is mapped to three destinations. To add a new icon, just add the icon name as a new section and then the destination(s) as a list.

You can run uv run scripts/validate_mapping.py to validate the mapping file for correct syntax.

Finding the icons

Unfortunately, there are multiple locations for icons on Linux.

There is a icon search script which helps finding mappings.

Run uv run scripts/icon_search.py <keyword> to find icons containing the keyword as well as desktop files. This searches the most common places. You can use the parameters -v to see from which files the mappings were found, --no-icons to only search desktop files and --no-desktop to only search icon folders.

Generating icons

Run uv run scripts/generate_icons.py -c generate-icons.toml to generate the icons.

Necessary information for a PR

New icons

• You can create a PR as soon as you place the new icons inside the icons_linux directory. If you don't want to edit the mapping file, you can just give the mapping in the PR description.

• You can edit the mapping file to include the mappings just at the bottom of the file. While generating the icons, the mapping file will be sorted automatically.

• If you like, you can also generate the icons on your machine to include them in the PR. Be aware that for this to work, you need to have the main Arcticons repo pulled as the submodule; additionally, you need to have Inkscape installed.

New mappings

• If adding the mapping an icon which doesn't exist yet in the mapping file, adding it to the bottom of the file is perfectly fine, it will be sorted automatically when generating the icons.

• If adding a mapping to an icon which is already in the file, you can add the mapping to the list. It will be sorted automatically when generating the icons.

• If you like, you can also generate the icons on your machine to include them in the PR. Be aware that for this to work, you need to have the main Arcticons repo as pulled as submodule; additionally, you need to have Inkscape installed.

Uploading to GitHub

Now, when you open your GitHub Desktop window, you'll see a summary of the changes that you've made.

1. Give your commit a small summary.

2. Press the Current branch button, then create a new branch. Give it a name and press Create.

3. Publish your branch and commit the changes.

4. Now you can create a pull request by pressing the button. This will open the GitHub site again.

5. Create your pull request and you're done!

There you go, now all you have to do is wait for it to be merged into the Linux theme.