Accoutrement 4.0.5

WebFonts

Webfont configuration is most useful for handling any font that requires @font-face importing – locally-hosted files, base64 data, etc. But collecting all your font data in a single location allows us to automate various actions: @font-face imports, font-family fallback stacks, font aliases (for semantic access), or even documentation and font-specimens with a tool like Herman.

We provide options for maintaining various font-types, from locally-hosted, to base64 embedded, and even CDN imports from sites like typekit and google fonts.

$font-path (string)

scss 
$font-path: '' !default;

The path to your fonts directory, often relative to your output CSS.

This base-path will be added to the start of every relative font-path given in your $fonts map - an optional shortcut to keep from writing long and repetitive paths for every font.

Since type-4.0.0:

  • BREAKING: The default changed from '../fonts/' to '' – so that no path is added unless explicitly requested.

Example

scss 
$font-path: '../fonts/';

Used By

@function font-url()

$fonts (map)

scss 
$fonts: () !default;

A map for managing all your fonts on a project. By storing this font data in map format, we can automate @font-face imports, call fonts with a semantic access-key, define fallback font-stacks, and generate font specimens with a tool like Herman.

All the provided tools will ignore unknown font properties, so you can safely include any extra data you need access to. For example, we often include a source property in our font maps, providing a link to the font foundry, license, or CDN. If you are using Herman to font previews, it will include source links in the output.

Since 3.0.0:

  • NEW: Supports display map key for setting CSS font-display property

Since 0.1.0:

  • NEW: Supports 'bold italic' weight/style syntax in addition to ('bold', 'italic')
  • BREAKING: Full support for the token map-reference syntax, not just font-name alias reference

Since type-4.0.0:

  • BREAKING: Remove the $font-formats variable, and replaced it with a formats property in each individual font map
  • BREAKING: No longer accepts regular as a font-variant, use the CSS-friendly normal instead
  • NEW: Allow explicit configuration maps for each font variant, to support variant-specific local and svgid options, along with the ability to specify explicit urls for each format desired The old string value will be treated the same as a map with only 'path' defined
  • NEW: Supports unicode-range CSS property, as described on MDN

Map Properties

<key>: (map)

Give each font a key for access in the code, with a nested map defining the font details.

<key>.name: <key> (string)

The actual name of the font-face, if it’s different from the given .

<key>.stack: (list)

A list of fallback fonts for browsers that can’t load the given webfont.

<key>.formats: (list)

A list of font formats (e.g. 'woff2' 'eot') to use when interpolating font-file paths for font-face imported fonts.

<key>.unicode-range: (list)

Optionally import only specific unicode ranges. See MDN unicode-range documentation for details.

<key>.display: (string)

Optionally set the font-display property when importing web fonts. See MDN font-display documentation for details.

<key>.<variant>: (string | map)

When describing locally-hosted or data-embedded fonts, provide a key for each font-variant to import. Multi-word variants can be written as a list (600 'italic') or a string ('600 italic').

  • In the simplest use-case, this value can be a string: a generic path to the appropriate font-files ('path/to/my-font-bold') with file-extensions removed. We’ll add extensions for you, based on the formats setting.

  • For more control over individual variants and formats, we also accept a map value. See the <key>.<variant>.<format> property below…

<key>.<variant>.path: (list)

An optional string defining the font-path to interpolate for each given formats. This is the same as providing a string variant-path.

<key>.<variant>.local: (list)

A list of names (strings) to use for local() font-src values.

<key>.<variant>.svgid: (list)

Fragment identifier for svg fonts, to be appended on relevant import URLs.

<key>.<variant>.<format>: (list)

Optionally provide individual font-path overrides, or base64 data-URIs for specific formats.

Examples

