Font Library: Add documentation for Font Collections

[matiasbenedetto]

This is an issue to describe this proposal, part of the Font Library feature proposed to merge in WordPress core 6.5

What is a Font Collection?

A Font Collection is a list of font family definitions ready to be installed by the user. The font family definition is a fontFamily item in theme.json format.

What is its purpose?

The font collections are presented to the users in the editor so one can choose whether to install a font family to their WordPress site.

How it works?

The only responsibility of a font collection is to present a list of font families in a correct format. Font collections are not in charge of installing the fonts; they just list a group of font families so users can choose the one they want to install. If the font family includes font faces, those font faces should have links to bundled (e.g: in a plugin assets) or external (e.g: from a CDN) font assets that will be downloaded or linked when the font family is installed.

How it looks in the UI?

Image	Description
	Google Fonts collection registered by default
	Custom font collecction

How can extenders add a new Font Collection?

A new font collection can be added by registering a font collection with PHP and a JSON file or just with PHP.

Example: register a font collection with PHP:

$font_families = [
    array(
        'font_family_settings' => (
            array (
                'fontFamily' => 'Ubuntu, system-ui, sans-serif',
                'slug'       => 'ubuntu',
                'name'       => 'Ubuntu',
            )
        ),
        'categories' => [ 'system-ui' ],
    ),
    array(
        'font_family_settings' => (
            array (
                'fontFamily' => 'Arial, Helvetica, Tahoma, Geneva, sans-serif',
                'slug'       => 'arial',
                'name'       => 'Arial',
            )
        ),
        'categories' => [ 'sans-serif' ],
    ),
];

$categories = [
    array(
        'slug' => 'system-ui',
        'name' => 'Sytem UI',
    ),
    array(
        'slug' => 'sans-serif',
        'name' => 'Sans Serif',
    ),
];

$config = array (
    'name'          => 'My sytem fonts collection',
    'slug'          => 'my-system-fonts',
    'description'   => 'Stacks of modern systems fonts, not font face assets needed. The look will vary on each system.',
    'font_families' => $font_families,
    'categories'    => $categories,
);

wp_register_font_collection ( $config );

Example: register a font collection with PHP and a JSON file.

$config = array (
    'slug'          => 'my-font-collection',
    'name'        => 'My Font Collection',
    'description' => 'This is an example font collection.',
    'src'         => path_join( __DIR__, 'my-collection.json' ),
);
wp_register_font_collection ( $config );

my-collection.json file example:

