Update documentation on icons management, with available icons

docs/advanced_topics/icons.md

@@ -14,14 +14,6 @@ Elements that use icons are:
 
 This document describes how to choose, add and customise icons.
 
-## Available icons and their names
-
-An icon name corresponds with the value of `id` in the SVG file: `<svg id="<name>"`.
-
-Icons are SVG files in the [Wagtail admin template folder](https://github.com/wagtail/wagtail/tree/main/wagtail/admin/templates/wagtailadmin/icons).
-
-Alternatively, enable the [styleguide](styleguide) to view the available icons and their names.
-
 ## Add a custom icon
 
 Draw or download an icon and save it in a template folder:
@@ -80,3 +72,18 @@ Place your app before any Wagtail apps in `INSTALLED_APPS`.
 
 Wagtail icons live in `wagtail/admin/templates/wagtailadmin/icons/`.
 Place your own SVG files in `<your_app>/templates/wagtailadmin/icons/`.
+
+## Available icons
+
+Enable the [styleguide](styleguide) to view the available icons and their names for any given project.
+
+Here are all available icons out of the box:
+
+<details open>
+
+<summary>Toggle icons table</summary>
+
+```{include} ../_static/wagtail_icons_table.txt
+```
+
+</details>

docs/contributing/ui_guidelines.md

@@ -89,3 +89,20 @@ First think of how to name the controller. Keep it concise, one or two words ide
 This is an area of active improvement for Wagtail, with [ongoing discussions](https://github.com/wagtail/wagtail/discussions/8017).
 
 -   Always use the `trimmed` attribute on `blocktranslate` tags to prevent unnecessary whitespace from being added to the translation strings.
+
+## SVG icons
+
+We use inline SVG elements for Wagtail’s icons, for performance and so icons can be styled with CSS. View [](icons) for information on how icons are set up for Wagtail users.
+
+### Adding icons
+
+Icons are SVG files in the [Wagtail admin template folder](https://github.com/wagtail/wagtail/tree/main/wagtail/admin/templates/wagtailadmin/icons). 
+
+When adding or updating an icon,
+
+1. Run it through [SVGO](https://jakearchibald.github.io/svgomg/) with appropriate compression settings.
+2. Manually remove any unnecessary attributes.
+3. Manually add its `id` attribute with a prefix of `icon-` and the icon name matching the file name.
+4. Keep the icon as named from its source if possible, and leave the licensing information in the SVG file if there is any.
+5. Add the icon to Wagtail’s own implementation of the `register_icons` hook, in alphabetical order.
+6. Go to the styleguide and copy the Wagtail icons table according to instructions in the template, pasting the result in `wagtail_icons_table.txt`.

docs/reference/contrib/settings.md

@@ -127,7 +127,7 @@ class SiteSpecificSocialMediaSettings(BaseSiteSetting):
         verbose_name = "Site-specific social media settings"
 ```
 
-For a list of all available icons, please see the [styleguide](styleguide).
+Wagtail’s default icon set can be seen in our [icons overview](icons). All icons available in a given project are displayed in the [styleguide](styleguide).
 
 ## Using the settings
 

docs/topics/streamfield.md

@@ -201,7 +201,7 @@ class PersonBlock(blocks.StructBlock):
         icon = 'user'
 ```
 
-For a list of the recognised icon identifiers, see the [](styleguide).
+For a list of icons available out of the box, see our [icons overview](icons). Project-specific icons are also displayed in the [styleguide](styleguide).
 
 ### ListBlock
 

wagtail/contrib/styleguide/templates/wagtailstyleguide/base.html

@@ -639,9 +639,9 @@
 
             {% for source, icons in all_icons %}
                 {% if source == "wagtailadmin/icons" %}
+                    {# Bespoke copy script with good line breaks to review icon update diffs in git. #}
                     <!-- Copy this section to update the `icons.md` documentation (wagtail_icons.html file). -->
-                    {# Copy the markup with good line breaks to review icon update diffs in git. #}
-                    <!-- In DevTools: copy($$('[data-icons-table^="wagtailadmin"]')[0].innerHTML.replace(/\s+/g, ' ').replace(/<t>/g, '\n<t>')) -->
+                    <!-- In DevTools: copy($$('[data-icons-table^="wagtailadmin"]')[0].innerHTML.replace(/\s+/g, ' ').replace(/<t/g, '\n<t')) -->
                 {% endif %}
                 <div class="w-mb-10" data-icons-table="{{ source }}">
                     <!-- Auto-generated with Wagtail’s styleguide. -->
@@ -659,7 +659,7 @@
                                 <tr>
                                     {# Renders the icon’s SVG within a SVG element, #}
                                     {# so we fully control the rendering without changing the icon’s markup. #}
-                                    {# Icons are loaded with render_to_string in Python, so need |safe. #}
+                                    {# Icons are loaded with render_to_string, so need |safe. #}
                                     <td><svg width="32" height="32" fill="currentColor">{{ item.icon|safe }}</svg></td>
                                     <td><code>{{ item.id }}</code></td>
                                     <td><code>{{ item.file_path }}</code></td>