@carbon/styles 1.111.0 → 1.112.0-rc.0

package/README.md

@@ -74,6 +74,95 @@ To learn more about the various helpers that `@carbon/styles` provides, checkout
 the overview of the files available to use in our
 [Sass docs](./docs/sass.md#files).
 
+## Replacing the typeface
+
+Carbon is designed, tested, and tuned for IBM Plex. We do not recommend
+replacing the Carbon typeface. If you absolutely need to use a different
+typeface, you'll need to treat it as a build-time Sass customization that your
+application owns. There is no support for runtime typeface overrides on
+prebuilt/CDN Carbon styles.
+
+<!-- prettier-ignore-start -->
+> [!WARNING]
+> **Use at your own risk**
+>
+> Overriding the Carbon typeface has broad design and accessibility
+> implications. Carbon type styles are tuned with IBM Plex metrics in mind,
+> including line heights, letter spacing, weight, glyph proportions, ligatures,
+> and fallback behavior. A replacement typeface can change layout, wrapping,
+> density, readability, and interaction states. It can be a significant design
+> and engineering effort to make another typeface work correctly across an
+> application.
+<!-- prettier-ignore-end -->
+
+To use Carbon with a different typeface, three things are needed:
+
+1. Turn off Carbon's Plex `@font-face` generation
+2. Change the root `font-family` definition(s)
+3. Supply your own `@font-face` rules
+
+You can accomplish the first two by configuring the Sass entrypoint that your
+application compiles. This configuration must happen before any other `@use` of
+Carbon Sass modules.
+
+```scss
+@use 'sass:string';
+
+@use '@carbon/styles' with (
+  // Turn off Carbon's Plex `@font-face` generation
+  $css--font-face: false,
+
+  // Change the root `font-family` definition(s)
+  $font-families:
+    (
+      'sans':
+        string.unquote(
+          "'Inter Local', system-ui, -apple-system, BlinkMacSystemFont, '.SFNSText-Regular', sans-serif"
+        ),
+      'mono':
+        string.unquote(
+          "'IBM Plex Mono', system-ui, -apple-system, BlinkMacSystemFont, '.SFNSText-Regular', monospace"
+        ),
+      'serif':
+        string.unquote(
+          "'IBM Plex Serif', system-ui, -apple-system, BlinkMacSystemFont, '.SFNSText-Regular', serif"
+        ),
+      // Include any other Carbon font family keys your application compiles.
+    )
+);
+```
+
+`$font-families` is not merged with Carbon's defaults. If you configure this
+map, include every family key your compiled styles need, such as `sans`, `mono`,
+`serif`, or any additional language-specific Plex stacks used by your
+application.
+
+Then, supply your own `@font-face` rules to load your replacement font assets.
+
+```scss
+@font-face {
+  font-display: swap;
+  font-family: 'Inter Local';
+  font-style: normal;
+  font-weight: 400;
+  src: url('./fonts/inter-latin-400-normal.woff2') format('woff2');
+}
+
+@font-face {
+  font-display: swap;
+  font-family: 'Inter Local';
+  font-style: normal;
+  font-weight: 600;
+  src: url('./fonts/inter-latin-600-normal.woff2') format('woff2');
+}
+```
+
+Only load the weights, styles, and Unicode ranges that your application needs,
+but make sure they cover the font weights and styles your Carbon usage emits. If
+you use a third-party font service, review its privacy and regional compliance
+implications carefully, including whether font requests expose user data in ways
+your application cannot accept.
+
 ## Theming
 
 You can change the default theme of Carbon by doing the following: