@financial-times/o-typography
Advanced tools
Readme
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.
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.
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.
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.
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:
oTypographyHeadlineoTypographyHeadingLevel1oTypographyHeadingLevel2oTypographyBodyoTypographyLinkoTypographyCaptionoTypographyBlockquote.article {
blockquote {
@include oTypographyBlockquote;
}
}
See more usecase mixins in the registry SassDoc documentation.
If you want to output only the font-family, font-size, and line-height, with no extra styles, use the type mixins.
oTypographySerifoTypographyDisplayoTypographySansoTypographyDisplayBoldoTypographySansBoldoTypographySerifBoldoTypographySerifItalicThese mixins take three arguments:
true by default.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.
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)));
}
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.
oTypographyMargin($top, $bottom) - (mixin) output top and bottom marginsoTypographyPadding($top, $bottom) - (mixin) output top and bottom paddingoTypographySpacingSize($units) - (function) returns a pixel valueThere is also a function that will cap line width based on the scale and the characters per line:
oTypographyMaxLineWidth($scale, $character-per-line) - (function) returns a pixel value..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:
backgroundColor to create the underline color.paper.teal.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'
);
}
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);
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();
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);
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.
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.
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.
V5 of o-typography is a complete overhaul of the typographic system for FT products. The update includes:
FinancierText font family and replace serif font with Georgia.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
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
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.
This software is published by the Financial Times under the MIT licence. For more see the demos in the registry.
FAQs
Unknown package
We found that @financial-times/o-typography demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 10 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers unpack a typosquatting package with malicious code that logs keystrokes and exfiltrates sensitive data to a remote server.
Security News
The JavaScript community has launched the e18e initiative to improve ecosystem performance by cleaning up dependency trees, speeding up critical parts of the ecosystem, and documenting lighter alternatives to established tools.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.