{
  "$schema": "https://schemas.wp.org/trunk/font-collection.json",
  "version": "1",
  "categories": [
    { "id": "sans-serif", "name": "Sans Serif" },
    { "id": "serif", "name": "Serif" },
    { "id": "display", "name": "Display" }
  ],
  "font_families": [
    {
      "font_family_settings": {
        "name": "Aboreto",
        "fontFamily": "Aboreto, system-ui",
        "slug": "aboreto",
        "fontFace": [
          {
            "src": "https://fonts.gstatic.com/s/aboreto/v2/5DCXAKLhwDDQ4N8blKHeA2yuxSY.woff2",
            "fontWeight": "400",
            "fontStyle": "normal",
            "fontFamily": "Aboreto",
            "preview": "https://s.w.org/images/fonts/16.7/previews/aboreto/aboreto-400-normal.svg"
          }
        ],
        "preview": "https://s.w.org/images/fonts/16.7/previews/aboreto/aboreto.svg"
      },
      "categories": ["display"]
    },
    {
      "font_family_settings": {
        "name": "Abril Fatface",
        "fontFamily": "Abril Fatface, system-ui",
        "slug": "abril-fatface",
        "fontFace": [
          {
            "src": "https://fonts.gstatic.com/s/abrilfatface/v23/zOL64pLDlL1D99S8g8PtiKchm-VsjOLhZBY.woff2",
            "fontWeight": "400",
            "fontStyle": "normal",
            "fontFamily": "Abril Fatface",
            "preview": "https://s.w.org/images/fonts/16.7/previews/abril-fatface/abril-fatface-400-normal.svg"
          }
        ],
        "preview": "https://s.w.org/images/fonts/16.7/previews/abril-fatface/abril-fatface.svg"
      },
      "categories": ["display"]
    },
    {
      "font_family_settings": {
        "name": "Abyssinica SIL",
        "fontFamily": "Abyssinica SIL, serif",
        "slug": "abyssinica-sil",
        "fontFace": [
          {
            "src": "https://fonts.gstatic.com/s/abyssinicasil/v5/oY1H8ezOqK7iI3rK_45WKoc8J6UcBFOVAXuI.woff2",
            "fontWeight": "400",
            "fontStyle": "normal",
            "fontFamily": "Abyssinica SIL",
            "preview": "https://s.w.org/images/fonts/16.7/previews/abyssinica-sil/abyssinica-sil-400-normal.svg"
          }
        ],
        "preview": "https://s.w.org/images/fonts/16.7/previews/abyssinica-sil/abyssinica-sil.svg"
      },
      "categories": ["serif"]
    },
    {
      "font_family_settings": {
        "name": "Aclonica",
        "fontFamily": "Aclonica, sans-serif",
        "slug": "aclonica",
        "fontFace": [
          {
            "src": "https://fonts.gstatic.com/s/aclonica/v22/K2FyfZJVlfNNSEBXGb7WCI6oBjLz.woff2",
            "fontWeight": "400",
            "fontStyle": "normal",
            "fontFamily": "Aclonica",
            "preview": "https://s.w.org/images/fonts/16.7/previews/aclonica/aclonica-400-normal.svg"
          }
        ],
        "preview": "https://s.w.org/images/fonts/16.7/previews/aclonica/aclonica.svg"
      },
      "categories": ["sans-serif"]
    }
  ]
}

How can extenders remove a Font Collection?

The slug of the font collection is used to unregister a font collection.
This is an example to unregister the collection registered by default:

wp_unregister_font_collection ( 'default-font-collection' );

Image	Description
	Font Library view with no font collection registered (the default one was unregistered)

Font Collection REST API

The font collections functionality only requires 2 enddpoints: GET wp/v2/font-collections and GET wp/v2/font-collections/<slug>. They are described below. If you want to know the complete font library proposed API specs refer to this issue: #57616

GET wp/v2/font-collections

List font collections

Request:

GET wp/v2/font-collections

Response:

[
    {
        "slug": "collection-example",
        "name": "Collection Example",
        "description": "This a Font Collection Example",
    },
    {
        "slug": "default-font-collection",
        "name": "Google Fonts",
        "description": "Google Fonts collection.",
    }
]

GET wp/v2/font-collections/<slug>

Get font collection by slug.

Request:

GET wp/v2/font-collections/collection-example

Response:

{
    "slug": "collection-example",
    "name": "Collection Example",
    "description": "Example font collection.",
    "theme_json_version": 2,
    "font_families": [
		{
		    "categories": [ "sans-serif" ],
                    "font_family_settings": {
                        "name": "Roboto",
                        "fontFamily": "Roboto, sans-serif",
                        "slug": "robot",
                        "category": "sans-serif",
                        "fontFace": [
                                {
                                    "src": "https://fonts.gstatic.com/s/roboto/v30/KFOkCnqEu92Fr1MmgWxPKTM1K9nz.ttf",
                                    "fontWeight": "400",
                                    "fontStyle": "normal",
                                    "fontFamily": "Roboto",
                                    "preview": "https://s.w.org/images/fonts/16.7/previews/roboto/roboto-400-normal.svg"
                                },
                                {
                                    "src": "https://fonts.gstatic.com/s/roboto/v30/KFOiCnqEu92Fr1Mu51QrIzcXLsnzjYk.ttf",
                                    "fontWeight": "400",
                                    "fontStyle": "italic",
                                    "fontFamily": "Roboto",
                                    "preview": "https://s.w.org/images/fonts/16.7/previews/roboto/roboto-400-italic.svg"
                                },
                       ]
               }
       }
],
"categories": [
        {
            "slug": "sans-serif",
            "name": "Sans Serif"
        }
    ]
}

