From d60dc1c024d9934f6ede2d57caa74de86ef5e7d0 Mon Sep 17 00:00:00 2001
From: Andrew Chadwick <61299+achadwick@users.noreply.github.com>
Date: Wed, 22 Jan 2025 13:24:34 +0000
Subject: [PATCH] tools/work/README.md fixup (#3912)
* docs: Exceptions where pure white/black are allowed
* docs: Outline, style, fixes.
* Update rools/work README.
* Reorder and reword.
* Typo fixes.
* Distinguish between base and foreground colours
- They have very different usage patterns
- Gets us thinking about contrast and accessibility ;)
* Try to distil useful rules for base and fg colour selection:
- Former apparent black and white requirement as lightness limits
- Pure white is "widely accepted", or widely used at least
- Pure black is almost never used though (surprised me, but true)
* Add loads of example icons from Papirus itself.
* Mention "paper" shade as a suggested meterial colour
* Clarify margins and "design to" areas
* Document how shadows and highlights are made in detail.
* Remove language about a palette because there isn't any official one.
* Improve wording.
* Split out the design notes, fix main README links.
---
README.md | 23 +++--
tools/work/DESIGN.md | 136 ++++++++++++++++++++++++++++++
tools/work/README.md | 195 ++++++++++++++++---------------------------
3 files changed, 224 insertions(+), 130 deletions(-)
create mode 100644 tools/work/DESIGN.md
diff --git a/README.md b/README.md
index 408952445a..845789f2fb 100644
--- a/README.md
+++ b/README.md
@@ -348,23 +348,29 @@ We welcome user contributions. If you don't know where to start, we've compiled
- new icons for missing applications
- symbolic links to an existing icon
- resolving open issues
+- improving our documentation
- spelling, grammar, phrasing
- improvements to our scripts
-Inside [tools/work](tools/work) you will find a step-by-step guide, an environment, and tools that will help you:
+Inside [tools/work](tools/work) you will find:
-- [create a new icon](tools/work#create-a-new-icon) from template
-- [make a symlink to an existing icon](tools/work#make-symlinks-to-an-existing-icon)
-- [edit an existing icon](tools/work#edit-an-existing-icon)
-- convert your icon to all variants of the theme
+- extensive [design notes](tools/work/DESIGN.md) for the Papirus icon theme
+- a working environment
+- template files you can adapt for new icons
+- scripts and tools for automating the entire design workflow:
+ - creating new icons
+ - editing existing icons
+ - symlinks to existing icons
+ - preparing/cleaning edited icons so they're ready to commit
+ - testing that the theme is right before you commit
+- a [step-by-step guide](tools/work/README.md#step-by-step-guide) to the scripted workflow
We are waiting for your pull requests and would love to see this icon theme become as complete as possible.
### How to design icons
-See the [Papirus wiki][wiki] for some useful guides to icon creation. There are topics in there covering just about every aspect of creating an icon for Papirus, as well as historical information about the project. Anyone can contribute a page, and we'd like it to be as useful as possible!
-
-[wiki]: https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/wiki
+- [detailed icon design notes](tools/work/DESIGN.md)
+- [our wiki](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/wiki), which dives deeper into various topics
## Donate
@@ -372,7 +378,6 @@ If you would like to support development by making one-time donation or by becom
-
## License
Papirus icon theme is free and open source project distributed under the terms of the GNU General Public License, version 3. See the [`LICENSE`](LICENSE) file for details.
diff --git a/tools/work/DESIGN.md b/tools/work/DESIGN.md
new file mode 100644
index 0000000000..42ef8fa163
--- /dev/null
+++ b/tools/work/DESIGN.md
@@ -0,0 +1,136 @@
+# Papirus Design Notes
+
+The following notes are a synthesis of many informal guidelines for Papirus icon design. They stop short of being an official style guide, and they may change over time.
+
+## Basic concepts
+
+Papirus is an SVG-based icon theme for Linux, drawing inspiration from Material Design and flat design.
+
+All elements are clear, distinct, and have recognisable outlines. Another main feature that distinguishes our theme is its use of warm color tones.
+
+Papirus icons are drawn in layers, moving from dark (down) to light (up).
+
+Objects have a thin highlight (`#ffffff` 20% or 10% for dark icons), and a shadow (always `#000000` 20%). See the template files for more info.
+
+## Main icon sizes
+
+Main icons have the following sizes: 16px, 22px, 24px, 32px and 48px. 64px icons are used for for apps, devices, places and mimetypes.
+
+Excluding their shadows, icon designs as a whole should fit within the following areas, centred on the icon.
+
+| Icon size | Design to | Margin |
+| --------- | --------- | ------ |
+| 16px | 16x16 | 0px |
+| 22px | 20x20 | 1px |
+| 24px | 20x20 | 2px |
+| 32px | 28x28 | 2px |
+| 48px | 40x40 | 4px |
+| 64px | 56x56 | 4px |
+
+### Q: Why do we need so many sizes for an SVG?
+
+Because if we use a single size for all then the icons will be blurred at some scales. All objects in Papirus icons need to have pixel alignment.
+
+## Base and foreground shapes
+
+Most Papirus icons have a shaped _base_ or background, and some have a _foreground_ design or logo drawn on top of the base too. Foreground elements like this need their own distinctive outline within the base shape, so there should be a good visual contrast between the base elements and any foreground design.
+
+Base element shapes must look good against both dark and light themes. See the sections below for guidelines about color choice for base elements.
+
+## Shadow and highlight
+
+The base elements of any icon should have a shadow and a highlight. Sometimes foreground elements do as well, if they're fairly large.
+
+Create the shadow by copying the elements you want to shadow, converting them to a single path with _Path → Object/Stroke to Path_ operations, ungroup, and _Union → Path_ in Inkscape, then changing the path's fill color to pure black, 20% object opacity. Move the shadow downwards by the distance in the table below.
+
+Create the highlight shape by copying the shape you made for the shadow twice, moving the top copy down by the distance in the table below, and subtracting it from the top one with _Path → Difference_ in Inkscape. Set the fill color to pure white at 20% object opacity, or 10% if you're putting a highlight on a dark element.
+
+| Icon size | Shadow offset (+y), hilight size (px) |
+| --------- | ------------------------------------- |
+| 16px | normally no shadow or highlight |
+| 22px | 0.5px (use the toolbar text entry) |
+| 24px | 0.5px |
+| 32px | 1px |
+| 48px | 1px |
+| 64px | 1px |
+
+Shadow and highlight offsets are an exception to the general rule about pixel alignments.
+
+## Selecting colors
+
+Please do not use very bright and toxic colors for Papirus. There is no official Papirus palette, but block colors should be warm-hued, juicy, and not overly saturated.
+
+Good examples colors are available in the main icon theme folders, and you can start with [the example SVG][svgex] in this folder too.
+
+For compatibility with the majority of GTK Themes, we use these brightness limits for base elements. Please don't pick color shades much brighter or darker than these for a base element, and treat these as hard limits for greyscale base elements. This doesn't include shadows and highlights.
+
+- white `#e4e4e4` (HSLuv L* of 91%)
+- black `#4f4f4f` (HSLuv L* of 34%)
+
+Suggested colors for object materials: these are especially useful for device icons.
+
+- paper `#e4e4e4`
+- steel `#afafb1`
+- aluminium `#8e8e8e`
+- plastic `#4f4f4f`
+
+[svgex]: ./examples-papirus.svg
+
+## Base element colors
+
+Base elements must be no brighter or darker than the black and white limits above. Papirus icons have to be compatible with a very wide range of GTK themes, some of which use white or pure black backgrounds.
+
+If the base elements are any lighter than `#e4e4e4`, they will tend to disappear into white backgrounds, and this will mess with the shape of the icon. Please avoid base element colors any lighter than the following examples:
+
+    
+
+    
+
+Similarly, base elements that are darker than `#4f4f4f` may be difficult to make out against a black background. Please avoid using base element colors that are any darker then the following examples
+
+    
+
+    
+
+## Foreground element colors
+
+The rules for color selection are a bit more relaxed when you're drawing a foreground element. Logos, text, or other other foreground elements that are fully on top of a base element can use brighter or darker colors than the rules for base elements allow. Put simply, they can be brighter or darker because they are isolated from the themed background color by their base.
+
+Pure `#ffffff` white is in widely accepted, widespread use on top of more vibrantly colored bases, even for quite large shapes:
+
+    
+
+    
+
+Some icons with dark foreground elements use darker colors like `#3f3f3f`. Note that pure black is only ever used for shadows in Papirus.
+
+    
+
+    
+
+The goal here is to create acceptable contrast between base and foreground elements. Consider checking the contrast between the icon's base shape and any foreground elements with a [WCAG 2.0 accessibility checker][checker1]. A rating of "AA" for the _Graphical Objects and User Interface Components_ category is a good minimum target for any logo. Finer designs and text should aim to pass under the _Normal Text_ category instead.
+
+[checker1]: https://webaim.org/resources/contrastchecker/
+
+## Monochrome icons
+
+Papirus now also supports KDE color scheme for monochrome actions, devices, places and panel icons. You can find more detailed info about that [here](https://techbase.kde.org/Development/Tutorials/Plasma5/ThemeDetails#Colors).
+
+Presently we only support the following icons:
+
+- actions (16px, 22px, 24px)
+- devices (16px)
+- places (16px)
+- panel (22px, 24px)
+
+## Gradients
+
+Avoid gradients. There's nothing technically wrong about them, it just isn't the Papirus style. Instead, workarounds are possible when redrawing particularly gradienty upstream icons in the Papirus style. Some examples of icons that evoke complex upsteam gradient with a bit of artistic posterization and some subtle shadows:
+
+   
+
+## Further reading
+
+See the [Papirus wiki][wiki] for some useful guides to icon creation. There are topics in there covering just about every aspect of icon creation workflow, as well as historical information about the project. Anyone can contribute a page, and we'd like it to be as useful as possible!
+
+[wiki]: https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/wiki
diff --git a/tools/work/README.md b/tools/work/README.md
index 0025c5b62f..49c685308d 100644
--- a/tools/work/README.md
+++ b/tools/work/README.md
@@ -4,147 +4,101 @@ Designing icons for Papirus is easy :)
You only need to draw icons for Papirus and then convert colors for ePapirus, Papirus Dark and Papirus-Light using our scripts.
-## Basic concepts
+## How to draw icons for Papirus
-Papirus is an SVG-based icon theme for Linux, drawing inspiration from Material Design and flat design.
-
-All elements are clear, distinct and have outlines. Another main feature that distinguishes our theme is its use of warm color tones.
-
-Papirus use layering style - moving from dark (down) to light (up) tone on layers.
-
-Objects have light stroke (#fff 20% or 10% for dark icons) and shadow (always #000 20%), see templates for more info.
-
-Mainly single size for all icons (without shadow):
-
-- 16px draw 16px icon
-- 22px draw 20px icon
-- 24px draw 20px icon
-- 32px draw 28px icon
-- 48px draw 40px icon
-- 64px draw 56px icon
-
-#### Main icons
-
-Main icons have the following sizes: 16px, 22px, 24px, 32px and 48px. Also available are some 64px icons for Apps, Devices, Places and Mimes.
-
-> Why do we need so many sizes for an SVG?
-
-Because if we use a single size for all then the icons will be blurred. All objects on Papirus have pixelated alignment.
-
-Keeping this in mind, **please do not use** very bright and toxic colors for Papirus.
-
-For compabillity with mostly GTK Themes we use this palette:
-
-- white `#e4e4e4`
-- black `#4f4f4f`
-
-For devices used material colors:
-
-- steel `#afafb1`
-- aluminium `#8e8e8e`
-- plastic `#4f4f4f`
-
-Examples are available in the main icon theme folders. In the `work` directory, you'll only find templates and scripts.
-
-#### Monochrome icons
-
-Papirus now also supports KDE color scheme for monochrome actions, devices, places and panel icons. You can find more detailed info about that [here](https://techbase.kde.org/Development/Tutorials/Plasma5/ThemeDetails#Colors).
-
-Presently we only support the following icons:
-
-- actions (16px, 22px, 24px)
-- devices (16px)
-- places (16px)
-- panel (22px, 24px)
+See the separate [Design Notes](DESIGN.md) document, and the [Papirus wiki](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/wiki).
## System Requirements
+The scripts in this folder require the following programs:
+
- Inkscape
- scour
For Debian/Ubuntu/Linux Mint users:
-```
+```sh
sudo apt update
-sudo apt install inkscape python-scour
-sudo pip install --upgrade scour
+sudo apt install inkscape python3-scour
```
+If you need a more recent version of scour, please install it with pipx.
+
## Step-by-Step Guide
### 1. Getting Started
-Open directory `work` in a file manager and open a terminal in the directory. You can do it from the context menu entry `Open in Terminal` or `Action → Open Terminal Here`.
+Open the `tools/work`folder in a file manager and open a terminal in that location. You can do that from the context menu entry `Open in Terminal` or `Action → Open Terminal Here`.
-- #### Create a new icon
+#### 1a. How to create a new icon
- Create a new icon from the provided template using the script `tools/work/new-icon.sh`. For all new icons, **please stick to using the template**. It is necessary because the template already has some needed objects, like a CSS stylesheet.
+You can create a new icon from the provided template using the `new-icon.sh` script in `tools/work`. For example,
- ```sh
- # For example
+```shell-session
+$ cd tools/work
+$ ./new-icon.sh apps abricotine
+'./Papirus/apps/_TEMPLATE@16x16.SVG' -> './Papirus/apps/abricotine@16x16.svg'
+'./Papirus/apps/_TEMPLATE@22x22.SVG' -> './Papirus/apps/abricotine@22x22.svg'
+'./Papirus/apps/_TEMPLATE@24x24.SVG' -> './Papirus/apps/abricotine@24x24.svg'
+'./Papirus/apps/_TEMPLATE@32x32.SVG' -> './Papirus/apps/abricotine@32x32.svg'
+'./Papirus/apps/_TEMPLATE@48x48.SVG' -> './Papirus/apps/abricotine@48x48.svg'
+'./Papirus/apps/_TEMPLATE@64x64.SVG' -> './Papirus/apps/abricotine@64x64.svg'
+```
- ./new-icon.sh apps abricotine
+This command has created six new working files inside the work directory from the template files. For all new icons, **please stick to using the template**. It is necessary because the template already has some needed objects, like a CSS stylesheet.
- # It creates the following files inside work directory
- # from the template files:
- #
- # ./Papirus/apps/abricotine@16x16.svg
- # ./Papirus/apps/abricotine@22x22.svg
- # ./Papirus/apps/abricotine@24x24.svg
- # ./Papirus/apps/abricotine@32x32.svg
- # ./Papirus/apps/abricotine@48x48.svg
- # ./Papirus/apps/abricotine@64x64.svg
- ```
+#### 1b. How to edit an existing icon
-- #### Edit an existing icon
+If you want to modify an existing icon, you can do that using the `get-from-theme.sh` script. For example,
- If you want to modify an existing icon, you can do that using the script `tools/work/get-from-theme.sh`.
+```shell-session
+$ cd tools/work
+$ ./get-from-theme.sh panel transmission-panel.svg
+'./../../Papirus/24x24/panel/transmission-panel.svg' -> './Papirus/panel/transmission-panel@24x24.svg'
+'./../../Papirus/16x16/panel/transmission-panel.svg' -> './Papirus/panel/transmission-panel@16x16.svg'
+'./../../Papirus/22x22/panel/transmission-panel.svg' -> './Papirus/panel/transmission-panel@22x22.svg'
+.svg
+```
- ```sh
- # For example
+#### 1c. How to make symlinks to an existing icon
- ./get-from-theme.sh panel transmission-tray-icon.svg
+This is an example of how you might fix issue [#354](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/issues/354). First, make sure there's an existing icon you can link to:
- # It copies following files into work directory from the
- # main icon theme folders:
- #
- # ./Papirus/panel/transmission-tray-icon@22x22.svg
- # ./Papirus/panel/transmission-tray-icon@24x24.svg
- ```
+```shell-session
+$ cd tools/work
+$ find ../../Papirus -type f -iname '*ardour*' -print
+./Papirus/16x16/apps/ardour.svg
+./Papirus/22x22/apps/ardour.svg
+./Papirus/24x24/apps/ardour.svg
+./Papirus/32x32/apps/ardour.svg
+./Papirus/48x48/apps/ardour.svg
+./Papirus/64x64/apps/ardour.svg
+```
-- #### Make symlinks to an existing icon
+Now you have the filename of an existing icon, `ardour.svg`, and the name of the new symlink from [#354](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/issues/354), `ardour5`. Create the symlinks with the command:
- It is a real example of the issue [#354](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/issues/354)
+```shell-session
+$ cd tools/work
+$ ./new-symlink.sh --help # this shows usage
+$ ./new-symlink.sh apps ardour.svg ardour5
+'./Papirus/apps/ardour5@16x16.svg' -> 'ardour.svg'
+'./Papirus/apps/ardour5@22x22.svg' -> 'ardour.svg'
+'./Papirus/apps/ardour5@24x24.svg' -> 'ardour.svg'
+'./Papirus/apps/ardour5@32x32.svg' -> 'ardour.svg'
+'./Papirus/apps/ardour5@48x48.svg' -> 'ardour.svg'
+'./Papirus/apps/ardour5@64x64.svg' -> 'ardour.svg'
+```
- Make sure those icons exist:
+**NOTE:** Symlinks will look like they're broken, but that's OK.
- ```sh
- find ../../Papirus -type f -iname '*ardour*' -print
+If your symlinks are in `apps`, `emblems` or `mimetypes` you can continue from step **4.3**, else continue from step **3**.
- # ./Papirus/16x16/apps/ardour.svg
- # ./Papirus/22x22/apps/ardour.svg
- # ./Papirus/24x24/apps/ardour.svg
- # ./Papirus/32x32/apps/ardour.svg
- # ./Papirus/48x48/apps/ardour.svg
- # ./Papirus/64x64/apps/ardour.svg
- ```
-
- Great, it's true, now you have the filename of the icon, it's `ardour.svg`, and the symlink name from the issue [#354](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme/issues/354), it's `ardour5`. Create symlinks with the command:
-
- ```sh
- # Usage: ./new-symlink.sh context ...
-
- ./new-symlink.sh apps ardour.svg ardour5
- ```
-
- **NOTE:** Symlinks will look like broken but is ok.
-
- If your symlinks are in apps, emblems or mimetypes you can continue from step **4.3**, else continue from step **3**.
-
-**IMPORTANT:** Please don't remove suffixes from the filename as it's needed for other scripts. Filename extension must be in lowercase.
+**IMPORTANT:** Please don't remove suffixes from the filename, as it's needed for other scripts. Filename extension must be in lowercase.
### 2. Papirus
+**IMPORTANT:** You should draw icons for the core Papirus theme first.
+
1. Open the created/copied file in Inkscape.
2. Delete any objects you do not need.
3. Draw new objects.
@@ -153,41 +107,40 @@ Open directory `work` in a file manager and open a terminal in the directory. Yo
### 3. Papirus Dark, Papirus Light and ePapirus
-1. Run script `tools/work/convert.sh`. It copies needed icons from `work/Papirus` to `work/Papirus-Dark`, `work/Papirus-Light` and `work/ePapirus` and changes their color schemes.
+1. Run `convert.sh`. It copies needed icons from `work/Papirus` to `work/Papirus-Dark`, `work/Papirus-Light`, and `work/ePapirus`. It then updates the copies' color schemes.
- **IMPORTANT:** You should draw icons for Papirus first.
-
- ```sh
- ./convert.sh
+ ```shell-session
+ $ cd tools/work
```
-2. Check result and edit manually if needed.
+2. Check the result, and edit manually if needed.
### 4. Final Steps
1. Run script `tools/work/prepare.sh` to clean the created icons:
- ```sh
- ./prepare.sh
+ ```shell-session
+ $ ./prepare.sh
```
2. Please check your icons again.
+
3. If everything is fine then put the icons into main icon theme folders:
- ```sh
- ./put-into-theme.sh
+ ```shell-session
+ $ ./put-into-theme.sh
```
4. Clean the `work` directory:
- ```sh
- ./clean.sh
+ ```shell-session
+ $ ./clean.sh
```
5. Run tests:
- ```sh
- make test
+ ```shell-session
+ $ make test
```
6. Everything is ready now! You can commit the changes to GitHub.