docs(extend): Add Icons page (#2889)

Author: hannahiss

site/assets/scss/_component-examples.scss

@@ -510,13 +510,13 @@
 // scss-docs-start icon-home
 .icon-home::before {
   display: inline-block;
-  width: 2rem;
-  height: 2rem;
+  width: 3rem;
+  height: 3rem;
   vertical-align: bottom;
   content: "";
-  background-color: var(--bs-color-content-default);
+  background-color: currentcolor;
   background-size: contain;
-  mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1000 1000'><path d='M553.478 147.416v.017a74.956 74.956 0 0 0-107.08.13v-.021L100 500h150v300a75 75 0 0 0 75 75h350a75 75 0 0 0 75-75V500h150ZM580 537.52V755H362.5a37.5 37.5 0 0 1-37.5-37.5V500h217.5a37.5 37.5 0 0 1 37.5 37.5v.02Z'/></svg>");
+  mask-image: escape-svg(url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1000 1000'><path d='M553.478 147.416v.017a74.956 74.956 0 0 0-107.08.13v-.021L100 500h150v300a75 75 0 0 0 75 75h350a75 75 0 0 0 75-75V500h150ZM580 537.52V755H362.5a37.5 37.5 0 0 1-37.5-37.5V500h217.5a37.5 37.5 0 0 1 37.5 37.5v.02Z'/></svg>"));
 }
 // scss-docs-end icon-home
 

site/content/docs/0.3/components/buttons.md

@@ -82,6 +82,12 @@ OUDS Web offers a few variations to use on [colored backgrounds]({{< docsref "/u
 
 ## With icon
 
+{{< callout info >}}
+The recommended way of using an icon in a button is through an [SVG sprite file]({{< docsref "/extend/icons/#svg-sprite" >}}). You need to fill it using `currentColor` to respect the button color scheme (can be set directly inside the SVG sprite).
+
+When icons are purely decorative, they should be hidden from assistive technologies using `aria-hidden="true"`, as we've done in our text and icon examples. For icon only, we chose to keep the icon hidden from assistive technologies and add a visually hidden label. See [icons accessibility]({{< docsref "/extend/icons/#icons-accessibility" >}}) for more info.
+{{< /callout >}}
+
 ### Text and icon
 
 The recommended way of using an icon in a button is an embedded SVG<!-- ({{< docsref "/extend/icons" >}}) -->. You need to fill it using `currentColor` to respect button color scheme (which can be done inside the SVG sprite file).

site/content/docs/0.3/components/links.md

@@ -60,18 +60,16 @@ Add `.link-chevron` to enhance your link with a chevron on the right side. Use t
 
 ## Icon link
 
-The `.icon-link` class modifies the default link styles to enhance their appearance and quickly align any pairing of icon and text. Alignment is set via inline flexbox styling and a default `gap` value. We style the underline with a custom offset and color. Icons are automatically sized to `1em` to best match their associated text's `font-size`.
-
 {{< callout info >}}
-Inside links, you should use Solaris icons, either in an SVG sprite (`<symbol>` element in an SVG file), which is the recommended method, or in an icon font. You can generate both with [Solaris Icons Finder](https://oran.ge/icons).
-
-We strongly advise against using an `<img>` or other techniques, especially because the icon will not benefit from dynamic color changes across states (hover, focus, active) and the color mode system will not work.
+The recommended way of using an icon in a link is through an [SVG sprite file]({{< docsref "/extend/icons/#svg-sprite" >}}). You need to fill it using `currentColor` to respect the link color scheme (can be set directly inside the SVG sprite).
 {{< /callout >}}
 
+The `.icon-link` class modifies the default link styles to enhance their appearance and quickly align any pairing of icon and text. Alignment is set via inline flexbox styling and a default `gap` value. We style the underline with a custom offset and color. Icons are automatically sized to `1em` to best match their associated text's `font-size`.
+
 If really needed, you can use a font icon associated to the `.icon` class to set correct parameters for the `font-size` and `line-height`.
 
 {{< callout >}}
-When icons are purely decorative, they should be hidden from assistive technologies using `aria-hidden="true"`, as we've done in our examples. For icons that convey meaning, provide an appropriate text alternative by adding `role="img"` and an appropriate `aria-label="..."` to the SVGs, or a `.visually-hidden` text for a font icon.
+When icons are purely decorative, they should be hidden from assistive technologies using `aria-hidden="true"`, as we've done in our links examples. See [icons accessibility]({{< docsref "/extend/icons/#icons-accessibility" >}}) for more info.
 {{< /callout >}}
 
 Take a regular `<a>` element, add `.icon-link`, and insert an icon on the left of your link text. The icon is automatically sized, placed, and colored.

site/content/docs/0.3/content/typography.md

@@ -76,7 +76,7 @@ All HTML headings, `<h1>` through `<h6>`, are available. Each class sets `font-s
 <p class="h6">h6. OUDS Web heading</p>
 {{< /example >}}
 
-You can easily add an icon with your font reference using [our icon helper]({{< docsref "/helpers/icon" >}}).
+You can easily add an icon with your font reference using [our icon size utilities]({{< docsref "/extend/icons#icons-size" >}}).
 
 <!-- OUDS mod: No customizing heading -->
 
@@ -182,7 +182,7 @@ Body medium is set by default on `:root` children but we don't set the `max-widt
 
 </details>
 
-You can easily add an icon with your font reference using [our icon helper]({{< docsref "/helpers/icon" >}}).
+You can easily add an icon with your font reference using [our icon size utilities]({{< docsref "/extend/icons#icons-size" >}}).
 
 ### Lead
 

site/content/docs/0.3/examples/grid-system/index.html

@@ -7,16 +7,6 @@
 - "/examples/grid-system"
 - "/docs/examples/grid-system"
 ---
-<svg xmlns="http://www.w3.org/2000/svg" class="d-none">
-  <symbol fill="currentColor" viewBox="0 0 1000 1000" id="warning-important-accessible">
-    <path d="M499.352 125a93.95 93.95 0 0 1 81.072 46.494L908.91 733.919A93.676 93.676 0 0 1 827.838 874.9H170.867A93.711 93.711 0 0 1 89.8 733.919l.8-1.3v-.1l327.681-561.025A93.83 93.83 0 0 1 499.352 125"/>
-    <path fill="#000" d="M500.352 679.926a47.494 47.494 0 1 0 47.484 47.494 47.53 47.53 0 0 0-47.484-47.494m0-379.949a47.53 47.53 0 0 0-47.483 47.493 28 28 0 0 0 .1 2.9l15.694 258.665v.5c.3 17.1 14.395 23.5 31.689 23.5 17.494 0 31.689-6.6 31.689-24l15.695-258.065.1-.9a23 23 0 0 0 .1-2.6 47.68 47.68 0 0 0-47.583-47.493"/>
-  </symbol>
-  <symbol fill="currentColor" viewBox="0 0 1000 1000" id="info">
-    <path d="M500 75.5c-234.72 0-425 190.28-425 425s190.28 425 425 425 425-190.28 425-425-190.28-425-425-425m0 100a75 75 0 1 1-75 75 75 75 0 0 1 75-75m125 600H400v-25.737l5.287-.167c15.555-.5 27.115-4.919 34.368-13.136 2.576-2.972 6.956-13.1 6.956-47.153v-227.2c0-32.392-4.523-44.6-8.311-49.141-5.359-6.391-16.516-10.147-33.17-11.156l-5.13-.31v-26h175v313.807c0 32.415 8.457 44.618 12.24 49.142 5.34 6.389 15.68 10.142 32.625 11.152l5.135.3v25.6Z" style="fill-rule: evenodd"/>
-  </symbol>
-</svg>
-
 <main class="min-vh-100">
   <div class="container-fluid container-max-width pt-tallest">
     <h1>OUDS Web grid system example</h1>