Understanding and Maintaining Type Specs

Our type system uses a combination of design tokens and t-sage- classes to make standardized type specs available to the application. This should be added to any element that uses type styles in order to apply the desired type spec consistently.

As some areas of the application use user-generated content or large blocks of content in which it would be impractical to apply t- classes to every type element, the sage-type class can be implemented on a container around such text. Elements inside that container will have the default styles for corresponding specs applied as a result, but these can also be overridden using the t- classes when desired.

The type specs themselves are set up in app/assets/stylesheets/sage/core/_typography.scss through a map called $type-specs. A loop in that same file generates both a %t-sage- extendable and .t-sage- class for each of these specs. The extendables exist primarily for the utility of applying styles within .sage-type containers described above and should be used sparingly elsewhere.

Consider this guidance for use of type settings in CSS:

• Prefer using the official t-sage- classes to apply type settings over using custom CSS.
• If a particular implementation of a type spec is not feasible to apply the t-sage class directly on the element, the corresponding %t-sage- may be extended instead. This ensures that the output of our CSS shows us the distinct set of elements that implement a particular type spec.
• If a particular type setting is found that does not match exactly to an existing spec (weight, size, leading, and kerning), double-check with Design that the element is set as desired. Assuming the divergence is still intended, add a new spec for this element as follows:
  1. Create a new entry for the spec in the _typography.css file. Duplication of settings in this file should be not be of concern, so do not feel any pressure to extend or modularize based on another spec as this could lead to tangled dependencies.
  2. Document the new spec and its settings in the table in app/views/sage/pages/typography.html.erb.