From 619f3959802fcaf364f2867a2d18e236ad9a250e Mon Sep 17 00:00:00 2001
From: Coen van der Kamp <coen@fourdigits.nl>
Date: Fri, 10 Feb 2023 08:22:45 +0100
Subject: [PATCH] Add new "Icons" page for icons customisation and reuse across
 the admin interface (#6028)

Co-authored-by: Thibaud Colas <thibaudcolas@gmail.com>
---
 CHANGELOG.txt                        |  1 +
 docs/advanced_topics/icons.md        | 82 ++++++++++++++++++++++++++++
 docs/advanced_topics/index.md        |  1 +
 docs/extending/extending_draftail.md |  2 +
 docs/releases/5.0.md                 |  1 +
 5 files changed, 87 insertions(+)
 create mode 100644 docs/advanced_topics/icons.md

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index 56010647c3..4773b37dd4 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -10,6 +10,7 @@ Changelog
  * Fix: Ensure `label_format` on StructBlock gracefully handles missing variables (Aadi jindal)
  * Fix: Adopt a no-JavaScript and more accessible solution for the 'Reset to default' switch to Gravatar when editing user profile (Loveth Omokaro)
  * Docs: Add code block to make it easier to understand contribution docs (Suyash Singh)
+ * Docs: Add new "Icons" page for icons customisation and reuse across the admin interface (Coen van der Kamp)
  * Maintenance: Update djhtml (html formatting) library to v 1.5.2 (Loveth Omokaro)
  * Maintenance: Re-enable `strictPropertyInitialization` in tsconfig (Thibaud Colas)
  * Maintenance: Refactor accessibility checker userbar item (Albina Starykova)
diff --git a/docs/advanced_topics/icons.md b/docs/advanced_topics/icons.md
new file mode 100644
index 0000000000..c6bc5d53dc
--- /dev/null
+++ b/docs/advanced_topics/icons.md
@@ -0,0 +1,82 @@
+(icons)=
+
+# Icons
+
+Wagtail comes with an SVG icon set. The icons are used throughout the admin interface.
+
+Elements that use icons are:
+
+- [Register Admin Menu Item](register_admin_menu_item)
+- [Client-side components](extending_clientside_components)
+- [Rich text editor toolbar buttons](extending_the_draftail_editor)
+- [ModelAdmin menu](modeladmin_menu_icon)
+- [StreamField blocks](custom_streamfield_blocks)
+
+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:
+
+```xml
+# app/templates/app_name/toucan.svg
+
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 800" id="icon-toucan">
+  <!-- This work is licensed under a CC0 license. https://creativecommons.org/publicdomain/zero/1.0/ -->
+  <path fill="currentColor" d="M321 662v1a41 41 0 1 1-83-2V470c0-129 71-221 222-221 122 0 153-42 153-93 0-34-18-60-53-72v-4c147 23 203 146 203 257 0 107-80 247-277 247v79a41 41 0 1 1-82-1v46a41 41 0 0 1-83 0v-46Z"/>
+  <path fill="currentColor" d="M555 136a23 23 0 1 0-46 0 23 23 0 0 0 46 0Zm-69-57H175c-60 0-137 36-137 145l9-8 367 6 72 18V79Z"/>
+</svg>
+```
+
+The `svg` tag should:
+
+- Set the `id="icon-<name>"` attribute, icons are referenced by this name
+- Set the `xmlns="http://www.w3.org/2000/svg"` attribute
+- Set the `viewBox="..."` attribute
+- Include license information, if applicable.
+
+Set `<path fill="currentColor"` to give the icon the current color.
+
+Add the icon with the `register_icons` hook.
+
+```python
+@hooks.register("register_icons")
+def register_icons(icons):
+    return icons + ['app_name/toucan.svg']
+```
+
+## Icon template tag
+
+Use an icon in a custom template:
+
+```html+django
+{% load wagtailadmin_tags %}
+{% icon name="toucan" classname="..." title="..." %}
+```
+
+## Changing icons via hooks
+
+```python
+@hooks.register("register_icons")
+def register_icons(icons):
+    icons.remove("wagtailadmin/icons/time.svg")  # Remove the original icon
+    icons.append("path/to/time.svg")  # Add the new icon
+    return icons
+```
+
+## Changing icons via template override
+
+When several applications provide different versions of the same template, the application listed first in `INSTALLED_APPS` has precedence.
+
+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/`.
diff --git a/docs/advanced_topics/index.md b/docs/advanced_topics/index.md
index f9b04d8e12..94a49c45cc 100644
--- a/docs/advanced_topics/index.md
+++ b/docs/advanced_topics/index.md
@@ -6,6 +6,7 @@ maxdepth: 2
 ---
 images/index
 documents/index
+icons
 embeds
 add_to_django_project
 deploying
diff --git a/docs/extending/extending_draftail.md b/docs/extending/extending_draftail.md
index dc7597956d..68decb7c24 100644
--- a/docs/extending/extending_draftail.md
+++ b/docs/extending/extending_draftail.md
@@ -1,3 +1,5 @@
+(extending_the_draftail_editor)=
+
 # Extending the Draftail Editor
 
 Wagtail’s rich text editor is built with [Draftail](https://www.draftail.org/), and its functionality can be extended through plugins.
diff --git a/docs/releases/5.0.md b/docs/releases/5.0.md
index ce3aebcc74..e5ccde3b4f 100644
--- a/docs/releases/5.0.md
+++ b/docs/releases/5.0.md
@@ -27,6 +27,7 @@ depth: 1
 ### Documentation
 
  * Add code block to make it easier to understand contribution docs (Suyash Singh)
+ * Add new "Icons" page for icons customisation and reuse across the admin interface (Coen van der Kamp)
 
 ### Maintenance