Directory

Font Library: Add documentation for Font Collections · Issue #57980 · WordPress/gutenberg · GitHub
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Font Library: Add documentation for Font Collections #57980

Closed
matiasbenedetto opened this issue Jan 18, 2024 · 15 comments
Closed

Font Library: Add documentation for Font Collections #57980

matiasbenedetto opened this issue Jan 18, 2024 · 15 comments
Labels
[Feature] Font Library [Feature] Typography Font and typography-related issues and PRs [Type] Discussion For issues that are high-level and not yet ready to implement.

Comments

@matiasbenedetto
Copy link
Contributor

matiasbenedetto commented Jan 18, 2024 •
edited

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
Screenshot from 2024-01-18 14-56-50 Google Fonts collection registered by default
image 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
image 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
Copy link
Contributor

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

@mikachan mikachan mentioned this issue Jan 19, 2024
Draft
@colorful-tones colorful-tones added the [Feature] Typography Font and typography-related issues and PRs label Jan 20, 2024
@jordesign jordesign added the [Type] Discussion For issues that are high-level and not yet ready to implement. label Jan 21, 2024
@colorful-tones
Copy link
Member

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

@matiasbenedetto
Copy link
Contributor Author

@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.

@creativecoder creativecoder mentioned this issue Jan 25, 2024
Open
@matiasbenedetto matiasbenedetto mentioned this issue Jan 26, 2024
Merged
@colorful-tones colorful-tones mentioned this issue Feb 2, 2024
Open
@colorful-tones
Copy link
Member

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
Copy link
Contributor Author

matiasbenedetto commented Feb 5, 2024 •
edited

@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
Copy link
Member

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
Copy link
Contributor Author

@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
Copy link
Member

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
Copy link
Contributor Author

Is this In Progress, Needs Decision, or other?

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

#54477

@fabiankaegy fabiankaegy changed the title Font Library: Font Collection Font Library: Add documentation for Font Collections Feb 19, 2024
@jasmussen jasmussen mentioned this issue Feb 23, 2024
Closed
@mikachan mikachan mentioned this issue Feb 29, 2024
Open
@mikachan
Copy link
Member

mikachan commented Mar 7, 2024

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
Copy link
Contributor

@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
Copy link
Member

mikachan commented Mar 7, 2024

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
Copy link
Contributor

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
Copy link
Contributor Author

matiasbenedetto commented Mar 7, 2024 •
edited

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
Copy link
Member

mikachan commented Mar 7, 2024

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.

@mikachan mikachan closed this as completed Mar 7, 2024
@justintadlock justintadlock mentioned this issue Mar 8, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
[Feature] Font Library [Feature] Typography Font and typography-related issues and PRs [Type] Discussion For issues that are high-level and not yet ready to implement.
Projects
WordPress 6.5 Editor Tasks
Status: ✅ Done
Milestone
No milestone
Development

No branches or pull requests
6 participants
@colorful-tones @jasmussen @matiasbenedetto @mikachan @creativecoder @jordesign