diff --git a/docs/images/icon-prep-evenodd-broken-conversion.png b/docs/images/icon-prep-evenodd-broken-conversion.png new file mode 100644 index 0000000000..a928d33724 Binary files /dev/null and b/docs/images/icon-prep-evenodd-broken-conversion.png differ diff --git a/docs/images/icon-prep-evenodd-correct-preview.png b/docs/images/icon-prep-evenodd-correct-preview.png new file mode 100644 index 0000000000..37bdd4ea8d Binary files /dev/null and b/docs/images/icon-prep-evenodd-correct-preview.png differ diff --git a/docs/images/icon-prep-stroke-broken-conversion.png b/docs/images/icon-prep-stroke-broken-conversion.png new file mode 100644 index 0000000000..a502dc21bc Binary files /dev/null and b/docs/images/icon-prep-stroke-broken-conversion.png differ diff --git a/docs/images/icon-prep-stroke-correct-preview.png b/docs/images/icon-prep-stroke-correct-preview.png new file mode 100644 index 0000000000..e9753dba7d Binary files /dev/null and b/docs/images/icon-prep-stroke-correct-preview.png differ diff --git a/docs/images/icon-prep-stroke-to-path-completed.png b/docs/images/icon-prep-stroke-to-path-completed.png new file mode 100644 index 0000000000..f7a9e1ba7b Binary files /dev/null and b/docs/images/icon-prep-stroke-to-path-completed.png differ diff --git a/docs/images/icon-prep-stroke-to-path-initial.png b/docs/images/icon-prep-stroke-to-path-initial.png new file mode 100644 index 0000000000..b3574d8eab Binary files /dev/null and b/docs/images/icon-prep-stroke-to-path-initial.png differ diff --git a/docs/subsystems/icons.md b/docs/subsystems/icons.md index c12a10ccb8..0f7c72682a 100644 --- a/docs/subsystems/icons.md +++ b/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 + + + + + + +``` + +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 `` 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 `` 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 + + + + + + + + + + +``` + +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