Origami Frontend Components & Services

Readme: o-typography

Typographical styles for FT branded sites - font families, weight, colors, sizes and vertical rhythm. The module provides styles for headings, titles, leads and body content.


By default, o-typography uses a single typographic scale for use with all fonts. The scale consists of font-size and line-height combinations, as shown below:

Scale Font size Line height
-2 12px 16px
-1 14px 16px
0 16px 20px
1 18px 20px
2 20px 24px
3 24px 28px
4 28px 32px
5 32px 32px
6 40px 40px
7 48px 48px
8 56px 56px
9 72px 72px
10 84px 84px

Note: The whitelabel branded version of o-typography has a different default scale. The font sizes are the same, but the line-height is 1.2x the font size at every scale.

This scale makes up all typographic styles available through o-typography. It is available when using Sass through the typography mixins.

Markup

Predefined CSS classes in o-typography are available when using the build service, and can be included optionally via Sass.

Classes do not depend on specific HTML, but we encourage developers to use semantic elements.

E.g.

<h1 class="o-typography-heading-level-1">Heading level 1</h1>
<h2 class="o-typography-heading-level-2">Heading level 2</h2>
<p class="o-typography-body">Some body copy.</p>
<a class="o-typography-link" href="#" >Some link.</a>
<!-- etc. -->

o-typography also provides wrapper classes. These reduce the need for developers to apply styles to specific elements. By using a wrapper, body styles get applied to the HTML element and descendent typographic elements: h1, h2, h3, h4, h5, p, a, blockquote, footer, strong, em, small, sup, sub, ul, ol, li.

Example:

<div class="o-typography-wrapper">
    <h1>Heading level 1</h1>
    <h2>Heading level 2</h2>
    <p>Some body copy.</p>
    <a href="#">Some link.</a>
</div>

See the demos for a full list of the classes provided and their effects.

Progressive loading web fonts

One of the drawbacks of using web fonts is some browsers hide the text while the font is downloading (Flash of Invisible Text, aka FOIT). A common pattern for avoiding this is to use a system fallback font initially. Then, once the web font has loaded, remove a class from the html element used to display the fallback font.

The CSS would look a little like this:

p {
    font-family: FinancierDisplayWeb, serif;
    font-size: 20px;
    line-height: 24px;
}

.font-loading-serif p {
    font-family: serif;
    font-size: 18px;
}

Include both the CSS and JavaScript for o-typography in your project. While ensuring you have the loading classes for each font you wish to load on your html element:

<html class="o-typography--loading-sans o-typography--loading-sansBold o-typography--loading-display o-typography--loading-displayBold">

If you build your projects using Sass, styles for progressively loading fonts are output by default when using the use case mixins or type mixins.

Sass

To include all typography classes use the oTypography mixin:

    @include oTypography();

To include typography styles granularly pass an options argument with the features to include:

    @include oTypography($opts: (
        'wrapper'
    ));
Feature Description Brand support
headings Heading classes. E.g. o-typography-heading-level-1, o-typography-heading-level-2, etc. For the master brand these are currently article-style headings, but standard sans-serif headings for internal and whitelabel brands. master, internal, whitelabel
wrapper A class o-typography-wrapper which styles children elements based on semantics including headings, paragraphs, lists, links, and more e.g. <h1>, <p>, <li>, <a>, <figcaption> master, internal, whitelabel
body A class for standard body copy, such as paragraphs. master, internal, whitelabel
links A class for anchor tags, including a seperate class to indicate external links. master, internal, whitelabel
lists Classes to style lists, ordered or unordered. master, internal, whitelabel
caption A class to style captions. master, internal, whitelabel
footer A class to style footers. master, internal, whitelabel
blockquote A class to style blockquotes, including child paragraphs and footer. master, internal, whitelabel
utilities A collection of classes to modify typography including weight, style, superscript, and subscript. master, internal, whitelabel
product-headings Non-article heading classes, sans-serif. E.g. o-typography-product-heading-level-1 master, internal(deprecated)
product-wrapper A class o-typography-wrapper--product, which acts like the wrapper feature described above, but with non-article/product headings. master, internal(deprecated)
article This outputs article classes such as for collection headings, topic, author name, standfirst, timestamp, and big number. master
big-number Outputs a class to style a big number o-typography-big-number. master
collection Outputs a class to style a collection header o-typography-collection-heading. Previously used within articles but now a candidate for potential deprecation. master
read-next Outputs a class o-typography-read-next to style the heading in an article's aside. This is a candidate for potential deprecation. master

See the demos for a full list of the CSS classes provided by these features.

Note: Including fonts

By calling the mixin oTypography, or if silent mode is off (set to false), o-typography will download FT webfonts. To suppress this, set $o-typography-load-fonts to false:

