RFC: Typography API (again) - Prefer absolute values over semantic names

[SiAdcock]

The typography API maps font families and font sizes to create more readable semantic names. For example:

font-family: "GH Guardian Headline, Guardian Egyptian Web, Georgia, serif";
font-size: 34px;
font-weight: 700;
line-height: 1.5;

can be achieved using:

headline.medium({ fontWeight: 'bold', lineHeight: 'loose' })

Problems

There's a handful of problems with semantic font size and line height names:

• the names are relative to something, but what? What does headline.medium mean? When should we use medium as opposed to large or small? The API doesn't provide enough context for the relative size names to be meaningful or useful.
• the names are an abstraction used by engineers only. Designers don't use these names, for the point raised above. They prefer to think in terms of absolute sizes (e.g. Headline / bold / 34px / 115%)
• Because designers don't use these names, it's harder for engineers to go from Figma to code. They have to inspect the text in Figma, find the font size, go to the Source typography docs and find the font size name that maps to the font size.
• It's hard to add new font sizes without breaking changes. For instance if we wanted to add a font size between large and xlarge, all names above large would need to change.

Proposal

Use an API that is closer to the way a designer thinks about typography.

Instead of:

headline.medium({ fontWeight: 'bold', lineHeight: 'loose' })

We use:

headline({ fontSize: '34px', fontWeight: 'bold', lineHeight: '150%' })

It's slightly more verbose, but it saves going through the Source documentation every time we need to translate a design into code. We could define types to help with autocompletion.

type HeadlineSizes = "28px" | "34px" | "42px"
type HeadlineWeights = "normal" | "bold"

const headline = ({
	fontSize,
	fontWeight,
}: {
	fontSize: HeadlineSizes
	fontWeight: HeadlineWeights
}) => {
	return `
		font-family: "GH Guardian Headline, Guardian Egyptian Web, Georgia, serif";
		font-size: ${size};
		font-weight: ${weight};
	`
}

Happy to hear any thoughts on this 👂

[i-hardy]

I'm in favour of this. I know a couple of the semantic names as they translate to pixel sizes now, but I always end up spending a lot of time rooting around in the Source docs to translate font sizes from a design into code, and it's definitely a pain point.

[oliverlloyd]

I would definitely prefer to see the actual values being used represented in the names - I've been caught out here a few times

[tjsilver]

I think this would be a really useful change - I have also found myself having to follow the flow outlined in bullet point 3 above which is quite time-consuming.