Add icon policy documentation

Bosch-0 commented at 6:01 am on December 3, 2020: none

I created some documentation as to how icons should be prepared, optimized, styled, contributed and attributed within Bitcoin Core. Having guidelines for iconography helps with making applications more consistent and efficient.

The current icon set does not yet follow this policy but I will be updating them in future PRs. To see the current icon set using this policy see this figma source file.

Merge pull request #1 from bitcoin-core/master

.

b40d4d494e

Added icon policy documentation 169834bfd4

in doc/icon_policy.md:7 in 169834bfd4 outdated

0@@ -0,0 +1,59 @@
1+# Icon policy
2+This document provides guidelines for contributing icons to Bitcoin Core.
3+
4+
5+
6+## Preparing Icons
7+Both an icon source file, in Scalable Vector Graphics (SVG) format, and an optimised production file, in Portable Network Graphics (PNG) format, are required for

jarolrod commented at 11:20 pm on December 3, 2020:

optimized is misspelled

0Both an icon source file, in Scalable Vector Graphics (SVG) format, and an optimized production file, in Portable Network Graphics (PNG) format, are required for

Bosch-0 commented at 9:30 am on December 4, 2020:

My mistake, I write in British English - will make this change to be more consistent with other documentation.

in doc/icon_policy.md:10 in 169834bfd4 outdated

 5+
 6+## Preparing Icons
 7+Both an icon source file, in Scalable Vector Graphics (SVG) format, and an optimised production file, in Portable Network Graphics (PNG) format, are required for 
 8+each icon.
 9+
10+SVGs are used as source files due to being able to scale to any size whilst retaining image quality, but are not used in production due to limited support by

jarolrod commented at 11:28 pm on December 3, 2020:

NIT: add title, cleanup text

0#### SVG Source File
1SVGs are used as source files because they can scale while retaining image quality, but are not used in production due to limited application support.

in doc/icon_policy.md:11 in 169834bfd4 outdated

 6+## Preparing Icons
 7+Both an icon source file, in Scalable Vector Graphics (SVG) format, and an optimised production file, in Portable Network Graphics (PNG) format, are required for 
 8+each icon.
 9+
10+SVGs are used as source files due to being able to scale to any size whilst retaining image quality, but are not used in production due to limited support by 
11+applications. If different sized production (PNG) icons are required they can be generated from the associated scaled SVG source file in a vector based tool like

jarolrod commented at 11:30 pm on December 3, 2020:

NIT: text cleanup

0In the event that different-sized production (PNG) icons are required, they can be generated from the associated SVG source file in a vector-based tool such as:

in doc/icon_policy.md:12 in 169834bfd4 outdated

 7+Both an icon source file, in Scalable Vector Graphics (SVG) format, and an optimised production file, in Portable Network Graphics (PNG) format, are required for 
 8+each icon.
 9+
10+SVGs are used as source files due to being able to scale to any size whilst retaining image quality, but are not used in production due to limited support by 
11+applications. If different sized production (PNG) icons are required they can be generated from the associated scaled SVG source file in a vector based tool like 
12+Inkspace, Adobe illustrator, Figma, Sketch or Adobe XD.

jarolrod commented at 11:30 pm on December 3, 2020:

the word Illustrator in Adobe Illustrator should be capitalized, missing comma after Sketch

0Inkspace, Adobe Illustrator, Figma, Sketch, or Adobe XD.

in doc/icon_policy.md:14 in 169834bfd4 outdated

 9+
10+SVGs are used as source files due to being able to scale to any size whilst retaining image quality, but are not used in production due to limited support by 
11+applications. If different sized production (PNG) icons are required they can be generated from the associated scaled SVG source file in a vector based tool like 
12+Inkspace, Adobe illustrator, Figma, Sketch or Adobe XD.
13+
14+PNGs are used in production due to their wide support in applications, support of transparent backgrounds and better image quality than competing file types

jarolrod commented at 11:36 pm on December 3, 2020:

NIT: add title, cleanup text

