Skip to content

Commit 6addeb3

Browse files
kbondkbond
committed
minor #1663 [Doc] UX Icons doc tweaks (javiereguiluz)
This PR was squashed before being merged into the 2.x branch. Discussion ---------- [Doc] UX Icons doc tweaks | Q | A | ------------- | --- | Bug fix? | no | New feature? | no | Issues | - | License | MIT The docs contained some minor issues (understandable because the doc merge produced a ton of hard-to-solve conflicts 🙏 ). I fixed those and made some minor tweaks. Commits ------- 4ef2251 [Doc] UX Icons doc tweaks
2 parents e9faf78 + 4ef2251 commit 6addeb3

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.
@@ -286,19 +265,6 @@ HTML Syntax
286265

287266
``symfony/ux-twig-component`` is required to use the HTML syntax.
288267

289-
HTML Attributes
290-
~~~~~~~~~~~~~~~
291-
292-
The second argument of the ``ux_icon`` function is an array of attributes to add to the icon.
293-
294-
.. code-block:: twig
295-
296-
{# renders "user-profile.svg" with class="w-4 h-4" #}
297-
{{ ux_icon('user-profile', {class: 'w-4 h-4'}) }}
298-
299-
{# renders "user-profile.svg" with class="w-4 h-4" and aria-hidden="true" #}
300-
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-hidden': true}) }}
301-
302268
Default Attributes
303269
~~~~~~~~~~~~~~~~~~
304270

@@ -325,60 +291,39 @@ Now, all icons will have the ``fill`` attribute set to ``currentColor`` by defau
325291
Accessibility
326292
-------------
327293

328-
Icons are a used to add visual elements to your website, but they can be a challenge
329-
for accessibility.
330-
331-
According to the `W3C <https://design-system.w3.org/styles/svg-icons.html>`_, there are
332-
three methods to improve icons accessibility, depending on the context:
333-
334-
* **Decorative**: Icons that are purely decorative and do not convey any meaning or function.
335-
* **Informative**: Icons that convey information or a function.
336-
* **Functional**: Icons that are interactive and perform a function.
337-
338-
Decorative Icons
339-
~~~~~~~~~~~~~~~~
340-
341-
If the icon is purely decorative and does not convey any meaning or function, it should be
342-
hidden from screen readers using the ``aria-hidden`` attribute.
343-
344-
.. code-block:: html+twig
345-
346-
<a href="/profile">
347-
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-hidden': true}) }}
348-
Back to profile
349-
</a>
350-
351-
Informative Icons
352-
~~~~~~~~~~~~~~~~~
353-
354-
If the icon conveys information or a function, it should be given a text alternative that presents
355-
the same content or function, so that it can fulfill the same purpose.
294+
Icons add visual elements to your website and they can be a challenge for accessibility.
295+
According to the `W3C guide about SVG icon accessibility`_, there are
296+
three methods to improve icons accessibility, depending on the context.
356297

357-
.. code-block:: twig
358-
359-
Today's weather:
360-
{{ ux_icon('cloud-rain', {'aria-label': 'Rainy weather'}) }}
298+
**Decorative icons**
299+
They are purely decorative and do not convey any meaning or function. They
300+
should be hidden from screen readers using the ``aria-hidden`` attribute:
361301

362-
Functional Icons
363-
~~~~~~~~~~~~~~~~
302+
.. code-block:: html+twig
364303

365-
If the icon is interactive and performs a function, it should be given a text alternative that
366-
presents the same content or function, so that it can fulfill the same purpose.
367-
368-
.. code-block:: twig
304+
<a href="/profile">
305+
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-hidden': true}) }}
306+
Back to profile
307+
</a>
369308

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

372-
.. note::
314+
.. code-block:: twig
373315
374-
The ``aria-label`` attribute is used to provide a label for the icon. It is read by
375-
screen readers and other assistive technologies.
316+
Today's weather:
317+
{{ ux_icon('cloud-rain', {'aria-label': 'Rainy weather'}) }}
376318
377-
.. note::
319+
**Functional icons**
320+
They are interactive and perform a function. They should define a text alternative
321+
that presents the same content or function via the ``aria-label`` attribute
322+
used by screen readers and other assistive technologies:
378323

379-
The ``aria-hidden`` attribute is used to hide the icon from screen readers and other
380-
assistive technologies.
324+
.. code-block:: twig
381325
326+
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-label': 'User Profile'}) }}
382327
383328
Performance
384329
-----------
@@ -398,7 +343,6 @@ in the future. Additionally, the cache warming process will take significantly l
398343
many _on-demand_ icons. You can think of importing the icon as *locking it* (similar to how
399344
``composer.lock`` _locks_ your dependencies).
400345

401-
402346
Icon Caching
403347
~~~~~~~~~~~~
404348

@@ -441,9 +385,9 @@ This command looks in all your Twig templates for ``ux_icon()`` calls and
441385
TwigComponent
442386
~~~~~~~~~~~~~
443387

444-
The ``ux_icon`` function is optimized to be as fast as possible. To deliver the same level
445-
of performance with the TwigComponent (``<twig:UX:Icon name="..." />``), the TwigComponent
446-
usual overhead is reduced to the bare minimum, immediately calling the IconRenderer and
388+
The ``ux_icon()`` function is optimized to be as fast as possible. To deliver the
389+
same level of performance when using the HTML syntax (``<twig:UX:Icon name="..." />``),
390+
the TwigComponent overhead is reduced by calling the IconRenderer immediately and
447391
returning the HTML output.
448392

449393
.. warning::
@@ -460,7 +404,6 @@ returning the HTML output.
460404
<path fill="currentColor" d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/>
461405
</svg>
462406

463-
464407
Configuration
465408
-------------
466409

@@ -473,7 +416,6 @@ the ``ux_icons`` key in your application configuration.
473416
ux_icons:
474417
{# ... #}
475418
476-
477419
Debugging Configuration
478420
~~~~~~~~~~~~~~~~~~~~~~~
479421

@@ -520,3 +462,16 @@ Learn more
520462
.. _`ux.symfony.com/icons`: https://ux.symfony.com/icons
521463
.. _`Iconify`: https://iconify.design
522464
.. _`symfony/asset-mapper`: https://symfony.com/doc/current/frontend/asset_mapper.html
465+
.. _`W3C guide about SVG icon accessibility`: https://design-system.w3.org/styles/svg-icons.html#svg-accessibility
466+
.. _`Bootstrap Icons`: https://icons.getbootstrap.com/
467+
.. _`Boxicons`: https://boxicons.com/
468+
.. _`Flowbite`: https://github.com/themesberg/flowbite
469+
.. _`FontAwesome Icons`: https://github.com/FortAwesome/Font-Awesome
470+
.. _`Heroicons`: https://github.com/tailwindlabs/heroicons
471+
.. _`Iconoir`: https://github.com/iconoir-icons/iconoir
472+
.. _`Ionicons`: https://github.com/ionic-team/ionicons
473+
.. _`Lucide Icons`: https://github.com/lucide-icons/lucide
474+
.. _`Material Design Icons`: https://github.com/google/material-design-icons
475+
.. _`Octicons`: https://github.com/primer/octicons/
476+
.. _`Phosphor Icons`: https://github.com/phosphor-icons/homepage
477+
.. _`Tabler Icons`: https://github.com/tabler/tabler-icons

0 commit comments

Comments
 (0)