minor #1717 [Icons] aria-hidden="true" doc (smnandre)

This PR was merged into the 2.x branch.

Discussion
----------

[Icons] aria-hidden="true" doc

Add documentation to explain why & how this works.

(moved the first paragraph down to end with the feature / code examples)

Commits
-------

e644df4 [Icons] aria-hidden="true" doc

Author: kbond

src/Icons/doc/index.rst

@@ -342,17 +342,6 @@ Icons add visual elements to your website and they can be a challenge for access
 According to the `W3C guide about SVG icon accessibility`_, there are
 three methods to improve icons accessibility, depending on the context.
 
-**Decorative icons**
-    They are purely decorative and do not convey any meaning or function. They
-    should be hidden from screen readers using the ``aria-hidden`` attribute:
-
-    .. code-block:: html+twig
-
-        <a href="/profile">
-            {{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-hidden': true}) }}
-            Back to profile
-        </a>
-
 **Informative icons**
     They convey information or a function. They should define a text alternative
     that presents the same content or function via the ``aria-label`` attribute
@@ -372,6 +361,33 @@ three methods to improve icons accessibility, depending on the context.
 
         {{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-label': 'User Profile'}) }}
 
+**Decorative icons**
+    They are purely decorative and do not convey any meaning or function. They
+    should be hidden from screen readers using the ``aria-hidden`` attribute.
+
+    .. code-block:: html
+
+        <a href="/profile">
+            <svg viewBox="0 0 24 24" class="w-4 h-4" aria-hidden="true">
+                <!-- ... -->
+            </svg>
+            Back to profile
+        </a>
+
+That is why the ``ux_icon()`` function and the ``<twig:ux:icon>`` component add
+``aria-hidden="true"`` attribute **automatically** to icons not having at least one
+of the following attributes: ``aria-label``, ``aria-labelledby`` or ``title``.
+
+.. note::
+
+    If you don't want to set ``aria-hidden="true"`` for a specific icon, you can
+    explicitly set the ``aria-hidden`` attribute to ``false``:
+
+    .. code-block:: twig+html
+
+        <twig:UX:Icon name="user-profile" aria-hidden="false" />
+
+
 Performance
 -----------