From fbfa174ad0492345cded393915a00447515628b7 Mon Sep 17 00:00:00 2001
From: Michael Weimann <michaelw@matrix.org>
Date: Mon, 9 Jan 2023 08:11:32 +0100
Subject: [PATCH] Improve icon doc (#9869)

---
 docs/icons.md | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/docs/icons.md b/docs/icons.md
index ef02e681a2..acf78d060c 100644
--- a/docs/icons.md
+++ b/docs/icons.md
@@ -1,29 +1,37 @@
 # Icons
 
-Icons are loaded using [@svgr/webpack](https://www.npmjs.com/package/@svgr/webpack). This is configured in [element-web](https://github.com/vector-im/element-web/blob/develop/webpack.config.js#L458)
+Icons are loaded using [@svgr/webpack](https://www.npmjs.com/package/@svgr/webpack).
+This is configured in [element-web](https://github.com/vector-im/element-web/blob/develop/webpack.config.js#L458).
 
-Each .svg exports a `ReactComponent` at the named export `Icon`.
+Each `.svg` exports a `ReactComponent` at the named export `Icon`.
 Icons have `role="presentation"` and `aria-hidden` automatically applied. These can be overriden by passing props to the icon component.
 
-eg
+SVG file recommendations:
+
+-   Colours should not be defined absolutely. Use `currentColor` instead.
+-   There should not be a padding in SVG files. It should be added by CSS.
+
+Example usage:
 
 ```
 import { Icon as FavoriteIcon } from 'res/img/element-icons/favorite.svg';
 
 const MyComponent = () => {
     return <>
-        <FavoriteIcon>
-        <FavoriteIcon className="mx_MyComponent-icon" role="img" aria-hidden="false">
+        <FavoriteIcon className="mx_Icon mx_Icon_16">
     </>;
 }
 ```
 
-## Styling
+If possible, use the icon classes from [here](../res/css/compound/_Icon.pcss).
 
-Icon components are svg elements and can be styled as usual.
+## Custom styling
 
-```
-// _MyComponents.pcss
+Icon components are svg elements and may be custom styled as usual.
+
+`_MyComponents.pcss`:
+
+```css
 .mx_MyComponent-icon {
     height: 20px;
     width: 20px;
@@ -32,13 +40,15 @@ Icon components are svg elements and can be styled as usual.
         fill: $accent;
     }
 }
+```
 
-// MyComponent.tsx
+`MyComponent.tsx`:
+
+```typescript
 import { Icon as FavoriteIcon } from 'res/img/element-icons/favorite.svg';
 
 const MyComponent = () => {
     return <>
-        <FavoriteIcon>
         <FavoriteIcon className="mx_MyComponent-icon" role="img" aria-hidden="false">
     </>;
 }