+ );
+};
diff --git a/packages/documentation-site/patternfly-docs/content/content-design/writing-guides/tooltips.md b/packages/documentation-site/patternfly-docs/content/content-design/writing-guides/tooltips.md
index 20a44b482d..fdf38bd037 100644
--- a/packages/documentation-site/patternfly-docs/content/content-design/writing-guides/tooltips.md
+++ b/packages/documentation-site/patternfly-docs/content/content-design/writing-guides/tooltips.md
@@ -4,28 +4,22 @@ section: content-design
subsection: writing-guides
---
-import ArrowCircleUpIcon from '@patternfly/react-icons/dist/esm/icons/arrow-circle-up-icon';
-import BellIcon from '@patternfly/react-icons/dist/esm/icons/bell-icon';
-import CogIcon from '@patternfly/react-icons/dist/esm/icons/cog-icon';
-import CopyIcon from '@patternfly/react-icons/dist/esm/icons/copy-icon';
-import DownloadIcon from '@patternfly/react-icons/dist/esm/icons/download-icon';
-import EllipsisVIcon from '@patternfly/react-icons/dist/esm/icons/ellipsis-v-icon';
-import PencilAltIcon from '@patternfly/react-icons/dist/esm/icons/pencil-alt-icon';
-import SearchIcon from '@patternfly/react-icons/dist/esm/icons/search-icon';
-import SearchMinusIcon from '@patternfly/react-icons/dist/esm/icons/search-minus-icon';
-import SearchPlusIcon from '@patternfly/react-icons/dist/esm/icons/search-plus-icon';
-import SyncAltIcon from '@patternfly/react-icons/dist/esm/icons/sync-alt-icon';
-import TrashIcon from '@patternfly/react-icons/dist/esm/icons/trash-icon';
-import ExportIcon from '@patternfly/react-icons/dist/esm/icons/export-icon';
-import TaskIcon from '@patternfly/react-icons/dist/esm/icons/task-icon';
-import QuestionCircleIcon from '@patternfly/react-icons/dist/esm/icons/question-circle-icon';
-import { Button, Icon, Tooltip, Split, SplitItem } from '@patternfly/react-core'
+import RhUiSettingsIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-settings-icon';
+import RhUiCopyIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-copy-icon';
+import RhUiSearchIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-search-icon';
+import RhUiQuestionMarkCircleIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-question-mark-circle-icon';
+import { Button, Tooltip, Split, SplitItem } from '@patternfly/react-core'
+import { TooltipIconReferenceTable } from './TooltipIconReferenceTable.jsx';
A **tooltip** is a message box that is shown when a UI element, like a button or an icon, is in a hover state. They contain short descriptions that offer additional information to help users better understand elements within a UI.
+
+
+
+
When writing tooltips, follow these general recommendations:
@@ -36,7 +30,7 @@ When writing tooltips, follow these general recommendations:
| Don't repeat information that is already available in the UI. | Do write content that is succinct, clear, and effective. |
| Don't use tooltips for critical information. | Do use tooltips for additional, non-essential information. |
| Don't end sentence fragments in a period. | Do end full sentences in a period. |
-| Don’t place tooltips on question-circle icons (). Instead, use a [popover](/components/popover). | Do follow [our tooltip development accessibility guidelines](/components/tooltip/accessibility) to ensure that tooltip content is available to all users.|
+| Don’t place tooltips on question-mark icons (). Instead, use a [popover](/components/popover). | Do follow [our tooltip development accessibility guidelines](/components/tooltip/accessibility) to ensure that tooltip content is available to all users.|
@@ -51,33 +45,18 @@ For example:
-
+
-
+
-
+
In PatternFly, there are commonly used icons that hold universal meanings. These should always use the same tooltip description, as shown in the following table:
-|**Icon** | **Name** | **Tooltip content** | **Note** |
-|------------|-----------|-----------|---- |
-| | fa-arrow-circle-up | Upgrade |
-| | fa-bell | Notifications |
-| | fa-cog | Settings |
-| | fa-copy | Copy |
-| | fa-download | Download |
-| | fa-ellipsis-v | More options |
-| | fa-pencil-alt | Edit |
-| | fa-search | Search |
-| | fa-search-minus | Search minus |
-| | fa-search-plus | Search plus |
-| | fa-sync-alt | Sync, Refresh, or Running | Choose the best fit for your scenario.|
-| | fa-trash | Delete |
-| | pficon-export | Export |
-| | pficon-task | Tasks |
+
You can learn more about the usage of these icons in our [design foundations.](/foundations-and-styles/iconography)
diff --git a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md
index 3e8166baf5..8e851991ba 100644
--- a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md
+++ b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md
@@ -2,7 +2,7 @@
id: Iconography
section: foundations-and-styles
---
-import { Icon, Content, ContentVariants } from '@patternfly/react-core';
+import { Icon, Content, ContentVariants, Alert } from '@patternfly/react-core';
import RhUiCheckCircleFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-check-circle-fill-icon';
import RhUiErrorFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-error-fill-icon';
import RhUiWarningFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-warning-fill-icon';
@@ -11,22 +11,34 @@ import RhUiNotificationFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-
import RhUiStarIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-star-icon';
import { IconsTable } from './IconsTable.jsx';
import './icons.css';
+import '../../../components/components.css';
-If you're a developer, check out our [development onboarding guide](/get-started/develop#using-icons) to learn how to install and use our icon set.
+We use Red Hat brand UI icons (`rh-ui-*`) in PatternFly, which are delivered via the [`@patternfly/react-icons` package](https://www.npmjs.com/package/@patternfly/react-icons) and the [icon component](/components/icon). The [all icons](#all-icons) table at the end of this page lists the icons commonly used in PatternFly, including their usage details.
-For React and HTML implementation examples, [refer to the icon component pages.](/components/icon)
+The [iconography documentation of the Red Hat Design System (RHDS)](https://ux.redhat.com/foundations/iconography/) outlines the full Red Hat icon catalog, including:
+- UI icons (the same set we use, plus more variants)
+- A large set of standard icons (more general, illustrative, and typically less appropriate for product UIs)
+- Microns (smaller, compact icons)
+- Social icons
-## Icon sizes
+In general, rely on the all-icons table on this page and supplement your needs with the RHDS catalog if needed. If there's no icon for your use case, [submit a new icon request](https://docs.google.com/forms/d/e/1FAIpQLSde61rTDD4keaZEA3JFzBPbQVJ5EgEkhNapsYoI6ajKCsX4_Q/viewform) to the Brand team.
-Icon size tokens use rems, rather than pixels. Rems are relative units that adjust font size based on a webpage's HTML document root element size. For example, if the root size is 10px, a rem size of 1.5 would be 15px.
-
-PatternFly's default root element size is 16px. If you change this default size, note that the following tables will no longer show accurate pixel measurements (though the rem values will stay the same).
+
+
+ To automatically migrate your Font Awesome and PatternFly icons to their respective Red Hat UI icons, you can use the
+ pfToRhIcons.mjs script. While you can still use Font Awesome or legacy PatternFly icons manually if necessary, they are no longer our recommended approach and should be replaced with Red Hat icons going forward.
+
+
## Inline icons
+Rather than pixels, icons are sized in rems, which are relative to your page’s root font size. For example, if the root size is 10px, a rem size of 1.5 is 15px. PatternFly’s default root is 16px. If you change the root, the following tables’ size values will only be accurate in rems.
+
[Inline icons](/components/icon#inline) must be center-aligned horizontally when placed next to text and center-aligned vertically when stacked.
+
Use the following semantic tokens to ensure that icons are properly aligned and match the correct font size:
@@ -34,24 +46,24 @@ Use the following semantic tokens to ensure that icons are properly aligned and
| **Size** | **Token** | **Example** |
| --- | --- | :---: |
-| 1.375rem (22px) | `pf-t--global--icon--size--font--heading--h1` | Heading |
-| 1.25rem (20px) | `pf-t--global--icon--size--font--heading--h2` | Heading |
-| 1.125rem (18px) | `pf-t--global--icon--size--font--heading--h3` | Heading |
-| 1rem (16px) | `pf-t--global--icon--size--font--heading--h4` | Heading |
-| 1rem (16px) | `pf-t--global--icon--size--font--heading--h5` | Heading |
-| 1rem (16px) | `pf-t--global--icon--size--font--heading--h6` | Heading |
+| 1.375rem (22px) | `--pf-t--global--icon--size--font--heading--h1` | Heading |
+| 1.25rem (20px) | `--pf-t--global--icon--size--font--heading--h2` | Heading |
+| 1.125rem (18px) | `--pf-t--global--icon--size--font--heading--h3` | Heading |
+| 1rem (16px) | `--pf-t--global--icon--size--font--heading--h4` | Heading |
+| 1rem (16px) | `--pf-t--global--icon--size--font--heading--h5` | Heading |
+| 1rem (16px) | `--pf-t--global--icon--size--font--heading--h6` | Heading |
### Body text
| **Size** | **Token** | **Example** |
| --- | --- | :---: |
-| 0.75rem (12px) | `pf-t--global--icon--size--font--body--sm` | Small body |
-| 0.875rem (14px) | `pf-t--global--icon--size--font--body--default` | Default body
-| 1rem (16px) | `pf-t--global--icon--size--font--body--lg` | Large body
+| 0.75rem (12px) | `--pf-t--global--icon--size--font--body--sm` | Small body |
+| 0.875rem (14px) | `--pf-t--global--icon--size--font--body--default` | Default body
+| 1rem (16px) | `--pf-t--global--icon--size--font--body--lg` | Large body
## Standalone icons
-Occasionally, you may need to use a standalone icon that isn't aligned with any kind of text. PatternFly supports a range of icon sizes that can adapt to these use cases, including small, medium, large, x-large, 2xl, and 3xl icons. These sizes correspond to the following font sizes and tokens:
+Occasionally, you may need to use a standalone icon that isn't aligned with any kind of text. We support a range of icon sizes for these use cases, including small, medium, large, x-large, 2xl, and 3xl icons. These sizes correspond to the following font sizes and tokens:
| **Size** | **Token** | **Example** |
| --- | --- | :---: |
@@ -62,10 +74,10 @@ Occasionally, you may need to use a standalone icon that isn't aligned with any
| 2xl (3.5rem, 56px) | `--pf-t--global--icon--size--2xl` | |
| 3xl (6rem, 96px) | `--pf-t--global--icon--size--3xl` | |
-Medium icons are typically the most versatile size to use in a UI. Most icons in PatternFly components are medium; other sizes are used sparingly.
+Most standalone icons in PatternFly components are medium, since that is typically the most versatile size for a UI—other sizes are used sparingly.
## Icon colors
-All icon colors that you use should align with the proper [semantic design token.](/foundations-and-styles/design-tokens/all-design-tokens) For example, a warning icon should use our approved warning color, a danger icon should use our approved danger color, and so on.
+All icon colors that you use should align with the proper [semantic design token.](/foundations-and-styles/design-tokens/all-design-tokens) For example, a warning icon should use our approved warning color token, a danger icon should use our approved danger color token, and so on.
| **Icon state** | **Color token** | **Example** |
| --- | --- | :---: |
@@ -77,26 +89,21 @@ All icon colors that you use should align with the proper [semantic design token
To learn more about icon colors and color tokens, visit our [colors page.](/foundations-and-styles/colors)
-## PatternFly icons
-We use Red Hat brand UI icons (`rh-ui-*`), delivered through `@patternfly/react-icons` and the [icon component](/components/icon). The following table lists the icons we document for use in PatternFly UIs.
-
-Use the [React Icon component](/components/icon) with imports from `@patternfly/react-icons`, or inline SVG from your product’s PatternFly assets. For setup details, see the [development onboarding guide](/get-started/develop#using-icons).
-
-### React icons
-Import icons from our [react-icons package](https://www.npmjs.com/package/@patternfly/react-icons):
+## Using icons in development
-`import { [insert-icon-name] } from '@patternfly/react-icons/dist/esm/icons/[insert-hyphenated-icon-name]';`
+Developers should first refer to our [development onboarding guide](/get-started/develop#using-icons) to install, import, and use icons within your product. For React and HTML examples, [refer to the icon component.](/components/icon)
-For example:
+### React imports
+Once installed, you can import individual icons from the [react-icons package](https://www.npmjs.com/package/@patternfly/react-icons). For example
`import RhUiStarIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-star-icon';`
## All icons
-The following table lists Red Hat UI icons with usage guidance for PatternFly.
+The table lists Red Hat UI icons with usage guidance for PatternFly. For the full catalog of Red Hat icons (UI, standard, microns, and social), refer to [the RDHS iconography guidelines](https://ux.redhat.com/foundations/iconography/).
-For guidance related to icon tooltips, [refer to our tooltips writing guide.](/content-design/writing-guides/tooltips#icon-tooltips)
+For guidance on icon tooltips, [refer to our tooltips writing guide.](/content-design/writing-guides/tooltips#icon-tooltips)
-Select any single icon in the table to download it as an SVG.
+Click an icon to download it as an SVG, or click the React name to copy the icon's name for use in React.
-
+
\ No newline at end of file
diff --git a/packages/documentation-site/patternfly-docs/content/get-started/develop.md b/packages/documentation-site/patternfly-docs/content/get-started/develop.md
index 14f69b5e67..370ce4ff36 100644
--- a/packages/documentation-site/patternfly-docs/content/get-started/develop.md
+++ b/packages/documentation-site/patternfly-docs/content/get-started/develop.md
@@ -74,6 +74,16 @@ If you wish to migrate an existing project to PatternFly you must install and co
yarn add @patternfly/react-core
```
+## Using icons
+
+PatternFly utilizes [Red Hat UI icons](https://www.redhat.com/en/about/brand/standards/icons) (`rh-ui-*`), which are available in the [`@patternfly/react-icons` package](https://www.npmjs.com/package/@patternfly/react-icons). Refer to the [icon component](/components/icon) and guidance on the [iconography](/foundations-and-styles/iconography) foundations page for more implementation guidance.
+
+### Migrating to Red Hat icons
+
+We offer a script to help you migrate from previous React icon component names to Red Hat UI icons: [`pfToRhIcons.mjs`](https://github.com/patternfly/patternfly-react/blob/main/packages/react-icons/scripts/icons/pfToRhIcons.mjs). This script allows you to automatically migrate icons across your product, based on a best-guess mapping. Note that it will not catch every icon that can be updated, so you might need to manually check its work and make additional changes.
+
+While you can still use the previous Font Awesome (`fa`, `fas`, `far`, and similar) or PatternFly (`pf`) icons if your product already relies on them, they are not the recommended path for new work.
+
## Develop with HTML/CSS
The PatternFly HTML/CSS library contains a collection of code samples that you can use to build interfaces with consistent PatternFly markup and styling.
@@ -117,7 +127,9 @@ Use these files to consume the library. The recommended consumption approach wil
### Using icons
-PatternFly uses [Font Awesome 5](https://fontawesome.com/), which can be utilized in 2 different ways:
+For the recommended Red Hat icon approach (including React), see ["Using icons"](#using-icons) at the start of this page. The following describes using our previously recommended Font Awesome icons in the HTML/CSS bundle, which you may still rely on for legacy markup.
+
+[Font Awesome 5](https://fontawesome.com/) can be utilized in 2 different ways:
* **Built into PatternFly:** By default, Font Awesome is included as part of the PatternFly CSS file. You do not need to do anything else to use this icon font family.
diff --git a/packages/documentation-site/patternfly-docs/content/patterns/status-and-severity/status-and-severity.md b/packages/documentation-site/patternfly-docs/content/patterns/status-and-severity/status-and-severity.md
index 1004719a13..0a897e4a05 100644
--- a/packages/documentation-site/patternfly-docs/content/patterns/status-and-severity/status-and-severity.md
+++ b/packages/documentation-site/patternfly-docs/content/patterns/status-and-severity/status-and-severity.md
@@ -4,19 +4,17 @@ section: patterns
---
import { Button, Icon, Content, ContentVariants } from '@patternfly/react-core';
import './status-and-severity.css';
-import SeverityCriticalIcon from '@patternfly/react-icons/dist/esm/icons/severity-critical-icon';
-import SeverityImportantIcon from '@patternfly/react-icons/dist/esm/icons/severity-important-icon';
-import SeverityMinorIcon from '@patternfly/react-icons/dist/esm/icons/severity-minor-icon';
-import SeverityModerateIcon from '@patternfly/react-icons/dist/esm/icons/severity-moderate-icon';
-import SeverityNoneIcon from '@patternfly/react-icons/dist/esm/icons/severity-none-icon';
-import SeverityUndefinedIcon from '@patternfly/react-icons/dist/esm/icons/severity-undefined-icon';
-import CheckCircleIcon from '@patternfly/react-icons/dist/esm/icons/check-circle-icon';
-import ExclamationCircleIcon from '@patternfly/react-icons/dist/esm/icons/exclamation-circle-icon';
-import ExclamationTriangleIcon from '@patternfly/react-icons/dist/esm/icons/exclamation-triangle-icon';
-import InfoCircleIcon from '@patternfly/react-icons/dist/esm/icons/info-circle-icon';
-import BellIcon from '@patternfly/react-icons/dist/esm/icons/bell-icon';
-import StarIcon from '@patternfly/react-icons/dist/esm/icons/star-icon';
-import ArrowRightIcon from '@patternfly/react-icons/dist/esm/icons/arrow-right-icon';
+import RhUiSeverityCriticalFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-severity-critical-fill-icon';
+import RhUiSeverityImportantFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-severity-important-fill-icon';
+import RhUiSeverityMinorFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-severity-minor-fill-icon';
+import RhUiSeverityModerateFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-severity-moderate-fill-icon';
+import RhUiSeverityNoneFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-severity-none-fill-icon';
+import RhUiSeverityUndefinedFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-severity-undefined-fill-icon';
+import RhUiCheckCircleFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-check-circle-fill-icon';
+import RhUiErrorFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-error-fill-icon';
+import RhUiWarningFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-warning-fill-icon';
+import RhUiInformationFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-information-fill-icon';
+import RhUiNotificationFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-notification-fill-icon';
# Communicating status versus severity
@@ -44,11 +42,11 @@ The following table outlines the proper combination of status type, icon, and co
| **Status** | **Icon** | **Color token** | **Usage** |
| --- | --- | :---: | --- |
-| Danger | |`--pf-t--global--icon--color--status--danger--default` | Use when a major error or blocking error has occurred. |
-| Warning | | `--pf-t--global--icon--color--status--warning--default` | Use when a non-critical error has occurred. |
-| Success | | `--pf-t--global--icon--color--status--success--default` | Use when a task or process has completed without error.|
-| Info | | `--pf-t--global--icon--color--status--info--default` | Use for general, informational messages. |
-| Custom | |`--pf-t--global--icon--color--status--custom--default` | Use for generic messages, with no associated severity. Allows you to use custom colors.|
+| Danger | |`--pf-t--global--icon--color--status--danger--default` | Use when a major error or blocking error has occurred. |
+| Warning | | `--pf-t--global--icon--color--status--warning--default` | Use when a non-critical error has occurred. |
+| Success | | `--pf-t--global--icon--color--status--success--default` | Use when a task or process has completed without error.|
+| Info | | `--pf-t--global--icon--color--status--info--default` | Use for general, informational messages. |
+| Custom | |`--pf-t--global--icon--color--status--custom--default` | Use for generic messages, with no associated severity. Allows you to use custom colors.|
### Usage
@@ -65,14 +63,14 @@ When there is an issue or incident related to a source of data, it is important
These icons utilize color and visual weight to reflect the sense of severity that the icon is communicating. As the icons progress from less severe to more severe, the visual weight shifts and the color becomes more attention-grabbing.
-| **Severity level** |
| `--pf-t--global--icon--color--severity--critical--default`| Reserve for the highest severity issues. |
-| Important |
| `--pf-t--global--icon--color--severity--important--default` | Use for high-threat issues. |
-| Moderate |
| `--pf-t--global--icon--color--severity--moderate--default`| Use for moderate-threat issues. |
-| Minor |
| `--pf-t--global--icon--color--severity--minor--default`| Use for low-threat issues. |
-| None |
| `--pf-t--global--icon--color--severity--none--default` | Use when there is no security threat. |
-| Undefined |
| `--pf-t--global--icon--color--severity--undefined--default` | Use if a severity level has not been determined yet, but is expected to change and be defined later. |
+| **Severity level** |
| rh-ui-severity-critical-fill | RhUiSeverityCriticalFillIcon | `--pf-t--global--icon--color--severity--critical--default`| Reserve for the highest severity issues. |
+| Important |
| rh-ui-severity-important-fill | RhUiSeverityImportantFillIcon | `--pf-t--global--icon--color--severity--important--default` | Use for high-threat issues. |
+| Moderate |
| rh-ui-severity-moderate-fill | RhUiSeverityModerateFillIcon | `--pf-t--global--icon--color--severity--moderate--default`| Use for moderate-threat issues. |
+| Minor |
| rh-ui-severity-minor-fill | RhUiSeverityMinorFillIcon | `--pf-t--global--icon--color--severity--minor--default`| Use for low-threat issues. |
+| None |
| rh-ui-severity-none-fill | RhUiSeverityNoneFillIcon | `--pf-t--global--icon--color--severity--none--default` | Use when there is no security threat. |
+| Undefined |
| rh-ui-severity-undefined-fill | RhUiSeverityUndefinedFillIcon | `--pf-t--global--icon--color--severity--undefined--default` | Use if a severity level has not been determined yet, but is expected to change and be defined later. |
### Usage
@@ -95,10 +93,10 @@ Due to varying use cases, you can use anywhere between 3 to 6 icons to communica
| **Scale** | **Levels** | **Icons** |
| --- | --- | --- |
-| 6-point scale | Critical, important, moderate, minor, none, undefined | |
-| 5-point scale | Critical, important, moderate, minor, none or undefined (choose 1) | or |
-| 4-point scale | Critical, important, moderate, minor | |
-| 3-point scale | Critical, moderate, minor | |
+| 6-point scale | Critical, important, moderate, minor, none, undefined | |
+| 5-point scale | Critical, important, moderate, minor, none or undefined (choose 1) | or |
+| 4-point scale | Critical, important, moderate, minor | |
+| 3-point scale | Critical, moderate, minor | |
These groups of severity icons are especially useful in data displays, like tables and cards.
From 8f16fef70dd2e2ccd153cf113cd58aad14997c74 Mon Sep 17 00:00:00 2001
From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com>
Date: Fri, 1 May 2026 11:00:16 -0400
Subject: [PATCH 3/4] Update icons in image
---
.../styles/iconography/icon-alignment.svg | 22 +++++++++----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/icon-alignment.svg b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/icon-alignment.svg
index 39395f2787..d30d997431 100644
--- a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/icon-alignment.svg
+++ b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/icon-alignment.svg
@@ -1,27 +1,27 @@
From b86939a4de8d70a14a91571ce6cc5f7ffe8d9e3b Mon Sep 17 00:00:00 2001
From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com>
Date: Mon, 4 May 2026 14:25:09 -0400
Subject: [PATCH 4/4] Update migration guidance.
---
.../styles/iconography/iconography.md | 13 ++++++-------
.../patternfly-docs/content/get-started/develop.md | 8 +-------
2 files changed, 7 insertions(+), 14 deletions(-)
diff --git a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md
index 8e851991ba..3383e3fb42 100644
--- a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md
+++ b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/iconography/iconography.md
@@ -2,7 +2,7 @@
id: Iconography
section: foundations-and-styles
---
-import { Icon, Content, ContentVariants, Alert } from '@patternfly/react-core';
+import { Icon, Content, ContentVariants } from '@patternfly/react-core';
import RhUiCheckCircleFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-check-circle-fill-icon';
import RhUiErrorFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-error-fill-icon';
import RhUiWarningFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-warning-fill-icon';
@@ -23,12 +23,11 @@ The [iconography documentation of the Red Hat Design System (RHDS)](https://ux.r
In general, rely on the all-icons table on this page and supplement your needs with the RHDS catalog if needed. If there's no icon for your use case, [submit a new icon request](https://docs.google.com/forms/d/e/1FAIpQLSde61rTDD4keaZEA3JFzBPbQVJ5EgEkhNapsYoI6ajKCsX4_Q/viewform) to the Brand team.
-
-
- To automatically migrate your Font Awesome and PatternFly icons to their respective Red Hat UI icons, you can use the
- pfToRhIcons.mjs script. While you can still use Font Awesome or legacy PatternFly icons manually if necessary, they are no longer our recommended approach and should be replaced with Red Hat icons going forward.
-
-
+## Migrating to Red Hat icons
+
+To migrate from our previous Font Awesome and PatternFly icon sets without having to manually update every import, apply the `pf-v6-icon-set-rh-ui` class on an outer element (typically the `` element). PatternFly uses the mapping in [`pfToRhIcons.mjs`](https://github.com/patternfly/patternfly-react/blob/main/packages/react-icons/scripts/icons/pfToRhIcons.mjs) to decide which legacy icons render as Red Hat UI icons. Not every legacy icon is mapped, so some might still require direct updates. This class also only points to the UI Red Hat icon set, not [microns](https://ux.redhat.com/foundations/iconography/#micron-icons) or [standard icons](https://ux.redhat.com/foundations/iconography/#standard-icons), which you might prefer for some scenarios.
+
+While you can still use the previous Font Awesome (`fa`, `fas`, `far`, and similar) or PatternFly (`pf`) icons if your product already relies on them, they are not the recommended path for new work.
## Inline icons
diff --git a/packages/documentation-site/patternfly-docs/content/get-started/develop.md b/packages/documentation-site/patternfly-docs/content/get-started/develop.md
index 370ce4ff36..ec80c35a47 100644
--- a/packages/documentation-site/patternfly-docs/content/get-started/develop.md
+++ b/packages/documentation-site/patternfly-docs/content/get-started/develop.md
@@ -76,13 +76,7 @@ If you wish to migrate an existing project to PatternFly you must install and co
## Using icons
-PatternFly utilizes [Red Hat UI icons](https://www.redhat.com/en/about/brand/standards/icons) (`rh-ui-*`), which are available in the [`@patternfly/react-icons` package](https://www.npmjs.com/package/@patternfly/react-icons). Refer to the [icon component](/components/icon) and guidance on the [iconography](/foundations-and-styles/iconography) foundations page for more implementation guidance.
-
-### Migrating to Red Hat icons
-
-We offer a script to help you migrate from previous React icon component names to Red Hat UI icons: [`pfToRhIcons.mjs`](https://github.com/patternfly/patternfly-react/blob/main/packages/react-icons/scripts/icons/pfToRhIcons.mjs). This script allows you to automatically migrate icons across your product, based on a best-guess mapping. Note that it will not catch every icon that can be updated, so you might need to manually check its work and make additional changes.
-
-While you can still use the previous Font Awesome (`fa`, `fas`, `far`, and similar) or PatternFly (`pf`) icons if your product already relies on them, they are not the recommended path for new work.
+PatternFly utilizes [Red Hat UI icons](https://www.redhat.com/en/about/brand/standards/icons) (`rh-ui-*`), which are available in the [`@patternfly/react-icons` package](https://www.npmjs.com/package/@patternfly/react-icons). Refer to the [icon component](/components/icon) and the [iconography](/foundations-and-styles/iconography) foundations page for implementation and usage guidance.
## Develop with HTML/CSS