diff --git a/package.json b/package.json index 3c1569f1a3..d5616ab7bb 100644 --- a/package.json +++ b/package.json @@ -59,6 +59,6 @@ "parse-git-config": ">=3.0.0", "ip": ">=2.0.0", "http-cache-semantics": ">=4.1.1", - "nanoid": ">=3.3.8" + "nanoid": "3.3.8" } } diff --git a/packages/ast-helpers/CHANGELOG.md b/packages/ast-helpers/CHANGELOG.md index f1c1cc4288..76dc3efe4b 100644 --- a/packages/ast-helpers/CHANGELOG.md +++ b/packages/ast-helpers/CHANGELOG.md @@ -3,6 +3,44 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +# 1.4.0-alpha.278 (2025-09-16) + + +### Bug Fixes + +* **theme-selector:** prevent overflow of the menu ([#4779](https://github.com/patternfly/patternfly-org/issues/4779)) ([767811f](https://github.com/patternfly/patternfly-org/commit/767811f252a888d0795f0fd13142724e160bc0cd)) + + + + + +# 1.4.0-alpha.277 (2025-09-10) + +**Note:** Version bump only for package @patternfly/ast-helpers + + + + + +# 1.4.0-alpha.276 (2025-09-10) + +**Note:** Version bump only for package @patternfly/ast-helpers + + + + + +# 1.4.0-alpha.275 (2025-09-09) + + +### Bug Fixes + +* address build issue with nanoid version ([#4774](https://github.com/patternfly/patternfly-org/issues/4774)) ([f78543a](https://github.com/patternfly/patternfly-org/commit/f78543acacb27e9fd638a2450d5ec37ef56de2d5)) + + + + + # 1.4.0-alpha.274 (2025-09-05) diff --git a/packages/ast-helpers/package.json b/packages/ast-helpers/package.json index 36a06ddf20..5f3904f06a 100644 --- a/packages/ast-helpers/package.json +++ b/packages/ast-helpers/package.json @@ -1,7 +1,7 @@ { "name": "@patternfly/ast-helpers", "description": "Acorn AST helpers for working with live code", - "version": "1.4.0-alpha.274", + "version": "1.4.0-alpha.278", "author": "Red Hat", "license": "MIT", "publishConfig": { diff --git a/packages/documentation-framework/CHANGELOG.md b/packages/documentation-framework/CHANGELOG.md index 1c911e08ed..1fa4eeee06 100644 --- a/packages/documentation-framework/CHANGELOG.md +++ b/packages/documentation-framework/CHANGELOG.md @@ -3,6 +3,44 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +## 6.22.8 (2025-09-16) + + +### Bug Fixes + +* **theme-selector:** prevent overflow of the menu ([#4779](https://github.com/patternfly/patternfly-org/issues/4779)) ([767811f](https://github.com/patternfly/patternfly-org/commit/767811f252a888d0795f0fd13142724e160bc0cd)) + + + + + +## 6.22.7 (2025-09-10) + +**Note:** Version bump only for package @patternfly/documentation-framework + + + + + +## 6.22.6 (2025-09-10) + +**Note:** Version bump only for package @patternfly/documentation-framework + + + + + +## 6.22.5 (2025-09-09) + + +### Bug Fixes + +* address build issue with nanoid version ([#4774](https://github.com/patternfly/patternfly-org/issues/4774)) ([f78543a](https://github.com/patternfly/patternfly-org/commit/f78543acacb27e9fd638a2450d5ec37ef56de2d5)) + + + + + ## 6.22.4 (2025-09-05) diff --git a/packages/documentation-framework/components/example/example.css b/packages/documentation-framework/components/example/example.css index 2018d81b5a..0e646106f2 100644 --- a/packages/documentation-framework/components/example/example.css +++ b/packages/documentation-framework/components/example/example.css @@ -72,8 +72,8 @@ .ws-full-page-utils { position: fixed; - right: 0; - bottom: 0; + inset-inline-start: 0; + inset-block-end: 0; padding: var(--pf-t--global--spacer--lg); z-index: var(--pf-t--global--z-index--2xl); } diff --git a/packages/documentation-framework/components/themeSelector/themeSelector.js b/packages/documentation-framework/components/themeSelector/themeSelector.js index dd0738cc01..39f9166922 100644 --- a/packages/documentation-framework/components/themeSelector/themeSelector.js +++ b/packages/documentation-framework/components/themeSelector/themeSelector.js @@ -103,6 +103,11 @@ export const ThemeSelector = ({ id }) => { )} shouldFocusToggleOnSelect onOpenChangeKeys={['Escape']} + popperProps={{ + position: 'right', + enableFlip: true, + preventOverflow: true + }} > diff --git a/packages/documentation-framework/package.json b/packages/documentation-framework/package.json index 14ffd1c747..ef78754604 100644 --- a/packages/documentation-framework/package.json +++ b/packages/documentation-framework/package.json @@ -1,7 +1,7 @@ { "name": "@patternfly/documentation-framework", "description": "A framework to build documentation for PatternFly.", - "version": "6.22.4", + "version": "6.22.8", "author": "Red Hat", "license": "MIT", "bin": { @@ -12,7 +12,7 @@ "@babel/preset-env": "7.27.1", "@babel/preset-react": "^7.24.1", "@mdx-js/util": "1.6.16", - "@patternfly/ast-helpers": "^1.4.0-alpha.274", + "@patternfly/ast-helpers": "^1.4.0-alpha.278", "@reach/router": "npm:@gatsbyjs/reach-router@1.3.9", "autoprefixer": "10.4.19", "babel-loader": "^9.1.3", @@ -41,7 +41,7 @@ "null-loader": "4.0.1", "parse-entities": "2.0.0", "path-browserify": "1.0.1", - "postcss": "8.5.0", + "postcss": "^8.4.31", "postcss-loader": "7.1.0", "process": "^0.11.10", "puppeteer": "^24.2.0", @@ -93,6 +93,6 @@ "parse-git-config": ">=3.0.0", "ip": ">=2.0.0", "http-cache-semantics": ">=4.1.1", - "nanoid": ">=3.3.8" + "nanoid": "3.3.8" } } diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/img/nav-elements.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/img/nav-elements.svg index cb3a942394..7533bf2bdf 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/img/nav-elements.svg +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/img/nav-elements.svg @@ -1,49 +1,76 @@ - + - - - - - - - - - - - + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + @@ -52,37 +79,37 @@ - + - + - + - - + + - + - - + + - - + + - + - + @@ -91,33 +118,46 @@ - - - - - - - - - - - - - + + + + + + + + + + + + + + + - + - + + + + + + + + + - + + + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/navigation.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/navigation.md index e0e484ca3a..53d229d69d 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/navigation.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/navigation/navigation.md @@ -12,93 +12,90 @@ import '../components.css'; ![Elements of the different navigations offered by PatternFly.](./img/nav-elements.svg) -1. **Masthead** -2. [**Horizontal navigation**](#horizontal-navigation) -3. **Menu icon button:** Provides a way for users to toggle vertical navigation -4. [**Vertical navigation**](#vertical-navigation) -5. [**Secondary horizontal navigation**](#secondary-horizontal-navigation) - +1. [**Masthead:**](/components/masthead) Contains and organizes global properties for easy and consistent access across all pages of an application. +1. **Hamburger menu icon button:** Provides a way for users to toggle vertical navigation +1. [**Secondary horizontal navigation:**](#secondary-horizontal-navigation) A method of nested navigation that provides flexibility and structure for more complex information architecture. ## Usage -Use navigation to organize a pages structure and content for user clarity and convenience. Use cases differ depending on component variation. +Use navigation to organize a page's structure and content for user clarity and convenience. Use cases differ depending on component variation. ## Variations -There are two main variations of the navigation component each of which contain subvariations. +There are 2 main navigation variations, each with sub-variations. -* [Vertical navigation](#vertical-navigation) +1. [Vertical navigation](#vertical-navigation) * [Simple vertical navigation](#simple-vertical-navigation) * [Grouped navigation](#grouped-navigation) - * [Expandable two-level navigation](#expandable-two-level-navigation) - * [Expandable three-level navigation](#expandable-three-level-navigation) - * [Fly-out navigation](#fly-out-navigation) - * [Drill-down navigation](#drill-down-navigation) -* [Horizontal navigation](#horizontal-navigation) + * [Expandable 2-level navigation](#expandable-2-level-navigation) + * [Expandable 3-level navigation](#expandable-3-level-navigation) + * [Flyout navigation](#flyout-navigation) + * [Drilldown navigation](#drilldown-navigation) +1. [Horizontal navigation](#horizontal-navigation) * [Secondary horizontal navigation](#secondary-horizontal-navigation) ### Vertical navigation -Vertical navigation is hierarchical global navigation that displays navigation options from top to bottom on the left side of a screen. PatternFly vertical navigation can be collapsed to provide additional screen real estate by using a menu icon button at the top left. +Vertical navigation is hierarchical global navigation that displays navigation options from top to bottom on the left side of a screen. PatternFly vertical navigation can be collapsed to provide additional screen real estate by using a hamburger menu icon button at the top left. -#### When to use +Use vertical navigation when: * You have 5 or more primary navigation items -* You have secondary navigation items (even if you have less than five primary navigation items) +* You have secondary navigation items (even if you have fewer than 5 primary navigation items) * You expect your application to be used on mobile devices -Patternfly vertical navigation system includes several variants as described below. +Vertical navigation can be customized with several variants, described in the following sections. -### Simple vertical navigation +#### Simple vertical navigation -When you only have one level of navigation to display, use a simple, single-level vertical navigation. +When you only have 1 level of navigation to display, use a simple, single-level vertical navigation.
![Example of simple vertical navigation.](./img/nav-vertical-simple.svg)
-### Grouped navigation +#### Grouped navigation -When you have a small amount of secondary navigation items, you can group your items and display them persistently beneath the primary navigation items. +You can group related navigation items and display them persistently beneath a non-interactive group header, which describes the group of items.
![Example of grouped vertical navigation.](./img/nav-vertical-grouped.svg)
-### Expandable two-level navigation +#### Expandable 2-level navigation -When you have a large number of secondary navigation items, you can use an expandable navigation to collapse and expand options as needed. +Instead of using grouped navigation when you have multiple related navigation items, you can use an expandable navigation that nests secondary items under a primary navigation item. Users can collapse and expand the nested items as needed.
![Example of expandable vertical navigation.](./img/nav-vertical-expand1.svg)
-### Expandable three-level navigation +#### Expandable 3-level navigation -When you have three levels of navigation items, you can use a three-level expandable navigation to expose tertiary navigation items. Expansion works well when there are small numbers of items at the current level and the entire page hierarchy can be visualized at the same time. +When you need 3 levels of nested navigation items, you can use a 3-level expandable navigation.
![Example of expandable tertiary vertical navigation.](./img/nav-vertical-expand2.svg)
-### Fly-out navigation +#### Flyout navigation -Fly-out navigation exposes navigation items nested within a parent node in an overlay panel that appears to the right of the parent item on hover or click. Fly-out menus can be used to expose secondary or tertiary levels of navigation. While fly-out menus can be cascaded to display two or more levels of hierarchy below the parent page, this is not recommended as the mouse interaction required to navigate a multi-tiered flyout menu can be difficult for some users. +Flyout navigation exposes navigation items nested within a parent node in an overlay panel that appears to the right of the parent item on hover or click. Flyout menus can be used to expose secondary or tertiary levels of navigation. While flyout menus can be cascaded to display 2 or more levels of hierarchy below the parent page, this is not recommended as the mouse interaction required to navigate a multi-tiered flyout menu can be difficult for some users.
-![Example of vertical navigation with a fly-out.](./img/nav-vertical-flyout.svg) +![Example of vertical navigation with a flyout.](./img/nav-vertical-flyout.svg)
-The advantage of fly-out menus is that they allow a user to easily scan through secondary menu items. When using fly-out menus, keep in mind that the page in view may not be exposed as a selected menu item at the top level. Therefore, when using fly-outs, we strongly recommend use of [breadcrumbs](/components/breadcrumb) to help users understand where they are currently working within the site hierarchy. +The advantage of flyout menus is that they allow a user to easily scan through secondary menu items. When using flyout menus, keep in mind that the page in view may not be exposed as a selected menu item at the top level. Therefore, when using flyouts, we strongly recommend use of [breadcrumbs](/components/breadcrumb) to help users understand where they are currently working within the site hierarchy. -Also, consider how likely it is that your application will be used on a mobile phone. Fly-outs are not mobile friendly and may require substitution a different menu pattern across platforms (mobile vs desktop). +Also, consider how likely it is that your application will be used on a mobile phone. Flyouts are not mobile friendly and may require substitution for a different menu pattern across platforms (mobile vs desktop). -### Drill-down navigation +#### Drilldown navigation -Drill-down menus replace the current navigation menu with the next set of child items in the page hierarchy when the user clicks on a parent item to drill down. A back link is provided at the top of the menu to return to the parent level. +Drilldown menus replace the current navigation menu with the next set of child items in the page hierarchy when the user clicks on a parent item to drill down. A back link is provided at the top of the menu to return to the parent level.
-![Example of drill-down navigation.](./img/nav-vertical-drilldown.svg) +![Example of drilldown navigation.](./img/nav-vertical-drilldown.svg)
-Using drill-down navigation, only the navigation items for the current page and its siblings will be visible at any given time. This pattern is very mobile-friendly as it minimizes the need for scrolling to see the entire menu. However, it should be avoided if you expect users to frequently move between levels. +Using drilldown navigation, only the navigation items for the current page and its siblings will be visible at any given time. This pattern is very mobile-friendly as it minimizes the need for scrolling to see the entire menu. However, it should be avoided if you expect users to frequently move between levels. ### Combining vertical navigation patterns @@ -106,32 +103,32 @@ PatternFly's vertical menus are designed to be composable. This means that you c When combining different types of menus: -* Use a consistent approach to represent items at the same level in the page hierarchy. For example, if drill-down is used from level 1 - 2, all items with children at that level should display the same behavior. Don’t mix fly-outs, drill-downs, and expansion at the same level. +* Use a consistent approach to represent items at the same level in the page hierarchy. For example, if drilldown is used from level 1 to 2, all items with children at that level should display the same behavior. Don’t mix flyouts, drilldowns, and expansion at the same level. -* Consider how important or likely it is for users to move between levels and/or across to items at the same level but in different branches of the hierarchy. Drill-downs are most effective when users will spend most of their time moving between pages with the same parent node. Therefore, drilling into a lower level in the page hierarchy and then employing expansions or fly-outs to navigate between pages at that level can be an effective approach. +* Consider how important or likely it is for users to move between levels and/or across to items at the same level but in different branches of the hierarchy. Drilldowns are most effective when users will spend most of their time moving between pages with the same parent node. Therefore, drilling into a lower level in the page hierarchy and then employing expansions or flyouts to navigate between pages at that level can be an effective approach. Here are some examples of hybrid navigation patterns that you may find useful. -#### Fly-outs with tertiary drill-down -By using fly-outs to expose secondary navigation items and then drilling into third level items, you can keep the current page and its siblings visible as the user works. This is a good pattern to use when you expect users to spend most of their time working within the same section of the application. +#### Flyouts with tertiary drilldown +By using flyouts to expose secondary navigation items and then drilling into third level items, you can keep the current page and its siblings visible as the user works. This is a good pattern to use when you expect users to spend most of their time working within the same section of the application.
-![Example of vertical navigation with fly-out and drill-down menus.](./img/nav-vertical-drilldown-flyout.svg) +![Example of vertical navigation with flyout and drilldown menus.](./img/nav-vertical-drilldown-flyout.svg)
-#### Two-level expansion with drill-downs -You can use expanded menus to expose the first two or three levels of page hierarchy and then drill-down to the lowest level. This pattern is preferred to using fly-outs with a drill-down when there are fewer secondary level items and/or you require a mobile friendly solution. +#### 2-level expansion with drilldowns +You can use expanded menus to expose the first 2 or 3 levels of page hierarchy and then drilldown to the lowest level. This pattern is preferred to using flyouts with a drilldown when there are fewer secondary level items and/or you require a mobile friendly solution.
-![Example of vertical navigation with expansion and drill-down menus.](./img/nav-vertical-expansion-drilldown.svg) +![Example of vertical navigation with expansion and drilldown menus.](./img/nav-vertical-expansion-drilldown.svg)
-#### Drill-down with tertiary expansion +#### Drilldown with tertiary expansion -Consider using a drill-down menu at the primary level and expansion to expose levels two and three when you want to make it easy for users to move between items at levels two and three without the need to frequently move back to the primary level to explore other branches. +Consider using a drilldown menu at the primary level and expansion to expose levels 2 and 3 when you want to make it easy for users to move between items at levels 2 and 3 without the need to frequently move back to the primary level to explore other branches.
-![Example of vertical navigation with drill-downs and tertiary expansion.](./img/nav-vertical-drilldown-tertiary-expansion.svg) +![Example of vertical navigation with drilldowns and tertiary expansion.](./img/nav-vertical-drilldown-tertiary-expansion.svg)
### Horizontal navigation @@ -142,28 +139,36 @@ Horizontal navigation is global navigation that displays navigation items from l ![Example of horizontal navigation.](./img/nav-horizontal.svg) -#### When to use +Use horizontal navigation when: * You have less than 5 primary navigation items * You have only 1 level of navigation and no secondary navigation items -### Secondary horizontal navigation +#### Secondary horizontal navigation + +Use secondary horizontal navigation when you want to provide more granular navigation specific to a particular page or window in your application. When using secondary horizontal navigation, the page title should reflect the selected secondary navigation item. + +This differs from [tabs](/components/tabs), since tabs would allow you to switch perspective on the same page, while each secondary horizontal navigation item would be sending you to a distinct URL. For example, a user might navigate to settings page using the primary navigation, and then access privacy and general user settings via the secondary navigation. -Use secondary horizontal navigation when you want to provide more granular navigation specific to a particular page or window in your application. This differs from [tabs](/components/tabs), since tabs would allow you to switch perspective on the same page, while each secondary horizontal navigation item would be sending you to a distinct URL. For example, a user might use global navigation to get to a settings page, and then use local navigation to access privacy and general user settings. +You can provide additional nested information by using tabs within the page content. -Secondary horizontal navigation can be paired with vertical or horizontal navigation. It provides deeper nesting to the vertical navigation, which may help prevent the navigation from becoming too long. The title of the page should reflect the selected horizontal navigation item. You can provide further nested information by using tabs. +Secondary horizontal navigation follows a similar responsive design as our other horizontal navigation types. For smaller screens, overflow items can be navigated to by using horizontal scroll or the arrows.
-![Example of secondary horizontal navigation.](./img/nav-secondary-vertical.svg) +![Example of horizontal navigation on a mobile screen.](./img/nav-mobile.svg)
+##### Vertical primary navigation + +When used with vertical navigation, secondary navigation provides deeper nesting, which may help prevent the main navigation menu from becoming too long. +
-![Example of horizontal primary and secondary navigation.](./img/nav-secondary-horizontal.svg) +![Example of secondary horizontal navigation.](./img/nav-secondary-vertical.svg)
+#### Horizontal primary navigation -Secondary horizontal navigation follows a similar responsive design as our other horizontal navigation types. -Overflow items can be navigated to by using horizontal scroll or the arrows. +Secondary horizontal navigation can also be used with primary horizontal navigation.
-![Example of horizontal navigation on a mobile screen.](./img/nav-mobile.svg) -
+![Example of horizontal primary and secondary navigation.](./img/nav-secondary-horizontal.svg) + \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-basic.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-basic.png deleted file mode 100644 index a02a494e55..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-basic.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-canvas-view.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-canvas-view.png deleted file mode 100644 index 887a9cea1d..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-canvas-view.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-card-view.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-card-view.png deleted file mode 100644 index 3f23deaa91..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-card-view.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-compact.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-compact.png deleted file mode 100644 index 489d0bc810..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-compact.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-custom-icons.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-custom-icons.png deleted file mode 100644 index be8d623f54..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-custom-icons.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-elements.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-elements.png deleted file mode 100644 index 0e0c8d9edb..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-elements.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-help-popover.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-help-popover.png deleted file mode 100644 index 36ebcb2a53..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-help-popover.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-table-view-popover.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-table-view-popover.png deleted file mode 100644 index 7d081443f2..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-table-view-popover.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-table-view.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-table-view.png deleted file mode 100644 index 6a1c668261..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-table-view.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-vertical.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-vertical.png deleted file mode 100644 index deecf90298..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-vertical.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-with-description.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-with-description.png deleted file mode 100644 index 8b8fe1b3d5..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/img/progress-stepper-with-description.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/progress-stepper.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/progress-stepper.md index df2a127207..14f337a404 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/progress-stepper.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress-stepper/progress-stepper.md @@ -13,24 +13,24 @@ A **progress stepper** displays progress through a sequence of linear steps and 1. **Progress title:** Describes the task or process underway. -2. **Progress description (optional):** Provides additional information on the task or process -3. **Completed status:** Informs the user of a successfully completed step -4. **In progress status:** Informs the user what step they are on -5. **Failure status:** Informs the user of a failure or error in the step -6. **Warning status:** Informs the user of a non-critical error in step -7. **Pending step:** Upcoming steps needed to complete the task or process +2. **Progress description (optional):** Provides additional information on the task or process. +3. **Completed status:** Informs the user of a successfully completed step. +4. **In progress status:** Informs the user what step they are on. +5. **Failure status:** Informs the user of a failure or error in the step. +6. **Warning status:** Informs the user of a non-critical error in a step. +7. **Pending step:** Upcoming steps needed to complete the task or process. ## Usage -Use a progress stepper to convey to a user how many steps are required to complete a task or process. Similar to the [progress bar](/components/progress), the progress stepper can help to keep users informed about how much effort or time the task or process will take to complete. One advantage is it displays the total number of steps at all times. Additionally, it informs the user exactly where they are in the process and how much is left until their task or process is completed. +Use a progress stepper to convey the number of steps required to complete a task or process. Similar to the [progress component](/components/progress), the progress stepper can help keep users informed about how much effort or time a task or process will take to complete. An advantage of the progress stepper is that the total number of steps is displayed at all times, which informs users about where they are in a process and how much is left until completion. ### When to use -* A user is completing a multi-step process in a card +- For multi-step processes within a card.
![Example of a progress stepper in a card.](./img/multi-stepper-card.svg)
-* A user is showing progression through a workflow in a table or card +- To show progression through a workflow in a table or card.
![Example of a progress stepper in a table.](./img/stepper-table.svg) @@ -40,7 +40,7 @@ Use a progress stepper to convey to a user how many steps are required to comple ![Example of a progress stepper in a card.](./img/stepper-card.svg)
-* A user is checking the status of the installation process in a popover +- To display the status of a process, like an installation, in a popover.
![Example of a progress stepper in a popover.](./img/stepper-popover.svg) @@ -49,53 +49,62 @@ Use a progress stepper to convey to a user how many steps are required to comple ### When to use progress stepper vs. wizard Use a progress stepper: -* To indicate to the user where they are in a step-by-step linear process on a single page. -* When the steps in the process could be completed by the user or happening in the background without the user completing the task themselves. +- To indicate to the user where they are in a step-by-step linear process on a single page. +- When the steps in the process could be completed by the user or could happen automatically in the background. Use a [wizard](/components/wizard): -* To guide the user through a multi-step flow where they must complete specific tasks in order. -* When the steps are complex enough they need to be broken up into smaller, more manageable steps and does not keep user on the same screen. +- To guide the user through a multi-step flow where they must complete specific tasks in order. +- When the steps are complex enough to be broken up into smaller, more manageable steps, that require navigating between different screens. + +### When to use progress bar vs. progress stepper + +Use a progress stepper: +- To indicate to a user where they are in a step-by-step linear process on a single page. + +Use a [progress bar](/components/progress): +- To indicate to a user that the system is progressing through a task. +- To let users monitor background tasks. ## Variations -There are a few variations of the progress stepper that can be used for different use cases. All variations can be displayed horizontally or vertically, and the text on each step can be left justified or centered. +There are a few variations of the progress stepper that can be used for different use cases. All variations can be displayed horizontally or vertically, and the text on each step can be left-aligned or centered. ### Basic progress stepper -The basic progress stepper can be used when just the title of the step is enough to inform the user. +A basic progress stepper can be used when just the title of the step is enough to inform the user.
![Example of a basic progress stepper.](./img/stepper-basic.svg)
### Basic with descriptions -If more description is needed, a basic progress stepper with descriptions can be used which allows for more context for each step. +If more description is needed, you can use a basic progress stepper with descriptions, which allows for more context for each step.
![Example of a progress stepper with descriptions.](./img/stepper-with-descriptions.svg)
### Vertical progress stepper -The vertical alignment can be used in pages with a split view where one side houses the progress stepper and the other side houses each step’s content. These can also be used to display progress in a popover. +A vertical progress stepper can be used in pages with a split view, where one side contains the progress stepper and the other side contains each step’s content. These can also be used to display progress in a popover.
![Example of a vertical progress stepper.](./img/stepper-vertical.svg)
### Compact progress stepper -In areas with less real estate such as table rows, the compact progress stepper can be used. The component will not display as much information such as each step’s title and/or description and will be smaller in size. The compact progress stepper also accounts for the alignment variations. +In areas with less space, like table rows, the compact progress stepper can be used. Compact progress steppers will not display as much information—like each step’s title or description—and will be smaller in size. The compact progress stepper also accounts for the alignment variations.
![Example of a compact progress stepper.](./img/stepper-compact.svg)
### Progress stepper with icons -Custom icons can also be used for each step of the progress stepper based on the use case and the product’s need. +Custom icons can also be used for each step of the progress stepper based on the use case and product needs.
![Example of a progress stepper with custom icons.](./img/stepper-custom-icons.svg)
### Progress stepper with help popover -If additional help information or help text is needed and there is not enough real estate for a description, a popover on each step’s title can be used. +If additional information or help text is needed and there is not enough space for a description, a popover on each step’s title can be used.
![Example of a progress stepper with a help popover.](./img/stepper-help-popover.svg) @@ -112,10 +121,10 @@ For **in progress** steps, write your progress stepper title with present partic
-| **Do** | **Don't** | +| **Don't** | **Do** | |:-------------------------------:|:--------------------------:| -| Installing cluster | Cluster is installing | -| Creating cache | Cluster creation in progress | +| Cluster is installing | Installing cluster | +| Cluster creation in progress | Creating cache |
@@ -123,10 +132,10 @@ For **failed** steps, write your progress stepper title in past tense. Avoid tel
-| **Do** | **Don't** | +| **Don't** | **Do** | |:-------------------------------:|:--------------------------:| -| Could not install cluster | Cluster installation failed | -| Could not validate account credentials | Account validation unsuccessful | +| Cluster installation failed | Could not install cluster | +| Account validation unsuccessful | Could not validate account credentials |
@@ -134,12 +143,12 @@ For **complete** steps, write your progress stepper title in past tense. Use thi
-| **Do** | **Don't** | +| **Don't** | **Do** | |:-------------------------------:|:--------------------------:| -| Cluster installed | Installation is complete | -| Validated account credentials | Successfully validated account credentials | +| Installation is complete | Cluster installed | +| Successfully validated account credentials | Validated account credentials |
## Accessibility -For information regarding accessibility, visit the progress stepper [accessibility tab](/components/progress-stepper/accessibility). +For information regarding accessibility, visit the progress stepper [accessibility tab](/components/progress-stepper/accessibility). \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-complete.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-complete.png deleted file mode 100644 index 5481d82ff7..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-complete.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-do-dont.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-do-dont.png deleted file mode 100644 index 52f750d3d1..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-do-dont.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-during-file-download.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-during-file-download.png deleted file mode 100644 index 61cc9220bf..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-during-file-download.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-error-state.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-error-state.png deleted file mode 100644 index 93df0bf4bb..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-error-state.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-dashboard.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-dashboard.png deleted file mode 100644 index c8c135e5c4..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-dashboard.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-progress.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-progress.png deleted file mode 100644 index 1298395016..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-progress.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-table.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-table.png deleted file mode 100644 index 4f3f05708d..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-table.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-wizard.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-wizard.png deleted file mode 100644 index 05c24e2adb..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-in-wizard.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-left-aligned-progress-value.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-left-aligned-progress-value.png deleted file mode 100644 index 08965dccf7..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-left-aligned-progress-value.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-right-aligned-progress-value.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-right-aligned-progress-value.png deleted file mode 100644 index 57549fa808..0000000000 Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-bar-right-aligned-progress-value.png and /dev/null differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-sizes.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-sizes.svg new file mode 100644 index 0000000000..e7849e4951 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-sizes.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-table-multiple.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-table-multiple.svg new file mode 100644 index 0000000000..26026707f7 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-table-multiple.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-table.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-table.svg index cf82fa8a9d..9358993152 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-table.svg +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/img/progress-table.svg @@ -1,149 +1,102 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/progress.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/progress.md index e4fcfcbc56..1077cfe399 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/progress.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/progress/progress.md @@ -20,13 +20,24 @@ import '../components.css'; Use a progress bar to keep users informed about how much effort or time they can expect to allocate for long or ongoing processes like loading or updating an app, submitting a form, or completing a multi-step tutorial. ### When to use -* A user must complete a series of tasks and will want indication that they are making progress. -* A user needs indication that the system is progressing through loading, saving, or downloading. -* A user needs to monitor a background process, especially if that process may take a long time. +* To show progress as a user completes a series of tasks. +* To indicate that the system is progressing through loading, saving, or downloading. +* To allow users to monitor a background process, especially if that process may take a long time. +### When to use progress bar vs. spinner Depending on your use case, you might choose between 2 types of loading indicators: Progress bars and [spinners](/components/spinner). Never use a progress bar and spinner together. -Default to progress bars for processes that take longer than 4 seconds or require more specific information about process completion. If a process takes less than four seconds, use a [spinner](/components/spinner) instead. +- Default to progress bars for processes that take longer than 4 seconds or require more specific information about process completion. +- If a process takes less than 4 seconds, use a [spinner](/components/spinner) instead. + +### When to use progress bar vs. progress stepper + +Use a progress bar: +- To indicate to a user that the system is progressing through a task. +- To let users monitor background tasks. + +Use a [progress stepper](/components/progress-stepper): +- To indicate to a user where they are in a step-by-step linear process on a single page. ## Variations @@ -34,20 +45,29 @@ Default to progress bars for processes that take longer than 4 seconds or requir Whenever possible, use a determinate progress bar to communicate progress with measurable values like time or percentage. -Use a percentage as a progress value if the process will take less than a minute to complete or a percentage will be more accurate than estimating a task’s duration. - -Use a time interval value such as “4 minutes remaining” to communicate progress if the process takes more than one minute to complete. +- **Percentage:** Use as a progress value if the process will take less than 1 minute to complete or a percentage will be more accurate than estimating a task’s duration. +- **Time interval:** Use as a progress value to communicate progress if the process takes more than one minute to complete. For example, “4 minutes remaining.” ### Indeterminate progress bar Avoid using indeterminate progress bars to communicate progress that can’t be measured. To track progress that can’t be quantified with a percentage, time, or step, use a [spinner](/components/spinner) instead. +Follow these general style guidelines when designing your progress bars. For information about writing progress bar titles for each status type, see the [content considerations](#content-considerations). + +### Progress bar sizes -Follow these general style guidelines when designing your progress bars. For information about writing progress bar titles for each status type, see the [Content](#content) section. +There are 3 size options for progress bars depending on your use case: +- **Small:** A thin progress bar to use in pages or elements without much space. +- **Default:** A basic progress bar to use in the majority of situations. +- **Large:** A thick progress bar to use when a progress value (like a percentage) is displayed within the bar or to use for prominent progress bars, like those [in a wizard](#in-a-wizard). + +
+![Three progress bars, one small, one default sized, and one large.](./img/progress-sizes.svg) +
### In progress -A blue progress bar represents a process that is currently underway. +A `--pf-t--global--color--brand--default` progress bar represents a process that is currently underway.
![Example of a progress bar in the "in progress" state.](./img/in-progress.svg) @@ -55,7 +75,7 @@ A blue progress bar represents a process that is currently underway. ### Error state or failure -A red progress bar represents a process that has failed. Accompany a failed progress bar with a [red danger icon](/design-foundations/icons/#all-icons) to demonstrate that an error occurred in the process. +A `--pf-t--global--color--status--danger--default` progress bar represents a process that has failed. Accompany a failed progress bar with a [danger icon](/design-foundations/icons/#all-icons) to demonstrate that an error occurred in the process.
![Example of a progress bar in the error or failed state.](./img/error.svg) @@ -63,7 +83,7 @@ A red progress bar represents a process that has failed. Accompany a failed prog ### Complete or success -A green progress bar represents the successful completion of a process. Accompany a complete progress bar with a [green check-circle icon](/design-foundations/icons/#all-icons) to demonstrate that the process has finished with no errors. +A `--pf-t--global--color--status--success--default` progress bar represents the successful completion of a process. Accompany a complete progress bar with a [check-circle icon](/design-foundations/icons/#all-icons) to demonstrate that the process has finished with no errors.
![Example of a progress bar in the complete or successful state.](./img/success.svg) @@ -73,12 +93,16 @@ A green progress bar represents the successful completion of a process. Accompan Use a progress bar in a table to communicate the status of processes or tasks within it. -Place a progress bar into a table just as you would other table content. If a progress bar records the progress of multiple line items, group these items in adjoining cells and keep the progress bar in-line with the first item it pertains to. For multi-item progress bars that apply to non-consecutive items, consider adding a progress bar in-line with each individual item. +
+![Example of progress bars in a table.](./img/progress-table.svg) +
+ +Place a progress bar into a table just as you would other table content. If a progress bar records the progress of multiple line items, group these items in adjoining cells and keep the progress bar inline with the first item it pertains to. For multi-item progress bars that apply to non-consecutive items, consider adding a progress bar inline with each individual item. If your table includes multiple progress bars, designate a “Status” or “Progress” column for each one.
-![Example of progress bars in a table.](./img/progress-table.svg) +![Multiple columns containing progress bars in a table, with a "status" and "progress" heading.](./img/progress-table-multiple.svg)
### In a dashboard view @@ -91,7 +115,7 @@ Use a progress bar in a dashboard view to track the progress trends within each ### During a file download -Use a [toast notification](/components/alert/design-guidelines/#using-toast-alerts) and a progress bar to demonstrate progress during a file download. +Use a [toast alert](/components/alert/design-guidelines) and a progress bar to demonstrate progress during a file download.
![Example of a progress bar in a toast alert to communicate progress during a file download.](./img/progress-file-download.svg) @@ -127,12 +151,12 @@ Always set an “outside fixed width measure” for determinate progress bars. T ## Placement +Always place progress bars in alignment with their relevant context, such as the feature, function, or task they reflect. Keep progress bars within the user’s line of sight: Never isolate a progress bar at the top or bottom of a page, or outside of its relevant content view. +
![Examples of dos and don'ts for placing a progress bar in your designs.](./img/progress-placement.svg)
-Always place progress bars in alignment with their relevant context, such as the feature, function, or task they reflect. Keep progress bars within the user’s line of sight: Never isolate a progress bar at the top or bottom of a page, or outside of its relevant content view. - Use progress bars to communicate progress in a variety of contexts including: * [In a table](#in-a-table) @@ -145,7 +169,10 @@ Use progress bars to communicate progress in a variety of contexts including: Progress bars should be self-explanatory and therefore include minimal written content: A title and an optional progress value. -In some use cases, longer progress bars might feature multiple lines of copy that change as a process moves through several phases. Default to one title per progress bar, unless your progress bar measures a multi-step process or procedure that isn’t detailed elsewhere. +In some use cases, longer progress bars might feature multiple lines of copy that change as a process moves through several phases. Default to 1 title per progress bar, unless your progress bar measures a multi-step process or procedure that isn’t detailed elsewhere. + +### Styling for statuses +Styling for progress bar statuses should follow accessibility guidelines by communicating each state through several messaging types: color, microcopy, and icons. ### Titles @@ -155,11 +182,11 @@ Never punctuate progress bar titles, since they consist of fragments, not full s
-| **Do** | **Don't** | +| **Don't** | **Do** | |:-------------------------------:|:--------------------------:| -| Downloading [application name] | Your application is downloading... | -| Creating cache | This may take a few minutes... | -| Validating account credentials | We're validating your account credentials| +| Your application is downloading... | Downloading [application name] | +| This may take a few minutes... | Creating cache | +| We're validating your account credentials | Validating account credentials |
@@ -169,10 +196,10 @@ For **in progress** statuses, write your progress bar title with present partici
-| **Do** | **Don't** | +| **Don't** | **Do** | |:-------------------------------:|:--------------------------:| -| Installing cluster | Cluster is installing | -| Creating cache | Cluster creation in progress | +| Cluster is installing | Installing cluster | +| Cluster creation in progress | Creating cache |
@@ -180,10 +207,10 @@ For **failed** statuses, write your progress bar title in past tense. Avoid tell
-| **Do** | **Don't** | +| **Don't** | **Do** | |:-------------------------------:|:--------------------------:| -| Could not install cluster | Cluster installation failed | -| Could not validate account credentials | Account validation unsuccessful | +| Cluster installation failed | Could not install cluster | +| Account validation unsuccessful | Could not validate account credentials |
@@ -191,14 +218,11 @@ For **complete** statuses, write your progress bar title in past tense. Use this
-| **Do** | **Don't** | +| **Don't** | **Do** | |:-------------------------------:|:--------------------------:| -| Cluster installed | Installation is complete | -| Validated account credentials | Successfully validated account credentials | +| Installation is complete | Cluster installed | +| Successfully validated account credentials | Validated account credentials |
-Progress bars should only use content in their title and progress value. Never write additional content inside the progress track. - -### Styling for statuses -Styling for progress bar statuses should follow accessibility guidelines by communicating each state through several messaging types: Color, microcopy, and icons. +Progress bars should only use content in their title and progress value. Never write additional content inside the progress track. \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/dark-theme-handbook.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/dark-theme-handbook.md similarity index 98% rename from packages/documentation-site/patternfly-docs/content/developer-resources/dark-theme-handbook.md rename to packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/dark-theme-handbook.md index 0badffb58e..8414ebf4de 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/dark-theme-handbook.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/dark-theme-handbook.md @@ -1,7 +1,7 @@ --- -id: Dark theme handbook -title: PatternFly dark theme handbook -section: developer-resources +id: Theming +section: design-foundations +source: dark-theme-handbook --- ## Enabling dark theme diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-dark.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-dark.svg new file mode 100644 index 0000000000..9a34db1186 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-dark.svg @@ -0,0 +1,212 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-light.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-light.svg new file mode 100644 index 0000000000..298db20125 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-light.svg @@ -0,0 +1,212 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/figma-dark-mode.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/figma-dark-mode.png new file mode 100644 index 0000000000..508582f321 Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/figma-dark-mode.png differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/theming.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/theming.md new file mode 100644 index 0000000000..47141c749d --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/theming.md @@ -0,0 +1,80 @@ +--- +id: Theming +section: design-foundations +source: about +--- + +import '../../components/components.css' +import { Alert, AlertActionLink} from '@patternfly/react-core'; +import ExternalLinkAltIcon from '@patternfly/react-icons/dist/esm/icons/external-link-alt-icon'; + +A **theme** applies a specific visual style to all UI components in order to create a unique, cohesive, and purposeful look. The use of theming can provide more flexibility for user preferences, as well as different options for accessibility needs. + +Theming is supported in PatternFly through [our design token system](/tokens/about-tokens), which was intentionally structured so that sets of tokens can be adjusted together to create alternate UI styles. By reassigning color and dimension token values, the fonts, spacing, shadows, and borders in a UI can be changed together to create a theme. This system has enabled us to create multiple PatternFly themes, while also supporting the ability for you to create custom themes. + +## PatternFly themes + +The following themes are currently supported across PatternFly components and are designed to meet specific [WCAG accessibility standards](https://www.w3.org/WAI/standards-guidelines/wcag/). You can explore our different themes on our website by toggling your display preferences in our site's masthead dropdown. + +### Light mode + +Generally, light mode is the default appearance of PatternFly. In this mode, dark text is presented on light backgrounds to meet a [text contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#contrast-minimum), while colors for other UI elements meet a [non-text contrast ratio of at least 3:1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#non-text-contrast). Some users might find it easier to read text on light screens, while others might simply prefer the appearance. + +
+![A collage of multiple light-themed PatternFly components, like a calendar, alert, and menu. The components have white backgrounds and black text.](./img/components-light.svg) +
+ +### Dark mode + +In dark mode, light text is presented on dark backgrounds backgrounds, and our color palette adapts to maintain a [text contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#contrast-minimum) and [non-text contrast ratio of at least 3:1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#non-text-contrast). Some users might prefer dark mode for aesthetics, while others find it to be easier on the eyes and less straining for those with light sensitivities. + +
+![A collage of multiple dark-themed PatternFly components, like a calendar, alert, and menu. The components have dark gray backgrounds and white text.](./img/components-dark.svg) +
+ +### High contrast mode + + +Learn more + +} +> +

High contrast mode is still under development and will continue to evolve and be enabled for charts and extensions. This beta allows you to preview our progress.

+ + +High contrast mode adjusts our default colors to meet an [enhanced contrast ratio of at least 7:1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced.html), making it more suitable for users who require higher contrast between UI elements. By using wider border strokes and adjusted fill colors, high contrast mode creates more visual distinction and clarity between interactive elements. + +In high contrast mode, distinct borders are also added to components to ensure that their boundaries are clearly defined without requiring users to rely on subtle background colors as a visual cue. + +## Using themes in Figma + +Our Figma libraries fully support theming. Designers can create a single layout and then use Figma's appearance feature to swap a wireframe to light, dark, or high contrast mode. This makes it easy to visually test and validate designs across all supported themes. + +
+![A dark colored flyout menu within an "Appearance" section. The menu expands "Semantic Color Tokens" with selectable options for "Auto (Light)", "Light", and "Dark."](./img/figma-dark-mode.png) +
+ +## Custom themes + +To branch off of our themes and create your own, you can alter design token values to specify new styles. + +Our layered design tokens allow you to create new themes simply by changing base token values in a single file. These adjustments will then apply appropriately to all semantic tokens across your codebase. + +### When to create a custom theme + +| **Don't** | **Do** | +| --- | --- | +| Create a theme just for one-off adjustments, like changing a single button color. Instead, modify small design changes using component props or utility classes. | Create a theme to adjust the overall brand identity of your application. | + +### How to create a custom theme + +When creating a custom theme, it is your responsibility to ensure that your new color combinations and styles continue to meet accessibility standards, such as a minimum text contrast ratio of 4.5:1. + +Add: Technical details and guidance (consider separate tab if this gets long) +- In which files must you override default values? +- Code example snippet. +- Tips or best practices? \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md b/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md index 3ad55eafac..b34c4098c8 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md @@ -652,6 +652,6 @@ All of our components have a new look to match. As you use the alpha website, ta In order to support PatternFly 6, and any future visual theming capabilities, we have implemented a design token system for PatternFly. For more details and instructions on how to use tokens, you can refer to our new [design token documentation](/tokens/about-tokens). -Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/developer-resources/dark-theme-handbook) to align with our tokens. +Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/design-foundations/theming/dark-theme-handbook) to align with our tokens. **Note:*- The PatternFly 5 design library is not built with tokens. To take advantage of our token system, you must [upgrade your product to PatternFly 6](/get-started/upgrade). diff --git a/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md b/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md index 4ac133506a..0c537dc286 100644 --- a/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md +++ b/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md @@ -17,7 +17,7 @@ In the event that there isn't a semantic token that fits your use case, then you Our token system supports both light and dark themes by default. To enable dark theme, you just need to add the class `pf-[version]-theme-dark` (for example, `pf-v6-theme-dark`) to your application's `` tag. Then, when dark theme is enabled, your product will automatically pull in dark theme tokens, in order to adapt visual styles appropriately. -For more information, refer to our [dark theme handbook.](/developer-resources/dark-theme-handbook) +For more information, refer to our [dark theme handbook.](/design-foundations/theming/dark-theme-handbook) ## Migrate to tokens diff --git a/packages/site/src/content/get-started/release-highlights.mdx b/packages/site/src/content/get-started/release-highlights.mdx index cef730fe87..8952b70181 100644 --- a/packages/site/src/content/get-started/release-highlights.mdx +++ b/packages/site/src/content/get-started/release-highlights.mdx @@ -437,6 +437,6 @@ All of our components have a new look to match. As you use the alpha website, ta In order to support PatternFly 6, and any future visual theming capabilities, we have implemented a design token system for PatternFly. For more details and instructions on how to use tokens, you can refer to our new [design token documentation](/tokens/about-tokens). -Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/developer-resources/dark-theme-handbook) to align with our tokens. +Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/design-foundations/theming/dark-theme-handbook) to align with our tokens. **Note:*- The PatternFly 5 design library is not built with tokens. To take advantage of our token system, you must [upgrade your product to PatternFly 6](/get-started/upgrade). diff --git a/yarn.lock b/yarn.lock index 26d8d330ff..d18b2b9e78 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4055,7 +4055,7 @@ __metadata: languageName: node linkType: hard -"@patternfly/ast-helpers@npm:^1.4.0-alpha.274, @patternfly/ast-helpers@workspace:packages/ast-helpers": +"@patternfly/ast-helpers@npm:^1.4.0-alpha.278, @patternfly/ast-helpers@workspace:packages/ast-helpers": version: 0.0.0-use.local resolution: "@patternfly/ast-helpers@workspace:packages/ast-helpers" dependencies: @@ -4114,7 +4114,7 @@ __metadata: "@babel/preset-env": "npm:7.27.1" "@babel/preset-react": "npm:^7.24.1" "@mdx-js/util": "npm:1.6.16" - "@patternfly/ast-helpers": "npm:^1.4.0-alpha.274" + "@patternfly/ast-helpers": "npm:^1.4.0-alpha.278" "@reach/router": "npm:@gatsbyjs/reach-router@1.3.9" autoprefixer: "npm:10.4.19" babel-loader: "npm:^9.1.3" @@ -4143,7 +4143,7 @@ __metadata: null-loader: "npm:4.0.1" parse-entities: "npm:2.0.0" path-browserify: "npm:1.0.1" - postcss: "npm:8.5.0" + postcss: "npm:^8.4.31" postcss-loader: "npm:7.1.0" process: "npm:^0.11.10" puppeteer: "npm:^24.2.0" @@ -16619,12 +16619,12 @@ __metadata: languageName: node linkType: hard -"nanoid@npm:>=3.3.8": - version: 5.1.5 - resolution: "nanoid@npm:5.1.5" +"nanoid@npm:3.3.8": + version: 3.3.8 + resolution: "nanoid@npm:3.3.8" bin: - nanoid: bin/nanoid.js - checksum: 10c0/e6004f1ad6c7123eeb037062c4441d44982037dc043aabb162457ef6986e99964ba98c63c975f96c547403beb0bf95bc537bd7bf9a09baf381656acdc2975c3c + nanoid: bin/nanoid.cjs + checksum: 10c0/4b1bb29f6cfebf3be3bc4ad1f1296fb0a10a3043a79f34fbffe75d1621b4318319211cd420549459018ea3592f0d2f159247a6f874911d6d26eaaadda2478120 languageName: node linkType: hard @@ -18393,17 +18393,6 @@ __metadata: languageName: node linkType: hard -"postcss@npm:8.5.0": - version: 8.5.0 - resolution: "postcss@npm:8.5.0" - dependencies: - nanoid: "npm:^3.3.8" - picocolors: "npm:^1.1.1" - source-map-js: "npm:^1.2.1" - checksum: 10c0/ce4fb520808a932566a0fd97be905b43e219b55a3752fc8daa944082a35848fa8aff300b89b77dc52c8c3bb5cd53e77182ddb37addc6cacf586f1ef42a34ef45 - languageName: node - linkType: hard - "postcss@npm:^8.4.19": version: 8.4.38 resolution: "postcss@npm:8.4.38" @@ -18415,6 +18404,17 @@ __metadata: languageName: node linkType: hard +"postcss@npm:^8.4.31": + version: 8.5.6 + resolution: "postcss@npm:8.5.6" + dependencies: + nanoid: "npm:^3.3.11" + picocolors: "npm:^1.1.1" + source-map-js: "npm:^1.2.1" + checksum: 10c0/5127cc7c91ed7a133a1b7318012d8bfa112da9ef092dddf369ae699a1f10ebbd89b1b9f25f3228795b84585c72aabd5ced5fc11f2ba467eedf7b081a66fad024 + languageName: node + linkType: hard + "postcss@npm:^8.5.3": version: 8.5.3 resolution: "postcss@npm:8.5.3"