The web-font mixin should be easier to use

[ry5n]

The existing web-font mixin provides a way to write @font-face. Here is the current mixin signature:

@mixin web-font($font-family, $path, $formats: $font-formats, $font-weight: normal, $font-style: normal, $cache-buster: false) {}

It has a number of shortcomings, although my main concern is that it doesn’t reduce the complexity of using @font-face. If anything it requires the developer to specify all the same information as writing font-face by hand, but expressed as function params instead of copying an example @font-face block from say CSS Tricks.

I propose we re-think the mixin with the goal of making it significantly easier than writing @font-face by hand, prevents being caught by any gotchas (see note on SVG fonts below) and guides users to the best implementations (e.g. which formats are needed).

Further details:

• This relies on passing a map for the $formats param (e.g. ('woff': 'woff', 'ttf': 'truetype')). Even though there is a default $font-formats variable that is used if none is passed, users still have to deal with a somewhat obscure map both when learning the mixin or when passing the $font-weight and $font-style params.
• After Add the ability to specify multiple weights and styles in the same font-family #32, the “mixin [will expect] fonts to be named a specific way”. Is this really necessary? I’m afraid it will be harder for people to learn how to format the file names than it will be for them to pass a list of the full file paths themselves.
• This leaves out an important implementation detail for SVG fonts: the url hash, which is (apparently) necessary. It looks like this: url('path/to/fonts/font-name.svg#svgFontName'). The hash must match a particular id attribute in the SVG markup. Our mixin provides no way to do this.

(As a side note, SVG fonts are not needed even for complete mobile browser support, as woff and ttf together cover iOS 4.2+, Android 2.2+, Chrome, Firefox, Opera, and Win Phone 8).

[ry5n]

Copy-pasting on behalf of @kpeatt from #32:

Some examples of other font-face mixins:

• Bourbon: https://github.com/thoughtbot/bourbon/blob/master/app/assets/stylesheets/css3/_font-face.scss
• Compass: http://compass-style.org/reference/compass/css3/font_face/#mixin-font-face
• http://clubmate.fi/scss-font-face-mixin/
• http://codepen.io/javasteve99/pen/hDxpn

[ry5n]

Quick survey:

• Bourbon: broadly reasonable. Issues: assumes that all font formats will be provided.
• Compass: seems ok, except the weird $eot param, which is the $eot font file but isn’t part of the $font-files param.
• The clubmate one is pretty bad, it hard-codes parts of the file path, also assumes you’ll provide all file formats, has some weird param names, and also does too much (it writes out a placeholder selector).
• The codepen-hosted one seems straightforward but also forces all formats. We can ignore the Chrome for windows bugfix which is the only other strange thing.

Edit: also worth noting these are all called font-face.

[ry5n]

So what about something like this:

@mixin font-face($font-family, $font-files, $font-weight: normal, $font-style: normal) {}

This is a little bit simpler than actual @font-face since we can forget about font formats (they would be derived from the file extensions in $font-files).

Example usage:

@include font-face('Source Sans', (
    'path/to/fonts/source-sans-bold-italic.woff2',
    'path/to/fonts/source-sans-bold-italic.woff',
    'path/to/fonts/source-sans-bold-italic.ttf'),
    bold,
    italic
);

The one thing I’d like to add to this is some sugar to avoid writing out lots of similar paths. Not sure about the exact syntax, but maybe something like this:

@include font-face('Source Sans', 'path/to/fonts/source-sans-bold-italic.woff2+woff+ttf', bold, italic);

Ideally, you could write

@include font-face('Source Sans', 'path/to/fonts/source-sans-bold-italic.*', bold, italic);

and it would actually find the matching files on disk and write out URLs for them. That might be possible by writing a Ruby Sass extension. That would also theoretically allow the correct hash to be read directly from SVG font files.

[kpeatt]

Thoughts on avoiding writing a Ruby extension with this?:

@include font-face('Source Sans', 'path/to/fonts/source-sans-bold-italic, ('woff2', 'woff', 'ttf'), bold, italic);

Otherwise I think this looks a lot better. I'm hesitant to add more ruby dependencies. Completely agree with all of your above points.

[jeffkamo]

This looks alot better.

Kyle's file extension approach seems to most sane, but might be confusing to users who usually expect a path to be a full path (directory + filename + file extension).

In other words, how will we make it clear that you do NOT add the file extension in the path?

[ry5n]

Yup, totally agree with both of these comments. I was struggling with the same concerns as Jeff trying to think of a more concise way to express this. Ideally I’d like to keep the longhand and reserve the shorthand for “advanced” users, so I’m not crazy about the formats list as a parameter.

[kpeatt]

Another thing that might make this cooler: Not having to redeclare the mixin for every single different style.