Skip to content

Commit ecc6329

Browse files
mmalerbammalerba
committed
docs(material/core): show typography as part of the theme
also recommend the mdc typography for the mdc components
1 parent 6a858aa commit ecc6329

File tree

3 files changed

+157
-146
lines changed

3 files changed

+157
-146
lines changed

‎guides/theming.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,9 @@ $candy-app-theme: mat-light-theme((
9595
primary: $candy-app-primary,
9696
accent: $candy-app-accent,
9797
warn: $candy-app-warn,
98-
)
98+
),
99+
typography: mat-typography-config(),
100+
density: 0, // Defaults to 0 if omitted, but shown for completeness.
99101
));
100102

101103
// Include theme styles for core and each component used in your app.
@@ -152,7 +154,8 @@ $candy-app-theme: mat-light-theme((
152154
color: (
153155
primary: $candy-app-primary,
154156
accent: $candy-app-accent,
155-
)
157+
),
158+
typography: mat-typography-config()
156159
));
157160

158161
// Include the default theme styles (color and default density)
@@ -237,7 +240,8 @@ $candy-app-theme: mat-light-theme((
237240
color: (
238241
primary: $candy-app-primary,
239242
accent: $candy-app-accent,
240-
)
243+
),
244+
typography: mat-typography-config()
241245
));
242246

243247
// Include the theme styles for only specified components.

‎guides/typography.md

