Update icons documentation

dev_docs/05_icons.md

@@ -1,48 +1,31 @@
 # Icons
 
-This page is all about Kolibri Design System icons. It includes information on our icon sources and provides guidelines on related workflows.
+Here, you can find all about icons - where to get them, how to add them, etc.
 
-## Sources and regenerating Vue components
+## Introduction
 
-There are three sources of icons:
+Source icon files are stored as svg files in [`custom-icons`](../custom-icons/).
 
-- [Google Material Design Icons](https://github.com/material-icons/material-icons) (version pinned in [yarn.lock](yarn.lock))
-- [Material Design Icons](https://github.com/Templarian/MaterialDesign-SVG) (version pinned in [yarn.lock](yarn.lock))
-- [Custom Learning Equality icons]([custom-icons](../custom-icons/))
+### Vue icons
 
-Icons from these sources are then converted to Vue components by our custom precompilation script. After updating any of these sources, we need to regenerate the Vue components by running:
+Source svg files are converted to Vue components by our precompilation script. The resulting Vue components are made public via [the icons definitions file `lib/KIcon/iconDefinitions.js`](../lib/KIcon/iconDefinitions.js). The documentation website contains automatically generated [list of available icons](https://design-system.learningequality.org/icons/#icons) that can be used via Vue components, such as `KIcon`.
 
-```bash
-yarn run precompile-svgs
-```
+### Icons for reStructuredText
 
-You can also regenerate just the custom icons which is faster:
+In order to use icons on some Learning Equality's documentation pages written in reStructuredText, we also have a script to generate a set of reStructuredText replacement strings to [`docs/rstIconReplacements.txt`](../docs/rstIconReplacements.txt) which can be used in docs based on Sphinx. The file is available for download from https://design-system.learningequality.org/icons/#rst.
 
-```bash
-yarn run precompile-custom-svgs
-```
+## How to add a new icon
 
-One of these commands should be run after any icon changes.
+1. Paste a svg file to [`custom-icons`](../custom-icons/)
+2. Run `yarn run precompile-custom-svgs` to generate a corresponding Vue component. The generated component will be saved to [`lib/KIcon/precompiled-icons/le`](../lib/KIcon/precompiled-icons/le)
+3. Add a new entry for the generated component to [the icons definitions file](../lib/KIcon/iconDefinitions.js). Choose a unique alias that describes the purpose of the icon in our products well.
+4. Run `yarn run pregenerate` to update icons for reStructuredText documents. Note that it's important to run this step **after** updating the icons definitions file, otherwise it won't be detected.
 
-We don't expose all icons in our KDS public API. Only icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js) are exposed, and we use our custom aliases for them.
+To check that the new icon is successfully added:
+- Run the development server
+- See that the new icon is present in the icons list: http://localhost:4000/icons#icons
+- See that there is a new entry for the icon in the reStructuredText replacement strings file: http://localhost:4000/icons#rst
 
-In order to use icons in documentation we also output a set of reStructuredText replacement strings. These are added the file `docs/rstIconReplacements.txt` which can be used in docs based on Sphinx. The file is available for download from https://design-system.learningequality.org/icons/#rst
+## How to update an existing icon
 
-This command should be run after any icon ID changes.
-
-```bash
-yarn run pregenerate
-```
-
-### Example: Upgrading Google Material Design Icons
-
-It is advised to commit changes at each step to make reviewing files other than those in *precompiled-icons/* easier, especially in case of large updates.
-
-1. Run `yarn upgrade @material-icons/svg`
-2. Run `yarn run precompile-svgs`
-3. Review updates of all public icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js)
-
-Large upgrades can result in a colossal git diff which makes reviewing changes of selected public icons in detail difficult. To make such upgrades smoother, in addition to visually reviewing [icons in KDS documentation](https://design-system.learningequality.org/icons/#icons), you can use a report that is printed in a terminal as soon as the precompilation process ends. It contains all exposed icons aliases together with information about whether an icon has been updated or no. If it's been updated, git diff will be printed.
-
-4. Run `yarn run pregenerate`
-5. Write down notes to the changelog about any public updates like visual changes of icons, updates of their aliases, and updates of reStructuredText replacement strings
+The update process is similar to creating a new icon. After every update, run `yarn run precompile-custom-svgs` and `yarn run pregenerate`.