docs/features/interface/icons.md

@@ -168,12 +168,32 @@ You can find the sources of these icons in `release/datafiles/assets/icons/toolb
 This is the [blender-assets](https://projects.blender.org/blender/blender-assets) repository,
 used as a Git submodule in the Blender repository.
 
-To create the actual icons, follow the built-in `README.txt` inside
+### Creating / Modifying New Icons
-`toolbar.blend`. This will guide you through creating the icon mesh
+- Object names are used to generate filenames: e.g. `ops.gpencil.draw.eraser`
-correctly.
+  will be written to `${BLENDER}/release/datafiles/icons/ops.gpencil.draw.eraser.dat`
+- An objects children are recursively included when exporting to allow easily sharing
+  geometry between icons.
 
-Once you do the geometry in Blender, you can transform it into a .dat
+  These may be transformed as long as they remain in the icon bounds.
-file with the command: `make icons_geom`
+- Material colors are multiplied by vertex colors when exporting.
+- Geometry depth is used so closer faces draw on top.
+- Vertex alpha can be used.
+- Try to keep the file well organized.
+
+### Exporting Icons
+
+#### Requirements
+- Objects must be meshes to be exported
+- Icon objects and any shared children must be in the **Export** collection to be considered for exporting.
+- Icon detail should be kept low since more complex icons will take more time to draw (while cached,
+  avoid unnecessary overhead).
+
+After the file has been committed to the `blender-assets` repository, the icons can be generated
+for use inside Blender via the following process.
+
+- Run: `make icons_geom`
+- Commit: `${BLENDER}/release/datafiles/icons/<icon_name>.dat` and
+  `${BLENDER}/source/blender/editors/datafiles/CMakeLists.txt`
 
 ## Built-in Assets