RFC: Font Registration

[fikrikarim]

Background

Makeswift currently supports adding fonts from Google Fonts. This works great for most users, but it has several limitations:

1. Users cannot use custom fonts
2. Users cannot use fonts they already have in the host

For example, let’s say a user has a custom font called Metalsmith, located on the public folder. They are already importing the font with CSS, and they are using it on their Next.js app. When integrating their app with Makeswift, they cannot select the Metalsmith font in the builder, because Makeswift doesn’t know about the existence of the font.

The main goal of this RFC is to propose an API for users to register fonts they already have on the host, so they can select them in the Makeswift builder.

Font registration is the first step in a larger effort to allow Makeswift hosts to expose existing or project-specific resources like colors, typographies, pages, files, and breakpoints in Makeswift.

Proposal

We propose adding a fonts field on MakeswiftApiHandler that will look like this on pages/api/makeswift/[...makeswift].ts:

import { MakeswiftApiHandler } from "@makeswift/runtime/next";

export default MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY!, {
  fonts: [
    {
      family: "Roboto",
      variants: [
        { weight: "400", style: "italic" },
        { weight: "400", style: "normal" },
      ]
    },
    {
      family: "Open Sans",
      variants: [{ weight: "400", style: "normal" }],
    },
    {
      family: "Metalsmith",
      variants: [
        { weight: "400", style: "italic", src: "/fonts/Metalsmith.woff" },
      ],
    },
  ],
});

type Fonts = Font[]

type Font = {
  family: string
  variants: Variant[]
}

type Variant = { weight: string; style: 'italic' | 'normal'; src?: string }

Once we have that, then we can choose the font family and the variant in the Makeswift Text component or in the Style control:

The image above shows the font selection in Makeswift. The first three fonts are registered from the host, and the last four fonts are added from Makeswift.

Technical details

• We were considering adding the fonts field on makeswift.config.js instead. But it has the downside of not being able to ability import from a .ts file. This is a dealbreaker because we want to support @next/font in the future and we want users to be able to import their @next/font directly.
• We had a discussion about Tailwind integration. We decided that the Tailwind integration would be on a Typography level and not on the Font level.
• On the first iteration, we had type: 'google' and type: 'custom' fields on the font so we could load the Google Font directly without needing the users to specify the src. We decided to drop these fields because we could still load the font from Google Fonts based on the family name.
• family is the most important part, as it is the value for each item in the dropdown.
• If src is provided we can load the font and use it in the builder. This is optional, as we can still show the font family on the dropdown without loading the font.
• The src could be either a relative URL or an absolute URL.

Backwards Compatibility

This is a new feature, so it will be backward compatible.

Alternative Approaches

Instead of manually registering the fonts, Makeswift could also automatically register all the fonts using document.fonts. But this has several downsides: relying on the DOM, users need to opt out if they don't want to register the font, and feeling like magic (not an explicit behavior).

Feedback

We’d love to gather as much feedback as possible on this RFC before we start implementation to make sure that the API covers all the relevant use cases.

[migueloller]

If the src property will be optional and when present only used for the dropdown item's style, would it be more concise to group together the fonts?

module.exports = {
  fonts: [
    { family: 'Roboto', weights: ['400', '500', '600'] }
  ]
}

What does the UI for picking weights look like? What about for italics? Perhaps that can help constraint the API? For example, with Tailwind CSS one just specifies the font family and the browser will pick the proper font file given a font weight or style on a best effort-basis.

[migueloller]

I don't totally have experience to back up this being a bad idea, but I have read a lot of dissenting opinions on doing this. Custom italics glyphs were made for a reason, and at the least we need a way of allowing people to use them long term.

If there's italic glyphs available the browser will use that, but that is outside the scope of this API, this API is just to let the builder know what capabilities the host has. Whether a host can use them or not is completely independent of Makeswift. The question we need to answer here is if we want to limit the controls in Makeswift based on the capabilities of the host.

