From 0dc172aae53689d6287adc1fed79e9f682fe2e8e Mon Sep 17 00:00:00 2001
From: Amy Sorto <8575252+amysorto@users.noreply.github.com>
Date: Tue, 21 May 2024 06:15:04 -0700
Subject: [PATCH] docs: Make typography guide M3 specific (#29075)
---
guides/material-2.md | 220 +++++++++++++++++++++++++++++++++++++++++++
guides/theming.md | 7 +-
guides/typography.md | 193 +++++++++++--------------------------
3 files changed, 277 insertions(+), 143 deletions(-)
diff --git a/guides/material-2.md b/guides/material-2.md
index 9a9fdf6ae69a..3d3ad39b6564 100644
--- a/guides/material-2.md
+++ b/guides/material-2.md
@@ -714,6 +714,226 @@ You can mirror this structure in your components by defining your own mixins. Th
should accept an Angular Material theme, from which they can read color and typography values. You
can then include these mixins in your application along with Angular Material's own mixins.
+## Customizing Typography
+
+### Including font assets
+
+Angular Material's typography APIs let you specify any font-face. The default font-face value is
+configured to [Google's Roboto font][roboto] with the 300, 400, and 500 font-weight styles. To use
+Roboto, your application must load the font, which is not included with Angular Material. The
+easiest way to load Roboto, or any other custom font, is by using Google Fonts. The following
+snippet can be placed in your application's `` to load Roboto from Google Fonts.
+
+```html
+
+
+```
+
+See [Getting Started with the Google Fonts API][fonts-api] for more about using Google Fonts. Also
+note that, by default, [the Angular CLI inlines assets from Google Fonts to reduce render-blocking
+requests][font-inlining].
+
+[roboto]: https://fonts.google.com/share?selection.family=Roboto:wght@300;400;500
+[fonts-api]: https://developers.google.com/fonts/docs/getting_started
+[font-inlining]: https://angular.io/guide/workspace-config#fonts-optimization-options
+
+### Typography levels
+
+A **typography level** is a collection of typographic styles that corresponds to a specific
+part of an application's structure, such as a header. Each level includes styles for font family,
+font weight, font size, and letter spacing. Angular Material uses the [typography levels
+from the 2018 version of the Material Design specification][2018-typography], outlined in the
+table below.
+
+| Name | Description |
+|-----------------|--------------------------------------------------------------|
+| `headline-1` | One-off header, usually at the top of the page (e.g. a hero header). |
+| `headline-2` | One-off header, usually at the top of the page (e.g. a hero header). |
+| `headline-3` | One-off header, usually at the top of the page (e.g. a hero header). |
+| `headline-4` | One-off header, usually at the top of the page (e.g. a hero header). |
+| `headline-5` | Section heading corresponding to the `
` tag. |
+| `headline-6` | Section heading corresponding to the `
` tag. |
+| `subtitle-1` | Section heading corresponding to the `
` tag. |
+| `subtitle-2` | Section heading corresponding to the `
` tag. |
+| `body-1` | Base body text. |
+| `body-2` | Secondary body text. |
+| `caption` | Smaller body and hint text. |
+| `button` | Buttons and anchors. |
+
+[2018-typography]: https://m2.material.io/design/typography/the-type-system.html#type-scale
+
+#### Define a level
+
+You can define a typography level with the `m2-define-typography-level` Sass function. This function
+accepts, in order, CSS values for `font-size`, `line-height`, `font-weight`, `font-family`, and
+`letter-spacing`. You can also specify the parameters by name, as demonstrated in the example below.
+
+```scss
+@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,
+);
+```
+
+### Typography config
+
+A **typography config** is a collection of all typography levels. Angular Material represents this
+config as a Sass map. This map contains the styles for each level, keyed by name. You can create
+a typography config with the `m2-define-typography-config` Sass function. Every parameter for
+`m2-define-typography-config` is optional; the styles for a level will default to Material Design's
+baseline if unspecified.
+
+```scss
+@use '@angular/material' as mat;
+
+$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),
+ // ...
+);
+```
+
+#### Typography configs and theming
+
+You can provide a typography config when defining a theme to customize typographic styles. See the [theming guide][theming-system] for details on custom themes.
+
+The following example shows a typical theme definition and a "kids theme" that only applies when
+the `".kids-theme"` CSS class is present. You can [see the theming guide for more guidance on
+defining multiple themes](#defining-multiple-themes).
+
+```scss
+@use '@angular/material' as mat;
+
+@include mat.core();
+
+$my-primary: mat.m2-define-palette(mat.$indigo-palette, 500);
+$my-accent: mat.m2-define-palette(mat.$pink-palette, A200, A100, A400);
+$my-typography: mat.m2-define-typography-config();
+
+$my-theme: mat.m2-define-light-theme((
+ color: (
+ primary: $my-primary,
+ accent: $my-accent,
+ ),
+ typography: $my-typography,
+));
+
+@include mat.all-component-themes($my-theme);
+
+.kids-theme {
+ $kids-primary: mat.m2-define-palette(mat.$cyan-palette);
+ $kids-accent: mat.m2-define-palette(mat.$yellow-palette);
+
+ // Typography config based on the default, but using "Comic Sans" as the
+ // default font family for all levels.
+ $kids-typography: mat.m2-define-typography-config(
+ $font-family: 'Comic Sans',
+ );
+
+ $kids-theme: mat.m2-define-light-theme((
+ color: (
+ primary: $kids-primary,
+ accent: $kids-accent,
+ ),
+ typography: $kids-typography,
+ ));
+
+ @include mat.all-component-themes($kids-theme);
+}
+```
+
+Each component also has a `typography` mixin that emits only the typography styles for that
+component, based on a provided typography config. The following example demonstrates applying
+typography styles only for the button component.
+
+```scss
+@use '@angular/material' as mat;
+
+$kids-typography: mat.m2-define-typography-config(
+ // Specify "Comic Sans" as the default font family for all levels.
+ $font-family: 'Comic Sans',
+);
+
+// Now we have sweet buttons with Comic Sans.
+@include mat.button-typography($kids-typography);
+```
+
+### Using typography styles in your application
+
+In addition to styles shared between components, the `typography-hierarchy` mixin includes CSS
+classes for styling your application. These CSS classes correspond to the typography levels in your
+typography config. This mixin also emits styles for native header elements scoped within the
+`.mat-typography` CSS class.
+
+```scss
+@use '@angular/material' as mat;
+
+// Use the default configuration.
+$my-typography: mat.m2-define-typography-config();
+@include mat.typography-hierarchy($my-typography);
+```
+
+The table below lists the CSS classes emitted and the native elements styled.
+
+| CSS class | Level name | Native elements |
+|------------------------------------------|----------------|-----------------|
+| `.mat-headline-1` | `headline-1` | None |
+| `.mat-headline-2` | `headline-2` | None |
+| `.mat-headline-3` | `headline-3` | None |
+| `.mat-headline-4` | `headline-4` | None |
+| `.mat-h1` or `.mat-headline-5` | `headline-5` | `
` |
+| `.mat-h2` or `.mat-headline-6` | `headline-6` | `
` |
+| `.mat-h3` or `.mat-subtitle-1` | `subtitle-1` | `
` |
+| `.mat-h4` or `.mat-body-1` | `body-1` | `
` |
+| `.mat-h5` | None | `
` |
+| `.mat-h6` | None | `
` |
+| `.mat-body` or `.mat-body-2` | `body-2` | Body text |
+| `.mat-body-strong` or `.mat-subtitle-2` | `subtitle-2` | None |
+| `.mat-small` or `.mat-caption` | `caption` | None |
+
+In addition to the typographic styles, these style rules also include a `margin-bottom` for
+headers and paragraphs. For `body` styles, text is styled within the provided CSS selector.
+
+The `.mat-h5` and `.mat-h6` styles don't directly correspond to a specific Material Design
+typography level. The `.mat-h5` style uses the `body-2` level with the font-size scaled down by
+`0.83`. The `.mat-h6` style uses the `body-2` level with the font-size scaled down by `0.67`.
+
+The `button` and `input` typography levels do not map to CSS classes.
+
+The following example demonstrates usage of the typography styles emitted by the
+`typography-hierarchy` mixin.
+
+```html
+
+
+
Top header
+
+
+
Introductory text
+
+
+
+
Inner header
+
+
+
Some inner text
+
+
+```
+
+#### Reading typography values from a config
+
+It is possible to read typography properties from a theme for use in your own components. For more
+information about this see our section on [Theming your own components](https://material.angular.io/guide/material-2#theming-your-components),
+
### Step-by-step example
To illustrate participation in Angular Material's theming system, we can look at an example of a
diff --git a/guides/theming.md b/guides/theming.md
index 49df750a3b0d..252ae6f91b3d 100644
--- a/guides/theming.md
+++ b/guides/theming.md
@@ -138,9 +138,7 @@ Learn more about this schematic in its [documentation](https://github.com/angula
#### Customizing your typography
The following aspects of your app's typography can be customized via the `typography` property of
-the theme configuration object (see the
-[M3 typography spec](https://m3.material.io/styles/typography/type-scale-tokens) to learn more about
-these terms):
+the theme configuration object.
| Typography Property | Description |
| ------------------- | -------------------------------------------------------------------- |
@@ -150,6 +148,9 @@ these terms):
| `medium-weight` | [Optional] The font weight to use for medium text. |
| `regular-weight` | [Optional] The font weight to use for regular text. |
+See the [typography guide](https://material.angular.io/guide/typography) for more
+information.
+
#### Customizing your density
The following aspects of your app's density can be customized via the `density` property of the
diff --git a/guides/typography.md b/guides/typography.md
index 47d488de4a8f..31616e2e501e 100644
--- a/guides/typography.md
+++ b/guides/typography.md
@@ -1,5 +1,8 @@
# Customizing Typography
+**Note: The information on this page is specific to Material 3, for Material 2
+information on typography go to the [Material 2 guide](https://material.angular.io/guide/material-2-theming#customizing-typography).**
+
## What is typography?
Typography is a way of arranging type to make text legible, readable, and appealing when displayed.
@@ -33,137 +36,72 @@ requests][font-inlining].
[fonts-api]: https://developers.google.com/fonts/docs/getting_started
[font-inlining]: https://angular.io/guide/workspace-config#fonts-optimization-options
-## Typography levels
-
-A **typography level** is a collection of typographic styles that corresponds to a specific
-part of an application's structure, such as a header. Each level includes styles for font family,
-font weight, font size, and letter spacing. Angular Material uses the [typography levels
-from the 2018 version of the Material Design specification][2018-typography], outlined in the
-table below.
-
-| Name | Description |
-|-----------------|--------------------------------------------------------------|
-| `headline-1` | One-off header, usually at the top of the page (e.g. a hero header). |
-| `headline-2` | One-off header, usually at the top of the page (e.g. a hero header). |
-| `headline-3` | One-off header, usually at the top of the page (e.g. a hero header). |
-| `headline-4` | One-off header, usually at the top of the page (e.g. a hero header). |
-| `headline-5` | Section heading corresponding to the `
` tag. |
-| `headline-6` | Section heading corresponding to the `
` tag. |
-| `subtitle-1` | Section heading corresponding to the `
` tag. |
-| `subtitle-2` | Section heading corresponding to the `
` tag. |
-| `body-1` | Base body text. |
-| `body-2` | Secondary body text. |
-| `caption` | Smaller body and hint text. |
-| `button` | Buttons and anchors. |
-
-[2018-typography]: https://m2.material.io/design/typography/the-type-system.html#type-scale
-
-### Define a level
-
-You can define a typography level with the `define-typography-level` Sass function. This function
-accepts, in order, CSS values for `font-size`, `line-height`, `font-weight`, `font-family`, and
-`letter-spacing`. You can also specify the parameters by name, as demonstrated in the example below.
+## Configuring Typography
-```scss
-@use '@angular/material' as mat;
-
-$my-custom-level: mat.define-typography-level(
- $font-family: Roboto,
- $font-weight: 400,
- $font-size: 1rem,
- $line-height: 1,
- $letter-spacing: normal,
-);
-```
-
-## Typography config
-
-A **typography config** is a collection of all typography levels. Angular Material represents this
-config as a Sass map. This map contains the styles for each level, keyed by name. You can create
-a typography config with the `define-typography-config` Sass function. Every parameter for
-`define-typography-config` is optional; the styles for a level will default to Material Design's
-baseline if unspecified.
-
-```scss
-@use '@angular/material' as mat;
+The following aspects of your app's typography can be customized via the `typography` property of
+the theme configuration object.
-$my-custom-typography-config: mat.define-typography-config(
- $headline-1: mat.define-typography-level(112px, 112px, 300, $letter-spacing: -0.05em),
- $headline-2: mat.define-typography-level(56px, 56px, 400, $letter-spacing: -0.02em),
- $headline-3: mat.define-typography-level(45px, 48px, 400, $letter-spacing: -0.005em),
- $headline-4: mat.define-typography-level(34px, 40px, 400),
- $headline-5: mat.define-typography-level(24px, 32px, 400),
- // ...
-);
-```
+| Typography Property | Description |
+| ------------------- | -------------------------------------------------------------------- |
+| `plain-family` | [Optional] The font family to use for plain text, such as body text. |
+| `brand-family` | [Optional] The font family to use for brand text, such as headlines. |
+| `bold-weight` | [Optional] The font weight to use for bold text. |
+| `medium-weight` | [Optional] The font weight to use for medium text. |
+| `regular-weight` | [Optional] The font weight to use for regular text. |
-### Typography configs and theming
+These are used to generate the styles for the different typescale levels.
-You can provide a typography config when defining a theme to customize typographic styles. See the [theming guide][theming-system] for details on custom themes.
+## Type scale levels
-The following example shows a typical theme definition and a "kids theme" that only applies when
-the `".kids-theme"` CSS class is present. You can [see the theming guide for more guidance on
-defining multiple themes](https://material.angular.io/guide/theming#defining-multiple-themes).
+A **type scale** is a selection of font styles that can be used across an app.
+They’re assigned based on use (such as display or headline), and grouped more
+broadly into categories based on scale (such as large or small). For more
+information, see the [M3 typography spec](https://m3.material.io/styles/typography/type-scale-tokens).
-```scss
-@use '@angular/material' as mat;
+There are `large`, `medium`, and `small` variations for the following type roles:
+- **Display**: Display styles are reserved for short, important text or numerals. They work best on large screens.
+- **Headline**: Headline styles are best-suited for short, high-emphasis text on smaller screens. These styles can be good for marking primary passages of text or important regions of content.
+- **Title**: Title styles are smaller than headline styles, and should be used for medium-emphasis text that remains relatively short. For example, consider using title styles to divide secondary passages of text or secondary regions of content.
+- **Body**: Body styles are used for longer passages of text in your app.
+- **Label**: Label styles are smaller, utilitarian styles, used for things like the text inside components or for very small text in the content body, such as captions.
-@include mat.core();
+The table below lists the CSS classes emitted and the native elements styled.
-$my-primary: mat.define-palette(mat.$indigo-palette, 500);
-$my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
-$my-typography: mat.define-typography-config();
+| CSS class | Typesale level |
+|---------------------------|---------------------|
+| `.mat-display-large` | `display-large` |
+| `.mat-display-medium` | `display-medium` |
+| `.mat-display-small` | `display-small` |
+| `.mat-headline-large` | `headline-large` |
+| `.mat-headline-medium` | `headline-medium` |
+| `.mat-headline-small` | `headline-small` |
+| `.mat-title-large` | `title-large` |
+| `.mat-title-medium` | `title-medium` |
+| `.mat-title-small` | `title-small` |
+| `.mat-body-large` | `body-large` |
+| `.mat-body-medium` | `body-medium` |
+| `.mat-body-small` | `body-small` |
+| `.mat-label-large` | `label-large` |
+| `.mat-label-medium` | `label-medium` |
+| `.mat-label-small` | `label-small` |
-$my-theme: mat.define-light-theme((
- color: (
- primary: $my-primary,
- accent: $my-accent,
- ),
- typography: $my-typography,
-));
-
-@include mat.all-component-themes($my-theme);
-
-.kids-theme {
- $kids-primary: mat.define-palette(mat.$cyan-palette);
- $kids-accent: mat.define-palette(mat.$yellow-palette);
-
- // Typography config based on the default, but using "Comic Sans" as the
- // default font family for all levels.
- $kids-typography: mat.define-typography-config(
- $font-family: 'Comic Sans',
- );
-
- $kids-theme: mat.define-light-theme((
- color: (
- primary: $kids-primary,
- accent: $kids-accent,
- ),
- typography: $kids-typography,
- ));
-
- @include mat.all-component-themes($kids-theme);
-}
-```
+## Using typography styles in your application
-Each component also has a `typography` mixin that emits only the typography styles for that
-component, based on a provided typography config. The following example demonstrates applying
-typography styles only for the button component.
+See the [theming guide](https://material.angular.io/guide/theming#defining-a-theme)
+for details on setting up a theme that has typography configured.
-```scss
-@use '@angular/material' as mat;
+### Reading typography values from a config
-$kids-typography: mat.define-typography-config(
- // Specify "Comic Sans" as the default font family for all levels.
- $font-family: 'Comic Sans',
-);
+It is possible to read typography properties from a theme for use in your own components. For more
+information about this see our guide on [Theming your own components][reading-typography].
-// Now we have sweet buttons with Comic Sans.
-@include mat.button-typography($kids-typography);
-```
+[reading-typography]: https://material.angular.io/guide/theming-your-components#reading-typography-values
## Using typography styles in your application
+**Note: this section is applicable only if you are using the [M2 backwards compatability
+mixin](https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-typography-hierarchy).**
+
In addition to styles shared between components, the `typography-hierarchy` mixin includes CSS
classes for styling your application. These CSS classes correspond to the typography levels in your
typography config. This mixin also emits styles for native header elements scoped within the
@@ -177,24 +115,6 @@ $my-typography: mat.define-typography-config();
@include mat.typography-hierarchy($my-typography);
```
-The table below lists the CSS classes emitted and the native elements styled.
-
-| CSS class | Level name | Native elements |
-|------------------------------------------|----------------|-----------------|
-| `.mat-headline-1` | `headline-1` | None |
-| `.mat-headline-2` | `headline-2` | None |
-| `.mat-headline-3` | `headline-3` | None |
-| `.mat-headline-4` | `headline-4` | None |
-| `.mat-h1` or `.mat-headline-5` | `headline-5` | `
` |
-| `.mat-h2` or `.mat-headline-6` | `headline-6` | `
` |
-| `.mat-h3` or `.mat-subtitle-1` | `subtitle-1` | `
` |
-| `.mat-h4` or `.mat-body-1` | `body-1` | `
` |
-| `.mat-h5` | None | `
` |
-| `.mat-h6` | None | `
` |
-| `.mat-body` or `.mat-body-2` | `body-2` | Body text |
-| `.mat-body-strong` or `.mat-subtitle-2` | `subtitle-2` | None |
-| `.mat-small` or `.mat-caption` | `caption` | None |
-
In addition to the typographic styles, these style rules also include a `margin-bottom` for
headers and paragraphs. For `body` styles, text is styled within the provided CSS selector.
@@ -224,10 +144,3 @@ The following example demonstrates usage of the typography styles emitted by the
```
-
-### Reading typography values from a config
-
-It is possible to read typography properties from a theme for use in your own components. For more
-information about this see our guide on [Theming your own components][reading-typography].
-
-[reading-typography]: https://material.angular.io/guide/theming-your-components#reading-typography-values