Added variant support to Hero.Description (#867)

Author: rezrah

.changeset/perfect-needles-guess.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+`Hero.Description` updated to support `variant="muted"`

apps/docs/content/components/Hero/index.mdx

@@ -21,7 +21,9 @@ export default ComponentLayout
 
 Use the hero component to provide a title, description and action that introduces the main content of a page. The hero component is designed to be positioned at the top of a page and spans the full width of the viewport. Consider using the [CTA banner](/components/CTABanner) to replicate the content and actions in other parts of the page.
 
-Both heading and description of the hero should be short and descriptive. Heading should be not be longer than 2 lines, and description should be no longer than 3-4 lines.
+Both the heading and description of the hero should be concise and descriptive. The heading should not exceed two lines, and the description should be limited to 3–4 lines.
+
+The description must maintain a minimum contrast ratio of 4.5:1 at all times. Since it may appear in either the `default` or `muted` text colors, ensure the `muted` variant is used only when contrast is sufficient and no background imagery is present.
 
 The hero component is not designed to provide a lot of information to the user. Consider using other components, such as the [section intro](/components/SectionIntro) or the [river](/components/River) component instead.
 
@@ -47,8 +49,6 @@ The hero can optionally include primary and secondary actions. These actions are
 
 ## Options
 
-
-
 ### Alignment
 
 Hero elements can be aligned to the start or center of the page. By default, the hero is aligned to the start of the page to allow for an image or a visual asset to be positioned on the right of the hero. Use the center alignment if the asset is centered or not present, or the scenario calls for it.

apps/docs/content/components/Hero/react.mdx

@@ -16,6 +16,8 @@ import {
   HeadingStretch,
   defaultHeadingTag,
   HeadingLetterSpacing,
+  TextVariants,
+  defaultTextVariant,
 } from '@primer/react-brand'
 import {Label} from '@primer/react'
 import {PropTableValues} from '../../../src/components'
@@ -121,9 +123,10 @@ Forwards all props from the [Heading component](/components/Heading), including
 
 ### Hero.Description
 
-| name        | type     | default | description             |
-| ----------- | -------- | ------- | ----------------------- |
-| `className` | `string` |         | Sets a custom CSS class |
+| name        | type                                                    | default                                           | description                         |
+| ----------- | ------------------------------------------------------- | ------------------------------------------------- | ----------------------------------- |
+| `className` | `string`                                                |                                                   | Sets a custom CSS class             |
+| `variant`   | <PropTableValues values={TextVariants} addLineBreaks /> | <PropTableValues values={[defaultTextVariant]} /> | Specify alternative text appearance |
 
 Forwards `size` and `weight` props from the [Text component](/components/Text).
 

apps/docs/scripts/components-with-animation.js

@@ -9,8 +9,8 @@ export const supportedComponents = [
   'Image',
   'Label',
   'Pillar',
-  'Stack',
   'SectionIntro',
+  'Stack',
   'Statistic',
   'Testimonial',
   'Text',

packages/react/src/Hero/Hero.features.stories.tsx

@@ -32,6 +32,18 @@ export const Centered: StoryFn<typeof Hero> = _args => (
   </Hero>
 )
 
+export const WithMutedDescriptions: StoryFn<typeof Hero> = _args => (
+  <Hero align="center">
+    <Hero.Label>Label</Hero.Label>
+    <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
+    <Hero.Description variant="muted">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+      felis nam pulvinar risus elementum.
+    </Hero.Description>
+    <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
+  </Hero>
+)
+
 export const WithImageBlockEndDefault: StoryFn<typeof Hero> = _args => (
   <Grid>
     <Grid.Column>

packages/react/src/Hero/Hero.tsx

@@ -3,7 +3,7 @@ import clsx from 'clsx'
 import styles from './Hero.module.css'
 import {Button, ButtonBaseProps} from '../Button'
 import {Heading, HeadingProps} from '../Heading'
-import {Text, TextSizes, TextWeightVariants, ResponsiveWeightMap} from '../Text'
+import {Text, TextSizes, TextWeightVariants, ResponsiveWeightMap, TextProps} from '../Text'
 import {Label, LabelProps} from '../Label'
 import {Image, ImageProps} from '../Image'
 import {Grid} from '../Grid'
@@ -133,12 +133,20 @@ const HeroHeading = forwardRef<HTMLHeadingElement, HeroHeadingProps>(({children,
 type HeroDescriptionProps = {
   size?: (typeof TextSizes)[number]
   weight?: TextWeightVariants | ResponsiveWeightMap
-} & BaseProps<HTMLParagraphElement>
+} & BaseProps<HTMLParagraphElement> &
+  TextProps
 
 const HeroDescription = forwardRef<HTMLParagraphElement, PropsWithChildren<HeroDescriptionProps>>(
-  ({size = '200', weight, children, className}: PropsWithChildren<HeroDescriptionProps>, ref) => {
+  ({size = '200', weight, children, variant = 'default', className}: PropsWithChildren<HeroDescriptionProps>, ref) => {
     return (
-      <Text ref={ref} className={clsx(styles['Hero-description'], className)} as="p" size={size} weight={weight}>
+      <Text
+        ref={ref}
+        className={clsx(styles['Hero-description'], className)}
+        as="p"
+        size={size}
+        weight={weight}
+        variant={variant}
+      >
         {children}
       </Text>
     )

packages/react/src/Hero/Hero.visual.spec.ts

@@ -21,6 +21,15 @@ test.describe('Visual Comparison: Hero', () => {
     expect(await page.screenshot({fullPage: true})).toMatchSnapshot()
   })
 
+  test('Hero / With Muted Descriptions', async ({page}) => {
+    await page.goto(
+      'http://localhost:6006/iframe.html?args=&id=components-hero-features--with-muted-descriptions&viewMode=story',
+    )
+
+    await page.waitForTimeout(500)
+    expect(await page.screenshot({fullPage: true})).toMatchSnapshot()
+  })
+
   test('Hero / With an image (left + bottom)', async ({page}) => {
     await page.goto(
       'http://localhost:6006/iframe.html?args=&id=components-hero-features--with-image-block-end-default&viewMode=story',