$o-typography-load-fonts: false;
@import 'o-typography/main';
@include oTypography();

If silent mode is on (set to true) and the main mixin oTypography() is not used, o-typography does not load web fonts. In this case products should load web fonts themselves using o-fonts.

The Sass in o-typography also provides several mixins for use in your project. To explore all functions/mixins see the SassDoc documentation in the registry.

Use Case mixins

The module has common typographic use cases that are available as mixins, rather than using o-typography classes output with the main oTypography() mixin.

E.g:

.article {
    blockquote {
        @include oTypographyBlockquote;
    }
}

See more usecase mixins in the registry SassDoc documentation.

Type mixins

If you want to output only the font-family, font-size, and line-height, with no extra styles, use the type mixins.

These mixins take three arguments:

Sass:

.example {
    // Outputs font-family, line-height, and font-size for the given scale, with a fallback font for progressive font loading.
    @include oTypographySans($scale: 7);
}
.example {
    // Outputs font-family, font-size for the given scale, the custom line-height, and no fallback font.
    @include oTypographySans($scale: 1, $line-height: 28px, $progressive: false);
}
.example {
    // Responsive font scales are also supported
    // In this example the scale is 0, then 1 on a medium display, 2 on an extra large display.
    @include oTypographySans($scale: (default: 0, M: 1, XL: 2) );
}

See more type mixins in the registry SassDoc documentation.

Font Scale mixin

If you want to output only the font-size and line-height from the font scale, you can use the oTypographySize mixin.

.example {
    @include oTypographySize($scale: 8);
}

It can also accept a second parameter of $line-height to override the default value from the font scale.

.example {
    @include oTypographySize($scale: 8, $line-height: 1.4);
}

As with the type mixins, the oTypographySize mixin can accept a map for a responsive scale.

.example {
    @include oTypographySize($scale: (default: 0, M: 1, XL: 2));
}

To provide a custom line height for each individual breakpoint pass the scale as a list, where the custom line height is the second item. In this example the scale is 0 and line-height is 1.4 by default. On large XL screens the scale is 2 and the line-height is 1.2.

.example {
    @include oTypographySize($scale: (default: (0, 1.4), XL: (2, 1.2)));
}

Spacing

Along with font sizing o-typography provides spacing mixins, for spacing elements within a baseline grid. The baseline grid defaults to 4px, stored in $o-typography-baseline-unit.

There are 2 mixins and a function provided for working with the baseline grid. Each mixin or function takes arguments used as multipliers of the $o-typography-baseline-unit variable.

There is also a function that will cap line width based on the scale and the characters per line:

.example-box {
    @include oTypographyMargin($top: 3, $bottom: 5);
    @include oTypographyPadding($top: 0, $bottom: 5);
}

See more details about spacing in the registry SassDoc documentation.

Links in o-typography have a custom underline which uses borders. As well as the default link mixin (oTypographyLink), we expose oTypographyLinkCustom which allows you to output link styles with your own colors.

For a link that launches another window / tab, use oTypographyLinkExternal.

This mixin accepts four arguments, all of which must be valid o-colors palette colors:

Example usage:

.my-custom-link {
    @include oTypographyLinkCustom(
        $baseColor: 'claret',
        $hoverColor: 'claret-30'
    );
}

.dark-background .my-custom-link {
    @include oTypographyLinkCustom(
        $baseColor: 'lemon',
        $hoverColor: 'lemon-30',
        $backgroundColor: 'slate'
    );
}

Line Width capping

If you need to cap the line width, o-typography provides a function which limits that value based on the size of the font and an optimal amount of characters per line (65~).

    max-width: oTypographyMaxLineWidth($scale: 1);

Use A Custom Font

To set a custom font, first register the font using o-fonts.

Then set the custom font using oTypographySetFont before calling any other o-typography mixins. It accepts a font type (sans, serif, or display) and the custom font family.

    // Set custom sans font.
     @include oTypographySetFont($type: 'sans', $family: 'MySansFont, sans');
    // The custom sans font is now output by other `o-typography` mixins such as `oTypography`.
    @include oTypography();

Use A Custom Font Scale

o-typography supports multiple fonts scales, so each font may use a different scale. To register a custom scale use oTypographyDefineFontScale. The mixin accepts the font family the scale is for and the scale map (a map of scale numbers to font size/line height).

If defining a scale for a custom font, first set the custom font.

$example-custom-font-family: 'MySansFont, sans';
$example-custom-font-scale: (
   -2: (12, 16), // $scale: ($font-size, $line-height)
   -1: (14, 16),
    0: (16, 20),
    1: (18, 20),
    2: (20, 24),
    3: (24, 28),
    4: (28, 32),
    5: (32, 32),
    6: (40, 40),
    7: (48, 48),
    8: (56, 56),
    9: (72, 72),
   10: (84, 84),
);