0#### PNG Production File
1PNGs are used in production due to wide application support, transparency support, and better image quality in comparison to competing file types

in doc/icon_policy.md:19 in 169834bfd4 outdated

14+PNGs are used in production due to their wide support in applications, support of transparent backgrounds and better image quality than competing file types 
15+such as JPEG.
16+
17+
18+### Icon Grid
19+Bitcoin Core uses an 8-point grid system for its icons which utilises size increments of 8px to visually orientate elements within a grid. Majority of screen sizes are divisible by 8 which makes fitting elements easier using an 8-point grid system. This makes things more efficient for designers and maintains consistency across applications.

jarolrod commented at 0:08 am on December 4, 2020:

utilizes is misspelled, The majority ... is correct The usage of orientate is wrong in this context.

0Bitcoin Core uses an 8-point grid system for its icons which utilizes size increments of 8px to visually orientate elements within a grid. The majority of screen sizes are divisible by 8 which makes fitting elements easier using an 8-point grid system. This makes things more efficient for designers and maintains consistency across applications.

in doc/icon_policy.md:29 in 169834bfd4 outdated

24+
25+- Icons should be minimal with little to no fine details. This is to make sure icons look good at any scale.  
26+- Icons size should be 32x32px. Different sized icons sizes may be necessary in some circumstances. If 32x32px is too small for the required icon placement, then the icon should be scaled up or down whilst sticking to the 8-point grid system.
27+- Shapes should be consistent and avoid organic elements that do not scale well.
28+- Colors should be consistent with other icons used in Bitcoin Core. 
29+- Icons should should follow an 8-point grid system (see above).

jarolrod commented at 0:18 am on December 4, 2020:

duplicate should, NIT on word choice While here: Is this needed? We mention the 8-point grid system in the second style principle where icons should be 32x32px

0- Icons should adhere to the 8-point grid system (see above).

Bosch-0 commented at 9:36 am on December 4, 2020:

Good point, could probably remove this

in doc/icon_policy.md:27 in 169834bfd4 outdated

22+### Icon Style
23+Icon style should follow a few basic principles to maintain consistency and clarity:
24+
25+- Icons should be minimal with little to no fine details. This is to make sure icons look good at any scale.  
26+- Icons size should be 32x32px. Different sized icons sizes may be necessary in some circumstances. If 32x32px is too small for the required icon placement, then the icon should be scaled up or down whilst sticking to the 8-point grid system.
27+- Shapes should be consistent and avoid organic elements that do not scale well.

jarolrod commented at 0:18 am on December 4, 2020:

What does it mean for shapes to be consistent? NIT on word choice

0- Icon should avoid organic shapes or elements, these do not scale well.

in doc/icon_policy.md:28 in 169834bfd4 outdated

23+Icon style should follow a few basic principles to maintain consistency and clarity:
24+
25+- Icons should be minimal with little to no fine details. This is to make sure icons look good at any scale.  
26+- Icons size should be 32x32px. Different sized icons sizes may be necessary in some circumstances. If 32x32px is too small for the required icon placement, then the icon should be scaled up or down whilst sticking to the 8-point grid system.
27+- Shapes should be consistent and avoid organic elements that do not scale well.
28+- Colors should be consistent with other icons used in Bitcoin Core.

jarolrod commented at 0:19 am on December 4, 2020:

NIT word choice

0- Colors should be consistent with existing Bitcoin Core icons.

in doc/icon_policy.md:26 in 169834bfd4 outdated

21+
22+### Icon Style
23+Icon style should follow a few basic principles to maintain consistency and clarity:
24+
25+- Icons should be minimal with little to no fine details. This is to make sure icons look good at any scale.  
26+- Icons size should be 32x32px. Different sized icons sizes may be necessary in some circumstances. If 32x32px is too small for the required icon placement, then the icon should be scaled up or down whilst sticking to the 8-point grid system.

jarolrod commented at 0:26 am on December 4, 2020:

misspellings and word choice

