Docs could be clearer on when we should have to define styles

[feinstein]

trafficstars

Page URL

https://docs.flutter.dev/cookbook/design/fonts/

Page source

https://github.com/flutter/website/tree/main/src/content/cookbook/design/fonts.md

Describe the problem

The website describes how to use custom fonts, but it says:

Set styles and weights with font files

When you declare which font files represent styles or weights of a font, you can apply the style or weight properties.

The wording here implies that it's optional, it says we can apply not that we should apply.

For example, if I have imported Raleway-Regular.ttf, Raleway-Italic.ttf, and RobotoMono-Bold.ttf, will Flutter automatically understand that a font file ending with Italic is the italic style, or do I have to define it?

The text mentions that when Flutter doesn't have the proper definition, then Flutter will try to force a visual distortion that might look bad, but it's not clear how far can Flutter infer the options, and avoiding all of that boiler plate while defining fonts it's very welcomed.

For example, here's what I have to add to configure one typeface that my design team wants to use:

    - family: TTNormsPro
      fonts:
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Regular.ttf
          weight: 400
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Normal.ttf
          weight: 400
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Italic.ttf
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-NormalItalic.ttf
          style: italic
          weight: 400
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Light.ttf
          weight: 300
        - asset: assets/fonts/TTNormsPro/TTNormsPro-LightItalic.ttf
          weight: 300
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-ExtraLight.ttf
          weight: 200
        - asset: assets/fonts/TTNormsPro/TTNormsPro-ExtraLight-Italic.ttf
          weight: 200
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Thin.ttf
          weight: 100
        - asset: assets/fonts/TTNormsPro/TTNormsPro-ThinItalic.ttf
          weight: 100
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Medium.ttf
          weight: 500
        - asset: assets/fonts/TTNormsPro/TTNormsPro-MediumItalic.ttf
          weight: 500
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-DemiBold.ttf
          weight: 600
        - asset: assets/fonts/TTNormsPro/TTNormsPro-DemiBoldItalic.ttf
          weight: 600
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Bold.ttf
          weight: 700
        - asset: assets/fonts/TTNormsPro/TTNormsPro-BoldItalic.ttf
          weight: 700
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-ExtraBold.ttf
          weight: 800
        - asset: assets/fonts/TTNormsPro/TTNormsPro-ExtraBoldItalic.ttf
          weight: 800
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-Black.ttf
          weight: 900
        - asset: assets/fonts/TTNormsPro/TTNormsPro-BlackItalic.ttf
          weight: 900
          style: italic
        - asset: assets/fonts/TTNormsPro/TTNormsPro-ExtraBlack.ttf
          weight: 950
        - asset: assets/fonts/TTNormsPro/TTNormsPro-ExtraBlackItalic.ttf
          weight: 950
          style: italic

If the docs made it clear that I can avoid typing all of this, then this would save me some time. (I have thought about testing this, but I am not sure if I would be able, as Flutter will distort my fonts to try to comply with my style selection, and I rather have a documented answer).

As an extra, maybe I got this wrong, but the doc firstly explains the difference between a typeface and a font, which for me it appears that a typeface is a collection of fonts, and a font is only one file, like RobotoMono-Bold.ttf, but then the rest of the document only uses the word "font", which I feel like in many places maybe it was meaning more "typeface".

Expected fix

Clarify if we always have to define the style and weight for each font that's being imported, or if Flutter has some basic rules and applies them by default and we don't have to worry.

Additional context

The Google Fonts package docs says that if the fonts are in a specific format, then we don't have to worry about defining the styles and fonts, but it's not clear if this is a feature from the package or if Flutter itself is handling this.

I would like to fix this problem.

• [ ] I will try and fix this problem on docs.flutter.dev.

[sfshaza2]

@Piinks, any idea who might know this?

[Piinks]

I've asked around, and it sounds like @jason-simmons may know best here. This lives in the engine. :)

[jason-simmons]

The current implementation of font matching in the Flutter engine ignores the weights and styles declared in pubspec.yaml. (see https://github.com/flutter/engine/blob/66832de608c9f61e4db04589d52b2b899bca38eb/lib/ui/text/font_collection.cc#L121)

Font matching is instead based on the weight, style, and other attributes defined within the font asset files.

(I don't know if the web platform makes use of the weight and style declarations.)

[feinstein]

@jason-simmons so you are saying that this tutorial is completely outdated and we shouldn't be defining weights and styles at all inside pubspec.yaml?

[jason-simmons]

The font style and weight attributes in pubspec.yaml are currently not used by the engine. In theory the engine could someday use them for some purpose (although I suspect this is unlikely to change given that users depend on the current behavior).

@yjbanov Does Flutter Web use the font weights and styles in pubspec.yaml in any way? (I did not notice any usage when looking through lib/web_ui)

If nobody uses or intends to use this data, then we should deprecate it and remove it from the documentation.

[sfshaza2]

I agree with Jason!

On Tue, Jan 14, 2025 at 8:09 AM Jason Simmons @.***> wrote:

The font style and weight attributes in pubspec.yaml are currently not used by the engine. In theory the engine could someday use them for some purpose (although I suspect this is unlikely to change given that users depend on the current behavior).

@yjbanov https://github.com/yjbanov Does Flutter Web use the font weights and styles in pubspec.yaml in any way? (I did not notice any usage when looking through lib/web_ui)

If nobody uses or intends to use this data, then we should deprecate it and remove it from the documentation.

— Reply to this email directly, view it on GitHub https://github.com/flutter/website/issues/11581#issuecomment-2590376393, or unsubscribe https://github.com/notifications/unsubscribe-auth/AKS4PKKEXF7M3NZ3CVBBE2L2KUZDLAVCNFSM6AAAAABU5XH7B2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKOJQGM3TMMZZGM . You are receiving this because you commented.Message ID: @.***>

[feinstein]

Not only that, but the docs state that if not defined, the expected behaviour will change and your texts will appear distorted, so I can't see a scenario where we can keep the text as is.

[sfshaza2]

@jason-simmons, thanks for much for clarifying! However, have you looked at the referenced cookbook recipe? https://docs.flutter.dev/cookbook/design/fonts

The entire thing is based on using the pubspec file to specify the font characteristics. So... either I need to deprecate this page, or add some sort of a caveat, but I am unsure what that would be. Does this approach work in some cases?

thx!

[jason-simmons]

The Flutter Web HTML renderer is still using the weight and style attributes in pubspec.yaml. See the use of descriptors in HtmlFontCollection, which applies these attributes to font face objects that are used by browser font matching.

Deprecation of these attributes should be deferred until the removal of the HTML renderer is complete.

[feinstein]

@jason-simmons @sfshaza2 should we then update the tutorial with an info box saying this whole page only applies to Flutter Web apps still using the old HTML renderer?