[v12] feat(ui-heading): rework Heading #2365

ToMESSKa · 2026-01-15T15:20:23Z

INSTUI-4869

ISSUE:

Heading needs to be migrated to the new theming system

TEST PLAN:

compare the component to the Figma design https://www.figma.com/design/5WFqF3HVlNdfcJooCaiFoh/InstUI-Component-Library---Beta?node-id=9871-951&p=f&m=dev
check if all tokens are used in styles.ts
check if the component works the same as before
check the icons gaps (gap between the icon and the text) and icon sizes for each variant/level/as prop value against the Figma and the v11 version:

<div>
  <Heading variant="titlePageDesktop" level="h1" renderIcon={<IconAdminSolid/>}>titlePageDesktop</Heading><br/>
  <Heading variant="titlePageMobile" level="h1" renderIcon={<IconAdminSolid/>}>titlePageMobile</Heading><br/>
  <Heading variant="titleSection" level="h2" renderIcon={<IconAdminSolid/>}>titleSection</Heading><br/>
  <Heading variant="titleCardSection" level="h2" renderIcon={<IconAdminSolid/>}>titleCardSection</Heading><br/>
  <Heading variant="titleModule" level="h2" renderIcon={<IconAdminSolid/>}>titleModule</Heading><br/>
  <Heading variant="titleCardLarge" level="h3" renderIcon={<IconAdminSolid/>}>titleCardLarge</Heading><br/>
  <Heading variant="titleCardRegular" level="h3" renderIcon={<IconAdminSolid/>}>titleCardRegular</Heading><br/>
  <Heading variant="titleCardMini" level="h4" renderIcon={<IconAdminSolid/>}>titleCardMini</Heading><br/>
  <Heading variant="label" level="h5" renderIcon={<IconAdminSolid/>}>label</Heading><br/>
  <Heading variant="labelInline" level="h6" renderIcon={<IconAdminSolid/>}>labelInline</Heading><br/>
</div>

<div>
  <Heading level="h1" renderIcon={<IconAdminSolid/>}>titlePageDesktop</Heading><br/>
  <Heading level="h2" renderIcon={<IconAdminSolid/>}>titlePageMobile</Heading><br/>
  <Heading level="h3" renderIcon={<IconAdminSolid/>}>titleSection</Heading><br/>
  <Heading level="h4" renderIcon={<IconAdminSolid/>}>titleCardSection</Heading><br/>
  <Heading level="h5" renderIcon={<IconAdminSolid/>}>titleModule</Heading><br/>
  <Heading level="h6" renderIcon={<IconAdminSolid/>}>titleCardLarge</Heading><br/>
</div>

<div>
  <Heading as="h1" renderIcon={<IconAdminSolid/>}>titlePageDesktop</Heading><br/>
  <Heading as="h2" renderIcon={<IconAdminSolid/>}>titlePageMobile</Heading><br/>
  <Heading as="h3" renderIcon={<IconAdminSolid/>}>titleSection</Heading><br/>
  <Heading as="h4" renderIcon={<IconAdminSolid/>}>titleCardSection</Heading><br/>
  <Heading as="h5" renderIcon={<IconAdminSolid/>}>titleModule</Heading><br/>
  <Heading as="h6" renderIcon={<IconAdminSolid/>}>titleCardLarge</Heading><br/>
</div>

<div>
  <Heading variant="titlePageDesktop" renderIcon={<IconAdminSolid/>}>titlePageDesktop</Heading><br/>
  <Heading variant="titlePageMobile" renderIcon={<IconAdminSolid/>}>titlePageMobile</Heading><br/>
  <Heading variant="titleSection" renderIcon={<IconAdminSolid/>}>titleSection</Heading><br/>
  <Heading variant="titleCardSection" renderIcon={<IconAdminSolid/>}>titleCardSection</Heading><br/>
  <Heading variant="titleModule" renderIcon={<IconAdminSolid/>}>titleModule</Heading><br/>
  <Heading variant="titleCardLarge" renderIcon={<IconAdminSolid/>}>titleCardLarge</Heading><br/>
  <Heading variant="titleCardRegular" renderIcon={<IconAdminSolid/>}>titleCardRegular</Heading><br/>
  <Heading variant="titleCardMini" renderIcon={<IconAdminSolid/>}>titleCardMini</Heading><br/>
  <Heading variant="label" renderIcon={<IconAdminSolid/>}>label</Heading><br/>
  <Heading variant="labelInline" renderIcon={<IconAdminSolid/>}>labelInline</Heading><br/>
