Improve the documentation for icons

diff --git a/docs/migration/wsc55/icons.md b/docs/migration/wsc55/icons.md
index b569a9089b8e8484a054c5c722f2f1f42a4fcf6e..0baeecbda39de80537b3699a5d20a5f0825888bd 100644 (file)
--- a/docs/migration/wsc55/icons.md
+++ b/docs/migration/wsc55/icons.md
@@ -27,7 +27,7 @@ Additionally there is no title which leaves users clueless about what the option
 WoltLab Suite 6.0 addresses this issue by removing all default styling from `<button>` elements, making them the ideal choice for button type elements.
 
 ```smarty
-<button class="jsMyDeleteButton" data-some-object-id="123" title="descriptive title here">{icon size=16 name='xmark'}</button>
+<button class="jsMyDeleteButton" data-some-object-id="123" title="descriptive title here">{icon name='xmark'}</button>
 ```
 
 The icon will appear just as before, but the button is now properly accessible.
@@ -45,14 +45,20 @@ The new template function `{icon}` was added to take care of generating the HTML
 Icons in HTML should not be constructed using the actual HTML element, but instead always use `{icon}`.
 
 ```smarty
-<button class="button">{icon size=16 name='bell'} I‘m a button with a bell icon</button>
+<button class="button">{icon name='bell'} I‘m a button with a bell icon</button>
 ```
 
 Unless specified the icon will attempt to use a non-solid variant of the icon if it is available.
 You can explicitly request a solid version of the icon by specifying it with `type='solid'`.
 
 ```smarty
-<button class="button">{icon size=16 name='bell' type='solid'} I‘m a button with a solid bell icon</button>
+<button class="button">{icon name='bell' type='solid'} I‘m a button with a solid bell icon</button>
+```
+
+Icons will implicitly assume the size `16`, but you can explicitly request a different icon size using the `size` attribute:
+
+```smarty
+{icon size=24 name='bell' type='solid'}
 ```
 
 ### Brand Icons
@@ -69,11 +75,18 @@ Buttons can be dynamically created using the native `document.createElement()` u
 
 ```ts
 const icon = document.createElement("fa-icon");
-icon.size = 16;
 icon.setIcon("bell", true);
 
 // This is the same as the following call in templates:
-// {icon size=16 name='bell' type='solid'}
+// {icon name='bell' type='solid'}
+```
+
+You can request a size other than the default value of `16` through the `size` property:
+
+```ts
+const icon = document.createElement("fa-icon");
+icon.size = 24;
+icon.setIcon("bell", true);
 ```
 
 ### Creating Icons in HTML Strings
@@ -81,12 +94,12 @@ icon.setIcon("bell", true);
 You can embed icons in HTML strings by constructing the `fa-icon` element yourself.
 
 ```ts
-element.innerHTML = '<fa-icon size="16" name="bell" solid></fa-icon>';
+element.innerHTML = '<fa-icon name="bell" solid></fa-icon>';
 ```
 
 ### Changing an Icon on Runtime
 
-You can alter the size by changing the `size` attribute which accepts the numbers `16`, `24`, `32`, `48`, `64`, `96`, `128` and `144`.
+You can alter the size by changing the `size` property which accepts the numbers `16`, `24`, `32`, `48`, `64`, `96`, `128` and `144`.
 The icon itself should be always set through the `setIcon(name: string, isSolid: boolean)` function which validates the values and rejects unknown icons.
 
 ## Migrating Icons
@@ -96,7 +109,7 @@ The script itself is very defensive and only replaces obvious matches, it will l
 
 ### Replacing Icons With the Helper Script
 
-The helperscript is part of WoltLab Suite Core and can be found in the repository at `extra/migrate-fa-v4.php`.
+The helper script is part of WoltLab Suite Core and can be found in the repository at `extra/migrate-fa-v4.php`.
 The script must be executed from CLI and requires PHP 8.1.
 
 ```shell
@@ -107,4 +120,21 @@ The target directory will be searched recursively for files with the extension `
 
 ### Replacing Icons Manually by Example
 
-TODO
\ No newline at end of file
+The helper script above is limited to only perform replacements for occurrences that it can identify without doubt.
+It will not replace occurrences that are formatted differently and/or make use of additional attributes, including the icon misuse as clickable elements.
+
+```smarty
+<li>
+    <span class="icon icon16 fa-times pointer jsButtonFoo jsTooltip" title="{lang}foo.bar.baz{/lang}">
+</li>
+```
+
+This can be replaced using a proper button element which also provides proper accessibility for free.
+
+```smarty
+<li>
+    <button class="jsButtonFoo jsTooltip" title="{lang}foo.bar.baz{/lang}">
+        {icon name='xmark'}
+    </button>
+</li>
+```