Lines changed: 143 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,143 @@
1-
# Angular Material typography
2-
3-
### What is typography?
4-
Typography is a way of arranging type to make text legible, readable, and appealing when displayed.
5-
Angular Material's typography is based on the guidelines from the [Material Design spec][1] and is
6-
arranged into typography levels. Each level has a `font-size`, `line-height` and `font-weight`. The
7-
available levels are:
8-
9-
10-
| Name | CSS classes | Description |
11-
|-----------------|----------------------------------|-----------------------------------------------------------------------------|
12-
| `display-4` | `.mat-display-4` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
13-
| `display-3` | `.mat-display-3` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
14-
| `display-2` | `.mat-display-2` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
15-
| `display-1` | `.mat-display-1` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
16-
| `headline` | `.mat-h1`, `.mat-headline` | Section heading corresponding to the `<h1>` tag. |
17-
| `title` | `.mat-h2`, `.mat-title` | Section heading corresponding to the `<h2>` tag. |
18-
| `subheading-2` | `.mat-h3`, `.mat-subheading-2` | Section heading corresponding to the `<h3>` tag. |
19-
| `subheading-1` | `.mat-h4`, `.mat-subheading-1` | Section heading corresponding to the `<h4>` tag. |
20-
| `body-1` | `.mat-body`, `.mat-body-1` | Base body text. |
21-
| `body-2` | `.mat-body-strong`, `.mat-body-2`| Bolder body text. |
22-
| `caption` | `.mat-small`, `.mat-caption` | Smaller body and hint text. |
23-
| `button` | None. Used only in components. | Buttons and anchors. |
24-
| `input` | None. Used only in components. | Form input fields. |
25-
26-
27-
The typography levels are collected into a typography config which is used to generate the CSS.
28-
29-
### Usage
30-
To get started, you first include the `Roboto` font with the 300, 400 and 500 weights.
31-
You can host it yourself or include it from [Google Fonts][2]:
32-
33-
```html
34-
<link rel="preconnect" href="https://fonts.gstatic.com">
35-
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">
36-
```
37-
38-
Now you can add the appropriate CSS classes to the elements that you want to style:
39-
40-
```html
41-
<h1 class="mat-display-1">Jackdaws love my big sphinx of quartz.</h1>
42-
<h2 class="mat-h2">The quick brown fox jumps over the lazy dog.</h2>
43-
```
44-
45-
By default, Angular Material doesn't apply any global CSS. To apply the library's typographic styles
46-
more broadly, you can take advantage of the `mat-typography` CSS class. This class will style all
47-
descendant native elements.
48-
49-
```html
50-
<!-- By default, Angular Material applies no global styles to native elements. -->
51-
<h1>This header is unstyled</h1>
52-
53-
<!-- Applying the mat-tyography class adds styles for native elements. -->
54-
<section class="mat-typography">
55-
<h1>This header will be styled</h1>
56-
</section>
57-
```
58-
59-
### Customization
60-
Typography customization is an extension of Angular Material's Sass-based theming. Similar to
61-
creating a custom theme, you can create a custom **typography configuration**.
62-
63-
```scss
64-
@import '~@angular/material/theming';
65-
66-
// Define a custom typography config that overrides the font-family as well as the
67-
// `headlines` and `body-1` levels.
68-
$custom-typography: mat-typography-config(
69-
$font-family: 'Roboto, monospace',
70-
$headline: mat-typography-level(32px, 48px, 700),
71-
$body-1: mat-typography-level(16px, 24px, 500)
72-
);
73-
```
74-
75-
As the above example demonstrates, a typography configuration is created by using the
76-
`mat-typography-config` function, which is given both the font-family and the set of typographic
77-
levels described earlier. Each typographic level is defined by the `mat-typography-level` function,
78-
which requires a `font-size`, `line-height`, and `font-weight`. **Note** that the `font-family`
79-
has to be in quotes.
80-
81-
82-
Once the custom typography definition is created, it can be consumed to generate styles via
83-
different Sass mixins.
84-
85-
```scss
86-
// Override typography CSS classes (e.g., mat-h1, mat-display-1, mat-typography, etc.).
87-
@include mat-base-typography($custom-typography);
88-
89-
// Override typography for a specific Angular Material components.
90-
@include mat-checkbox-typography($custom-typography);
91-
92-
// Override typography for all Angular Material, including mat-base-typography and all components.
93-
@include angular-material-typography($custom-typography);
94-
```
95-
96-
If you're using Material's theming, you can also pass in your typography config to the
97-
`mat-core` mixin:
98-
99-
```scss
100-
// Override the typography in the core CSS.
101-
@include mat-core($custom-typography);
102-
```
103-
104-
For more details about the typography functions and default config, see the
105-
[source](https://github.com/angular/components/blob/master/src/material/core/typography/_typography.scss).
106-
107-
108-
### Material typography in your custom CSS
109-
Angular Material includes typography utility mixins and functions that you can use to customize your
110-
own components:
111-
112-
* `mat-font-size($config, $level)` - Gets the `font-size`, based on the provided config and level.
113-
* `mat-font-family($config)` - Gets the `font-family`, based on the provided config.
114-
* `mat-line-height($config, $level)` - Gets the `line-height`, based on the provided
115-
config and level.
116-
* `mat-font-weight($config, $level)` - Gets the `font-weight`, based on the provided
117-
config and level.
118-
* `mat-typography-level-to-styles($config, $level)` - Mixin that takes in a configuration object
119-
and a typography level, and outputs a short-hand CSS `font` declaration.
120-
121-
```scss
122-
@import '~@angular/material/theming';
123-
124-
// Create a config with the default typography levels.
125-
$config: mat-typography-config();
126-
127-
// Custom header that uses only the Material `font-size` and `font-family`.
128-
.unicorn-header {
129-
font-size: mat-font-size($config, headline);
130-
font-family: mat-font-family($config);
131-
}
132-
133-
// Custom title that uses all of the typography styles from the `title` level.
134-
.unicorn-title {
135-
@include mat-typography-level-to-styles($config, title);
136-
}
137-
```
138-
139-
140-
[1]: https://material.io/archive/guidelines/style/typography.html
141-
[2]: https://fonts.google.com/
1+
# Angular Material typography
2+
3+
### What is typography?
4+
Typography is a way of arranging type to make text legible, readable, and appealing when displayed.
5+
Angular Material's typography is based on the guidelines from the [Material Design spec][1] and is
6+
arranged into typography levels. Each level has a `font-size`, `line-height` and `font-weight`. The
7+
available levels are:
8+
9+
10+
| Name | CSS classes | Description |
11+
|-----------------|----------------------------------|-----------------------------------------------------------------------------|
12+
| `display-4` | `.mat-display-4` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
13+
| `display-3` | `.mat-display-3` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
14+
| `display-2` | `.mat-display-2` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
15+
| `display-1` | `.mat-display-1` | Large, one-off header, usually at the top of the page (e.g. a hero header). |
16+
| `headline` | `.mat-h1`, `.mat-headline` | Section heading corresponding to the `<h1>` tag. |
17+
| `title` | `.mat-h2`, `.mat-title` | Section heading corresponding to the `<h2>` tag. |
18+
| `subheading-2` | `.mat-h3`, `.mat-subheading-2` | Section heading corresponding to the `<h3>` tag. |
19+
| `subheading-1` | `.mat-h4`, `.mat-subheading-1` | Section heading corresponding to the `<h4>` tag. |
20+
| `body-1` | `.mat-body`, `.mat-body-1` | Base body text. |
21+
| `body-2` | `.mat-body-strong`, `.mat-body-2`| Bolder body text. |
22+
| `caption` | `.mat-small`, `.mat-caption` | Smaller body and hint text. |
23+
| `button` | None. Used only in components. | Buttons and anchors. |
24+
| `input` | None. Used only in components. | Form input fields. |
25+
26+
27+
The typography levels are collected into a typography config which is used to generate the CSS.
28+
29+
### Usage
30+
To get started, you first include the `Roboto` font with the 300, 400 and 500 weights.
31+
You can host it yourself or include it from [Google Fonts][2]:
32+
33+
```html
34+
<link rel="preconnect" href="https://fonts.gstatic.com">
35+
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">
36+
```
37+
38+
Now you can add the appropriate CSS classes to the elements that you want to style:
39+
40+
```html
41+
<h1 class="mat-display-1">Jackdaws love my big sphinx of quartz.</h1>
42+
<h2 class="mat-h2">The quick brown fox jumps over the lazy dog.</h2>
43+
```
44+
45+
By default, Angular Material doesn't apply any global CSS. To apply the library's typographic styles
46+
more broadly, you can take advantage of the `mat-typography` CSS class. This class will style all
47+
descendant native elements.
48+
49+
```html
50+
<!-- By default, Angular Material applies no global styles to native elements. -->
51+
<h1>This header is unstyled</h1>
52+
53+
<!-- Applying the mat-tyography class adds styles for native elements. -->
54+
<section class="mat-typography">
55+
<h1>This header will be styled</h1>
56+
</section>
57+
```
58+
59+
### Customization
60+
Typography customization is an extension of Angular Material's Sass-based theming. Similar to
61+
creating a custom theme, you can create a custom **typography configuration**.
62+
63+
```scss
64+
@import '~@angular/material/theming';
65+
66+
// Define a custom typography config that overrides the font-family as well as the
67+
// `headlines` and `body-1` levels.
68+
$custom-typography-theme: (
69+
typography: mat-typography-config(
70+
$font-family: 'Roboto, monospace',
71+
$headline: mat-typography-level(32px, 48px, 700),
72+
$body-1: mat-typography-level(16px, 24px, 500)
73+
)
74+
);
75+
```
76+
77+
As the above example demonstrates, a typography configuration is created by using the
78+
`mat-typography-config` function, which is given both the font-family and the set of typographic
79+
levels described earlier. Each typographic level is defined by the `mat-typography-level` function,
80+
which requires a `font-size`, `line-height`, and `font-weight`. **Note** that the `font-family`
81+
has to be in quotes.
82+
83+
84+
Once the custom typography definition is created, it can be consumed to generate styles via
85+
different Sass mixins.
86+
87+
```scss
88+
// Override typography CSS classes (e.g., mat-h1, mat-display-1, mat-typography, etc.).
89+
@include mat-base-typography($custom-typography-theme);
90+
91+
// Override typography for a specific Angular Material components.
92+
@include mat-checkbox-typography($custom-typography-theme);
93+
94+
// Override typography for all Angular Material, including mat-base-typography and all components.
95+
@include angular-material-typography($custom-typography-theme);
96+
```
97+
98+
If you're using Material's theming, you can also pass in your typography config to the
99+
`mat-core` mixin:
100+
101+
```scss
102+
// Override the typography in the core CSS.
103+
@include mat-core($custom-typography-theme);
104+
```
105+
106+
For more details about the typography functions and default config, see the
107+
[source](https://github.com/angular/components/blob/master/src/material/core/typography/_typography.scss).
108+
109+
110+
### Material typography in your custom CSS
111+
Angular Material includes typography utility mixins and functions that you can use to customize your
112+
own components:
113+
114+
* `mat-font-size($config, $level)` - Gets the `font-size`, based on the provided config and level.
115+
* `mat-font-family($config)` - Gets the `font-family`, based on the provided config.
116+
* `mat-line-height($config, $level)` - Gets the `line-height`, based on the provided
117+
config and level.
118+
* `mat-font-weight($config, $level)` - Gets the `font-weight`, based on the provided
119+
config and level.
120+
* `mat-typography-level-to-styles($config, $level)` - Mixin that takes in a configuration object
121+
and a typography level, and outputs a short-hand CSS `font` declaration.
122+
123+
```scss
124+
@import '~@angular/material/theming';
125+
126+
// Create a config with the default typography levels.
127+
$config: mat-typography-config();
128+
129+
// Custom header that uses only the Material `font-size` and `font-family`.
130+
.unicorn-header {
131+
font-size: mat-font-size($config, headline);
132+
font-family: mat-font-family($config);
133+
}
134+
135+
// Custom title that uses all of the typography styles from the `title` level.
136+
.unicorn-title {
137+
@include mat-typography-level-to-styles($config, title);
138+
}
139+
```
140+
141+
142+
[1]: https://material.io/archive/guidelines/style/typography.html
143+
[2]: https://fonts.google.com/

‎src/material-experimental/README.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,9 +61,14 @@ be included in the pre-built CSS mixin and will need to be explicitly included.
6161
color: (
6262
primary: $my-primary,
6363
accent: $my-accent
64-
)
64+
),
65+
// Using `mat-mdc-typography-config` rather than `mat-typography-config` generates a typography
66+
// config directly from the official Material Design styles. This includes using `rem`-based
67+
// measurements rather than `px`-based ones as the spec recommends.
68+
typography: mat-mdc-typography-config(),
69+
// The density level to use in this theme, defaults to 0 if not specified.
70+
density: 0
6571
));
6672

6773
@include angular-material-mdc-theme($my-theme);
68-
@include angular-material-mdc-typography();
6974
```

0 commit comments

Comments
 (0)