Skip to content

Commit a241645

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

File tree

3 files changed

+287
-143
lines changed

3 files changed

+287
-143
lines changed

‎guides/material-2.md

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

719949
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)