Typography

About

Typography is a crucial element of any brand’s visual identity. The typography section in _brand.yml allows you to define the fonts, sizes, weights, and other typographic properties.

Structure

You can approach translating brand guidelines into a _brand.yml file in two steps:

  1. First, specify the fonts used by your brand, using local or online font sources.

    • fonts: This top-level attribute is where you list font family definitions.

  2. Second, define the fonts and styles used by different typographic elements (base text, headings, monospace text, etc.). The remaining attributes of typography comprise these settings:

    • base
      Font and appearance settings for the base (body) text.

    • headings
      Font and appearance settings for heading text.

    • monospace
      Font and appearance settings for monospaced text.

    • monospace-inline
      Font and appearance settings for inline monospaced text.

    • monospace-block
      Font and appearance settings for block (multi-line) monospaced text.

    • link
      Font and appearance settings for hyperlink text.

Examples

Minimal Example

At its most minimal1, you can directly set the font families for base text, headings, and monospace text.

_brand.yml
typography:
  base: Open Sans
  headings: Roboto Slab
  monospace: Fira Code

This saves a bit of typing and is equivalent to the following.

_brand.yml
typography:
  base:
    family: Open Sans
  headings:
    family: Roboto Slab
  monospace:
    family: Fira Code

Currently, Quarto and Shiny assume that a font family mentioned in the typography section is available on the user’s system. To use fonts from Google Fonts or Bunny Fonts (a GDPR-compliant Google Fonts replacement), define the font sources in fonts.

_brand.yml
typography:
  fonts:
    - family: Open Sans
      source: google
    - family: Roboto Slab
      source: google
    - family: Fira Code
      source: google
  base: Open Sans
  headings: Roboto Slab
  monospace: Fira Code

Simple Example with Additional Properties

Typography encompasses more than just the font selection. This example also sets typographic properties such as line height, font size, and color:

_brand.yml
color:
  primary: blue
typography:
  base:
    family: Open Sans
    line-height: 1.25
    size: 1rem
  headings:
    family: Roboto Slab
    color: primary
    weight: semi-bold
  monospace:
    family: Fira Code
    size: 0.9em

Comprehensive Example with Font Definitions

This example demonstrates how to define fonts from various sources and apply them to different text elements:

_brand.yml
color:
  primary: "#f24242"
typography:
  fonts:
    # Local files
    - family: Open Sans
      source: file
      files:
        - path: fonts/open-sans/OpenSans-Variable.ttf
        - path: fonts/open-sans/OpenSans-Variable-Italic.ttf
          style: italic
    # Online files
    - family: Closed Sans
      source: file
      files:
        - path: https://example.com/Closed-Sans-Bold.woff2
          weight: bold
        - path: https://example.com/Closed-Sans-Italic.woff2
          style: italic
    # Google Fonts
    - family: Roboto Slab
      source: google
      weight: [600, 900]
      style: normal
      display: block
    # Bunny Fonts
    - family: Fira Code
      source: bunny

  base:
    family: Open Sans
    line-height: 1.25
    size: 1rem
  headings:
    family: Roboto Slab
    color: primary
    weight: 600
  monospace:
    family: Fira Code
    size: 0.9em
1
Local fonts use source: file and typically come as a set of files, each with a weight and style. List each font file under files with a path attribute, optionally specifying the weight and style associated with the font file.
2
Online font files might be hosted somewhere by the company or brand. These also use source: file (see local fonts above), but the path attribute is a URL.
3
Google Fonts define an entire family of fonts. Here weight and style select the weights and styles that should be included in the fonts downloaded from Google Fonts.
4
Bunny Fonts follow the same format as Google Fonts but use a GDPR-compliant host.
5
Fonts are referenced by family name in the other attributes of typography. Note that not all fonts need to be used, but they’ll be made available by Quarto or Shiny.

Example with Color Definitions

Colors defined in the color section can be referenced by name in the color and background-color attributes of the typography settings. Note that this applies to both theme colors and colors in the brand’s color palette.

