From 858b94e5eb00fa4e3ac088c702e924b9d8d3168e Mon Sep 17 00:00:00 2001 From: lboehling Date: Tue, 21 Jul 2026 17:19:07 -0400 Subject: [PATCH 01/10] docs(hero): add design guidelines for Hero component Add a Design guidelines tab for the beta Hero component covering elements, usage, Default/Glass variants, content, and spacing aligned to PatternFly 6.6 implementation. Includes placeholder images to be replaced with final Figma exports. Co-authored-by: Cursor --- .../content/components/hero/hero.md | 140 ++++++++++++++++++ .../components/hero/img/hero-elements.svg | 18 +++ .../components/hero/img/hero-placement.svg | 15 ++ .../components/hero/img/hero-responsive.svg | 21 +++ .../components/hero/img/hero-variants.svg | 20 +++ 5 files changed, 214 insertions(+) create mode 100644 packages/documentation-site/patternfly-docs/content/components/hero/hero.md create mode 100644 packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg create mode 100644 packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg create mode 100644 packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg create mode 100644 packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md new file mode 100644 index 0000000000..ad268445bc --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -0,0 +1,140 @@ +--- +id: Hero +section: components +--- +import '../components.css'; + +Use a hero at the top of a homepage or landing page to introduce a clear value proposition and primary call to action. + +Hero is currently a [beta component](/get-started/about-PatternFly#beta-components). These guidelines reflect what is implemented today and may evolve as the component matures. + +## Elements + +A hero is a compositional container. Structure content with PatternFly typography and button components inside the hero body. + +
+![Annotated default hero showing headline, description, call-to-action buttons, and optional right-aligned brand asset.](./img/hero-elements.svg) +
+ +1. **Headline:** A concise statement about the offering or page purpose. Use heading XL typography (28px, Red Hat Display Medium). On a landing page, this should typically be the page `h1`. +2. **Description:** Supporting context for the headline. Use body large typography (16px). +3. **Visual content (optional):** A right-aligned brand asset applied as a background image. Decorative assets should support the message without competing with text. +4. **Call to action(s):** Include at least one primary action; one secondary or tertiary action is optional. Use [CTA buttons](/components/button#call-to-action-cta-buttons) at size `lg`. + +## Usage + +### When to use + +Use a hero when the primary purpose of the page is to: + +- Establish brand tone and communicate a key value proposition. +- Introduce a new product, feature, or campaign. +- Drive users toward a specific high-value action or conversion. + +Common placements include homepages, product landing pages, and main dashboard landing views (such as Compass). + +### When not to use + +Do not use a hero as a generic page header on: + +- Pages focused on content discovery, data management, or dense workflows (use a standard page header instead). +- Detail views, settings pages, or views where the user's primary task is utility- or task-driven rather than conversion-oriented. + +For in-page promotional content that is not at the top of the view, use a [hint](/components/hint/design-guidelines) or horizontal split card instead. + +### Placement + +- Place the hero at the top of the page content area, spanning the full content width. +- Do not place a hero in the middle or bottom of a page. +- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a `.pf-v6-c-compass__panel` container. +- Constrain text content with the hero body defaults (`bodyWidth` 800px, `bodyMaxWidth` 80%) so copy stays on the left and does not collide with a right-aligned background asset. + +
+![Hero placed at the top of a Compass-style layout over the page background, outside the main content panel.](./img/hero-placement.svg) +
+ +## Variants + +### Default + +Use by default on standard landing pages. Default heroes use asymmetric corner radii to reflect Red Hat brand styling (16px on the start-start and end-end corners; 48px on the start-end and end-start corners) and uniform 64px padding to draw attention. + +### Glass + +Use in glass theme contexts—especially Compass and generative UI layouts—when the hero sits directly over a background image rather than within a standard page section. + +Glass styling requires **both**: + +- The glass theme (`.pf-v6-theme-glass`), and +- The glass variant (`isGlass` in React, or `.pf-m-glass` in HTML/CSS) + +Glass heroes use a translucent background, backdrop blur, and the glass box shadow token. + +
+![Side-by-side comparison of the default hero and glass hero variants.](./img/hero-variants.svg) +
+ +**Note:** Compact, expandable, and dismissable variants are in design review and will be documented once implemented. + +## Content considerations + +Write hero content that is clear, concise, and action-oriented: + +| Element | Guidance | +| --- | --- | +| **Headline** | 1 short sentence. Lead with the core user benefit. Use sentence case. | +| **Description** | 1–2 sentences maximum. Add essential context without repeating the headline. | +| **Primary CTA** | Start with an action verb. Be specific ("Start free trial," not "Click here"). | +| **Secondary CTA** | Use for a lower-commitment or supporting action ("Learn more," "View documentation"). | + +- **CTA limit:** Use a maximum of 2 buttons. If more links are needed, put them in the description or in the page body below the hero. +- For voice and tone, follow [brand voice and tone](/ux-writing/brand-voice-and-tone). Hero copy should feel informative and supportive. + +## Visual content and responsive behavior + +### Brand assets + +- Apply visual assets as a **background image** (not a separate image slot). Position on the right, aligned to right-center (`background-position: right center`; `background-size: contain`). +- Ensure sufficient contrast between text and any part of the background the text might sit over. +- Provide distinct light- and dark-theme asset variants when using background imagery (`backgroundSrcLight` / `backgroundSrcDark` in React). + +### Responsive behavior + +- Keep the headline and description left-aligned within the hero body so they do not overlap the right-hand brand asset. +- On mobile and narrow viewports, **omit or override** the background image so content can stack cleanly. Hero does not hide the background asset automatically at small breakpoints. +- Call-to-action buttons may wrap to a second row on narrow viewports. + +
+![Desktop hero with a right-aligned brand asset next to a narrow viewport hero with the brand asset omitted and content stacked vertically.](./img/hero-responsive.svg) +
+ +### Gradients and backgrounds + +When using gradient overlays or background images, verify color contrast in both light and dark themes. If you remove the background asset, adjust `bodyWidth` and `bodyMaxWidth` as needed so text still reads well at large viewport sizes. + +## Spacing and typography reference + +### Hero container (implemented) + +| Spec / Element | Value | Token | +| --- | --- | --- | +| **Padding** | 64px (all sides) | `--pf-t--global--spacer--3xl` | +| **Body width** | 800px | `--pf-v6-c-hero__body--Width` | +| **Body max width** | 80% | `--pf-v6-c-hero__body--MaxWidth` | +| **Border radius (small corners)** | 16px | `--pf-t--global--border--radius--medium` | +| **Border radius (large corners)** | 48px | Custom value (no global token) | +| **Default background** | Tertiary fill | `--pf-t--global--background--color--tertiary--default` | +| **Glass background** | Glass primary | `--pf-t--global--background--color--glass--primary--default` | +| **Glass shadow** | Glass default | `--pf-t--global--box-shadow--glass--default` | + +### Recommended composition (not Hero CSS) + +These gaps come from nested content components (`Content`, `Flex`, `ActionList`), not from `.pf-v6-c-hero` itself: + +| Spec / Element | Recommended value | Token | +| --- | --- | --- | +| **Headline** | Heading XL (28px / ~36.4px line-height) | `--pf-t--global--font--size--heading--xl` | +| **Body** | Body large (16px / 24px line-height) | `--pf-t--global--font--size--body--lg` | +| **Headline → description gap** | 16px | `--pf-t--global--spacer--md` | +| **Content → CTAs gap** | 32px | `--pf-t--global--spacer--xl` | +| **CTA gap** | 16px between buttons | `--pf-t--global--spacer--gap--action-to-action--default` | diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg new file mode 100644 index 0000000000..04eb1fb0eb --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg @@ -0,0 +1,18 @@ + + Hero elements + Annotated default hero showing headline, description, call-to-action buttons, and optional right-aligned brand asset. Replace with final design export. + + + + + + 1. Headline + 2. Description  supporting context for the headline + + 3. Primary CTA + + Secondary CTA + + 4. Visual content + Placeholder  replace with Figma export (Default hero, annotated) + diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg new file mode 100644 index 0000000000..fb247c06ba --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg @@ -0,0 +1,15 @@ + + Hero placement in Compass layouts + Hero placed at the top of a Compass-style layout over the page background, outside the main content panel. Replace with final design export. + + + Masthead / navigation + + Glass hero + Sits over page background  not inside a compass panel + + + .pf-v6-c-compass__panel + Main page content lives here + Placeholder  replace with Figma/Compass placement screenshot + diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg new file mode 100644 index 0000000000..9fbcc46dd8 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg @@ -0,0 +1,21 @@ + + Hero responsive behavior + Desktop hero with a right-aligned brand asset next to a narrow viewport hero with the brand asset omitted and content stacked vertically. Replace with final design export. + + Desktop + + Hero title + Main body content + + + + Brand asset + Narrow / mobile + + Hero title + Main body content + + + Brand asset omitted + Placeholder  replace with Figma export (desktop vs mobile) + diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg new file mode 100644 index 0000000000..a80d3acf4f --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg @@ -0,0 +1,20 @@ + + Hero variants + Side-by-side comparison of the default hero and glass hero variants. Replace with final design export. + + Default + + Hero title + Main body content + + + + Glass + + Hero title + Main body content + + + + Placeholder  replace with Figma export (Default vs Glass) + From 84a69d6d359e25424ba4efca6baeb59d6e44f502 Mon Sep 17 00:00:00 2001 From: lboehling Date: Tue, 21 Jul 2026 17:59:36 -0400 Subject: [PATCH 02/10] docs(hero): replace placeholder guideline images with final SVGs Co-authored-by: Cursor --- .../components/hero/img/hero-elements.svg | 78 ++++-- .../components/hero/img/hero-placement.svg | 232 ++++++++++++++++-- .../components/hero/img/hero-responsive.svg | 223 +++++++++++++++-- .../components/hero/img/hero-variants.svg | 184 ++++++++++++-- 4 files changed, 647 insertions(+), 70 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg index 04eb1fb0eb..0976287514 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg @@ -1,18 +1,62 @@ - - Hero elements - Annotated default hero showing headline, description, call-to-action buttons, and optional right-aligned brand asset. Replace with final design export. - - - - - - 1. Headline - 2. Description  supporting context for the headline - - 3. Primary CTA - - Secondary CTA - - 4. Visual content - Placeholder  replace with Figma export (Default hero, annotated) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg index fb247c06ba..397f3b4e41 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-placement.svg @@ -1,15 +1,219 @@ - - Hero placement in Compass layouts - Hero placed at the top of a Compass-style layout over the page background, outside the main content panel. Replace with final design export. - - - Masthead / navigation - - Glass hero - Sits over page background  not inside a compass panel - - - .pf-v6-c-compass__panel - Main page content lives here - Placeholder  replace with Figma/Compass placement screenshot + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg index 9fbcc46dd8..6a8a62ded9 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg @@ -1,21 +1,204 @@ - - Hero responsive behavior - Desktop hero with a right-aligned brand asset next to a narrow viewport hero with the brand asset omitted and content stacked vertically. Replace with final design export. - - Desktop - - Hero title - Main body content - - - - Brand asset - Narrow / mobile - - Hero title - Main body content - - - Brand asset omitted - Placeholder  replace with Figma export (desktop vs mobile) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg index a80d3acf4f..6bd7377d87 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-variants.svg @@ -1,20 +1,166 @@ - - Hero variants - Side-by-side comparison of the default hero and glass hero variants. Replace with final design export. - - Default - - Hero title - Main body content - - - - Glass - - Hero title - Main body content - - - - Placeholder  replace with Figma export (Default vs Glass) + + + + + + + + + + + + + + + + + + + + + +
 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 4968fbab66af3d7864a8b2e4d80b75b890829a0b Mon Sep 17 00:00:00 2001 From: lboehling Date: Tue, 21 Jul 2026 18:03:42 -0400 Subject: [PATCH 03/10] docs(hero): update Compass placement guidance for Panel layout Clarify that Glass heroes sit over the page background, not inside Panel or the Compass main-header/content regions. Co-authored-by: Cursor --- .../patternfly-docs/content/components/hero/hero.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index ad268445bc..7aec818e31 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -46,11 +46,11 @@ For in-page promotional content that is not at the top of the view, use a [hint] - Place the hero at the top of the page content area, spanning the full content width. - Do not place a hero in the middle or bottom of a page. -- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a `.pf-v6-c-compass__panel` container. +- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a [Panel](/components/panel) (`.pf-v6-c-panel`), or within `.pf-v6-c-compass__main-header` or `.pf-v6-c-compass__content`. Those regions typically make up the Compass page layout, with panels nested inside them. - Constrain text content with the hero body defaults (`bodyWidth` 800px, `bodyMaxWidth` 80%) so copy stays on the left and does not collide with a right-aligned background asset.
-![Hero placed at the top of a Compass-style layout over the page background, outside the main content panel.](./img/hero-placement.svg) +![Hero placed at the top of a Compass-style layout over the page background, outside the main header and content regions.](./img/hero-placement.svg)
## Variants From 46cdf6016e6ec646aa6129baf76c635c9ba7e1e3 Mon Sep 17 00:00:00 2001 From: lboehling Date: Tue, 21 Jul 2026 18:05:11 -0400 Subject: [PATCH 04/10] docs(hero): trim Compass placement sentence Co-authored-by: Cursor --- .../patternfly-docs/content/components/hero/hero.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index 7aec818e31..1a8e31187f 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -46,7 +46,7 @@ For in-page promotional content that is not at the top of the view, use a [hint] - Place the hero at the top of the page content area, spanning the full content width. - Do not place a hero in the middle or bottom of a page. -- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a [Panel](/components/panel) (`.pf-v6-c-panel`), or within `.pf-v6-c-compass__main-header` or `.pf-v6-c-compass__content`. Those regions typically make up the Compass page layout, with panels nested inside them. +- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a [Panel](/components/panel) (`.pf-v6-c-panel`), or within `.pf-v6-c-compass__main-header` or `.pf-v6-c-compass__content`. - Constrain text content with the hero body defaults (`bodyWidth` 800px, `bodyMaxWidth` 80%) so copy stays on the left and does not collide with a right-aligned background asset.
From a35eb666463e55bed70a0a363f27c755cd1df4a8 Mon Sep 17 00:00:00 2001 From: lboehling Date: Tue, 21 Jul 2026 18:10:55 -0400 Subject: [PATCH 05/10] docs(hero): remove parenthetical asides outside spacing tables Co-authored-by: Cursor --- .../content/components/hero/hero.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index 1a8e31187f..fa191bed9a 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -16,10 +16,10 @@ A hero is a compositional container. Structure content with PatternFly typograph ![Annotated default hero showing headline, description, call-to-action buttons, and optional right-aligned brand asset.](./img/hero-elements.svg)
-1. **Headline:** A concise statement about the offering or page purpose. Use heading XL typography (28px, Red Hat Display Medium). On a landing page, this should typically be the page `h1`. -2. **Description:** Supporting context for the headline. Use body large typography (16px). -3. **Visual content (optional):** A right-aligned brand asset applied as a background image. Decorative assets should support the message without competing with text. -4. **Call to action(s):** Include at least one primary action; one secondary or tertiary action is optional. Use [CTA buttons](/components/button#call-to-action-cta-buttons) at size `lg`. +1. **Headline:** A concise statement about the offering or page purpose. Use heading XL typography. On a landing page, this should typically be the page `h1`. +2. **Description:** Supporting context for the headline. Use body large typography. +3. **Optional visual content:** A right-aligned brand asset applied as a background image. Decorative assets should support the message without competing with text. +4. **Calls to action:** Include at least one primary action; one secondary or tertiary action is optional. Use [CTA buttons](/components/button#call-to-action-cta-buttons) at size `lg`. ## Usage @@ -31,13 +31,13 @@ Use a hero when the primary purpose of the page is to: - Introduce a new product, feature, or campaign. - Drive users toward a specific high-value action or conversion. -Common placements include homepages, product landing pages, and main dashboard landing views (such as Compass). +Common placements include homepages, product landing pages, and main dashboard landing views such as Compass. ### When not to use Do not use a hero as a generic page header on: -- Pages focused on content discovery, data management, or dense workflows (use a standard page header instead). +- Pages focused on content discovery, data management, or dense workflows. Use a standard page header instead. - Detail views, settings pages, or views where the user's primary task is utility- or task-driven rather than conversion-oriented. For in-page promotional content that is not at the top of the view, use a [hint](/components/hint/design-guidelines) or horizontal split card instead. @@ -46,8 +46,8 @@ For in-page promotional content that is not at the top of the view, use a [hint] - Place the hero at the top of the page content area, spanning the full content width. - Do not place a hero in the middle or bottom of a page. -- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a [Panel](/components/panel) (`.pf-v6-c-panel`), or within `.pf-v6-c-compass__main-header` or `.pf-v6-c-compass__content`. -- Constrain text content with the hero body defaults (`bodyWidth` 800px, `bodyMaxWidth` 80%) so copy stays on the left and does not collide with a right-aligned background asset. +- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a [Panel](/components/panel), or within `.pf-v6-c-compass__main-header` or `.pf-v6-c-compass__content`. +- Constrain text content with the hero body defaults so copy stays on the left and does not collide with a right-aligned background asset. Use `bodyWidth` 800px and `bodyMaxWidth` 80%.
![Hero placed at the top of a Compass-style layout over the page background, outside the main header and content regions.](./img/hero-placement.svg) @@ -57,7 +57,7 @@ For in-page promotional content that is not at the top of the view, use a [hint] ### Default -Use by default on standard landing pages. Default heroes use asymmetric corner radii to reflect Red Hat brand styling (16px on the start-start and end-end corners; 48px on the start-end and end-start corners) and uniform 64px padding to draw attention. +Use by default on standard landing pages. Default heroes use asymmetric corner radii to reflect Red Hat brand styling and uniform 64px padding to draw attention. ### Glass @@ -65,8 +65,8 @@ Use in glass theme contexts—especially Compass and generative UI layouts&m Glass styling requires **both**: -- The glass theme (`.pf-v6-theme-glass`), and -- The glass variant (`isGlass` in React, or `.pf-m-glass` in HTML/CSS) +- The glass theme, `.pf-v6-theme-glass`, and +- The glass variant, `isGlass` in React or `.pf-m-glass` in HTML/CSS Glass heroes use a translucent background, backdrop blur, and the glass box shadow token. @@ -84,8 +84,8 @@ Write hero content that is clear, concise, and action-oriented: | --- | --- | | **Headline** | 1 short sentence. Lead with the core user benefit. Use sentence case. | | **Description** | 1–2 sentences maximum. Add essential context without repeating the headline. | -| **Primary CTA** | Start with an action verb. Be specific ("Start free trial," not "Click here"). | -| **Secondary CTA** | Use for a lower-commitment or supporting action ("Learn more," "View documentation"). | +| **Primary CTA** | Start with an action verb. Be specific—for example, "Start free trial," not "Click here". | +| **Secondary CTA** | Use for a lower-commitment or supporting action such as "Learn more" or "View documentation". | - **CTA limit:** Use a maximum of 2 buttons. If more links are needed, put them in the description or in the page body below the hero. - For voice and tone, follow [brand voice and tone](/ux-writing/brand-voice-and-tone). Hero copy should feel informative and supportive. @@ -94,9 +94,9 @@ Write hero content that is clear, concise, and action-oriented: ### Brand assets -- Apply visual assets as a **background image** (not a separate image slot). Position on the right, aligned to right-center (`background-position: right center`; `background-size: contain`). +- Apply visual assets as a **background image**, not a separate image slot. Position on the right, aligned to right-center. Use `background-position: right center` and `background-size: contain`. - Ensure sufficient contrast between text and any part of the background the text might sit over. -- Provide distinct light- and dark-theme asset variants when using background imagery (`backgroundSrcLight` / `backgroundSrcDark` in React). +- Provide distinct light- and dark-theme asset variants when using background imagery. In React, use `backgroundSrcLight` and `backgroundSrcDark`. ### Responsive behavior From 2edbe2f4545f74b8c559867f63ec860028c8ea64 Mon Sep 17 00:00:00 2001 From: lboehling Date: Tue, 21 Jul 2026 18:12:28 -0400 Subject: [PATCH 06/10] docs(hero): restore body copy; trim spacing section headings only Revert the broader parentheses cleanup and only remove parenthetical text from the Hero container and Recommended composition headings. Co-authored-by: Cursor --- .../content/components/hero/hero.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index fa191bed9a..242f5a42e8 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -16,10 +16,10 @@ A hero is a compositional container. Structure content with PatternFly typograph ![Annotated default hero showing headline, description, call-to-action buttons, and optional right-aligned brand asset.](./img/hero-elements.svg)
-1. **Headline:** A concise statement about the offering or page purpose. Use heading XL typography. On a landing page, this should typically be the page `h1`. -2. **Description:** Supporting context for the headline. Use body large typography. -3. **Optional visual content:** A right-aligned brand asset applied as a background image. Decorative assets should support the message without competing with text. -4. **Calls to action:** Include at least one primary action; one secondary or tertiary action is optional. Use [CTA buttons](/components/button#call-to-action-cta-buttons) at size `lg`. +1. **Headline:** A concise statement about the offering or page purpose. Use heading XL typography (28px, Red Hat Display Medium). On a landing page, this should typically be the page `h1`. +2. **Description:** Supporting context for the headline. Use body large typography (16px). +3. **Visual content (optional):** A right-aligned brand asset applied as a background image. Decorative assets should support the message without competing with text. +4. **Call to action(s):** Include at least one primary action; one secondary or tertiary action is optional. Use [CTA buttons](/components/button#call-to-action-cta-buttons) at size `lg`. ## Usage @@ -31,13 +31,13 @@ Use a hero when the primary purpose of the page is to: - Introduce a new product, feature, or campaign. - Drive users toward a specific high-value action or conversion. -Common placements include homepages, product landing pages, and main dashboard landing views such as Compass. +Common placements include homepages, product landing pages, and main dashboard landing views (such as Compass). ### When not to use Do not use a hero as a generic page header on: -- Pages focused on content discovery, data management, or dense workflows. Use a standard page header instead. +- Pages focused on content discovery, data management, or dense workflows (use a standard page header instead). - Detail views, settings pages, or views where the user's primary task is utility- or task-driven rather than conversion-oriented. For in-page promotional content that is not at the top of the view, use a [hint](/components/hint/design-guidelines) or horizontal split card instead. @@ -46,8 +46,8 @@ For in-page promotional content that is not at the top of the view, use a [hint] - Place the hero at the top of the page content area, spanning the full content width. - Do not place a hero in the middle or bottom of a page. -- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a [Panel](/components/panel), or within `.pf-v6-c-compass__main-header` or `.pf-v6-c-compass__content`. -- Constrain text content with the hero body defaults so copy stays on the left and does not collide with a right-aligned background asset. Use `bodyWidth` 800px and `bodyMaxWidth` 80%. +- In Compass or layered layouts, place a Glass hero directly over the page background—not inside a [Panel](/components/panel) (`.pf-v6-c-panel`), or within `.pf-v6-c-compass__main-header` or `.pf-v6-c-compass__content`. +- Constrain text content with the hero body defaults (`bodyWidth` 800px, `bodyMaxWidth` 80%) so copy stays on the left and does not collide with a right-aligned background asset.
![Hero placed at the top of a Compass-style layout over the page background, outside the main header and content regions.](./img/hero-placement.svg) @@ -57,7 +57,7 @@ For in-page promotional content that is not at the top of the view, use a [hint] ### Default -Use by default on standard landing pages. Default heroes use asymmetric corner radii to reflect Red Hat brand styling and uniform 64px padding to draw attention. +Use by default on standard landing pages. Default heroes use asymmetric corner radii to reflect Red Hat brand styling (16px on the start-start and end-end corners; 48px on the start-end and end-start corners) and uniform 64px padding to draw attention. ### Glass @@ -65,8 +65,8 @@ Use in glass theme contexts—especially Compass and generative UI layouts&m Glass styling requires **both**: -- The glass theme, `.pf-v6-theme-glass`, and -- The glass variant, `isGlass` in React or `.pf-m-glass` in HTML/CSS +- The glass theme (`.pf-v6-theme-glass`), and +- The glass variant (`isGlass` in React, or `.pf-m-glass` in HTML/CSS) Glass heroes use a translucent background, backdrop blur, and the glass box shadow token. @@ -84,8 +84,8 @@ Write hero content that is clear, concise, and action-oriented: | --- | --- | | **Headline** | 1 short sentence. Lead with the core user benefit. Use sentence case. | | **Description** | 1–2 sentences maximum. Add essential context without repeating the headline. | -| **Primary CTA** | Start with an action verb. Be specific—for example, "Start free trial," not "Click here". | -| **Secondary CTA** | Use for a lower-commitment or supporting action such as "Learn more" or "View documentation". | +| **Primary CTA** | Start with an action verb. Be specific ("Start free trial," not "Click here"). | +| **Secondary CTA** | Use for a lower-commitment or supporting action ("Learn more," "View documentation"). | - **CTA limit:** Use a maximum of 2 buttons. If more links are needed, put them in the description or in the page body below the hero. - For voice and tone, follow [brand voice and tone](/ux-writing/brand-voice-and-tone). Hero copy should feel informative and supportive. @@ -94,9 +94,9 @@ Write hero content that is clear, concise, and action-oriented: ### Brand assets -- Apply visual assets as a **background image**, not a separate image slot. Position on the right, aligned to right-center. Use `background-position: right center` and `background-size: contain`. +- Apply visual assets as a **background image** (not a separate image slot). Position on the right, aligned to right-center (`background-position: right center`; `background-size: contain`). - Ensure sufficient contrast between text and any part of the background the text might sit over. -- Provide distinct light- and dark-theme asset variants when using background imagery. In React, use `backgroundSrcLight` and `backgroundSrcDark`. +- Provide distinct light- and dark-theme asset variants when using background imagery (`backgroundSrcLight` / `backgroundSrcDark` in React). ### Responsive behavior @@ -114,7 +114,7 @@ When using gradient overlays or background images, verify color contrast in both ## Spacing and typography reference -### Hero container (implemented) +### Hero container | Spec / Element | Value | Token | | --- | --- | --- | @@ -127,7 +127,7 @@ When using gradient overlays or background images, verify color contrast in both | **Glass background** | Glass primary | `--pf-t--global--background--color--glass--primary--default` | | **Glass shadow** | Glass default | `--pf-t--global--box-shadow--glass--default` | -### Recommended composition (not Hero CSS) +### Recommended composition These gaps come from nested content components (`Content`, `Flex`, `ActionList`), not from `.pf-v6-c-hero` itself: From 9eeff3810cd0e1812724fb4cb5cfa1c6e802ed67 Mon Sep 17 00:00:00 2001 From: Lucia Boehling <46571616+lboehling@users.noreply.github.com> Date: Wed, 22 Jul 2026 16:56:42 -0400 Subject: [PATCH 07/10] Update packages/documentation-site/patternfly-docs/content/components/hero/hero.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com> --- .../patternfly-docs/content/components/hero/hero.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index 242f5a42e8..c7fb4e944d 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -94,7 +94,7 @@ Write hero content that is clear, concise, and action-oriented: ### Brand assets -- Apply visual assets as a **background image** (not a separate image slot). Position on the right, aligned to right-center (`background-position: right center`; `background-size: contain`). +- Apply visual assets as a **background image** (not a separate image slot). Position on the right, aligned to right-center (`background-position: right center`, `background-size: contain`). - Ensure sufficient contrast between text and any part of the background the text might sit over. - Provide distinct light- and dark-theme asset variants when using background imagery (`backgroundSrcLight` / `backgroundSrcDark` in React). From 8c9702ab835e3e4f417c4e6393afbef0039e322a Mon Sep 17 00:00:00 2001 From: lboehling Date: Mon, 27 Jul 2026 16:15:45 -0400 Subject: [PATCH 08/10] docs(hero): use beta inline alert on design guidelines Replace the manual beta notice with frontmatter beta: true so the design guidelines tab shows the same beta alert as HTML/React. Co-authored-by: Cursor --- .../content/components/hero/hero.md | 5 +- .../components/hero/img/hero-elements.svg | 103 +++++++++--------- 2 files changed, 52 insertions(+), 56 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index c7fb4e944d..c60eb60a1b 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -1,12 +1,11 @@ --- id: Hero section: components +beta: true --- import '../components.css'; -Use a hero at the top of a homepage or landing page to introduce a clear value proposition and primary call to action. - -Hero is currently a [beta component](/get-started/about-PatternFly#beta-components). These guidelines reflect what is implemented today and may evolve as the component matures. +Use a hero at the top of a home page or landing page to introduce a clear value proposition and primary call to action. ## Elements diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg index 0976287514..8d1172b750 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-elements.svg @@ -1,62 +1,59 @@ - - - - - - + + + + + + - - - - - - - + + + + + + + - - + + - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - + + + + + + + + + + + + + - - + + From 437d5357d6bc7d8ff2016d02dab26f88ee4b0f45 Mon Sep 17 00:00:00 2001 From: lboehling Date: Mon, 27 Jul 2026 16:18:17 -0400 Subject: [PATCH 09/10] docs: prefer "home page" over "homepage" in guidelines Align Hero and Masthead design guideline terminology with the PatternFly content-design glossary. Co-authored-by: Cursor --- .../patternfly-docs/content/components/hero/hero.md | 2 +- .../patternfly-docs/content/components/masthead/masthead.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index c60eb60a1b..c6c01128e5 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -30,7 +30,7 @@ Use a hero when the primary purpose of the page is to: - Introduce a new product, feature, or campaign. - Drive users toward a specific high-value action or conversion. -Common placements include homepages, product landing pages, and main dashboard landing views (such as Compass). +Common placements include home pages, product landing pages, and main dashboard landing views (such as Compass). ### When not to use diff --git a/packages/documentation-site/patternfly-docs/content/components/masthead/masthead.md b/packages/documentation-site/patternfly-docs/content/components/masthead/masthead.md index 3467185a5b..8dac79d54a 100644 --- a/packages/documentation-site/patternfly-docs/content/components/masthead/masthead.md +++ b/packages/documentation-site/patternfly-docs/content/components/masthead/masthead.md @@ -9,7 +9,7 @@ section: components **1. Show/hide menu:** The `fa-bars` icon at the left of the masthead provides a way for users to show or hide the vertical navigation. It is not included when horizontal navigation is being used. At large viewport (desktop) sizes, navigation is shown, by default, and the user can click this icon to hide it and expand the content area. Once hidden, the user can click the icon again to reveal it. At small viewport (tablet and phone) sizes, the vertical navigation will be hidden by default and the user must use this control to open the menu. -**2. Logotype:** The logotype area should clearly display the application name and the application logo if applicable. It is common to link the logotype to the application’s homepage. It is recommended to have the application name in .svg format for better performance. +**2. Logotype:** The logotype area should clearly display the application name and the application logo if applicable. It is common to link the logotype to the application’s home page. It is recommended to have the application name in .svg format for better performance. **3. Utility items:** Place any items in the utility area that you want to have accessible from all pages in the application. Utility items are right aligned and placed to the left of the user menu. The following are common items ordered from left to right. All items are optional depending on the needs of your application. From 347bc23ec44f16582889ad66c3ecb050765a43f7 Mon Sep 17 00:00:00 2001 From: lboehling Date: Fri, 31 Jul 2026 11:31:29 -0400 Subject: [PATCH 10/10] docs(hero): clarify glass placement and link horizontal split card Note that glass theme belongs on html and the glass variant on the hero, and link the horizontal split card alternative. Co-authored-by: Cursor --- .../content/components/hero/hero.md | 6 +- .../components/hero/img/hero-responsive.svg | 124 ++++++++++-------- 2 files changed, 70 insertions(+), 60 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md index c6c01128e5..d5b4f42714 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/hero.md +++ b/packages/documentation-site/patternfly-docs/content/components/hero/hero.md @@ -39,7 +39,7 @@ Do not use a hero as a generic page header on: - Pages focused on content discovery, data management, or dense workflows (use a standard page header instead). - Detail views, settings pages, or views where the user's primary task is utility- or task-driven rather than conversion-oriented. -For in-page promotional content that is not at the top of the view, use a [hint](/components/hint/design-guidelines) or horizontal split card instead. +For in-page promotional content that is not at the top of the view, use a [hint](/components/hint/design-guidelines) or [horizontal split card](/components/card/react-demos#horizontal-split) instead. ### Placement @@ -64,8 +64,8 @@ Use in glass theme contexts—especially Compass and generative UI layouts&m Glass styling requires **both**: -- The glass theme (`.pf-v6-theme-glass`), and -- The glass variant (`isGlass` in React, or `.pf-m-glass` in HTML/CSS) +- The glass theme (`.pf-v6-theme-glass`) on the `` element +- The glass variant (`isGlass` in React, or `.pf-m-glass` in HTML/CSS) on the hero component Glass heroes use a translucent background, backdrop blur, and the glass box shadow token. diff --git a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg index 6a8a62ded9..082c8473a7 100644 --- a/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg +++ b/packages/documentation-site/patternfly-docs/content/components/hero/img/hero-responsive.svg @@ -1,50 +1,50 @@ - + - - + + - + - - + + - - + + - + - - - + + + - + - + - + - + @@ -65,13 +65,13 @@ - + - - - + + + @@ -79,6 +79,11 @@ + + + + + @@ -87,117 +92,122 @@ - - + + - + - + - + - + - + - - + + - + - - + + - - + + - + - - - + + + - + - + - + - - - + + + - - + + + + + + + - + - + - + - + - + - + - + - + - + - + - +