diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icon-alignment.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icon-alignment.png new file mode 100644 index 0000000000..38b9090976 Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icon-alignment.png differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icon_alignment.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icon_alignment.png deleted file mode 100644 index 9a8459f076..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icon_alignment.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icons.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icons.md index 4f4757da0a..b4ef85b951 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icons.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/icons/icons.md @@ -2,10 +2,13 @@ id: Icons section: design-foundations --- -import { Card, CardBody, Divider, Flex, FlexItem, Grid, GridItem, Icon } from '@patternfly/react-core'; +import { Alert, Card, CardBody, Divider, Flex, FlexItem, Grid, GridItem, Icon, Text, TextVariants } from '@patternfly/react-core'; import CaretDownIcon from '@patternfly/react-icons/dist/esm/icons/caret-down-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 GithubIcon from '@patternfly/react-icons/dist/esm/icons/github-icon'; import OutlinedCalendarAltIcon from '@patternfly/react-icons/dist/esm/icons/outlined-calendar-alt-icon'; import StarIcon from '@patternfly/react-icons/dist/esm/icons/star-icon'; @@ -15,129 +18,104 @@ import { IconRecommendations } from './IconRecommendations'; import { IconsTable } from './IconsTable'; import './icons.css'; -If you're a developer, check out our [getting started](/get-started/develop#using-styles) page to learn more about how to get and use our icon set. +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. -## Icon colors -Visit our [colors page](/design-foundations/colors) to learn more about icon colors. +For additional usage instruction, [refer to the icon component pages.](/components/icon) ## Icon sizes - - -

- PatternFly supports a range of icon sizes so that all icons can be adapted to different use cases. This range includes small, medium, large, and x-large icons, which correspond to the following font sizes and CSS variables: -

- - - - - - - -

Small (12px)

- --pf-v6-global--icon--FontSize--sm - - - - - - - - - -

Medium (16px)

- --pf-v6-global--icon--FontSize--md - - - - - - - - - -

Large (24px)

- --pf-v6-global--icon--FontSize--lg - - - - - - - - - -

X-large (54px)

- --pf-v6-global--icon--FontSize--xl - - -

- Medium icons are typically the most versatile size to use across UIs. PatternFly uses medium icons in most applications. Small, large and x-large icons are used sparingly across PatternFly components. -

- - - - -

Small icons

- - - Small icons - - - Small icons - - -

Medium icons

- Medium icons -

Large icons

- Large icons -

X-large icons

- Extra large icons - - - - -

- - No matter the size of an icon, when it is placed next to text, it should be center-aligned horizontally, as shown in our [link button example.](/components/button/design-guidelines#link-buttons) Stacked icons should also be center-aligned vertically. - -
Icon alignment
- - - -

-## PatternFly icons -PatternFly uses custom icons and selections from Font Awesome Free. If PatternFly doesn't offer an icon for your use case, you can download SVGs of additional 'fa' icons from Font Awesome's free set. Be sure to properly attribute these additional icons as outlined on the Font Awesome site. +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). + +## Inline icons + +[Inline icons](/components/icon#inline) must be center-aligned horizontally when placed next to text and center-aligned vertically when stacked. + +Icon alignment + +Use the following semantic tokens to ensure that icons are properly aligned and match the correct font size: + +### Headings + +| **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 | + +### 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 -These icons are the same as those in the [PatternFly Sketch design kit](/get-started/design#whats-in-the-design-kit), but you can use any Font Awesome icon so long it aligns with our icon guidelines. +## 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: + +| **Size** | **Token** | **Example** | +| --- | --- | :---: | +| Small (0.75rem, 12px) | `--pf-t--global--icon--size--sm` | | +| Medium (0.875rem, 14px) | `--pf-t--global--icon--size--md` | | +| Large (1rem, 16px) | `--pf-t--global--icon--size--lg` | | +| X-large (1.375rem, 22px) | `--pf-t--global--icon--size--xl` | | +| 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. + +## Icon colors +All icon colors that you use should align with the proper [semantic design token.](/tokens/all-patternfly-tokens) For example, a warning icon should use our approved warning color, a danger icon should use our approved danger color, and so on. + +| **Icon state** | **Color token** | **Example** | +| --- | --- | :---: | +| Danger | `--pf-t--global--icon--color--status--danger--default` | | +| Warning | `--pf-t--global--icon--color--status--warning--default` | | +| Success | `--pf-t--global--icon--color--status--success--default` | | +| Info | `--pf-t--global--icon--color--status--info--default` | | +| Custom | `--pf-t--global--icon--color--status--custom--default` | | + +To learn more about icon colors and color tokens, visit our [colors page.](/design-foundations/colors) + +## PatternFly icons +PatternFly uses custom icons and selections from Font Awesome Free, as shown in [this table](#all-icons). If PatternFly doesn't offer an icon for your use case, you can download SVGs of additional 'fa' icons from Font Awesome's free set. Be sure to properly attribute these additional icons as outlined on the Font Awesome site. ### HTML icons When using HTML, use the following syntax: -- For 'pficon' icons: ``
-- For 'fa' solid icons: ``
-- For 'fa' regular icons: ``
+- For 'pficon' icons: `` +- For 'fa' solid icons: `` +- For 'fa' regular icons: `` -**Note:** Be sure to read [how to get started with icons](/get-started/develop#using-styles) when using 'fa' regular icons. +**Note:** Be sure to reference our [development onboarding guide](/develop#using-icons) when using 'fa' regular icons. ### React icons -When using React, include the following import line for 'pficon' icons: `import { [insert-icon-name] } from '@patternfly/react-icons'` +When using React, you can import 'pficon' icons from our [react-icons package](https://www.npmjs.com/package/@patternfly/react-icons) by including the following line: `import { [insert-icon-name] } from '@patternfly/react-icons/dist/esm/icons/[insert-hyphenated-icon-name]';` + +For example: +`import StarIcon from '@patternfly/react-icons/dist/esm/icons/star-icon';` ### Font Awesome solid (FAS) vs Font Awesome regular (FAR) -The Font Awesome icons included with PatternFly are Font Awesome solid (FAS) webfont icons. If you're using icons via ``, you can use any FAS icon. If you need to use a Font Awesome regular (FAR) icon, you must include the FAR icon(s) yourself by doing one of the following: +The Font Awesome icons included with PatternFly are Font Awesome solid (FAS) webfont icons. If you're using icons via ``, you can use any FAS icon. If you need to use a Font Awesome regular (FAR) icon, you must include the FAR icons yourself by doing one of the following: -1. [Hosting it yourself](https://fontawesome.com/how-to-use/on-the-web/setup/hosting-font-awesome-yourself) -2. [Including the icon(s) via a package manager](https://fontawesome.com/how-to-use/on-the-web/setup/using-package-managers) -3. [Linking to a CDN](https://cdnjs.com/libraries/font-awesome) -4. Using the SVG code directly from [fontawesome.com](https://fontawesome.com) (proper attribution is required) +1. [Host it yourself](https://fontawesome.com/how-to-use/on-the-web/setup/hosting-font-awesome-yourself) +2. [Include the icons via a package manager](https://fontawesome.com/how-to-use/on-the-web/setup/using-package-managers) +3. [Link to a CDN](https://cdnjs.com/libraries/font-awesome) +4. Use the SVG code directly from [fontawesome.com](https://fontawesome.com) (proper attribution is required) ## All icons -The following table outlines details for all icons supported by PatternFly, as well as guidance for using each icon. +The following table provides details and usage information for all icons that PatternFly supports. -For guidance related to tooltips for icons, [refer to our tooltips writing guide.](/ux-writing/tooltips#icon-tooltips) +For guidance related to icon tooltips, [refer to our tooltips writing guide.](/ux-writing/tooltips#icon-tooltips) -Select any single icon in the table to download it as an SVG. You can also download all icon SVGs on GitHub. +Select any single icon in the table to download it as an SVG. You can also download all icon SVGs on GitHub (via patternfly-icons.zip.)