_brand.yml
color:
  palette:
    red: "#FF6F61"
  primary: "#87CEEB"
  secondary: "#50C878"
  danger: red
  foreground: "#1b1818"
  background: "#f7f4f4"

typography:
  headings:
    color: primary
  monospace-inline:
    color: background
    background-color: red
  monospace-block:
    color: foreground
    background-color: background
  link:
    color: danger

Attributes

fonts

The fonts attribute is a list of font family definitions. Each definition describes a font family that is available to the brand. Fonts may be stored in files (either adjacent to _brand.yml or hosted online) or may be provided by Google Fonts or Bunny Fonts.

Local fonts are specified using source: file and typically consist of multiple files, each representing a different weight and style. To use local fonts, list each file under the files section, providing a path attribute and optionally specifying the weight and style for each file.

For fonts hosted online by a company or brand, you can use the same source: file approach as local fonts, but instead of a local file path, you’ll use a URL in the path attribute.

typography:
  fonts:
    # Local files
    - family: Open Sans
      source: file
      files:
        - path: fonts/open-sans/OpenSans-Variable.ttf
        - path: fonts/open-sans/OpenSans-Variable-Italic.ttf
          style: italic
    # Online files
    - family: Closed Sans
      source: file
      files:
        - path: https://example.com/Closed-Sans-Bold.woff2
          weight: bold
        - path: https://example.com/Closed-Sans-Italic.woff2
          style: italic

Google Fonts offers entire font families at once, and uses a slightly different syntax. With Google Fonts, you can specify which weights and styles should be included in the downloaded font package using the weight and style attributes. Bunny Fonts provide a GDPR-compliant alternative to Google Fonts and follow the same format for implementation.

typography:
  fonts:
    # Google Fonts
    - family: Roboto Slab
      source: google
      weight: [600, 900]
      style: normal
    # Bunny Fonts
    - family: Fira Code
      source: bunny
1
The weight attribute specifies the font weights to include in the downloaded font package. In this example, weights 600 and 900 are included. Leaving this empty includes weights from 100 to 900. Variable font weights can be written as a string 600..900.
2
The style attribute specifies the font styles to include in the downloaded font package. In this example, only the normal style is included. Leaving this empty includes both normal and italic styles as [normal, italic].

In other typography-related attributes, fonts are referenced by their family name. It’s worth noting that while you can define multiple fonts, not all of them need to be actively used in your project. However, Quarto or Shiny will make all defined fonts available for potential use.

Typography Attributes

The following attributes are used to define the typographic properties of different text elements.

Attribute Description Supported Fields
base Default text, primarily used in the document body.
  • family
  • size
  • line-height
  • weight
headings All heading levels (h1, h2, etc.).
  • family
  • weight
  • style
  • line-height
  • color
monospace General monospaced text, typically used in code blocks and other programming-related content.
  • family
  • size
  • weight
monospace-inline Inline monospaced text, usually used for code snippets within regular text. Inherits from monospace.
  • family
  • size
  • weight
  • color
  • background-color
monospace-block Block (multi-line) monospaced text, typically used for code blocks. Inherits from monospace.
  • family
  • size
  • weight
  • line-height
  • color
  • background-color
link Hyperlinks.
  • weight
  • color
  • background-color
  • decoration

The supported fields are generally described as follows:

  • family: The font family to be used for a typographic element. This should match a font resource declared in typography.fonts.

  • size: The font size for a typographic element. Should be specified using a CSS length unit (e.g., “14px”, “1em”, “0.9rem”).

  • weight: The font weight (or boldness) of the text. Can be a numeric value between 100 and 900, or a string like “normal” or “bold”.

  • style: The font style for the text, typically either “normal” or “italic”.

  • line-height: The line height of the text, which refers to the vertical space between lines. Often expressed as a multiple of the font size or in fixed units.

  • color: The color of the text. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.

  • background-color: The background color for the text element. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.

  • decoration: The text decoration, typically used for links. Common values include “underline”, “none”, or “overline”.

Footnotes

  1. All parts of brand.yml are optional, so you could even more minimally set only one of base, headings or monospace. And the absolute minimum, of course, would be to exclude the typography section entirely.↩︎