Skip to content

Commit 1979b81

Browse files
crisbetocrisbeto
committed
docs: add a typography guide
Adds a guide that shows how to use the typography setup.
1 parent 0aaeb69 commit 1979b81

File tree

2 files changed

+128
-2
lines changed

2 files changed

+128
-2
lines changed

‎guides/compatibility-mode.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
## What is compatibility mode?
2-
Compatibility mode for `@angular/material` allows the components to exist side-by-side with AngularJS Material components without any CSS collisions.
2+
Compatibility mode for `@angular/material` allows the components to exist side-by-side with
3+
AngularJS Material components without any CSS collisions.
34

45
## What does compatibility mode do?
5-
When enabled, compatibility mode enforces that all template APIs use the prefix `mat-` instead of `md-`. This will prevent any CSS from AngularJS Material from affecting the components in `@angular/material`.
6+
When enabled, compatibility mode enforces that all template APIs use the prefix `mat-` instead of
7+
`md-`. This will prevent any CSS from AngularJS Material from affecting the components in
8+
`@angular/material`.
69

710
## How is compatibility mode enabled?
811
Import `NoConflictStyleCompatibilityMode` into your application's root `NgModule`.

‎guides/typography.md

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

0 commit comments

Comments
 (0)