docs-bug(Typography): It isn't clear how to customise Material 3 typography

[DzmVasileusky]

Documentation Feedback

Material 2 docs were pretty clear about how to customise typography.

@use '@angular/material' as mat;

$my-custom-level: mat.m2-define-typography-level(
  $font-family: Roboto,
  $font-weight: 400,
  $font-size: 1rem,
  $line-height: 1,
  $letter-spacing: normal,
);

$my-custom-typography-config: mat.m2-define-typography-config(
  $headline-1: mat.m2-define-typography-level(112px, 112px, 300, $letter-spacing: -0.05em),
  $headline-2: mat.m2-define-typography-level(56px, 56px, 400, $letter-spacing: -0.02em),
  $headline-3: mat.m2-define-typography-level(45px, 48px, 400, $letter-spacing: -0.005em),
  $headline-4: mat.m2-define-typography-level(34px, 40px, 400),
  $headline-5: mat.m2-define-typography-level(24px, 32px, 400),
  // ...
);

The current page called "Customizing Typography" doesn't have an information on how to customise it at all. It describes the usage only.

Migration guide isn't answering this question as well (https://material.angular.io/guide/material-2-theming#how-to-migrate-an-app-from-material-2-to-material-3).

Affected documentation page

https://material.angular.io/guide/theming#customizing-your-typography

[amysorto]

I agree this is an area of improvement, in the meantime the customizable fields are here: https://material.angular.io/guide/typography#configuring-typography. This is how you apply it to your theme: https://material.angular.io/guide/theming#defining-a-theme

[DzmVasileusky]

@amysorto But what about font-size, line-height, font-weight of specific typography levels? Why the customisation is so restricted? Can we really only choose font-family and font-weight for bold/medium now? Does it mean designers can't create their own typography now?

[DzmVasileusky]

Ok, I could customise it by overriding css vars at least like this:

:root {
    --mat-text-button-with-icon-horizontal-padding: 8px;
    --mdc-text-button-label-text-size: 16px;
}

however it is a partial customisation it would be better if we could customise it more globally

[crisbeto]

Another option could be to enable system variables for the theme and then only change the system variables.

[DzmVasileusky]

@crisbeto thanks, funny thing I didn't find docs on system variables on the official Angular material website but found it here https://angular-material.dev/articles/angular-material-theming-css-vars

Is it considered as a bad practice? Or are documents just not completed?

[crisbeto]

System variables are supported, we just haven't gotten around to writing a guide for them.

[DzmVasileusky]

@crisbeto thank you, having a guide for that would be really helpful

[shoff]

Couldn't agree more the M3 custom schematic documentation is just as bad if not worse. In the age of AI, there's no excuse for such horrible, incomplete and just flat wrong documentation. Either be professional, or stop publishing libraries with crap docs.

[shhdharmen]

I wrote an article about modifying typescales using CSS variables. You can read it here: https://angular-material.dev/articles/angular-material-18-typography