scss Defining a font for import 
$fonts: (
  'sans': (
    'name': 'Museo Sans',
    'stack': ('Helvetica', 'Arial', 'sans-serif'),
    'formats': ('woff2', 'woff', 'ttf'),
    'normal': 'museosans-regular-filename',
    'bold': 'museosans-bold-filename',
    'bold' 'italic': 'museosans-bolditalic-filename',
    'unicode-range': (U+0000-00FF, U+0131, U+0152-0153, U+02C6),
    'display': 'swap',
    // safely document any additional font data you want…
    'source': 'https://www.fontspring.com/fonts/exljbris/museo-sans',
  ),
);
scss Creating a secondary font alias 
// Create alias keys to provide more semantic naming as-needed.
$fonts: (
  'body-font': '#sans',
);
scss Setting explicit format-paths 
$fonts: (
  'sans': (
    'name': 'Museo Sans',
    'stack': ('Helvetica', 'Arial', 'sans-serif'),
    'bold': (
      'woff2': 'museosans-bold-woff2-path',
      'svg': 'museosans-bold-svg-path',
      'svgid': '#museosans',
    ),
    'bold' 'italic': (
      'woff2': 'museosans-bolditalic-woff2-path',
      'svg': 'museosans-bolditalic-svg-path.svg#museosans-bolditalic',
    ),
  ),
);
scss Base64 data-uri’s and local() src 
$fonts: (
  'uri-font': (
    'name': 'My Font',
    'stack': ('Helvetica', 'Arial', 'sans-serif'),
    'normal': (
      'local': ('My Font', 'my-font-regular'),
      'woff2': 'data:application/font-woff2;charset=utf-8;base64,…',
    ),
    'bold': (
      'local': ('My Font Bold', 'my-font-bold'),
      'woff2': 'data:application/font-woff2;charset=utf-8;base64,…',
    ),
  ),
);

Used By

@mixin add-font()

@mixin add-font()

In order to keep our $fonts map more manageable, we define individual map variables for each font, and use a mixin to merge them together into our global $fonts configuration.

This can be useful for internal organization, documentation with SassDoc, or integration with a pattern-library generator like Herman.

Parameters & Output & Return

$key: (map)

Give your font a semantic access-key for easy reference across your project.

$map: (map)

Map of font-data to be added at the given key.

{CSS output} (code block)

An updated global $fonts variable, with new maps merged in.

@error

Font key already exists. Rename or $force to continue

Example

scss 
$franklin: (
  'name': 'FranklinGothic',
  'stack': ('Helvetica', 'Arial', 'sans-serif'),
);

@include tools.add-font('heading', $franklin);

Requires

@function get() [private]

@function error() [private]

$fonts (map)

Using WebFonts

Once you’ve configured your webfont data into a map, these tools will help you access the data in various ways: from creating @font-face imports, to calling font-families by any given alias.

@function font()

Retrieve and normalize font data from the $fonts map

Since 2.0.0:

  • BREAKING: Non-map fonts are interpreted as font-stacks
  • BREAKING: Normalized font-data uses proper name-quotation, and ignores missing or private names/stacks

Since 1.0.0:

  • NEW: Provided to access and normalize a map of font data for any key in your global $fonts map
  • NEW: Accepts $source map argument, for custom source-palette

Parameters & Return

$font: (*)

A key for accessing the desired font in $fonts

$source: $fonts (map)

Optional Accoutrement-format map of fonts to use as the origin palette

@return (map)

A parsed and normalized map of font-data

Requires

@function get() [private]

Used By

@function font-family()

@mixin font-face()

@function font-values() [private]

@function compile-fonts()

Compile all the tokens in a font map. This is particularly useful for exporting a static version of the token map with all the Accoutrement syntax removed – e.g. for use in javascript or documentation.

Since 4.0.0:

  • NEW: Provides an export option for font token maps

Parameters & Return

$map: $fonts (map)

The map to be compiled

$source: $fonts (map | null)

A map of reference tokens that can be used for resolving fonts. (defaults to the global $fonts map)

@return (map)