0- Icon size should be 32x32px by default. A different sized icon may be necessary under special circumstances. In the event that the 32x32px size is too small for the required icon placement, then the icon should be scaled up or down while adhering to the 8-point grid system.

in doc/icon_policy.md:25 in 169834bfd4 outdated

20+
21+
22+### Icon Style
23+Icon style should follow a few basic principles to maintain consistency and clarity:
24+
25+- Icons should be minimal with little to no fine details. This is to make sure icons look good at any scale.

jarolrod commented at 0:29 am on December 4, 2020:

NIT reword

0- To ensure icons look good at any scale, a minimalistic design should be used.

in doc/icon_policy.md:23 in 169834bfd4 outdated

18+### Icon Grid
19+Bitcoin Core uses an 8-point grid system for its icons which utilises size increments of 8px to visually orientate elements within a grid. Majority of screen sizes are divisible by 8 which makes fitting elements easier using an 8-point grid system. This makes things more efficient for designers and maintains consistency across applications. 
20+
21+
22+### Icon Style
23+Icon style should follow a few basic principles to maintain consistency and clarity:

jarolrod commented at 0:32 am on December 4, 2020:

NIT reword

0Icon style should adhere to the following principles to maintain consistency and clarity:

in doc/icon_policy.md:33 in 169834bfd4 outdated

28+- Colors should be consistent with other icons used in Bitcoin Core. 
29+- Icons should should follow an 8-point grid system (see above). 
30+
31+
32+### Optimizing Production Files (PNG): 
33+Production (PNG) files are to be optmized before being added to Bitcoin Core. Optimizing PNG files removes various color profiles, ancillary (alla) and text chunks resulting in a reduction in size of the image file losslessly (without a lowered image quality). Any `zopflipng` / `pngcrush` based PNG optimizers can be used, below are some examples:

jarolrod commented at 0:42 am on December 4, 2020:

optimized is misspelled, missing comma after ancillary, grammatical fixes. NIT on some word choices.

0Production (PNG) files must be optimized before their inclusion in Bitcoin Core. PNG optimization removes various unnecessary color profiles, ancillary (alla), and text chunks resulting in a lossless reduction of the file's size. Any `zopflipng` / `pngcrush` based PNG optimizer can be used. Below are some examples:

in doc/icon_policy.md:37 in 169834bfd4 outdated

