RFC: material typography spec v2

[eps1lon]

This is a proposal for a migration path from the v1 typography spec to v2.

Breaking changes

• every variant will have a primary color. The spec does not list color as a property of typography.
• removes the following variants:
  • display1
  • display2
  • display3
  • display4
  • headline
  • title
  • subheading
• changes the style of the following variants:
  • body1
  • body2
  • caption
  • button

Implementation

Color

The spec does not mention color. Use primary by default and apply color manually on every usage.

Variant Name

Use names from spec but use headlineX instead of hX which matches mwc implementation

Roadmap

• new minor (implemented with [Typography] Add typography v2 variants #12916, scheduled for 3.2.0):
  • add new variants from the spec, conflicting names will be suffixed with Next
  • set suppressDeprecationWarning on every internal Typography usage to suppress warnings. They are for the user not the dev. Users should be warned if an internal component uses a deprecated variant. Recommend setting useNextVariants per component.
  • show deprecation warnings for categories that will be removed or restyled in a new minor version
  • expose useNextVariants to Typography. This will use the style of variants in the next major (only concerns variants that will be restyled for all variants so that using useNextVariants has no breaking change when switching to new major)
  • update typescript definitions
  • recommend new variants and colors that should replace deprecated variants
  • Update docs to use typography v2
• new major with:
  • useNextVariants, suppressDeprecationWarning will become noop props
  • write codemod for migration:
    • remove useNextVariants, suppressDeprecationWarning props
    • apply new variants and colors according to recommendation
  • refactor internal usage of Typography, use codemod
  • remove old variants
• new minor with:
  • warn when using useNextVariants, suppressDeprecationWarning because noop

If we don't consider style changes a breaking change we can skip the hole suppressDeprecationWarning step which reduces the workload but is probably annoying for users that aim at pixel perfect apps.

Misc

Spec:

• https://material.io/design/typography/the-type-system.html
• https://material.io/design/typography/understanding-typography.html

Existing Implementations:

• https://github.com/material-components/material-components-web/blob/master/packages/mdc-typography/_variables.scss

Related:

• Typography has incorrect theme presets #12377
• Add support for new material typographic scale (h1, h2, etc. instead of display4, display3) #11667

@oliviertassinari Could you ping core contributors?

[oliviertassinari]

@eps1lon Thanks for setting that up. We might not need a codemod for such change, the search&replace can potentially be simple to perform. I have no objection otherwise.

ping @mui-org/core-contributors

[leMaik]

Maybe we could provide a new @material-ui/typography package after that change that brings back the old Typography component so that we don't break people's projects?

Or maybe (even better) allow selecting the typography style in the theme? Thus making the change almost non-breaking by setting all typography properties in the theme and allow users to bring back the old typography config.

[oliviertassinari]

Maybe we could provide a new @material-ui/typography package after that change that brings back the old Typography component so that we don't break people's projects?

@leMaik I would rather avoid this type of operational overhead. What's wrong with adding a depreciation in a minor and removing the old variant in a major?

Or maybe (even better) allow selecting the typography style in the theme?

I love the idea. It's way more flexibility. We need to find a way to have dynamic prop-types, doesn't sounds good for TypeScript users. We also need a way to identify the theme.typography keys that are variants.

[leMaik]

What's wrong with adding a depreciation in a minor and removing the old variant in a major?

Nothing. A breaking change in this particular component just seems weird, it'll be like "Oh, you rely on our font styles? Well, better update everything because we dropped half of them." At least that's how it looks in our apps that use Material-UI. That's why I'd like to see a component that brings back the old Typography. It might be an unneccessary breaking change that causes a lot of work.

[eps1lon]

Maybe this seems overly pedantic but we do implement the material design and if this design changes so should we.

This is currently implemented with a simple feature flag in createTheme. I could start cherry picking my work to exclude the deprecation warnings but do we really want to support deprecated typography variants?

[nathanmarks]

I say we just include the deprecation warnings and remove them in the next major.

[JeanBeaurepaire]

In fact, this feature should also include new headers and both subheading, but also new category overline

[eps1lon]

@Abbo44 I'm aware of the spec. The new variants are almost finished.

I just need to polish the deprecation warnings so that they don't interfere with our own test suite.

[eps1lon]

Implemented typography v2 with deprecation warnings and docs in typography v2 in #12916.