Typography

The 📁 base/_typography.scss file contains the basic typography rules (e.g., vertical spacing), while the 📁 custom-style/_typography.scss file is where you can (optionally) set your own typography rules and modify the --text-base-size at specific breakpoints to make the whole system responsive.

Font family #

You can set the main font-family by updating the value of the --font-family variable in 📁 custom-style/_typography.scss. Optionally, you can create new CSS variables and add more font-families:

:root {
    /* font family */
    --font-primary: sans-serif;
    --font-secondary: serif;
}

Type scale #

The type scale is a modular scale of values stored in CSS variables:

:root {
  // body font size
  --text-base-size: 1em;
  
  // type scale
  --text-scale-ratio: 1.2;
  --text-xs: calc((1em / var(--text-scale-ratio)) / var(--text-scale-ratio));
  --text-sm: calc(var(--text-xs) * var(--text-scale-ratio));
  --text-md: calc(var(--text-sm) * var(--text-scale-ratio) * var(--text-scale-ratio));
  --text-lg: calc(var(--text-md) * var(--text-scale-ratio));
  --text-xl: calc(var(--text-lg) * var(--text-scale-ratio));
  --text-xxl: calc(var(--text-xl) * var(--text-scale-ratio));
  --text-xxxl: calc(var(--text-xxl) * var(--text-scale-ratio));
}

To control the scale, we’ve defined two variables: the --text-base-size and the --text-scale-ratio. The first one is the body font size, while the second one is the ratio used to generate the scale. The default value of --text-base-size is 1em.

By updating the --text-base-size and --text-scale-ratio values, you set global responsive rules that affect the responsiveness of both spacing and typography. Learn more about this method in our article 'An approach to responsive layouts based on CSS custom properties and em units'.

@supports(--css: variables) {
  :root {
    @include breakpoint(md) {
      --text-base-size: 1.25em;
      --text-scale-ratio: 1.25;
    }
  }
}

⚠️ Important: we wrap the variable update at the md (medium) breakpoint into a @supports(--css: variables) rule to prevent the postcss-css-variables plugin from generating a fallback (Which, in this case, would result in a lot of extra code).

.text-component #

The .text-component is a class to be applied to any block containing typography elements. It takes care of 1) vertical rhythm and 2) styling inline elements. A good example of how to use this class is our Article component.

Class	Description
`.text-component`	apply this class to blocks containing two or more text elements

Vertical spacing #

To control the vertical spacing of a text-component, you can edit the following CSS variables:

Variable	Description
`--heading-line-height`	headings line-height
`--body-line-height`	body line-height
`--line-height-multiplier`	modify the line-height of all text elements
`--text-vspace-multiplier`	edit margins of all text elements

Example:

Alternatively, you can use one of the line-height and vertical spacing utility classes.

.text-component__block #

The .text-component__block class can be added to any block element within a text-component. It's used to automatically set vertical spacing and, optionally, to outset content or create grids containing images.

Class	Description
`.text-component__block`	used to apply vertical spacing to block elements within a text-component
`.text-component__block--full-width`	set full-width for block element
`.text-component__block--left`	element floats left past 'sm' breakpoint
`.text-component__block--right`	element floats right past 'sm' breakpoint
`.text-component__block--outset`	element outset its parent past 'xl' breakpoint

⚠️ Please note that, when used within the .text-component, the following elements already have vertical spacing applied and don't require the .text-component__block class: <h1>, <h2>, <h3>, <h4>, <ul>, <ol>, <p>, <blockquote>, <hr>. A good example of how to use this class is the Article component.

Editing text size #

To edit the text size of a single element, you can use one of the text-size utility classes or target the element on a component level:

.component h1 { 
    font-size: 3em; /* the size is no longer affected by the --text-scale-ratio */
    font-size: calc(var(--text-base-size) * 3); /* use base size to create new value - off scale */
    font-size: calc(var(--text-xxl) - 0.8em); /* use original font size to create new value - off scale */
    font-size: var(--text-xl); /* update the value of the font size using a different variable */
}

If you want to edit the font-size of multiple text elements, by taking advantage of the em relative units, you can target any component and set a custom font-size value:

Method	Effect
`font-size: 1.2em;`	edit the font-size of the component and all its children - in this example the size is increased by 1.2
`font-size: 1rem`	reset text size - the text size of the component is not affected by its parent

To edit the text size on a component level, you can use the textUnit mixin. Pass to the mixin the value you want to use as new text base size (e.g., 1rem or 16px):

component {
  @include textUnit(1rem);
}

The mixin will automatically update all the --text-{size} variables based on the new text base value. This mixin is useful if you don't want to extend the automatic (typography) responsive behavior to a specific component.

Optionally, you can pass a second argument to the mixin: this will be used as new scale ratio (default is 1.2):

component {
  @include textUnit(1rem, 1.3);
}

If you do so, you create a new type scale, whose effect is limited to the component where the mixin is in use.

line-height crop #

To remove the top space on a text element caused by its line-height, you can use the lhCrop mixin.

Utility classes #

For a full list of typography utility classes, please refer to the Utilities page.