docs(icon): add font icon and custom svg documentation

cspell-wordlist.txt

@@ -38,6 +38,8 @@ comparewith
 composables
 engageable
 flexbox
+fontawesome
+fortawesome
 frontmatter
 fullscreen
 geolocation
@@ -59,13 +61,15 @@ preconfigured
 preflighted
 proxying
 quickstart
+remixicon
 retargeted
 runtimes
 scroller
 subcomponent
 subcomponents
 subpath
 subpaths
+svgs
 swipeable
 templating
 transpiling

docs/api/icon.md

@@ -10,36 +10,70 @@ title: 'ion-icon'
   />
 </head>
 
-Icon is a simple component made available through the <a href="https://ionic.io/ionicons">Ionicons</a> library, which comes pre-packaged by default with all Ionic Framework applications. It can be used to display any icon from the Ionicons set, or a custom SVG. It also has support for styling such as size and color.
+Icon is a universal container for displaying icons. While <a href="https://ionic.io/ionicons">Ionicons</a> is included by default with all Ionic Framework applications, the component can display Ionicons, custom SVGs, font-based icon libraries, and other icon systems. It provides consistent styling and sizing regardless of where an icon comes from.
 
-For a list of all available icons, see <a href="https://ionic.io/ionicons">ionic.io/ionicons</a>. For more information including styling and custom SVG usage, see <a href="https://ionic.io/ionicons/usage">the Usage page</a>.
+For Ionicons documentation, refer to <a href="https://ionic.io/ionicons">ionic.io/ionicons</a>.
 
 ## Basic Usage
 
 import Basic from '@site/static/usage/v9/icon/basic/index.md';
 
 <Basic />
 
+## Font Icons
+
+Font-based icons from libraries such as Font Awesome, Bootstrap Icons, Remix Icons, and Phosphor Icons can be displayed by slotting them into Icon.
+
+import FontIcons from '@site/static/usage/v9/icon/font-icons/index.md';
+
+<FontIcons />
+
+## Custom SVGs
+
+Custom SVGs can be displayed with Icon in two ways: by loading an external SVG file using the `src` property or by slotting SVG content directly into the component.
+
+import CustomSVGs from '@site/static/usage/v9/icon/custom-svgs/index.md';
+
+<CustomSVGs />
 
 ## Accessibility
 
 Icons that are purely decorative content should have <code>aria-hidden="true"</code>. This will not visually hide the icon, but it will hide the element from assistive technology.
 
 ```html
+<!-- Ionicon -->
 <ion-icon name="heart" aria-hidden="true"></ion-icon>
-```
 
+<!-- Font-based icon -->
+<ion-icon aria-hidden="true">
+  <i class="fas fa-heart"></i>
+</ion-icon>
+```
 
 If the icon is interactive, it should have alternate text defined by adding an <code>aria-label</code>.
 
 ```html
+<!-- Ionicon -->
 <ion-icon name="heart" aria-label="Favorite"></ion-icon>
+
+<!-- Font-based icon -->
+<ion-icon aria-label="Favorite">
+  <i class="fas fa-heart"></i>
+</ion-icon>
 ```
 
 Alternatively, if the icon is inside of another element that it is describing, that element should have the <code>aria-label</code> added to it, and the icon should be hidden using <code>aria-hidden</code>.
 
 ```html
+<!-- Ionicon -->
 <ion-button aria-label="Favorite">
   <ion-icon name="heart" aria-hidden="true"></ion-icon>
 </ion-button>
+
+<!-- Font-based icon -->
+<ion-button aria-label="Favorite">
+  <ion-icon aria-hidden="true">
+    <i class="fas fa-heart"></i>
+  </ion-icon>
+</ion-button>
 ```