====================
Icon themes for GIMP
====================

---------------
Released Themes
---------------

GIMP 2.10 comes with 4 icon themes:

(1) Symbolic: the default icon theme (made for dark themes).
We follow GNOME guidelines when possible:
https://developer.gnome.org/hig/stable/icons-and-artwork.html.en

(2) Symbolic-Inverted: programmatically generated from the "Symbolic"
icon theme by inverting colors. Icon designers should not create icons
specifically for "Symbolic-Inverted".

Note: exceptions on the icon generation can be applied.
For instance "gimp-default-colors" and "gimp-toilet-paper" icons are not
inverted. And "gimp-color-picker-black" is generated by inverting
"gimp-color-picker-white" and reciprocally.
Ask for developer help when such exceptions are needed.

(3) Color: a new color icon theme, also designed with vector graphics.

(4) Legacy: this icon theme which contains the old GIMP 2.8 icons. It is
not maintained anymore and we are not expecting new icons for Legacy.
Yet since we keep them in the source tree for now, we would accept
updates.

The Symbolic icon theme are our main target since they are considered
better suited for graphics work (less visual distraction). Color icons
are kept as fall-over since some users still prefer them.

----------------
Adding new icons
----------------

- Add new icons in the single SVG file inside their respective
directories, i.e. `icons/Symbolic/symbolic-scalable.svg` for symbolic
icons and `icons/Color/color-scalable.svg` for color icons.

A single file allows easier reuse of material, and easy overview of all
existing icons which simplifies consistent styling…

- The contents of the SVG file should be organized for easy management
and easy contribution. You can visually group similar icons, make use
of layers, whatever is necessary for organization.

- You should group all parts of a single icon into a single object and
id this object with the icon name. For instance the object containing
the Move Tool icon should be id-ed: "gimp-tool-move".

- Make sure the object has the right expected size. A good trick is to
group with a square of the right size, made invisible.

- Export the icon as PNG and SVG into the appropriate size directory.

Ideally this step should be done at build time, but we could not find
yet a reliable way to extract icons out of the single SVG file without
using crazy build dependencies (like Inkscape). So this is done by hand
for the time being.

- Add the icons in `icons/icon-list.mk`.
This file is shared by all 3 maintained icon themes (Symbolic,
Symbolic-Inverted and Color), so you must make sure that you have the
Symbolic as well as the Color icons drawn before adding them.

Pixel perfection
----------------

Even as vector images, icons should be pixel-perfect when possible.
Therefore the first step before making an icon is to determine which
size it is supposed to appear at.
If the icon could appear in several sizes:

- if the sizes are multiples, just design the smaller size. The bigger
icon will stay pixel-perfect when scaled by a multiple. So for instance,
if you want the icon to be 12x12 and 24x24, just design the 12x12 icon.

- of course, if the size difference is big enough, you may want to
create a new version with added details, even when this is a multiple
(i.e. 12x12 and 192x192 may be different designs). These are design
choices.

- when sizes are no multiple (i.e. 16x16 and 24x24), it is preferred to
have 2 pixel-perfect versions.

- if time is missing, creating the smaller size only is a first step
and is acceptable.

Sizes
-----

Some known sizes:

- tool icons: 16x16 and 22x22.
- dock tab icons: 16x16 and 24x24.
- menu icons: 16x16.
[…]

-------------
Testing icons
-------------

Menu items and buttons are not supposed to have icons any longer. Yet
our actions have icons and some desktop environments would enable them
in menus and buttons regardless. To test how we do on systems which do
so, set the environment variable `GIMP_ICONS_LIKE_A_BOSS`.

For instance, start GIMP like this:

    GIMP_ICONS_LIKE_A_BOSS=1 gimp-2.9