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

[feinstein]

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.