dev_docs: Add instructions for preparing icon files.

docs/subsystems/icons.md

@@ -45,12 +45,170 @@ case, you should:
    #design for web app icons). You can use the discussion thread linked from the
    issue you're working on if there is one.
 
-1. Once there is general consensus, @-mention Zulip's designer (Vlad Korobov) to
-   ask him to prepare the icon to be used.
+1. Once there is general consensus on the icon to be used, be sure to
+   [prepare the icon's SVG file](#preparing-icons-for-use-with-zulip)
+   so that it displays correctly in Zulip.
 
 1. Follow the [attribution guidelines](../contributing/licensing.md)
    to document the icon's source in `docs/THIRDPARTY/`.
 
+## Preparing icons for use with Zulip
+
+You may discover that your chosen icon looks terribly broken when displayed
+in Zulip. There are two common issues with SVG files that must be manually
+corrected:
+
+1. [Icons that rely on strokes](#correcting-icons-that-include-strokes),
+   rather than paths
+2. [Icons that have an `evenodd` value](#correcting-icons-with-an-evenodd-fill-rule)
+   on the `fill-rule` attribute
+
+Each of those problems requires a different fix, followed by some
+[cleanup of the resulting SVG file](#cleaning-up-the-svg-code).
+
+### Correcting icons that include strokes
+
+For example, the unaltered [Lucide expand icon](https://lucide.dev/icons/expand)
+illustrates what we'd expect to see versus what we actually see after the icon
+goes through Zulip's automated SVG-to-font conversion:
+
+| Expected icon (SVG)                                                               | Broken appearance (SVG to font)                                                      |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| ![Expected icon with four arrows](../images/icon-prep-stroke-correct-preview.png) | ![Broken icon with four triangles](../images/icon-prep-stroke-broken-conversion.png) |
+
+What happened there is that the icon uses strokes, which do not properly convert
+to font outlines in Zulip's automated conversion system.
+
+To properly prepare an SVG icon for use with Zulip, you need to make sure that
+all stroke components are converted to paths:
+
+1. Open the SVG file in [Inkscape](https://inkscape.org/), a free and open-source
+   visual editor for vector images, including SVG.
+
+1. Use `Ctrl + A` or otherwise select all components of the icon.
+
+1. Locate Inkscape's Path menu, and choose the Stroke to Path item. You'll
+   immediately see your icon appear to balloon up: this is expected, because
+   the previous stroke in use has now been applied to your icon's converted paths.
+
+1. Examine the Stroke style applied to your paths on the Fill and Stroke tab of
+   Inkscape's object panel. Be sure to reduce the Stroke to 0:
+
+| Stroke incorrectly still applied                                             | Stroke set to zero                                                                       |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| ![Ballooned-out icon shapes](../images/icon-prep-stroke-to-path-initial.png) | ![Expected icon shapes without stroke](../images/icon-prep-stroke-to-path-completed.png) |
+
+At this point, you can save your file in the `web/shared/icons/` directory and
+close Inkscape before [cleaning up the SVG file](#cleaning-up-the-svg-code).
+
+### Correcting icons with an `evenodd` fill rule
+
+Certain icons may include a `fill-rule="evenodd"` attribute-value pairing. Those are
+often found on icons where one path appears inside of another. That is the case with
+the custom eye icon here, which turns solid black after going through Zulip's automated
+SVG-to-font conversion:
+
+| Expected icon (SVG)                                                              | Broken appearance (SVG to font)                                                    |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| ![Expected icon with eye shape](../images/icon-prep-evenodd-correct-preview.png) | ![Broken icon with solid shape](../images/icon-prep-evenodd-broken-conversion.png) |
+
+Should you encounter an icon that includes a `fill-rule` (easily spotted in the SVG file's
+code), you'll need to bring it into Inkscape to rework its paths.
+
+1. Open the SVG file in [Inkscape](https://inkscape.org/), a free and open-source
+   visual editor for vector images, including SVG.
+
+1. Use `Ctrl + A` or otherwise select all components of the icon.
+
+1. Locate Inkscape's Path menu, and choose Object to Path. This converts circles
+   and other SVG shapes to paths.
+
+1. Use `Ctrl + A` again to make sure all paths are still selected. From the Path menu,
+   choose Flatten. This typically makes a reasonable combination of the visible areas
+   of multiple paths.
+
+1. Finally, again with `Ctrl + A` to ensure the flattened paths are selected, return to
+   the Path menu and choose Combine. That joins all paths into a single, complex path.
+
+At this point, you can save your file in the `web/shared/icons/` directory and
+close Inkscape before [cleaning up the SVG file](#cleaning-up-the-svg-code).
+
+### Cleaning up the SVG code
+
+While Inkscape does a fine job with altering SVG files for proper SVG-to-font
+conversion, it also leaves a lot of crufty markup behind. So next, open your
+icon's SVG file in your editor of choice.
+
+Once opened in your editor, the file's Inkscape source will look something like this
+(the example here shows only the first 25 lines or so):
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   width="24"
+   height="24"
+   viewBox="0 0 24 24"
+   fill="none"
+   stroke="currentColor"
+   stroke-width="2"
+   stroke-linecap="round"
+   stroke-linejoin="round"
+   class="lucide lucide-expand-icon lucide-expand"
+   version="1.1"
+   id="svg8"
+   sodipodi:docname="expand.svg"
+   inkscape:version="1.4 (e7c3feb1, 2024-10-09)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs8" />
+  <sodipodi:namedview
+     id="namedview8"
+     pagecolor="#ffffff" />
+
+<!-- ...and so on. -->
+```
+
+Your last task is to clean up the SVG's XML so that only its essential components
+remain:
+
+1. Consider using Git to add and temporarily commit the icon as output by Inkscape.
+   If you make a mistake while cleaning up the icon, you can use `git restore` to
+   return to that point.
+
+1. Strip back the opening of the file to include only the `<svg>` tag and its `xmlns`,
+   `width`, `height`, and `viewBox` attributes and their values as set by
+   Inkscape. (There is no need to preserve the `fill` attribute, as it defaults to
+   black for its [initial value](https://www.w3.org/TR/SVG2/painting.html#SpecifyingFillPaint).)
+
+1. Remove all other tags in the file except for the `<path>` tags, which should be
+   cleaned up until they have only a `d` attribute and its value as output by Inkscape.
+
+1. When you are finished, your SVG file's source code should look something like this:
+
+```xml
+<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+  <path d="m 15,14 a 1,1 0 0 0 -0.707031,0.292969 1,1 0 0 0 0,1.414062 l 6,6 a 1,1 0 0 0 1.414062,0 1,1 0 0 0 0,-1.414062 l -6,-6 A 1,1 0 0 0 15,14 Z"/>
+  <path d="m 20.292969,2.2929688 -6,6 a 1,1 0 0 0 0,1.4140625 1,1 0 0 0 1.414062,0 l 6,-6 a 1,1 0 0 0 0,-1.4140625 1,1 0 0 0 -1.414062,0 z"/>
+  <path d="m 21,15.199219 a 1,1 0 0 0 -1,1 V 20 h -3.800781 a 1,1 0 0 0 -1,1 1,1 0 0 0 1,1 H 21 a 1.0001,1.0001 0 0 0 1,-1 v -4.800781 a 1,1 0 0 0 -1,-1 z"/>
+  <path d="m 16.199219,2 a 1,1 0 0 0 -1,1 1,1 0 0 0 1,1 H 20 v 3.8007812 a 1,1 0 0 0 1,1.0000001 1,1 0 0 0 1,-1.0000001 V 3 A 1.0001,1.0001 0 0 0 21,2 Z"/>
+  <path d="m 3,15.199219 a 1,1 0 0 0 -1,1 V 21 a 1.0001,1.0001 0 0 0 1,1 H 7.8007812 A 1,1 0 0 0 8.8007813,21 1,1 0 0 0 7.8007812,20 H 4 v -3.800781 a 1,1 0 0 0 -1,-1 z"/>
+  <path d="m 9,14 a 1,1 0 0 0 -0.7070312,0.292969 l -6,6 a 1,1 0 0 0 0,1.414062 1,1 0 0 0 1.4140625,0 l 6,-6 a 1,1 0 0 0 0,-1.414062 A 1,1 0 0 0 9,14 Z"/>
+  <path d="M 3,2 A 1.0001,1.0001 0 0 0 2,3 V 7.8007812 A 1,1 0 0 0 3,8.8007813 1,1 0 0 0 4,7.8007812 V 4 H 7.8007812 A 1,1 0 0 0 8.8007813,3 1,1 0 0 0 7.8007812,2 Z"/>
+  <path d="m 3,2 a 1,1 0 0 0 -0.7070312,0.2929688 1,1 0 0 0 0,1.4140625 l 6,6 a 1,1 0 0 0 1.4140625,0 1,1 0 0 0 0,-1.4140625 l -6,-6 A 1,1 0 0 0 3,2 Z"/>
+</svg>
+```
+
+With the source code tided up, take a moment to preview your cleaned-up file in your
+browser or operating system. If you're satisfied with how it looks, you can run
+`git add` and `git commit --amend` to commit your cleaned up icon--overwriting the
+output from Inkscape that you committed above.
+
+Your commit should also follow the [attribution guidelines](../contributing/licensing.md)
+and document the icon's original source in `docs/THIRDPARTY/`.
+
 ## Updating UI icons in the help center
 
 When changing an icon for an existing feature, be sure to [update the help