basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    Your own font on a site: @font-face, subsets and loading without a jump

    Serve your own font as a woff2 file from your own site: one variable file gives every weight, each script comes as a separate subset, and the fallback font is matched by its metrics — when your font arrives, the text doesn’t jump. Here’s the CSS that Astro builds for this site, line by line.

    Where the file comes from

    Since 2020 browsers partition their cache by site: Chrome since version 86, Firefox since 85, Safari even earlier. A file from fonts.gstatic.com downloaded on one site is downloaded again on another, so the shared Google Fonts cache no longer wins anything. Your own server saves two connections — to fonts.googleapis.com for the CSS and to fonts.gstatic.com for the files — and the reader never contacts Google.

    Take the files from Google Fonts or the Fontsource packages and host them next to the site. This site does that at build time: Astro downloads the fonts listed in astro.config.mjs and writes their CSS itself.

    // astro.config.mjs
    fonts: [
      {
        provider: fontProviders.google(),
        name: 'Golos Text',
        cssVariable: '--font-golos',
        weights: ['400 700'],
        styles: ['normal'],
        subsets: ['latin', 'cyrillic'],
        fallbacks: ['sans-serif'],
      },
    ],

    weights: ['400 700'] is a range, so Astro takes the variable file. subsets says which subsets to download: Google also offers latin-ext and cyrillic-ext for Golos, with letters of other languages, which this site doesn’t need — a site in, say, Polish or Czech would need latin-ext. fallbacks says what to build the fallback from: for sans-serif Astro tunes Arial. The <Font cssVariable="--font-golos" /> component puts the CSS into <head>. Below is that CSS, without the hash Astro adds to the font’s name.

    The file

    Font CSS in the page’s <head>
    @font-face {
      font-family: "Golos Text";
      src: url("/_astro/fonts/ddd583b46ef3047f.woff2")
        format("woff2");
      font-weight: 400 700;
      font-style: normal;
      font-display: swap;
      unicode-range: U+0301, U+0400-045F, U+0490-0491,
        U+04B0-04B1, U+2116;
    }

    A variable file: font-weight: 400 700 is a range, and one 22 KB file serves both body text and bold headings; without a variable font there’d be a file per weight. unicode-range is Cyrillic: U+0400-045F covers the letters, U+2116 is “№”. The browser downloads the file only if the page has such characters.

    default:font-display autounicode-range every character

    @font-face {
      font-family: "Golos Text";
      src: url("/_astro/fonts/d911f2505890b67e.woff2")
        format("woff2");
      font-weight: 400 700;
      font-style: normal;
      font-display: swap;
      unicode-range: U+0000-00FF, U+0131, U+0152-0153,
        U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304,
        U+0308, U+0329, U+2000-206F, U+20AC, U+2122,
        U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
    }
    Key part

    The same name, a different range: the browser merges the blocks into one font and takes the right file for each character. The 38 KB Latin file is needed on a Russian page too: U+0000-00FF holds the space, digits, punctuation and guillemets, U+2000-206F dashes and curly quotes. So on a Russian page Golos is two files, 60 KB.

    @font-face {
      font-family: "Golos Text fallback";
      src: local("Arial");
      size-adjust: 103.6337%;
      ascent-override: 94.5638%;
      descent-override: 21.2286%;
      line-gap-override: 0%;
    }
    Key part

    The fallback is the system’s Arial, tuned to Golos: size-adjust stretches it by 3.6% so a paragraph takes the same width, and ascent-override and descent-override give the same line height. While Golos downloads, the text is already in its place, and the swap doesn’t move it. Astro computes the numbers from both fonts’ metrics — optimizedFallbacks, on by default.

    default:size-adjust 100%ascent-override from the font

    :root {
      --font-golos: "Golos Text", "Golos Text fallback",
        sans-serif;
      --f-sans: var(--font-golos);
    }
    
    body {
      font-family: var(--f-sans);
    }

    The order: your font, the tuned fallback, the generic sans-serif in case the system lacks even Arial. Astro declares the --font-golos variable, and the site takes it through its own --f-sans: another font for body text is a one-line change in the tokens.

    body {
      font-synthesis: none;
    }

    Forbids the browser from faking missing styles: bold by thickening, italic by slanting upright letters. Instead of a fake you get regular text, and you see at once which file is missing. Golos Text has no italic, and the site doesn’t use italic — so the line isn’t here.

    Preloading

    <link rel="preload" href="/_astro/fonts/ddd583b46ef3047f.woff2" as="font" type="font/woff2" crossorigin>

    Without preload the browser learns about the file late: it parses the HTML and CSS, builds the page, and only then sees that a paragraph needs Golos. With preload the download starts as soon as the browser reads that line in <head>. crossorigin is needed even for your own domain: fonts are requested in CORS mode, and without the attribute the preloaded file won’t match — the browser downloads it a second time.

    Preload one or two main styles: every preload shares the connection with the CSS and the first screen’s images. Here Russian pages preload both Golos files — a paragraph needs the Latin one from its first space — and Unbounded’s Cyrillic, and English pages the Latin files: <Font cssVariable="--font-golos" preload={[{ subset: 'cyrillic' }, { subset: 'latin' }]} />.

    What to show while the file downloads

    font-display decides what the reader sees before the file arrives. The numbers are the CSS Fonts specification’s recommendation, and browsers may deviate from it.

    Value While the file downloads When the file arrives When to use
    block text invisible, up to 3 s swaps in an icon font: a fallback would draw a letter instead of the icon
    swap the fallback right away swaps in whenever it arrives body text: readable at once. That’s this site, and Google Fonts with display=swap in the URL
    fallback the fallback after 100 ms swaps in only if it arrived within 3 s a jump is acceptable only in the first seconds
    optional the fallback after 100 ms too late — the page stays in the fallback, and the file is used on the next page a jump is worse than someone else’s font

    auto leaves the choice to the browser. Astro sets swap itself: the site’s astro.config.mjs doesn’t set display, and the built CSS has swap. With a tuned fallback the swap barely moves the text.

    How to check

    • DevTools, the Network tab, the Font filter, a reload without cache (Ctrl+Shift+R): on a Russian page Golos arrives as two files, about 22 and 38 KB; on an English page the 38 KB Latin file is the one preloaded. No extra subsets.
    • In the same place — Slow 4G throttling and a reload: the text is visible at once, and when the font swaps in, lines don’t rewrap and paragraphs don’t shift.
    • Elements, Computed, the Rendered Fonts block at the bottom — for a paragraph it shows Golos Text, not Arial.

    If it doesn’t work

    The font is set up, but the Network tab in DevTools shows no file

    Cause
    The name in font-family doesn’t match the name in @font-face — even by a space — or the page has no character from the unicode-range: then the browser doesn’t request the file.
    Fix
    Compare the names. In DevTools, Elements, Computed, the Rendered Fonts block at the bottom shows which font in fact drew the text.

    The font file downloads twice, and the console warns about preload

    Cause
    The <link rel=preload> has no crossorigin. Browsers always request fonts in CORS mode, and a file preloaded without it doesn’t match.
    Fix
    Add crossorigin — even for a file from your own domain.

    A font from a CDN won’t load, and the console shows a CORS error

    Cause
    The browser takes a font file from another domain only if the server answered with an Access-Control-Allow-Origin header.
    Fix
    Set the header on the CDN, or serve the file from your own domain — then CORS isn’t needed.

    The fallback is tuned, but in Safari lines still shift vertically on the swap

    Cause
    Safari supports size-adjust since version 17, but not yet ascent-override, descent-override and line-gap-override: width is matched, line height isn’t.
    Fix
    The vertical shift in Safari stays. preload of the main file reduces it: the sooner the file arrives, the less text gets drawn in the fallback.