docs(Plex): add plex, font-face documentation (#9371)

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
carbon-design-system · Aug 4, 2021 · 1ea5be5 · 1ea5be5
1 parent 06216df
commit 1ea5be5
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 2 deletions.
diff --git a/docs/migration/11.x-carbon-components.md b/docs/migration/11.x-carbon-components.md
@@ -70,7 +70,7 @@ below that goes over any API changes for the file.
 | [`scss/globals/grid/_grid.scss`](#scssglobalsgrid_gridscss)                     | Moved to `scss/_grid.scss`                |
 | [`scss/globals/scss/_colors.scss`](#scssglobalsscss_colorsscss)                 | Moved to `scss/_colors.scss`              |
 | [`scss/globals/scss/_css--body.scss`](#scssglobalsscss_css--bodyscss)           | TODO                                      |
-| [`scss/globals/scss/_css--font-face.scss`](#scssglobalsscss_css--font-facescss) | TODO                                      |
+| [`scss/globals/scss/_css--font-face.scss`](#scssglobalsscss_css--font-facescss) | Moved to `scss/_font-face.scss`           |
 | [`scss/globals/scss/_css--helpers.scss`](#scssglobalsscss_css--helpersscss)     | Moved to `scss/utilities/`                |
 | [`scss/globals/scss/_css--reset.scss`](#scssglobalsscss_css--resetscss)         | Moved to `scss/_reset.scss`               |
 | [`scss/globals/scss/_helper-classes.scss`](#scssglobalsscss_helper-classesscss) | Moved to `scss/utilities/`                |
@@ -150,7 +150,13 @@ TODO
 
 ### `scss/globals/scss/_css--font-face.scss`
 
-TODO
+Beginning in V11, the `@ibm/plex` package will be included as a dependency of
+`@carbon/styles`. Because of this, we will no longer be serving the files via
+Google Fonts. You will get the fonts by default by importing from the main
+entrypoint (`@use '@carbon/styles'`), or by referencing the font face file
+directly (`@use '@carbon/styles/scss/font-face'`). If you are already hosting
+the font files, and do not want the font files to be emitted, you can set the
+`$css--font-face` variable to `false`.
 
 ### `scss/globals/scss/_css--helpers.scss`
 

diff --git a/packages/styles/docs/sass.md b/packages/styles/docs/sass.md
@@ -51,6 +51,7 @@ between version updates.
 | [`scss/compat/`](#compatibility)       | Helper themes and tokens for migrating from v10 to v11     |
 | [`scss/config`](#config)               | Configure various options for the package                  |
 | [`scss/feature-flags`](#feature-flags) | Configure various feature flags for experiments            |
+| [`scss/font-face`](#font-face)         | Configure the IBM Plex font and languages                  |
 | [`scss/grid`](#grid)                   | Access and use the CSS Grid built-in to Carbon             |
 | [`scss/motion`](#motion)               | Helper function, mixins, and tokens for motion             |
 | [`scss/reset`](#reset)                 | A CSS Reset                                                |
@@ -100,6 +101,42 @@ docs.
 | :------------------------------------------ | :------------------------- |
 | `@use '@carbon/styles/scss/feature-flags';` | `scss/_feature-flags.scss` |
 
+## Font Face
+
+| Import                                  | Filepath               |
+| :-------------------------------------- | :--------------------- |
+| `@use '@carbon/styles/scss/font-face';` | `scss/_font-face.scss` |
+
+### Using IBM Plex
+
+By default, IBM Plex will be emitted when importing via the `@carbon/styles`
+main entrypoint or referencing the `font-face` file directly. If you do not want
+the font-face declarations to be emitted, you can set the `css--font-face` token
+to `false`:
+
+```scss
+@use '@carbon/styles/scss/config' with (
+  $css--font-face: false,
+);
+```
+
+### Emitting additional typefaces
+
+When using the font-face declarations, only `IBM Plex Sans` and `IBM Plex Mono`
+are emitted. If you would like to emit additional typefaces, like
+`IBM Plex Sans Arabic`, you can set additional config tokens:
+
+```scss
+@use '@carbon/styles/scss/config' with (
+  $css--plex-arabic: true,
+);
+```
+
+| IBM Plex Language | Token               |
+| :---------------- | :------------------ |
+| Arabic            | `$css--plex-arabic` |
+| TODO              | `TODO`              |
+
 ## Grid
 
 | Import                             | Filepath          |