</div>

check the AI variants
check if everything looks visible in dark mode

github-actions · 2026-01-15T15:24:46Z

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2365/
Built to branch `gh-pages` at 2026-01-23 09:12 UTC. Preview will be ready when the GitHub Pages deployment is complete.

ToMESSKa · 2026-01-15T15:43:40Z

packages/ui-heading/src/Heading/styles.ts

-      fontWeight: componentTheme.weightImportant,
-      fontSize: componentTheme.titlePageDesktop,
-      lineHeight: componentTheme.lineHeight125
+      ...componentTheme.titlePageDesktop


this is a composit token now

ToMESSKa · 2026-01-15T15:46:50Z

packages/ui-heading/src/Heading/index.tsx

-    if (aiVariant === 'stacked') {
-      return (
-        <>
-          <span css={this.props.styles?.igniteAIStacked}>
-            <IconAiColoredSolid />
-            <span css={this.props.styles?.igniteAI}>IgniteAI</span>
-          </span>
-          {children}
-        </>
-      )
-    }
-    if (aiVariant === 'horizontal') {
-      return (
-        <>
-          <IconAiColoredSolid />
-          <span css={this.props.styles?.igniteAI}>IgniteAI</span>
+          <StarsInstUIIcon color="ai" size="sm" />
          {children}
-        </>
-      )
-    }
-    if (aiVariant === 'iconOnly') {
-      return (
-        <>
-          <IconAiColoredSolid />
-          &nbsp;{children}
-        </>


I think this is some dead code/duplication as the 'stacked', 'horizontal' and 'iconOnly' AI cases are already checked above...(?)

adamlobler · 2026-01-16T11:05:19Z

packages/ui-heading/src/Heading/index.tsx

      return (
        <span css={[this.props.styles?.withIcon]} aria-hidden="true">
-          {callRenderProp(renderIcon)}&nbsp;{children}
+          {renderIconWithProps(renderIcon, iconSize, 'inherit')}


there was a "none breaking space" here before the heading text that is missing

before:

after:

I set a gap for that, can you please check it? (As with no variant or level specified, the component defaults to a h2 and that usually has a gapIconLg)

I just realized that the icon size doesn’t change based on the heading level, so H1 and H6 headings both use the same 20px icon. We should fix that and adjust the gap as well. I'll send you the mapping soon

*I was wrong it works with the Level prop but when I set the "as" prop it changes the font-size but it doesn't change the icon size. I write you on Slack about this

@adamlobler Okay, I fixed the as prop, can you check these please:

<div> <Heading as="h1" renderIcon={<IconAdminSolid/>}>titlePageDesktop</Heading><br/> <Heading as="h2" renderIcon={<IconAdminSolid/>}>titlePageMobile</Heading><br/> <Heading as="h3" renderIcon={<IconAdminSolid/>}>titleSection</Heading><br/> <Heading as="h4" renderIcon={<IconAdminSolid/>}>titleCardSection</Heading><br/> <Heading as="h5" renderIcon={<IconAdminSolid/>}>titleModule</Heading><br/> <Heading as="h6" renderIcon={<IconAdminSolid/>}>titleCardLarge</Heading><br/> </div>

Also I realized the AI variants can have different levels, can you please check these too for the icon sizes and gaps?

<div style={{display: 'flex', flexDirection: 'column', gap: '24px'}}> <Heading aiVariant="horizontal" level="h1">Main Title - Heading 1</Heading> <Heading aiVariant="horizontal" level="h2">Section Title - Heading 2</Heading> <Heading aiVariant="horizontal" level="h3">Nutrition Facts - Heading 3</Heading> <Heading aiVariant="horizontal" level="h4">Subsection - Heading 4</Heading> <Heading aiVariant="horizontal" level="h5">Detail Category - Heading 5</Heading> <Heading aiVariant="horizontal" level="h6">Fine Print - Heading 6</Heading> </div>

<div style={{display: 'flex', flexDirection: 'column', gap: '24px'}}> <Heading aiVariant="horizontal" variant="titlePageDesktop">titlePageDesktop</Heading> <Heading aiVariant="horizontal" variant="titlePageMobile">titlePageMobile</Heading> <Heading aiVariant="horizontal" variant="titleSection">titleSection</Heading> <Heading aiVariant="horizontal" variant="titleCardSection">titleCardSection</Heading> <Heading aiVariant="horizontal" variant="titleModule">titleModule</Heading> <Heading aiVariant="horizontal" variant="titleCardLarge">titleCardLarge</Heading> <Heading aiVariant="horizontal" variant="titleCardRegular">titleCardRegular</Heading> <Heading aiVariant="horizontal" variant="titleCardMini">titleCardMini</Heading> <Heading aiVariant="horizontal" variant="label">label</Heading> <Heading aiVariant="horizontal" variant="labelInline">labelInline</Heading> </div>

Great, thanks for the code snippets! The base ones look great, but in the AI variants the gaps aren’t aligned with the textsizes. Could you use the same gaps we use in the base ones for each heading level?

@adamlobler I fixed this, can you please check it now?

adamlobler · 2026-01-16T11:12:45Z

packages/ui-heading/src/Heading/index.tsx

  static defaultProps = {
    children: null,
    border: 'none',
    color: 'inherit'


Now the default text color is "inherit" and as a result it gets the color value from somewhere else from the system, I think it would be more secure to have the "primary" color by default, wdyt?

That's why we have this text color here as well in dark mode:

I chose to modify the examples a bit rather then changing the default "inherit" value because that can have some breaking changes.

I see your point, but I’m a bit concerned that these Heading components will mostly receive raw hex values that won’t work across light and dark modes.

@adamlobler Ok, I changed the default to "primary", check the examples in dark mode please

@matyasf can you check this conv? I’m not 100% sure about it, but it feels like the safer approach when introducing dark mode.

I think too that primary is better. Otherwise users might not set it to set to a wrong color and it will look off/have a11y issues. Be sure to mention this in the changelog (afaik I've done the same for Text)

I put in into the changelog.

packages/ui-heading/src/Heading/props.ts

adamlobler

The icon size and the gap don’t align with the font-size when only the as prop is set.

adamlobler

In the AI variants the gaps between the icon and the text aren’t aligned with the textsizes, they are always 0.25rem

INSTUI-4869

adamlobler

Perfect, thanks for the modifications 🙌

matyasf

nice work!

ToMESSKa self-assigned this Jan 15, 2026

ToMESSKa commented Jan 15, 2026

View reviewed changes

ToMESSKa requested review from HerrTopi, adamlobler and matyasf January 15, 2026 15:47

ToMESSKa changed the title ~~feat(ui-heading): rework Heading~~ [v12] feat(ui-heading): rework Heading Jan 15, 2026

adamlobler requested changes Jan 16, 2026

View reviewed changes

matyasf requested changes Jan 19, 2026

View reviewed changes

packages/ui-heading/src/Heading/props.ts Show resolved Hide resolved

ToMESSKa force-pushed the INSTUI-4869-heading-rework branch from ed57ffd to 467fc85 Compare January 21, 2026 15:11

ToMESSKa requested review from adamlobler and matyasf January 21, 2026 15:29

adamlobler requested changes Jan 22, 2026

View reviewed changes

ToMESSKa force-pushed the INSTUI-4869-heading-rework branch from 467fc85 to 464c80a Compare January 22, 2026 12:33

ToMESSKa requested a review from adamlobler January 22, 2026 12:48

adamlobler requested changes Jan 22, 2026

View reviewed changes

feat(ui-heading): rework Heading

d6810e2

INSTUI-4869

ToMESSKa force-pushed the INSTUI-4869-heading-rework branch from 464c80a to d6810e2 Compare January 23, 2026 09:08

ToMESSKa requested a review from adamlobler January 23, 2026 09:20

adamlobler approved these changes Jan 23, 2026

View reviewed changes

matyasf approved these changes Jan 23, 2026

View reviewed changes

[v12] feat(ui-heading): rework Heading #2365

Are you sure you want to change the base?

[v12] feat(ui-heading): rework Heading #2365

Conversation

ToMESSKa commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-01-23 09:12 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ToMESSKa Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ToMESSKa Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamlobler left a comment

Choose a reason for hiding this comment

Uh oh!

adamlobler left a comment

Choose a reason for hiding this comment

Uh oh!

adamlobler left a comment

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ToMESSKa commented Jan 15, 2026 •

edited

Loading

github-actions bot commented Jan 15, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-01-23 09:12 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

ToMESSKa Jan 15, 2026 •

edited

Loading

ToMESSKa Jan 22, 2026 •

edited

Loading