A copy of the original map, with all token values resolved

Requires

@function map-compile-with()

@function font-family()

Access a font-family from your $fonts map, with name and font-stack.

Since 1.0.0:

  • NEW: Accepts $source map argument, for custom source-palette

Since type-4.0.0:

  • BUGFIX: Provides the correct name for fonts when an alias is given

Parameters & Return

$key: (string)

The key-name of a font in your $fonts map.

$source: $fonts (map)

Optional Accoutrement-format map of fonts to use as the origin palette

@return (String)

The full font-stack for the given font, ready for output with the font-family property.

Example

scss 
$fonts: (
  'sans': (
    'name': 'FranklinGothic',
    'stack': (Helvetica, Arial, sans-serif),
  ),
);

html {
  font-family: tools.font-family('sans');
}
css compiled 
html {
  font-family: sans;
}

Requires

@function font()

@function get() [private]

Used By

@mixin font-family()

@mixin font-family()

Output a font-stack to font-family based on your $fonts configuration.

Since 1.0.0:

  • NEW: Accepts $source map argument, for custom source-palette

Parameters

$key: (string)

The key-name of a font in your $fonts map.

$source: $fonts (map)

Optional Accoutrement-format map of fonts to use as the origin palette

Example

scss 
$fonts: (
  'FranklinGothic': (
    'stack': (Helvetica, Arial, sans-serif),
  ),
  'sans': '#FranklinGothic',
);

html {
  @include tools.font-family('sans');
}
css compiled 
html {
  font-family: sans;
}

Requires

@function font-family()

@mixin font-face()

Import any local webfont defined in your $fonts configuration (variants without a path will not be imported).

Since 3.0.0:

  • NEW: Supports display setting in font-maps

Since 1.0.0:

  • NEW: Accepts $source map argument, for custom source-palette

Since type-4.0.0:

  • BREAKING: No longer accepts the $formats parameter

Parameters & Output

$key: (string)

The key-name of a font in your $fonts map

$source: $fonts (map)

Optional Accoutrement-format map of fonts to use as the origin palette

{CSS output} (code block)

@font-face import blocks for any defined font-variants.

Example

scss 
$fonts: (
  'body-font': (
    'name': 'Source Sans Pro',
    'formats': 'woff2' 'woff' 'eot',
    'normal': 'sans/sourcesanspro-regular-webfont',
    'italic': 'sans/sourcesanspro-italic-webfont',
    'bold': 'sans/sourcesanspro-bold-webfont',
  ),
);
@include tools.font-face('body-font');

Requires

@function font()

@function font-get-variants() [private]

@function get() [private]

Used By

@mixin import-webfonts()

@mixin import-webfonts()

Find all the fonts that include data for imports, and generate @font-face blocks for each individual font and variant.

Since 2.0.0:

  • NEW: Accepts $source parameter, which uses global $fonts by default
  • BREAKING: No longer imports private fonts, but will import a direct alias of the private font

Since 1.0.0:

  • BREAKING: No longer accepts the $fonts parameter

Since type-4.0.0:

  • BREAKING: No longer accepts the $formats parameter

Parameters & Output

$source: $fonts (map)

Optional Accoutrement-format map of fonts to use as the origin palette

{CSS output} (code block)

Any number of @font-face blocks.

Example

scss 
$fonts: (
  'body-font': (
    'name': 'Source Sans Pro',
    'formats': 'woff2' 'woff' 'eot',
    'normal': 'sans/sourcesanspro-regular-webfont',
    'italic': 'sans/sourcesanspro-italic-webfont',
    'bold': 'sans/sourcesanspro-bold-webfont',
  ),
  // alias keys, and fonts without path data will be ignored…
  'alias': '#body-font',
  'google-font': (
    'source': 'https://fonts.google.com/',
  ),
);
@include tools.import-webfonts;

Requires

@mixin font-face()

@function is-alias-for()

@function is-private-token()