I think that requiring a font family at a minimum but allowing to specify a subset via a weights and/or style option give us the best of both worlds: a simple API, while allowing the developer of the host to steer the user of the builder to "proper" use of the design system

[joshuawootonn]

I am sorry scratch my last comment.

This API is not for installing fonts

True. I was what I was missing. It's their job to setup their fonts correctly. We can just fallback to browser calculated version.

[joshuawootonn]

I think that requiring a font family at a minimum but allowing to specify a subset via a weights and/or style option give us the best of both worlds: a simple API, while allowing the developer of the host to steer the user of the builder to "proper" use of the design system

Agreed :)

[fikrikarim]

If we decided to make weights and style optional, we could also allow just using a string for fonts:

module.exports = {
  fonts: ['Roboto']
}

They can use just a string for registering a font family. If they want to add other fields, they can add an object.

[migueloller]

Yup, it's a matter of how many ways we want to allow fonts to be provided. For example, would an array of arrays also be supported, for fallbacks?

[alexhwoods]

Love it, great job @fikrikarim!

Couple questions:

1. What happens if a font is used on a page, and it is removed from that file? Are we doing any kind of de-registration?
2. Can we include a type for the font that can be used in makeswift.config.js? I think it may be complicated enough to warrant that, specifically type: "google" | "custom"

[migueloller]

I would expect us to have a MakeswiftConfig type that we can use for type safety, similar to Next.js'

i.e.:

/** @type {import('@makeswift/runtime').MakeswiftConfig} */
const makeswiftConfig = {
  fonts: []
}

module.exports = makeswiftConfig

[fikrikarim]

For the first question, you can still modify the text. But on the font family panel, it'll show you a warning like this:

This behavior is similar to what happens if you add a font in Makeswift, use it on a Text component, and remove the font from Makeswift. The difference is that, if we register it from the host, as long as you still have the font CSS included, then the font would still be rendered properly.

[joshuawootonn]

In my experience, designer make often make mistakes in naming variants in their design system. This results in terms being used incorrectly. Like have a font labeled as "Roboto Book" when it's weight in the design system is 400 (not 350).

Because of this it would be great if our API separated the concerns of

this label and the actual weight(500,600, or 700) / style (italics or not). Something like:

module.exports = {
  fonts: [
    { type: 'google', family: 'Roboto', variant: 'Book', weight: 400, style: 'italics'  }
  ]
}

We can include this incorrect mapping in the config rather than doing the translation in our head.

---

"Why don't you just push back on the incorrect design system?"

Sometimes the momentum is to great.

[fikrikarim]

Oh, do you mean adding a label for the font variant to show it on the dropdown? @joshuawootonn

[joshuawootonn]

Oh, do you mean adding a label for the font variant to show it on the dropdown? @joshuawootonn

Yes

or if we just always show all options and let the browser do it's default behavior (the browser will accept font-style and font-weight properties independent of what the font file supports and will try to do its best to render it).

this sounds good to me.

[migueloller]

Oh, do you mean adding a label for the font variant to show it on the dropdown? @joshuawootonn

Yes

My opinion on this matter is that we come up with labels for the 9 different font weight keyword values and use those and then for the font itself we use the font family. I'm not sure it's necessary to allow labels for different font weights. I'm open to being convinced otherwise, though

[joshuawootonn]

Based on the other thread / the simplicity of the other API. I don't think what I proposed is worth it just for the labels sake :P

module.exports = {
  fonts: [
    { family: 'Roboto', weights: [{value: '400', label: "Book"}, '500', '600'] }
  ]
}

We could do something like ^ in the future if we needed to as well without breaking changes

[migueloller]

Yeah. For now we're thinking of using the Google Fonts labels:

weight	label
100	Thin
200	Extra light
300	Light
400	Regular
500	Medium
600	Semi bold
700	Bold
800	Extra bold
900	Black