Skip to content

Commit 4ef2251

Browse files
javiereguiluzkbond
javiereguiluz
authored and
kbond
committed
[Doc] UX Icons doc tweaks
1 parent ed637a0 commit 4ef2251

File tree

1 file changed

+59
-104
lines changed

1 file changed

+59
-104
lines changed

‎src/Icons/doc/index.rst‎

Lines changed: 59 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ Installation
1616
1717
$ composer require symfony/ux-icons
1818
19-
2019
SVG Icons
2120
---------
2221

@@ -89,40 +88,25 @@ Icon Sets
8988

9089
There are many icon sets available, each with their own unique style and set of
9190
icons, providing a wide range of icons for different purposes, while maintaining
92-
a consistent look and feel across your application.
93-
94-
With more than 200,000 icons available, you can find the perfect icon for your
95-
project. Here are some of the most popular icon sets available:
96-
97-
========================= ======= ========== =========== =================
98-
Icon Set Icons License Prefix Example
99-
========================= ======= ========== =========== =================
100-
`Bootstrap Icons`_ 2000 MIT bi bi:check
101-
`Boxicons`_ 1700 MIT bx bx:check
102-
`Flowbite`_ 1000 MIT flowbite flowbite:check
103-
`FontAwesome Icons`_ 7000 CC BY 4.0 fa6-regular fa6-regular:check
104-
`Heroicons`_ 300 MIT heroicons heroicons:check
105-
`Iconoir`_ 1500 MIT iconoir iconoir:check
106-
`Ionicons`_ 1300 MIT ion ion:check
107-
`Lucide Icons`_ 1500 MIT lucide lucide:check
108-
`Material Design Icons`_ 5000 Apache 2 mdi mdi:check
109-
`Octicons`_ 600 MIT octicon octicon:check
110-
`Phosphor Icons`_ 7000 MIT ph ph:check
111-
`Tabler Icons`_ 5200 MIT tabler tabler:check
112-
========================= ======= ========== =========== =================
113-
114-
- `Bootstrap Icons <https://icons.getbootstrap.com/>`_
115-
- `Boxicons <https://boxicons.com/>`_
116-
- `Flowbite <https://github.com/themesberg/flowbite>`_
117-
- `FontAwesome Icons <https://github.com/FortAwesome/Font-Awesome>`_
118-
- `Heroicons <https://github.com/tailwindlabs/heroicons>`_
119-
- `Iconoir <https://github.com/iconoir-icons/iconoir>`_
120-
- `Ionicons <https://github.com/ionic-team/ionicons>`_
121-
- `Lucide Icons <https://github.com/lucide-icons/lucide>`_
122-
- `Material Design Icons <https://github.com/google/material-design-icons>`_
123-
- `Octicons <https://github.com/primer/octicons/>`_
124-
- `Phosphor Icons <https://github.com/phosphor-icons/homepage>`_
125-
- `Tabler Icons <https://github.com/tabler/tabler-icons>`_
91+
a consistent look and feel across your application. Here are some of the most
92+
popular icon sets available:
93+
94+
======================== ======= ========== =============== =====================
95+
Icon Set Icons License Prefix Example
96+
======================== ======= ========== =============== =====================
97+
`Bootstrap Icons`_ 2000 MIT ``bi`` ``bi:check``
98+
`Boxicons`_ 1700 MIT ``bx`` ``bx:check``
99+
`Flowbite`_ 1000 MIT ``flowbite`` ``flowbite:check``
100+
`FontAwesome Icons`_ 7000 CC BY 4.0 ``fa6-regular`` ``fa6-regular:check``
101+
`Heroicons`_ 300 MIT ``heroicons`` ``heroicons:check``
102+
`Iconoir`_ 1500 MIT ``iconoir`` ``iconoir:check``
103+
`Ionicons`_ 1300 MIT ``ion`` ``ion:check``
104+
`Lucide Icons`_ 1500 MIT ``lucide`` ``lucide:check``
105+
`Material Design Icons`_ 5000 Apache 2 ``mdi`` ``mdi:check``
106+
`Octicons`_ 600 MIT ``octicon`` ``octicon:check``
107+
`Phosphor Icons`_ 7000 MIT ``ph`` ``ph:check``
108+
`Tabler Icons`_ 5200 MIT ``tabler`` ``tabler:check``
109+
======================== ======= ========== =============== =====================
126110

