Skip to content

Commit e84f572

Browse files
amysortoamysorto
committed
docs: Make typography guide M3 specific
1 parent 3be8f7e commit e84f572

File tree

3 files changed

+277
-143
lines changed

3 files changed

+277
-143
lines changed

‎guides/material-2.md

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -714,6 +714,226 @@ You can mirror this structure in your components by defining your own mixins. Th
714714
should accept an Angular Material theme, from which they can read color and typography values. You
715715
can then include these mixins in your application along with Angular Material's own mixins.
716716

717+
## Customizing Typography
718+
719+
### Including font assets
720+
721+
Angular Material's typography APIs lets you specify any font-face. The default font-face value is
722+
configured to [Google's Roboto font][roboto] with the 300, 400, and 500 font-weight styles. To use
723+
Roboto, your application must load the font, which is not included with Angular Material. The
724+
easiest way to load Roboto, or any other custom font, is by using Google Fonts. The following
725+
snippet can be placed in your application's `<head>` to load Roboto from Google Fonts.
726+
727+
```html
728+
<link rel="preconnect" href="https://fonts.gstatic.com">
729+
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">
730+
```
731+
732+
See [Getting Started with the Google Fonts API][fonts-api] for more about using Google Fonts. Also
733+
note that, by default, [the Angular CLI inlines assets from Google Fonts to reduce render-blocking
734+
requests][font-inlining].
735+
736+
[roboto]: https://fonts.google.com/share?selection.family=Roboto:wght@300;400;500
737+
[fonts-api]: https://developers.google.com/fonts/docs/getting_started
738+
[font-inlining]: https://angular.io/guide/workspace-config#fonts-optimization-options
739+
740+
### Typography levels
741+
742+
A **typography level** is a collection of typographic styles that corresponds to a specific
743+
part of an application's structure, such as a header. Each level includes styles for font family,
744+
font weight, font size, and letter spacing. Angular Material uses the [typography levels
745+
from the 2018 version of the Material Design specification][2018-typography], outlined in the
746+
table below.
747+
748+
| Name | Description |
749+
|-----------------|--------------------------------------------------------------|
750+
| `headline-1` | One-off header, usually at the top of the page (e.g. a hero header). |
751+
| `headline-2` | One-off header, usually at the top of the page (e.g. a hero header). |
752+
| `headline-3` | One-off header, usually at the top of the page (e.g. a hero header). |
753+
| `headline-4` | One-off header, usually at the top of the page (e.g. a hero header). |
754+
| `headline-5` | Section heading corresponding to the `<h1>` tag. |
755+
| `headline-6` | Section heading corresponding to the `<h2>` tag. |
756+
| `subtitle-1` | Section heading corresponding to the `<h3>` tag. |
757+
| `subtitle-2` | Section heading corresponding to the `<h4>` tag. |
758+
| `body-1` | Base body text. |
759+
| `body-2` | Secondary body text. |
760+
| `caption` | Smaller body and hint text. |
761+
| `button` | Buttons and anchors. |
762+
763+
[2018-typography]: https://m2.material.io/design/typography/the-type-system.html#type-scale
764+
765+
#### Define a level
766+
767+
You can define a typography level with the `define-typography-level` Sass function. This function
768+
accepts, in order, CSS values for `font-size`, `line-height`, `font-weight`, `font-family`, and
769+
`letter-spacing`. You can also specify the parameters by name, as demonstrated in the example below.
770+
771+
```scss
772+
@use '@angular/material' as mat;
773+
774+
$my-custom-level: mat.define-typography-level(
775+
$font-family: Roboto,
776+
$font-weight: 400,
777+
$font-size: 1rem,
778+
$line-height: 1,
779+
$letter-spacing: normal,
780+
);
781+
```
782+
783+
### Typography config
784+
785+
A **typography config** is a collection of all typography levels. Angular Material represents this
786+
config as a Sass map. This map contains the styles for each level, keyed by name. You can create
787+
a typography config with the `define-typography-config` Sass function. Every parameter for
788+
`define-typography-config` is optional; the styles for a level will default to Material Design's
789+
baseline if unspecified.
790+
791+
```scss
792+
@use '@angular/material' as mat;
793+
794+
$my-custom-typography-config: mat.define-typography-config(
795+
$headline-1: mat.define-typography-level(112px, 112px, 300, $letter-spacing: -0.05em),
796+
$headline-2: mat.define-typography-level(56px, 56px, 400, $letter-spacing: -0.02em),
797+
$headline-3: mat.define-typography-level(45px, 48px, 400, $letter-spacing: -0.005em),
798+
$headline-4: mat.define-typography-level(34px, 40px, 400),
799+
$headline-5: mat.define-typography-level(24px, 32px, 400),
800+
// ...
801+
);
802+
```
803+
804+
#### Typography configs and theming
805+
806+
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.
807+
808+
The following example shows a typical theme definition and a "kids theme" that only applies when
809+
the `".kids-theme"` CSS class is present. You can [see the theming guide for more guidance on
810+
defining multiple themes](#defining-multiple-themes).
811+
812+
```scss
813+
@use '@angular/material' as mat;
814+
815+
@include mat.core();
816+
817+
$my-primary: mat.define-palette(mat.$indigo-palette, 500);
818+
$my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
819+
$my-typography: mat.define-typography-config();
820+
821+
$my-theme: mat.define-light-theme((
822+
color: (
823+
primary: $my-primary,
824+
accent: $my-accent,
825+
),
826+
typography: $my-typography,
827+
));
828+
829+
@include mat.all-component-themes($my-theme);
830+
831+
.kids-theme {
832+
$kids-primary: mat.define-palette(mat.$cyan-palette);
833+
$kids-accent: mat.define-palette(mat.$yellow-palette);
834+
835+
// Typography config based on the default, but using "Comic Sans" as the
836+
// default font family for all levels.
837+
$kids-typography: mat.define-typography-config(
838+
$font-family: 'Comic Sans',
839+
);
840+
841+
$kids-theme: mat.define-light-theme((
842+
color: (
843+
primary: $kids-primary,
844+
accent: $kids-accent,
845+
),
846+
typography: $kids-typography,
847+
));
848+
849+
@include mat.all-component-themes($kids-theme);
850+
}
851+
```
852+
853+
Each component also has a `typography` mixin that emits only the typography styles for that
854+
component, based on a provided typography config. The following example demonstrates applying
855+
typography styles only for the button component.
856+
857+
```scss
858+
@use '@angular/material' as mat;
859+
860+
$kids-typography: mat.define-typography-config(
861+
// Specify "Comic Sans" as the default font family for all levels.
862+
$font-family: 'Comic Sans',
863+
);
864+
865+
// Now we have sweet buttons with Comic Sans.
866+
@include mat.button-typography($kids-typography);
867+
```
868+
869+
### Using typography styles in your application
870+
871+
In addition to styles shared between components, the `typography-hierarchy` mixin includes CSS
872+
classes for styling your application. These CSS classes correspond to the typography levels in your
873+
typography config. This mixin also emits styles for native header elements scoped within the
874+
`.mat-typography` CSS class.
875+
876+
```scss
877+
@use '@angular/material' as mat;
878+
879+
// Use the default configuration.
880+
$my-typography: mat.define-typography-config();
881+
@include mat.typography-hierarchy($my-typography);
882+
```
883+
884+
The table below lists the CSS classes emitted and the native elements styled.
885+
886+
| CSS class | Level name | Native elements |
887+
|------------------------------------------|----------------|-----------------|
888+
| `.mat-headline-1` | `headline-1` | None |
889+
| `.mat-headline-2` | `headline-2` | None |
890+
| `.mat-headline-3` | `headline-3` | None |
891+
| `.mat-headline-4` | `headline-4` | None |
892+
| `.mat-h1` or `.mat-headline-5` | `headline-5` | `<h1>` |
893+
| `.mat-h2` or `.mat-headline-6` | `headline-6` | `<h2>` |
894+
| `.mat-h3` or `.mat-subtitle-1` | `subtitle-1` | `<h3>` |
895+
| `.mat-h4` or `.mat-body-1` | `body-1` | `<h4>` |
896+
| `.mat-h5` | None | `<h5>` |
897+
| `.mat-h6` | None | `<h6>` |
898+
| `.mat-body` or `.mat-body-2` | `body-2` | Body text |
899+
| `.mat-body-strong` or `.mat-subtitle-2` | `subtitle-2` | None |
900+
| `.mat-small` or `.mat-caption` | `caption` | None |
901+
902+
In addition to the typographic styles, these style rules also include a `margin-bottom` for
903+
headers and paragraphs. For `body` styles, text is styled within the provided CSS selector.
904+
905+
The `.mat-h5` and `.mat-h6` styles don't directly correspond to a specific Material Design
906+
typography level. The `.mat-h5` style uses the `body-2` level with the font-size scaled down by
907+
`0.83`. The `.mat-h6` style uses the `body-2` level with the font-size scaled down by `0.67`.
908+
909+
The `button` and `input` typography levels do not map to CSS classes.
910+
911+
The following example demonstrates usage of the typography styles emitted by the
912+
`typography-hierarchy` mixin.
913+
914+
```html
915+
<body>
916+
<!-- This header will *not* be styled because it is outside `.mat-typography` -->
917+
<h1>Top header</h1>
918+
919+
<!-- This paragraph will be styled as `body-1` via the `.mat-body` CSS class applied -->
920+
<p class="mat-body">Introductory text</p>
921+
922+
<div class="mat-typography">
923+
<!-- This header will be styled as `title` because it is inside `.mat-typography` -->
924+
<h2>Inner header</h2>
925+
926+
<!-- This paragraph will be styled as `body-1` because it is inside `.mat-typography` -->
927+
<p>Some inner text</p>
928+
</div>
929+
</body>
930+
```
931+
932+
#### Reading typography values from a config
933+
934+
It is possible to read typography properties from a theme for use in your own components. For more
935+
information about this see our section on [Theming your own components](https://material.angular.io/guide/material-2#theming-your-components),
936+
717937
### Step-by-step example
718938

719939
To illustrate participation in Angular Material's theming system, we can look at an example of a

‎guides/theming.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -138,9 +138,7 @@ Learn more about this schematic in its [documentation](https://github.com/angula
138138
#### Customizing your typography
139139

140140
The following aspects of your app's typography can be customized via the `typography` property of
141-
the theme configuration object (see the
142-
[M3 typography spec](https://m3.material.io/styles/typography/type-scale-tokens) to learn more about
143-
these terms):
141+
the theme configuration object.
144142

145143
| Typography Property | Description |
146144
| ------------------- | -------------------------------------------------------------------- |
@@ -150,6 +148,9 @@ these terms):
150148
| `medium-weight` | [Optional] The font weight to use for medium text. |
151149
| `regular-weight` | [Optional] The font weight to use for regular text. |
152150

151+
See the [typography guide](https://material.angular.io/guide/typography) for more
152+
information.
153+
153154
#### Customizing your density
154155

155156
The following aspects of your app's density can be customized via the `density` property of the

0 commit comments

Comments
 (0)