Documentation missing on how to use variable fonts with new font API

[davidjost]

📚 Subject area/topic

Font API

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/fonts/

📋 Description of content that is out-of-date or incorrect

Font providers offer usage of variable fonts instead of fixed width variants, example: https://www.fontshare.com/fonts/red-hat-display (scroll to bottom of the list)

I want to use the variable variant from this font but am unable to due to missing documentation.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[delucis]

Thanks for the feedback! We show how to use variable weights in the reference docs: https://docs.astro.build/en/reference/font-provider-reference/#weight

But I agree it might be worth explaining in a guide too.

[davidjost]

This results in the error Expected type "tuple", received "string".

Targeting this font as the variable version in the usual way is done via <link href="https://api.fontshare.com/v2/css?f[]=red-hat-display@1,2&display=swap" rel="stylesheet"> .

I tried using it via [1, 2], "1 2" and "100 900", neither syntax seems to return the expected variable font. Claude doesn't get it right either.

[delucis]

Oh, good to know, I guess the docs may be wrong then? Which font provider are you using?

Tagging in @florian-lefebvre here too.

[davidjost]

I'm centralizing my font control:

//theme.json
{
  "fonts": {
    "primary": {
      "name": "Red Hat Display",
      "weights": [300, 400, 500, 600, 700, 800, 900],
      "provider": "fontshare",
      "styles": ["normal", "italic"]
    }
  }
}

//astro.config.mjs
import { defineConfig, fontProviders } from "astro/config";
import mdx from "@astrojs/mdx";
import theme from "./src/config/theme.json";

const providerMap = {
  google: () => fontProviders.google(),
  fontshare: () => fontProviders.fontshare(),
  fontsource: () => fontProviders.fontsource(),
  bunny: () => fontProviders.bunny(),
};

export default defineConfig({
  integrations: [mdx()],
  devToolbar: {
    enabled: false,
  },
  fonts: Object.entries(theme.fonts).map(([key, font]) => ({
    name: font.name,
    cssVariable: `--font-${key}`,
    provider: providerMap[font.provider](),
    weights: font.weights,
    styles: font.styles,
  })),
});

//commonhead.astro
import theme from "../config/theme.json";
import { Font } from "astro:assets";
const fontEntries = Object.keys(theme.fonts);
---

{
  fontEntries.map((key) => {
    const cssVar = `--font-${key}` as any;
    return <Font cssVariable={cssVar} preload />;
  })
}

In my styles I then use --font-primary for the headlines. Changing the weights key to "100 900" results in the error mentioned above.

I might simply miss something obvious, I'm a designer, not a developer.

[delucis]

OK, it appears there are multiple issues:

1. weights: "100 900" isn’t supported, it has to be weights: ["100 900"], which doesn’t match what is documented (the same incorrect syntax is shown in the JSDoc comment for this option)

2. The fontshare provider seems not to return variable fonts? Even with a valid variable range, it always returns multiple static weights AFAICT. But there’s no error indicating this configuration–result mismatch. Switching to the google provider does work (Red Hat Display is available from Google too luckily).

3. Red Hat Display’s lowest available weight is 300 not 100, so ["100 900"] causes an error with the Google provider, but with ["300 900"], it successfully downloads the variable font as expected.

So a couple of action items coming out of that:

1. We should update the docs to correctly show the variable syntax (or if we intended to support providing a string, we should fix that support)

2. We should investigate if we can provide better errors for configuration issues like this one. The Google provider did throw something a tiny more helpful than the Fontshare one (“Could not resolve font face for Red Hat Display from google-c200761b0711fe56 provider”) which prompted me to look at the font and realise it didn’t include weights down to 100. But it’s still not super obvious though. Unfortunately, I suspect if we don’t get more info back from the font services, it’s hard to provide better user feedback.

[florian-lefebvre]

• The example you linked CHris is correct, this is how it works for the local provider. It is properly documented at https://docs.astro.build/en/reference/configuration-reference/#fontweights. But yeah maybe we should have a section for them in the guide (it should explain that most providers will try to fallback to individual weights if the variable cannot be found)
• Looking at Fontshare's API, it seems it doesn't return variable fonts? So I don't think unifont can do anything here unfortunately

[delucis]

• The example you linked CHris is correct, this is how it works for the local provider

Ah right. This was the docs page linked from the fonts guide — I didn’t think to go to the config reference. Maybe we shouldn’t link the provider docs too much if they’re mainly intended for implementing new providers? (Also a bit of a search issue because that page ranks higher than either the guide or the config reference.)

• Looking at Fontshare's API, it seems it doesn't return variable fonts? So I don't think unifont can do anything here unfortunately

If we know they don’t support them, then I guess we can proactively throw an error and provide that feedback to users? The current behaviour is that it silently returns something that is not what the user requested. I think an error would be clearer here.

[florian-lefebvre]

IIRC I implemented this behavior in unifont on purpose (unjs/unifont#108 for context). So maybe we should log a warning (in unifont or in astro) when we pick individual weights for a variable weight as input

[delucis]

IIRC I implemented this behavior in unifont on purpose (unjs/unifont#108 for context). So maybe we should log a warning (in unifont or in astro) when we pick individual weights for a variable weight as input

Not sure I understood the context: wouldn’t it be better to error and provide a clear message if the service doesn’t support the user’s config? I’m not really a fan of warnings as they’re easily overlooked.

In this case, the ideal behaviour I can imagine would be:

1. User sets weights: "100 900" — errors and says

   The value of weights must be an array, please change "100 900" to ["100 900"]

2. User sets weights: ["100 900"] but provider can’t provide variable fonts — errors and says

   Variable ranges are not supported by provider X, please specify the individual weights you want, e.g. ["100", "400", "900"]

3. User sets weights: ["100 900"] but this font only supports a smaller range — errors and says

   Variable range "100 900" is out of bounds for font X, which only supports a range of "300 900". Please update the requested range.

IIUC 3 might be impossible to do because it depends on the API response of the provider and they probably don’t provide a clear enough error, but 1 and 2 could be do-able? (1 is kind of already the case actually. Error message could probably be improved but it talks about wanting a “tuple”.)

[florian-lefebvre]

1. Yes easy to do, just needs some zod customization
2. Yeah I think that would work. So basically that means throwing here: https://github.com/unjs/unifont/blob/main/src/utils.ts#L41-L51. To be precise I think it should warn and keep this behavior, unless throwOnError is enabled in which case it just throws
3. I think it can be done similarly in this function

[florian-lefebvre]

So to recap, actions are:

1. Add a section in the fonts guide on variable fonts
2. Investigate ranking, config.fonts reference should probably come before the font provider reference
3. Improve the unifont prepareWeights() function to handle no variable fonts or incompatible range
4. Update Astro's font schemas to have better errors
5. Do what we have to do in Astro to benefit from the unifont update from 3)

[delucis]

Great summary — thanks @florian-lefebvre!

I think we’ve seen search ranking issues more generally, so probably something to tackle globally, not just for this page. From experience it will be hard to get config reference to rank higher than the dedicated Font Provider API page, but we can at least ensure the fonts guide ranks first.

[3x10RaiseTo8]

Just want to add a few things.

1. variableSettings property doesn't result in any change.
2. subsets are not defined. The article linked in the docs isn't helpful in knowing the actual keyword. Should be a list of defined enums.
3. stretch doesn't work as well in the below case.

 {
      name: "Noto Sans",
      cssVariable: "--font-sans",
      provider: fontProviders.google(),
      variationSettings: "'wdth' 75",
      subsets: ["latin"],
      stretch: "condensed"
}