127111
To see the full list of available icon sets, visit `ux.symfony.com/icons`_.
128112

@@ -180,7 +164,6 @@ a subdirectory, the *name* will be ``subdirectory:icon_name``.
180164
│ └─ ...
181165
└─ ...
182166
183-
184167
Icons On-Demand
185168
~~~~~~~~~~~~~~~
186169

@@ -190,10 +173,6 @@ from many different sets. This package provides a way to include any icon found
190173
`ux.symfony.com/icons`_ has a huge searchable repository of icons from many
191174
different sets. This package provides a way to include any icon found on this
192175
site *on-demand*:
193-
1. Visit `ux.symfony.com/icons`_ and search for an icon
194-
you'd like to use. Once you find one you like, copy one of the code snippets provided.
195-
2. Paste the snippet into your Twig template and the icon will be automatically fetched (and cached).
196-
3. That's it!
197176

198177
1. Visit `ux.symfony.com/icons`_ and search for an icon you'd like to use. Once
199178
you find one you like, copy one of the code snippets provided.
@@ -269,19 +248,6 @@ HTML Syntax
269248

270249
``symfony/ux-twig-component`` is required to use the HTML syntax.
271250

272-
HTML Attributes
273-
~~~~~~~~~~~~~~~
274-
275-
The second argument of the ``ux_icon`` function is an array of attributes to add to the icon.
276-
277-
.. code-block:: twig
278-
279-
{# renders "user-profile.svg" with class="w-4 h-4" #}
280-
{{ ux_icon('user-profile', {class: 'w-4 h-4'}) }}
281-
282-
{# renders "user-profile.svg" with class="w-4 h-4" and aria-hidden="true" #}
283-
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-hidden': true}) }}
284-
285251
Default Attributes
286252
~~~~~~~~~~~~~~~~~~
287253

@@ -308,60 +274,39 @@ Now, all icons will have the ``fill`` attribute set to ``currentColor`` by defau
308274
Accessibility
309275
-------------
310276

311-
Icons are a used to add visual elements to your website, but they can be a challenge
312-
for accessibility.
313-
314-
According to the `W3C <https://design-system.w3.org/styles/svg-icons.html>`_, there are
315-
three methods to improve icons accessibility, depending on the context:
316-
317-
* **Decorative**: Icons that are purely decorative and do not convey any meaning or function.
318-
* **Informative**: Icons that convey information or a function.
319-
* **Functional**: Icons that are interactive and perform a function.
320-
321-
Decorative Icons
322-
~~~~~~~~~~~~~~~~
323-
324-
If the icon is purely decorative and does not convey any meaning or function, it should be
325-
hidden from screen readers using the ``aria-hidden`` attribute.
326-
327-
.. code-block:: html+twig
328-
329-
<a href="/profile">
330-
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-hidden': true}) }}
331-
Back to profile
332-
</a>
333-
334-
Informative Icons
335-
~~~~~~~~~~~~~~~~~
336-
337-
If the icon conveys information or a function, it should be given a text alternative that presents
338-
the same content or function, so that it can fulfill the same purpose.
277+
Icons add visual elements to your website and they can be a challenge for accessibility.
278+
According to the `W3C guide about SVG icon accessibility`_, there are
279+
three methods to improve icons accessibility, depending on the context.
339280

340-
.. code-block:: twig
341-
342-
Today's weather:
343-
{{ ux_icon('cloud-rain', {'aria-label': 'Rainy weather'}) }}
281+
**Decorative icons**
282+
They are purely decorative and do not convey any meaning or function. They
283+
should be hidden from screen readers using the ``aria-hidden`` attribute:
344284

345-
Functional Icons
346-
~~~~~~~~~~~~~~~~
285+
.. code-block:: html+twig
347286

348-
If the icon is interactive and performs a function, it should be given a text alternative that
349-
presents the same content or function, so that it can fulfill the same purpose.
350-
351-
.. code-block:: twig
287+
<a href="/profile">
288+
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-hidden': true}) }}
289+
Back to profile
290+
</a>
352291

353-
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-label': 'User Profile'}) }}
292+
**Informative icons**
293+
They convey information or a function. They should define a text alternative
294+
that presents the same content or function via the ``aria-label`` attribute
295+
used by screen readers and other assistive technologies:
354296

355-
.. note::
297+
.. code-block:: twig
356298
357-
The ``aria-label`` attribute is used to provide a label for the icon. It is read by
358-
screen readers and other assistive technologies.
299+
Today's weather:
300+
{{ ux_icon('cloud-rain', {'aria-label': 'Rainy weather'}) }}
359301
360-
.. note::
302+
**Functional icons**
303+
They are interactive and perform a function. They should define a text alternative
304+
that presents the same content or function via the ``aria-label`` attribute
305+
used by screen readers and other assistive technologies:
361306

362-
The ``aria-hidden`` attribute is used to hide the icon from screen readers and other
363-
assistive technologies.
307+
.. code-block:: twig
364308
309+
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-label': 'User Profile'}) }}
365310
366311
Performance
367312
-----------
@@ -382,7 +327,6 @@ in the future. Additionally, the cache warming process will take significantly l
382327
many _on-demand_ icons. You can think of importing the icon as *locking it* (similar to how
383328
``composer.lock`` _locks_ your dependencies).
384329

385-
386330
Icon Caching
387331
~~~~~~~~~~~~
388332

@@ -425,9 +369,9 @@ This command looks in all your Twig templates for ``ux_icon()`` calls and
425369
TwigComponent
426370
~~~~~~~~~~~~~
427371

428-
The ``ux_icon`` function is optimized to be as fast as possible. To deliver the same level
429-
of performance with the TwigComponent (``<twig:UX:Icon name="..." />``), the TwigComponent
430-
usual overhead is reduced to the bare minimum, immediately calling the IconRenderer and
372+
The ``ux_icon()`` function is optimized to be as fast as possible. To deliver the
373+
same level of performance when using the HTML syntax (``<twig:UX:Icon name="..." />``),
374+
the TwigComponent overhead is reduced by calling the IconRenderer immediately and
431375
returning the HTML output.
432376

433377
.. warning::
@@ -444,7 +388,6 @@ returning the HTML output.
444388
<path fill="currentColor" d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/>
445389
</svg>
446390

447-
448391
Configuration
449392
-------------
450393

@@ -457,7 +400,6 @@ the ``ux_icons`` key in your application configuration.
457400
ux_icons:
458401
{# ... #}
459402
460-
461403
Debugging Configuration
462404
~~~~~~~~~~~~~~~~~~~~~~~
463405

@@ -504,3 +446,16 @@ Learn more
504446
.. _`ux.symfony.com/icons`: https://ux.symfony.com/icons
505447
.. _`Iconify`: https://iconify.design
506448
.. _`symfony/asset-mapper`: https://symfony.com/doc/current/frontend/asset_mapper.html
449+
.. _`W3C guide about SVG icon accessibility`: https://design-system.w3.org/styles/svg-icons.html#svg-accessibility
450+
.. _`Bootstrap Icons`: https://icons.getbootstrap.com/
451+
.. _`Boxicons`: https://boxicons.com/
452+
.. _`Flowbite`: https://github.com/themesberg/flowbite
453+
.. _`FontAwesome Icons`: https://github.com/FortAwesome/Font-Awesome
454+
.. _`Heroicons`: https://github.com/tailwindlabs/heroicons
455+
.. _`Iconoir`: https://github.com/iconoir-icons/iconoir
456+
.. _`Ionicons`: https://github.com/ionic-team/ionicons
457+
.. _`Lucide Icons`: https://github.com/lucide-icons/lucide
458+
.. _`Material Design Icons`: https://github.com/google/material-design-icons
459+
.. _`Octicons`: https://github.com/primer/octicons/
460+
.. _`Phosphor Icons`: https://github.com/phosphor-icons/homepage
461+
.. _`Tabler Icons`: https://github.com/tabler/tabler-icons

0 commit comments

Comments
 (0)