docs: Add documentation on using icons.

docs/subsystems/html-css.md

@@ -214,7 +214,8 @@ first add it to the appropriate place under `static/`.
   `web/src/portico`.
 - Custom SVG graphics living under `web/images/icons` are compiled into
   custom icon webfonts by webfont-loader according to the
-  `web/images/icons/template.hbs` template.
+  `web/images/icons/template.hbs` template. See
+  [icons](../subsystems/icons.md) for more details on adding icons.
 
 For your asset to be included in a development/production bundle, it
 needs to be accessible from one of the entry points defined either in

docs/subsystems/icons.md

@@ -1,5 +1,33 @@
 # Icons
 
+Zulip makes extensive use of icons to decorate elements in the UI as
+well as for compact buttons.
+
+## Using icons
+
+- Modern Zulip icons are implemented using `<i class="zulip-icon
+zulip-icon-smile"></i>`, which is rendered using generated CSS that
+  maps that class name combination to displaying the SVG file located
+  at `web/shared/icons/smile.svg`.
+
+- Older icons use [Font Awesome 4.7](https://fontawesome.com/),
+  declared in our HTML via `<i class="fa fa-paperclip"></i>`. We are
+  migrating away from Font Awesome both for design and licensing
+  reasons (Font Awesome 5.0+ is no longer fully open source).
+
+Always consider [accessibility](../subsystems/accessibility.md) when
+using icons. Typically, this means:
+
+- Icons that are used **purely as a decoration** to a textual label (for
+  example, in our popover menus) should use `aria-hidden`, so that
+  screenreaders ignore them in favor of reading the label.
+
+- Buttons whose **entire label** is an icon should have a
+  [tooltip](../subsystems/html-css.md#tooltips) as well as an
+  `aria-label` declaration, so that screenreaders will explain the
+  button. Generally, the tooltip text should be identical to the
+  `aria-label` text.
+
 ## Adding a new icon
 
 A new feature may require a new icon to represent it, for example to be used
@@ -7,7 +35,8 @@ next to a menu option. The issue you're working on may not have an icon
 specified upfront. In this case, you should:
 
 1. Prototype using a [Lucide icon](https://lucide.dev/icons/), which is the
-   default source for icons in Zulip.
+   default source for icons in Zulip. SVG files must be added under
+   `web/shared/icons/` (don't forget to `git add`) to be used.
 
 1. **When your feature is nearing completion**, post in the [appropriate
    channel](https://zulip.com/development-community/#where-do-i-send-my-message)