@include oTypographyDefineFontScale($example-custom-font-family, $example-custom-font-scale);

JavaScript

o-typography uses JavaScript to progressively load fonts to prevent a flash of invisible content (FOIC) if the web-fonts are taking a long time to load.

Unless you're using the Build Service no JS will run automatically. You must either construct an o-typography object or fire the o.DOMContentLoaded event, which oTypography listens for.

Constructing o-typography

const oTypography = require('o-typography');

const otypography = new oTypography();

Firing an oDomContentLoaded event

document.addEventListener('DOMContentLoaded', function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Both methods will trigger the font loading scripts. This will remove the loading classes from the html enabling progressive font loading.

Troubleshooting

Fonts not loading in IE11

This is likely due to a misconfigured Vary header. In IE11 if the Vary header contains the name of a header which the browser is not aware of E.G. FT-Site, then it will cancel downloading the fonts part way through recieving the response yet still report the response as having a 200 HTTP status code. The solution to this is to remove the erroneous Vary header values or to remove the Vary header altogether. You can read more about how IE handles the Vary header on MSDN.

Fonts not loading in any brower

This is likely due to the server sending the fonts having misconfigured Cross Origin Resource Sharing (CORS). The solution to this is to set the header Access-Control-Allow-Origin with the value * for any font requests.

Migration guide

Migrating from v4 to v5

V5 of o-typography is a complete overhaul of the typographic system for FT products. The update includes:

Mixins and sizes

To help you migrate from the v4 mixins to the v5 mixins. We have provided a table recommending the mixins and font scale you should use when migrating from v4 to v5.

The following mixins are now renamed:

- oTypographySerifDisplayBold
+ oTypographyDisplayBold

- oTypographySerifDisplay
+ oTypographyDisplay

- oTypographySansDataBold
+ oTypographySansBold

- oTypographySansData
+ oTypographySans

- font-size
+ oTypographySize

- oTypographyProgressiveFont
+ oTypographyProgressiveFontFallback

- oTypographyFallbackFontSize
+ _oTypographyProgressiveFontFallbackSize

- oTypographyHeading1
+ oTypographyHeadline

- oTypographyHeading2
+ oTypographyHeadingLevel2

- oTypographyHeading3
+ oTypographyHeadingLevel3

- oTypographyHeading4
+ oTypographyHeadingLevel4

- oTypographyHeading5
+ oTypographyHeadingLevel5

- oTypographyLinkTopic
- oTypographyLinkTopicMedium
+ oTypographyTopic

v5 also removes the following mixins:

- oTypographySansSize
- oTypographySansBoldSize
- oTypographySansDataSize
- oTypographySansDataBoldSize
- oTypographySansDataItalicSize
- oTypographySerifSize
- oTypographySerifBoldSize
- oTypographySerifItalicSize
- oTypographySerifDisplaySize
- oTypographySerifDisplayBoldSize
- oTypographySerifDisplayItalicSize

CSS classes

v5 introduces several changes to the CSS classes that are available. Whether using the build service or Sass with silent mode switched off you will need to update to the new classnames. The following diff shows removed class and what classname you should use instead, if available.

- .o-typography-block
+ .o-typography-body

- .o-typography-lead
- .o-typography-lead--small
+ .o-typography-standfirst

- o-typography-heading1
+ o-typography-headline

- o-typography-heading2
+ o-typography-heading-level-2

- o-typography-heading3
+ o-typography-heading-level-3

- o-typography-heading4
+ o-typography-heading-level-4

- o-typography-heading5
+ o-typography-heading-level-5

- .o-typography-link-topic
- .o-typography-link-topic--medium
+ .o-typography-topic

- .o-typography-body-wrapper
+ .o-typography-wrapper


// The following classnames do not have like-for-like replacements
- .o-typography-flyline
- .o-typography-subhead
- .o-typography-subhead--standard
- .o-typography-subhead--crosshead
- .o-typography-aside__title
- .o-typography-aside__title--large
- .o-typography-aside__headline
- .o-typography-aside__headline--small
- .o-typography-aside__headline--large
- .o-typography-aside__body
- .o-typography-aside__body--small
- .o-typography-aside-wrapper

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #ft-origami or email Origami Support.


Licence

This software is published by the Financial Times under the MIT licence.
For more see the demos in the registry.

Switch component view

GitHub Repository

Install o-typography

If using the Build Service, add o-typography@^5.8.3 to your script and link tags.

If running a Manual Build, run bower install --save "o-typography@^5.8.3".

Help & Support

o-typography is maintained directly by the Origami team. If you have any questions about o-typography or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com