[Typography][joy-ui] Improve levels after beta to avoid confusion

[zanivan]

Duplicates

• I have searched the existing issues

Latest version

• I have tested the latest version

Summary 💡

With the Joy UI beta release, we changed the default theme's typographic level system:

- display1 | display2 | h1 | h2 | h3 | h4 | h5 | h6 | body1 | body2 | body3 | body4 | body5
+ 'h1' | 'h2' | 'h3' | 'h4' | 'title-lg' | 'title-md' | 'title-sm' | 'body-lg' | 'body-md' | 'body-sm' | 'body-xs'

Although the consistency of the Typography scales has improved, the naming of the levels can get confusing due to h-* levels using a scale from 1 to 4, title-* using a scale from lg to sm and body-* using a scale from lg to xs

Examples 🌈

No response

Motivation 🔦

#37951 (comment)

Proposed solution 🎯

The idea is to simplify the scales to reduce the confusion of when to use one or another. So instead of having a h-, a title-, and a body-, we could reduce it to heading- and text-—and this would keep the parity of sizes on lg/md/sm from heading and texts levels, helping it to be used on components without further adjustments on extra margins.

Current	Proposal
h1	heading-xl3
h2	heading-xl2
h3	heading-xl1
h4	heading-xl
title-lg	heading-lg
title-md	heading-md
title-sm	heading-sm
body-lg	text-lg
body-md	text-md
body-sm	text-sm
body-xs	text-xs

[zanivan]

@danilo-leal @noraleonte @gerdadesign @DavidCnoops any thoughts/examples on how we should approach these scales?

[danilo-leal]

Sweet, thanks for opening this one up! I'm totally down to just having the heading & text levels ⎯ the current setup with heading + title is confusing for some reasons but primarily because both are title-sized texts that overlap each other.

However, I wouldn't have the nomenclature for h1 (and for the others down to h4) as heading-xl3 ⎯ that's similarly confusing. 😕 Having the h1 <-> h1 parity, for example, sounds like a safe idea & it's much more intuitive than h1 being equivalent to heading-xl3 (lots more to type, too).

Overall, while double-checking the current type scale, I also realized that the largest font size we support (currently the h1 level) is 36px, which is considerably small. That said, there's an opportunity to also review the scale at the same time as the token naming!

So, how about something like this:

Current	Proposal	Pixel value
h1	h1	60px
h2	h2	52px
h3	h3	48px
h4	h4	40px
title-lg	text-2xl	32px
title-md	text-xl	24px
title-sm	text-lg	18px
body-lg	text-md	16px
body-md	text-sm	14px
body-sm	text-xs	12px
body-xs	text-2xs	10px

Note that we maintain the same number of levels but the scale progresses in a way that gives more breadth. Might still need some fine-tuning on the pixel values there but it could be a good starting point for this iteration!

[oliviertassinari]

For Material UI v6, we might need to revamp the typography levels https://m3.material.io/styles/typography/type-scale-tokens.

Another benchmark: https://getbootstrap.com/docs/5.3/content/typography/

[zanivan]

For Material UI v6, we might need to revamp the typography levels https://m3.material.io/styles/typography/type-scale-tokens.
Another benchmark: https://getbootstrap.com/docs/5.3/content/typography/

Great point, and thanks for providing the benchmark 👍
However, I think it might be better to open a separate issue to discuss the Material UI v6 typography. Mixing the topics here might not be ideal, since the scales for Joy UI and Material UI won't be the same.

[zanivan]

Overall, while double-checking the current type scale, I also realized that the largest font size we support (currently the h1 level) is 36px, which is considerably small. That said, there's an opportunity to also review the scale at the same time as the token naming!

Definitely! I'm down for adding more sizes—tbh, the h1 really is too small when considering the usage on landing pages and whatnot.

Note that we maintain the same number of levels but the scale progresses in a way that gives more breadth. Might still need some fine-tuning on the pixel values there but it could be a good starting point for this iteration!

The issue with this linear scale is that it would bring back the problem of manually adjusting margins for components, especially when using them with icons.

[arobert93]

Maybe we could remove the heading- and text- prefixes from @danilo-leal example and use only sizes. It’s confusing seeing heading-* going from 1 to 4 because we’ll always try to relate them to the actual h1-6 tags.

[danilo-leal]

☝️ That's definitely an option, which makes me think of an overarching question: do we want to give any semantic connotation to the tokens? Because, technically speaking, this can happen: <Typography component="p" level="h1" /> which does look a bit confusing.

I'm sure we discussed this in the past 😅 but maybe reconsidering the typographic token name to not indicate any semantic usage (i.e. not having h as in heading and just text-) (also similar to Tailwind CSS, to that end) could be simpler.

[arobert93]

If we go with Tailwind strategy, we’ll need a different component for Heading and one for Text. The Heading would apply a different font weight that can be mapped, and also auto-resize for smaller devices.

[siriwatknp]

Definitely! I'm down for adding more sizes—tbh, the h1 really is too small when considering the usage on landing pages and whatnot.

I feel like landing pages are exceptional. The default theme is useful when you reuse it multiple times but for landing pages, you would do it once or maybe twice for the biggest heading. That's the reason I exclude landing page consideration from the default theme.

[siriwatknp]

To be honest, I would not do anything at this point because we just refined it and leave this issue open for more opinions.

[PupoSDC]

my 2 cents, as a joy ui user.

I guess this was changed recently, and i need to go revisit a bit my code since h5 and h6 are now gone and I use them quite a bit. Same for body1-4 tags. RIP 😢

As a matter of personal preference i really like the h1-hX approach over any other t-shirt based approach.
It feels closer to html, specially on the h tags, and to me at least numbers are a lot easier to reason with; The answer to "what tag is default for a variant="heading-xl1"" is a complete mistery, while "what tag is the default for a variant="h4"" is right in your face. This kind of simplicity is what I find appealing on Joy ui over mui.

[siriwatknp]

After going through all the comments, I still think that we should do nothing and close this issue.

I don't see a clear issue with the current levels and changing it again would cause more problems. cc @zanivan @danilo-leal

I think we can try to improve the docs first to explain how to use the levels in different use cases.

[zanivan]

After going through all the comments, I still think that we should do nothing and close this issue.
I don't see a clear issue with the current levels and changing it again would cause more problems. cc @zanivan @danilo-leal
I think we can try to improve the docs first to explain how to use the levels in different use cases.

Agreed! I think the current scale works, just need more examples in the docs showing the title and body usage.

However, I truly believe that we should add a title-xs to be consistent with body.

So to close this issue, I reckon we should:

• Add title-xs
• Review docs page about Typography to add more examples