32+### Optimizing Production Files (PNG): 
33+Production (PNG) files are to be optmized before being added to Bitcoin Core. Optimizing PNG files removes various color profiles, ancillary (alla) and text chunks resulting in a reduction in size of the image file losslessly (without a lowered image quality). Any `zopflipng` / `pngcrush` based PNG optimizers can be used, below are some examples:
34+
35+- Open source tool [ImageOptim](https://imageoptim.com/api).
36+- Open source tool [Trimage](https://trimage.org/).
37+- (Advanced) Run them through Bitcoin Cores [optimize-png.py](https://github.com/bitcoin-core/bitcoin-maintainer-tools/blob/master/optimise-pngs.py) script.

jarolrod commented at 0:45 am on December 4, 2020:

missing apostrophe: Bitcoin Cores -> Bitcoin Core's

0- (Advanced) Run them through Bitcoin Core's [optimize-png.py](https://github.com/bitcoin-core/bitcoin-maintainer-tools/blob/master/optimise-pngs.py) script.

in doc/icon_policy.md:42 in 169834bfd4 outdated

37+- (Advanced) Run them through Bitcoin Cores [optimize-png.py](https://github.com/bitcoin-core/bitcoin-maintainer-tools/blob/master/optimise-pngs.py) script.
38+
39+
40+
41+## Contributing
42+Icons should only be added to the Bitcoin Core repo via a pull request (PR) in two situations:

jarolrod commented at 0:48 am on December 4, 2020:

NIT: reword

0Icons are to be added to Bitcoin Core, via a pull request (PR), under these circumstances:

in doc/icon_policy.md:51 in 169834bfd4 outdated

46+
47+If a new icon is designed for an upcoming or active PR, the designer of the icon should [open an issue](https://github.com/bitcoin-core/gui/issues/new/choose) to get feedback on the design and to make sure it is consistent with Bitcoin Core's iconography.
48+
49+If a new feature is being added to the Bitcoin Core GUI that requires a new icon the developer should [open an issue](https://github.com/bitcoin-core/gui/issues/new/choose) requesting an icon to be designed. 
50+
51+Icons (both SVG and PNG) should not be added to the Bitcoin Core repo if they are not yet used in production.

jarolrod commented at 0:54 am on December 4, 2020:

NIT: reword

0Icons, both SVG and PNG, are not to be added to Bitcoin Core prior to a production use case.

jarolrod commented at 1:24 am on December 4, 2020:

While here: this could just say Icons are not to be added to Bitcoin Core prior to a production use case

in doc/icon_policy.md:49 in 169834bfd4 outdated

44+- An icon used in production is being replaced with a new icon.
45+- A feature is being added to the Bitcoin Core GUI that requires the addition of a new icon.
46+
47+If a new icon is designed for an upcoming or active PR, the designer of the icon should [open an issue](https://github.com/bitcoin-core/gui/issues/new/choose) to get feedback on the design and to make sure it is consistent with Bitcoin Core's iconography.
48+
49+If a new feature is being added to the Bitcoin Core GUI that requires a new icon the developer should [open an issue](https://github.com/bitcoin-core/gui/issues/new/choose) requesting an icon to be designed.

jarolrod commented at 1:10 am on December 4, 2020:

NIT reword

0If a new feature which requires a new icon is being added to the Bitcoin Core GUI, the developer should [open an issue](https://github.com/bitcoin-core/gui/issues/new/choose) requesting the new icon be designed.

in doc/icon_policy.md:53 in 169834bfd4 outdated

48+
49+If a new feature is being added to the Bitcoin Core GUI that requires a new icon the developer should [open an issue](https://github.com/bitcoin-core/gui/issues/new/choose) requesting an icon to be designed. 
50+
51+Icons (both SVG and PNG) should not be added to the Bitcoin Core repo if they are not yet used in production.
52+
53+When opening a PR that adds an icon source (SVG) files should be added to `src/qt/res/src` at 32x32px and optimized production (PNG) files should be added to `src/qt/res/icons` at 32x32px.

jarolrod commented at 1:16 am on December 4, 2020:

NIT reword Question: both files must be 32x32px, what about the special case where 32x32px is too small?

0When opening a PR that intends to add an icon, a SVG source file must be included under `src/qt/res/src`, and a optimized production file (PNG) must be included under `src/qt/res/icons`. Both source and production files should be 32x32px in size.

Bosch-0 commented at 9:39 am on December 4, 2020:

Than the SVG should be used to create a larger production (PNG) file. I’ll specify something about this just being the default size - different sizes will have to be tested by those contributing icons to see what size works best.

in doc/icon_policy.md:58 in 169834bfd4 outdated

53+When opening a PR that adds an icon source (SVG) files should be added to `src/qt/res/src` at 32x32px and optimized production (PNG) files should be added to `src/qt/res/icons` at 32x32px. 
54+
55+
56+
57+## Attribution 
58+Icon additions should have the appropriate attribution to the author, the licence used for the icon and any comments relevant to the icon included in the

jarolrod commented at 1:19 am on December 4, 2020:

NIT reword

0Icon additions must include appropriate attribution to the author, license information, and any comments relevant to the icon documented under the

jarolrod changes_requested

jonasschnelli commented at 8:49 am on December 4, 2020: contributor

Concept ACK. Great work. My only question would be, it this should belong to the root docs/ directory or if we should place it in src/qt/res/.

Update doc/icon_policy.md

Changed optimized spelling to optimised.

Co-authored-by: Jarol Rodriguez <jarolrod@tutanota.com>

78b214f8f5

Update doc/icon_policy.md