Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs adjust font loading polish #584

Merged
merged 2 commits into from
Oct 21, 2024
Merged

Docs adjust font loading polish #584

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a0fc69c
Docs: Font loading adjustments
jonniebigodes Oct 18, 2024
048235c
Minor tweak
jonniebigodes Oct 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 10 additions & 21 deletions src/content/snapshotOptions/font-loading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ sidebar: { order: 2 }

Browsers can decide to render HTML in multiple passes when custom fonts are used. They do this to speed up the time-to-first-meaningful-paint.

Unfortunately, this behavior can cause your story to render without the custom font. Or worse, render inconsistently. That triggers font rendering changes that you have to accept again and again. Here are ways to prevent that.
Unfortunately, this behavior can cause your tests to render without the custom font or, worse, render inconsistently. That triggers font rendering changes that you have to accept again and again. Here are ways to prevent that.

## Best practice: Fallback to web-safe fonts

Web font loading can vary between browsers, versions, and operating systems. Web-safe fonts are commonly installed by default on browsers and operating systems. We recommend you include a web-safe font in your font stack as a fallback in case your web font isn't available or doesn't load as expected.

```css
```css title="src/index.css"
/* Fallback to "Courier New" for monospace fonts */

code {
Expand All @@ -36,11 +36,9 @@ code {

## Solution A: Preload fonts

We recommend that you ensure fonts are always loaded prior to rendering the story. Preload fonts in Storybook by specifying them in `./storybook/preview-head.html`.

```js
// ./storybook/preview-head.html
We recommend that you always ensure fonts are loaded before your tests are executed. With Storybook, you can preload fonts by specifying them in [`./storybook/preview-head.html`](https://storybook.js.org/docs/configure/story-rendering#adding-to-head).

```js title="./storybook/preview-head.html"
<link
rel="preload"
href="path/to/font.woff2"
Expand All @@ -60,9 +58,7 @@ If your CSS has global `@font-face` declarations that point to a CDN, you may ne

For example, you might have a font CDN referenced in your stylesheets like so.

```css
/* yourglobalstyles.css */

```css title="src/index.css"
@font-face {
font-display: optional;
font-family: "YourFont";
Expand All @@ -76,9 +72,7 @@ To serve the fonts statically, you first need to put your fonts in a static dire

Next, create a `yourfontface.css` CSS inside your Storybook configuration directory (i.e., `.storybook`). We'll use it to reference the local path for your font in the `../public` directory.

```css
/* ./storybook/yourfontface.css */

```css title="./storybook/yourfontface.css"
@font-face {
font-display: optional;
font-family: "YourFont";
Expand All @@ -89,24 +83,19 @@ Next, create a `yourfontface.css` CSS inside your Storybook configuration direct
}
```

Reference the stylesheet in Storybook's `preview-head.html` configuration to load the font from the local path.
Reference the stylesheet in Storybook's [`preview-head.html`](https://storybook.js.org/docs/configure/story-rendering#adding-to-head) configuration file to load the font from the local path.

```js
// ./storybook/preview-head.html

// 👇 Add this
```js title="./storybook/preview-head.html"
<link rel="stylesheet" type="text/css" href="/yourfontface.css">
```

This technique loads a local font file during development and testing in Storybook. Meanwhile your users still load the font from the CDN in production.
This technique loads a local font file during development and testing in Storybook. Meanwhile, your users are still loading the font from the CDN in production.

## Solution C: Check fonts have loaded in a loader

This alternate solution uses the browser's font load API and the [`isChromatic()`](/docs/ischromatic) helper function to verify that fonts load when in the Chromatic environment.

```js
// .storybook/preview.js

```js title="./storybook/preview.js|ts"
import isChromatic from "chromatic/isChromatic";

// Use the document.fonts API to check if fonts have loaded
Expand Down
Loading