Update Heading

[flacoman91]

This doesn't change any of the underlying code, but it:

• updates props to pass child nodes into the Heading tag.
• add in a heading example that contains an Icon to show what we see in Complaint Explorer landing page

This prevents the nag warnings when passing in child elements such as Icons in the heading text

https://cfpb.github.io/design-system-react/pr-previews/pr-583/?path=/docs/components-verified-headings--overview&globals=responsivePreview:all

Breakout of #560

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cfpb.github.io/design-system-react/pr-previews/pr-583/
Built to branch gh-pages at 2026-05-19 16:55 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[natalia-fitzgerald]

@flacoman91
Is this duplicative with this: https://cfpb.github.io/design-system-react/?path=/story/components-draft-icons--icon-with-text

[flacoman91]

@flacoman91 Is this duplicative with this: https://cfpb.github.io/design-system-react/?path=/story/components-draft-icons--icon-with-text

The example I added, Heading with icon in the story seems redundant.
I can remove it, but it wasn't the first place I went to when looking for an example with a heading containing an icon w/ text. What do you think about adding a linking to the Icon story for those cases?

[natalia-fitzgerald]

@flacoman91
Putting "Icons with text" with the "Icons" component is consistent with how we handle this in the CFPB Design System. That doesn't mean it's the best approach, just that it's consistent with the existing approach. https://cfpb.github.io/design-system/foundation/iconography#icons-with-text-1 With that being said, in the DS and DSR, "Icons with text" is primarily meant to illustrate that icons should always appear with text.

If we include a story for "Heading with icon" in the way that you have set it up here, does it seem like we are recommend putting an icon next to an Heading 2? Or are we just providing the code needed to do so? The more common headings that are used with icons are smaller heading levels so if we want to show an example can we use an Heading 3 or Heading 4 with icon instead of a Heading 2 with icon?

Another option is that we move the table from icons with text and put it in Heading with icon. Then in Icon with text we could leave the documentation paragraph and show a basic example of an icon paired with text. And from that documentation page we could link to "heading with icon."

What's your preference?

[flacoman91]

@natalia-fitzgerald I wanted it in heading to have a code example since the way we do it with a Button or Link component is not the same even though they kind of look the same.

In the link / button we say iconLeft or iconRight

to have it render an icon on the respective side.

In Heading, it's inserted through child elements like
<Heading><Icon name="taxes" >Lorem ipsum</Heading>

I prefer having the documentation on the Heading page for the example on how to use it.

I'm ok with moving the Icon w/ text Table over to the Heading section, or give the heading with icon its own section kinda like how we do it for the

link with icon
https://cfpb.github.io/design-system-react/?path=/story/components-verified-links--with-icon

or button with icon
https://cfpb.github.io/design-system-react/?path=/story/components-verified-buttons--static-icon-buttons

Headings and Paragraph with icon can have their own with icons sections too.