Using fonts from a collection

Using fonts from a collection has 2 steps:

1. Installing

The Font Library UI enables browsing registered font collections, and choosing fonts from the collection to install to the site. When fonts are installed:

• The font family definition is saved to the site (using the wp_font_family post type).
• Child font faces definitions are saved to the site (using the wp_font_face post type).
• By default, font assets that are part of the font face definitions are downloaded to the site into the fonts directory (wp-content/fonts by default) and the src property of the font face changed to point to the downloaded file. This behavior can be configured to use the font assets directly from remote urls instead, if the collection allows that.

2. Activating

The user can activate any installed font for the current theme. This is done by saving the font family and child font face definitions into Global Styles typography settings for the theme. This makes the font available in the typography options for Global Styles and blocks.

[creativecoder]

Thanks for this! I added a short section at the end that explains installing and activating fonts.

[colorful-tones]

@matiasbenedetto is the Google Fonts collection the only default collection that will likely be targeted and available for 6.5 release? Just curious.

[matiasbenedetto]

@colorful-tones 👋 As far as I know, there only was one proposal around adding another font collection with system fonts, but it hasn't had much traction: #54186. It would be nice to add it, though.

[colorful-tones]

I still wanna test this all out to see it in action. I might give it a spin tomorrow, but will likely get pushed to Monday.

Curious, @matiasbenedetto is there any design or consideration on what might happen to the tabbed UI if there were to be several collections registered?

I’m probably jumping ahead and mostly curious. 😃

[matiasbenedetto]

@matiasbenedetto is there any design or consideration on what might happen to the tabbed UI if there were to be several collections registered?

@colorful-tones I'm not aware of mockups featuring a large number of font collections registered. It might be useful to count with a design exploration about that.

[colorful-tones]

Based on the recent Editor Triage async session - I'm moving this into the Punted to 6.6 column on the WordPress 6.5 Editor Tasks board.

[matiasbenedetto]

@colorful-tones 👋 This issue is about explaining/documenting the font collections functionality, which is part of the font library introduced in 6.5. Why it is being moved to the 'Punted to 6.6' column?

[colorful-tones]

This issue is about explaining/documenting the font collections functionality

Good to know @matiasbenedetto, and apologize for missing this additional context. I'm curious, are there any pull requests associated with the work here? From the sounds of it, it seems this work is decided and likely already introduced. This is based on the fact that we're already "documenting the font collections." 🤔

Is this In Progress, Needs Decision, or other?

Once we land on solidifying the status then I'm happy to triage.

[matiasbenedetto]

Is this In Progress, Needs Decision, or other?

I think it can be considered in-progress in this PR around adding docs:

#54477

[mikachan]

I'm wondering if this issue should be closed. As far as I'm aware, the documentation is being handled as part of the dev note and as part of the automated API docs at WP-API/docs#174.

[jasmussen]

@mikachan I want to echo that I remain skeptical that font-stack management should happen in this modal, I'd appreciate some consideration on having that interface live in the inspector instead, as discussed here: #54186 (comment)

[mikachan]

Thanks for highlighting that, @jasmussen. My question above was more because this current issue is listed on the 6.5 board and seems to only be related to documentation.

I'm happy to explore moving the font-stack management to the inspector. Do you think this needs to happen for the 6.5 release?

[jasmussen]

I think it can happen at any time, I'm mostly concerned that APIs are targetting the assumption that this will live in the modal.

[matiasbenedetto]

I want to #59294 (comment) that I remain skeptical that font-stack management should happen in this modal, I'd appreciate some consideration on having that interface live in the inspector instead, as discussed here: #54186 (comment)

Thanks for the comment, but this is unrelated to the issue regarding the font collections. The comment linked features a UI to edit font stacks, a functionality different from the font collections. I have some thoughts about it, but I will add them in: #54186

[mikachan]

I'll close this issue as it's related to docs, and we can continue the conversation about the font stacks implementation over in #54186.