[Icons] Add support for <title> and <desc> elements in SVG for accessibility

src/Icons/doc/index.rst

@@ -481,6 +481,47 @@
 
         <twig:ux:icon name="user-profile" aria-hidden="false" />
 
+## Accessibility: Descriptive Titles and Descriptions
+
+.. versionadded:: NEXT\_VERSION
+
+The `ux_icon()` function and the `<twig:ux:icon>` component now support accessible SVG metadata via the `title` and `desc` attributes.
+
+These are automatically injected into the `<svg>` markup as child elements, and properly referenced using `aria-labelledby` for improved screen reader support.
+
+**How it works:**
+
+When you pass a `title` and/or `desc` attribute, they are rendered inside the `<svg>` as follows:
+
+.. code-block:: html+twig
+
+```
+{{ ux_icon('bi:plus-square-dotted', {
+    width: '16px',
+    height: '16px',
+    class: 'text-success',
+    title: 'Add Stock',
+    desc: 'This icon indicates stock entry functionality.'
+}) }}
+```
+
+Renders:
+
+.. code-block:: html
+
+```
+<svg class="text-success" width="16px" height="16px" aria-labelledby="icon-title-abc icon-desc-def">
+    <title id="icon-title-abc">Add Stock</title>
+    <desc id="icon-desc-def">This icon indicates stock entry functionality.</desc>
+    <!-- inner SVG content -->
+</svg>
+```
+
+To learn more about accessible SVG elements:
+
+- `MDN: <title>`\_ — [https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title)
+- `MDN: <desc>`\_ — [https://developer.mozilla.org/en-US/docs/Web/SVG/Element/desc](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/desc)
+
 Performance
 -----------
 

src/Icons/src/Icon.php

@@ -139,27 +139,53 @@ public function __construct(
     public function toHtml(): string
     {
         $htmlAttributes = '';
-        foreach ($this->attributes as $name => $value) {
+        $innerSvg = $this->innerSvg;
+        $attributes = $this->attributes;
+
+        // Extract and remove title/desc attributes if present
+        $title = $attributes['title'] ?? null;
+        $desc = $attributes['desc'] ?? null;
+        unset($attributes['title'], $attributes['desc']);
+
+        // Prepare <title> and <desc> elements
+        $labelledByIds = [];
+        $a11yContent = '';
+
+        if ($title) {
+            $titleId = 'title-' . bin2hex(random_bytes(4));
+            $labelledByIds[] = $titleId;
+            $a11yContent .= sprintf('<title id="%s">%s</title>', $titleId, htmlspecialchars((string) $title, ENT_QUOTES));
+        }
+
+        if ($desc) {
+            $descId = 'desc-' . bin2hex(random_bytes(4));
+            $labelledByIds[] = $descId;
+            $a11yContent .= sprintf('<desc id="%s">%s</desc>', $descId, htmlspecialchars((string) $desc, ENT_QUOTES));
+        }
+
+        // Only add aria-labelledby if not already present and we have content
+        if ($a11yContent !== '' && !isset($attributes['aria-labelledby'])) {
+            $attributes['aria-labelledby'] = implode(' ', $labelledByIds);
+        }
+
+        // Build final attributes string
+        foreach ($attributes as $name => $value) {
             if (false === $value) {
                 continue;
             }
 
-            // Special case for aria-* attributes
-            // https://www.w3.org/TR/wai-aria-1.1/#state_prop_def
             if (true === $value && str_starts_with($name, 'aria-')) {
                 $value = 'true';
             }
 
             $htmlAttributes .= ' '.$name;
+
             if (true === $value) {
                 continue;
             }
 
-            $value = htmlspecialchars($value, \ENT_QUOTES | \ENT_SUBSTITUTE, 'UTF-8');
+            $value = htmlspecialchars((string) $value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
             $htmlAttributes .= '="'.$value.'"';
-        }
-
-        return '<svg'.$htmlAttributes.'>'.$this->innerSvg.'</svg>';
     }
 
     public function getInnerSvg(): string