Use these pages to inspect the toolkit foundations that sit underneath components and patterns.
+ Where practical, the values shown here are derived from the toolkit token files so the docs stay aligned with the code.
+
+ Design for mobile first using a single-column layout and work up to wider layouts.
- The default maximum page width is 960px, but you can make it wider if your content requires it. Lines of text should be no longer than 70 to 80 characters. Any longer will make the page difficult to read.
+ To set up your layout, you will need to use a container which sets the maximum width of the content.
The class column shows the container or utility class to apply to the wrapper that should take on that width behaviour.
+
+ {% set items = foundationStyles.layout.widths %}
+ {% set caption = "Container and width references" %}
+ {% set variant = "width" %}
+ {% set classColumnLabel = "Use this class" %}
+ {% set showNotes = true %}
+ {% include "design-system/styles/_partials/showcase-scale.njk" %}
The vertical padding can be made larger or smaller by using the modifier classes .ofh-main-wrapper--l or .ofh-main-wrapper--s. We recommend using smaller vertical padding on transactional services.
+ The vertical padding can be made larger or smaller by using the modifier classes .ofh-main-wrapper--l or .ofh-main-wrapper--s. We recommend using the smaller modifier on transactional services.
We use a grid to structure our designs and create consistent spacing. It gives us a flexible way to layout components that adapts to different device sizes.
+ We use a grid to structure our designs and create consistent spacing. It gives us a flexible way to lay out components that adapts to different device sizes.
You can add columns inside this wrapper to create your layout. To define your columns, add the class beginning with .ofh-grid-column- to a new container followed by the width, for example .ofh-grid-column-one-third, to make it the width you want.
+ You can add columns inside this wrapper to create your layout. To define your columns, add the class beginning with .ofh-grid-column- to a new container followed by the width, for example .ofh-grid-column-one-third.
+ Lines of text should be no longer than 70 to 80 characters.
- When using the fluid-width container or wider grid columns, wrap text content with .ofh-u-reading-width to apply a maximum width and limit the number of characters per line.
+ By default, grid columns sizes will go to 100% width of the container on screen sizes below the desktop breakpoint, which is 769px. These utility classes will enforce column widths on all screen sizes.
- By default, grid columns go to 100% width of the container on screen sizes below the desktop breakpoint, which is {{ foundationStyles.layout.breakpointsById.desktop.value }}. These utility classes will enforce column widths on all screen sizes.
+ These utility classes will enforce column widths on screen sizes larger than the mobile breakpoint, which is 320px.
+ These utility classes will enforce column widths from the tablet breakpoint upwards, which is {{ foundationStyles.layout.breakpointsById.tablet.value }}.
Spacing
@@ -59,81 +59,15 @@
Desktop is the reference size for each spacing key. Values then either stay the same or collapse at smaller breakpoints.
The responsive scales are split by direction. When you use the mixin with all, top and bottom use the vertical scale, while left and right use the horizontal scale.
- Horizontal spacing scale
-
- {{ table({
- panel: false,
- caption: "",
- head: [
- {
- text: "Size key"
- },
- {
- text: "Desktop",
- format: "numeric"
- },
- {
- text: "Tablet",
- format: "numeric"
- },
- {
- text: "Mobile",
- format: "numeric"
- }
- ],
- rows: [
- [{ text: "0" }, { text: "0", format: "numeric" }, { text: "0", format: "numeric" }, { text: "0", format: "numeric" }],
- [{ text: "2" }, { text: "2px", format: "numeric" }, { text: "2px", format: "numeric" }, { text: "2px", format: "numeric" }],
- [{ text: "4" }, { text: "4px", format: "numeric" }, { text: "4px", format: "numeric" }, { text: "4px", format: "numeric" }],
- [{ text: "8" }, { text: "8px", format: "numeric" }, { text: "8px", format: "numeric" }, { text: "8px", format: "numeric" }],
- [{ text: "12" }, { text: "12px", format: "numeric" }, { text: "12px", format: "numeric" }, { text: "12px", format: "numeric" }],
- [{ text: "16" }, { text: "16px", format: "numeric" }, { text: "16px", format: "numeric" }, { text: "16px", format: "numeric" }],
- [{ text: "24" }, { text: "24px", format: "numeric" }, { text: "24px", format: "numeric" }, { text: "16px", format: "numeric" }],
- [{ text: "32" }, { text: "32px", format: "numeric" }, { text: "32px", format: "numeric" }, { text: "16px", format: "numeric" }],
- [{ text: "40" }, { text: "40px", format: "numeric" }, { text: "32px", format: "numeric" }, { text: "16px", format: "numeric" }],
- [{ text: "48" }, { text: "48px", format: "numeric" }, { text: "32px", format: "numeric" }, { text: "16px", format: "numeric" }],
- [{ text: "56" }, { text: "56px", format: "numeric" }, { text: "32px", format: "numeric" }, { text: "16px", format: "numeric" }],
- [{ text: "64" }, { text: "64px", format: "numeric" }, { text: "32px", format: "numeric" }, { text: "16px", format: "numeric" }]
- ]
- }) }}
+ {% set items = foundationStyles.spacing.horizontalScale %}
+ {% set caption = "Horizontal spacing scale" %}
+ {% set variant = "spacing" %}
+ {% include "design-system/styles/_partials/showcase-scale.njk" %}
- Vertical spacing scale
-
- {{ table({
- panel: false,
- caption: "",
- head: [
- {
- text: "Size key"
- },
- {
- text: "Desktop",
- format: "numeric"
- },
- {
- text: "Tablet",
- format: "numeric"
- },
- {
- text: "Mobile",
- format: "numeric"
- }
- ],
- rows: [
- [{ text: "0" }, { text: "0", format: "numeric" }, { text: "0", format: "numeric" }, { text: "0", format: "numeric" }],
- [{ text: "2" }, { text: "2px", format: "numeric" }, { text: "2px", format: "numeric" }, { text: "2px", format: "numeric" }],
- [{ text: "4" }, { text: "4px", format: "numeric" }, { text: "4px", format: "numeric" }, { text: "4px", format: "numeric" }],
- [{ text: "8" }, { text: "8px", format: "numeric" }, { text: "8px", format: "numeric" }, { text: "8px", format: "numeric" }],
- [{ text: "12" }, { text: "12px", format: "numeric" }, { text: "8px", format: "numeric" }, { text: "8px", format: "numeric" }],
- [{ text: "16" }, { text: "16px", format: "numeric" }, { text: "8px", format: "numeric" }, { text: "8px", format: "numeric" }],
- [{ text: "24" }, { text: "24px", format: "numeric" }, { text: "16px", format: "numeric" }, { text: "16px", format: "numeric" }],
- [{ text: "32" }, { text: "32px", format: "numeric" }, { text: "24px", format: "numeric" }, { text: "24px", format: "numeric" }],
- [{ text: "40" }, { text: "40px", format: "numeric" }, { text: "32px", format: "numeric" }, { text: "32px", format: "numeric" }],
- [{ text: "48" }, { text: "48px", format: "numeric" }, { text: "40px", format: "numeric" }, { text: "40px", format: "numeric" }],
- [{ text: "56" }, { text: "56px", format: "numeric" }, { text: "48px", format: "numeric" }, { text: "48px", format: "numeric" }],
- [{ text: "64" }, { text: "64px", format: "numeric" }, { text: "56px", format: "numeric" }, { text: "56px", format: "numeric" }]
- ]
- }) }}
+ {% set items = foundationStyles.spacing.verticalScale %}
+ {% set caption = "Vertical spacing scale" %}
+ {% set variant = "spacing" %}
+ {% include "design-system/styles/_partials/showcase-scale.njk" %}
Spacing override classes
Occasionally, you might need to make minor adjustments like adding spacing or removing it from elements of your design. You can use the responsive spacing override classes for this.
@@ -142,12 +76,12 @@
The spacing override classes are structured to allow you to apply any size of the scale, using margin or padding in any direction.
The class name gives you the spacing size key, not a single fixed pixel value at every breakpoint.
To add padding use -padding instead of -margin.
- If you want to add the margin or padding in a particular direction, add left for left, right for right, top for top, or bottom for bottom. For example, -margin-top will set margin-top, -padding-right will set padding-right. If you do not specify a direction, the margin or padding will be applied to all sides of the element.
+ If you want to add the margin or padding in a particular direction, add left for left, right for right, top for top, or bottom for bottom. For example, -margin-top will set margin-top and -padding-right will set padding-right. If you do not specify a direction, the margin or padding will be applied to all sides of the element.
The last part of the class is the spacing size key. For example, ofh-u-margin-56 uses the 56 responsive spacing key and then applies the matching values from the relevant horizontal or vertical scale.
Examples:
- ofh-u-margin-bottom-56 uses the vertical scale, so it is 56px on desktop and 48px on tablet and mobile
ofh-u-margin-right-56 uses the horizontal scale, so it is 56px on desktop, 32px on tablet, and 16px on mobile
ofh-u-margin-bottom-56 uses the vertical scale, so it is {{ foundationStyles.spacing.byKey['56'].vertical.desktop }} on desktop and {{ foundationStyles.spacing.byKey['56'].vertical.tablet }} on tablet and mobile
ofh-u-margin-right-56 uses the horizontal scale, so it is {{ foundationStyles.spacing.byKey['56'].horizontal.desktop }} on desktop, {{ foundationStyles.spacing.byKey['56'].horizontal.tablet }} on tablet, and {{ foundationStyles.spacing.byKey['56'].horizontal.mobile }} on mobile
ofh-u-margin-56 combines both scales, so top and bottom use the vertical values while left and right use the horizontal values
Small spacing keys stay consistent across breakpoints. Larger keys reduce as the layout collapses.
@@ -170,7 +104,8 @@
}) }}
Spacing on custom components
- If you’re building your own components and want to reference spacing directly in SCSS, use the static size tokens for fixed geometry and the responsive spacing mixins for layout spacing.
+ If you are building your own components and want to reference spacing directly in SCSS, use the static size tokens for fixed geometry and the responsive spacing mixins for layout spacing.
+ The old ofh-spacing() helper was removed in toolkit v4.5.0, so fixed spacing values should now come from $ofh-size-* tokens.
Using the static spacing tokens
If you want a fixed value that does not change by breakpoint, use the matching $ofh-size-* token:
@@ -180,8 +115,8 @@
If you want layout spacing that adapts by breakpoint, use the responsive mixin with a size key from the tables above.
For example:
- use @include ofh-responsive-margin(40, "bottom"); for 40px margin-bottom on desktop and 32px on tablet and mobile
use @include ofh-responsive-padding(40); for 40px top and bottom on desktop, 32px top and bottom on tablet and mobile, and the matching horizontal scale on the left and right
use @include ofh-responsive-margin(40, "bottom"); for {{ foundationStyles.spacing.byKey['40'].vertical.desktop }} margin-bottom on desktop and {{ foundationStyles.spacing.byKey['40'].vertical.tablet }} on tablet and mobile
use @include ofh-responsive-padding(40); for {{ foundationStyles.spacing.byKey['40'].vertical.desktop }} top and bottom on desktop, {{ foundationStyles.spacing.byKey['40'].vertical.tablet }} top and bottom on tablet and mobile, and the matching horizontal scale on the left and right
Width override classes
diff --git a/packages/site/views/design-system/styles/typography/index.njk b/packages/site/views/design-system/styles/typography/index.njk
index d61e64586..1800df482 100644
--- a/packages/site/views/design-system/styles/typography/index.njk
+++ b/packages/site/views/design-system/styles/typography/index.njk
@@ -6,7 +6,6 @@
{% set backlog_issue_id = "1" %}
{% set hideContact = "true" %}
-
{% extends "app-layout.njk" %}
{% block breadcrumb %}
@@ -65,22 +64,37 @@
Font
Source Sans Pro
- Source Sans Pro is our primary typeface and should be used for all text content across our digital products and services.
+ Source Sans Pro is our primary typeface and should be used for text content across our digital products and services.
Fallback font
You can default to Arial when Source Sans Pro is not available.
- font-family: “Source Sans Pro”, Arial, sans-serif;
+ font-family: 'Source Sans Pro', Arial, sans-serif;
Typescale
- The typography scale depends on the viewport width. Phones and tablets share the same base sizes, and some styles step up at the desktop breakpoint from 769px and above.
+ The responsive type scale is defined in $ofh-typography-responsive-scale. It uses the same named tokens across the toolkit, docs, and published type utilities.
+ Phones and tablets share the same base sizes, and styles step up at the desktop breakpoint where the current token scale defines larger values.
+ The matrix below shows the current desktop, tablet, and mobile values behind the published typography utilities.
+ The class column shows the published class to apply when you want that typography style on an element.
+
+ {% set rows = foundationStyles.typography.rows %}
+ {% set caption = "Responsive typography matrix" %}
+ {% set showClassName = true %}
+ {% set showToken = false %}
+ {% set showLineHeight = true %}
+ {% set showNotes = true %}
+ {% set firstColumnLabel = "Token" %}
+ {% set classColumnLabel = "Apply this class" %}
+ {% include "design-system/styles/_partials/showcase-matrix.njk" %}
Headings
Write all headings in sentence case.
Style headings consistently to create a clear content structure throughout your service and a clear content hierarchy on a page.
Heading levels have meaning, especially for screen reader users and search engines. Using correct heading levels improves SEO and helps people using assistive technology to navigate through a page.
- Heading overrides
- We have 5 different classes that can be used to change the default font-size and spacing of headings. These classes can be used with any heading. Always ensure heading structure is semantically correct.
+ Heading overrides
+ We provide 5 heading utility classes, from ofh-heading-xl to ofh-heading-xs, which can be applied to any heading level.
+ h5 and h6 share the same responsive heading token.
+ Always ensure the heading structure is semantically correct, even when you override the visual size.
{{ designExample({
group: "styles",
@@ -90,8 +104,8 @@
}) }}
Captions
- Sometimes you may need to make it clear that a page is part of a larger section or group. To do this, you can use a heading with a caption
- We have 3 different sizes of caption, by default captions will display above headings. You can use an additional class to display the caption below headings.
+ Sometimes you may need to make it clear that a page is part of a larger section or group. To do this, you can use a heading with a caption.
+ We have 3 caption sizes. By default captions display above headings, and you can use an additional class to display the caption below the heading.
Consider whether the caption should be part of the page heading. This will determine whether the span is nested in the heading or not.
{{ designExample({
@@ -104,7 +118,7 @@
Paragraphs
Body
- The default paragraph font size is 20px on desktop and 18px on phones and tablets.
+ The default paragraph font size is {{ foundationStyles.typography.byId.paragraph.desktop }} on desktop and {{ foundationStyles.typography.byId.paragraph.mobile }} on mobile.
You can also add classes to create a lead paragraph or smaller body copy to convey content hierarchy in your page.
{{ designExample({
@@ -114,10 +128,9 @@
htmlOnly: true
}) }}
-
Lead paragraph
A lead paragraph is an introductory paragraph that you can use at the top of a page to summarise the content.
- Lead paragraphs use 24px type on desktop and 20px on phones and tablets. You should only use them once per page.
+ Lead paragraphs use {{ foundationStyles.typography.byId.lead.desktop }} type on desktop and {{ foundationStyles.typography.byId.lead.mobile }} on mobile. You should only use them once per page.
{{ designExample({
group: "styles",
@@ -128,7 +141,7 @@
Body small
You can use the ofh-body-s class sparingly to make your paragraph font size smaller.
- Small body text uses 16px across all breakpoints.
+ Small body text uses {{ foundationStyles.typography.byId['paragraph-small'].desktop }} on desktop and {{ foundationStyles.typography.byId['paragraph-small'].mobile }} on mobile.
{{ designExample({
group: "styles",
@@ -138,65 +151,23 @@
}) }}
Font override classes
- You might need to set the font size or font weight of an element outside the predefined heading and paragraph classes. To do this you can use the font override classes in your HTML or reference the typography mixins in your own components.
+ You might need to set the font size or font weight of an element outside the predefined heading and paragraph classes. To do this you can use the typography override classes in your HTML or reference the typography mixins in your own components.
Font size
- The font size override classes use the numeric responsive typography utilities, such as ofh-u-font-size-24 and ofh-u-font-size-20. They keep the pre-monorepo responsive values so maintainers can choose an override by the expected size.
+ The font size override classes use the numeric responsive typography utilities, such as ofh-u-font-size-24 and ofh-u-font-size-20. They keep the current toolkit utility scale so maintainers can choose an override by the expected rendered size.
Use these overrides sparingly where you need a utility-based typography adjustment, and visually check the result because they also apply the matching line height.
- The class name reflects the tablet-and-desktop size. On mobile, the utility collapses to the matching smaller value.
-
-
- Responsive font size override scale
-
-
-
-
-
-
-
-
-
- ofh-u-font-size-64 |
- 64px / 72px |
- 48px / 56px |
-
-
- ofh-u-font-size-48 |
- 48px / 56px |
- 32px / 40px |
-
-
- ofh-u-font-size-32 |
- 32px / 40px |
- 24px / 32px |
-
-
- ofh-u-font-size-24 |
- 24px / 32px |
- 20px / 28px |
-
-
- ofh-u-font-size-22 |
- 22px / 32px |
- 18px / 28px |
-
-
- ofh-u-font-size-20 |
- 20px / 28px |
- 18px / 24px |
-
-
- ofh-u-font-size-16 |
- 16px / 24px |
- 14px / 24px |
-
-
- ofh-u-font-size-14 |
- 14px / 24px |
- 12px / 20px |
-
-
-
+ The class name reflects the tablet-and-desktop size. Smaller utilities stay the same across breakpoints, while larger utilities step down on mobile.
+ The override utility class column shows the utility to add to an existing element when you need a one-off font-size adjustment.
+
+ {% set rows = foundationStyles.typography.utilityRows %}
+ {% set caption = "Responsive font size override scale" %}
+ {% set showClassName = true %}
+ {% set showToken = false %}
+ {% set showLineHeight = true %}
+ {% set showNotes = false %}
+ {% set firstColumnLabel = "Style" %}
+ {% set classColumnLabel = "Override utility class" %}
+ {% include "design-system/styles/_partials/showcase-matrix.njk" %}
{{ designExample({
group: "styles",
@@ -206,8 +177,8 @@
}) }}
Font weight
- You can add ofh-u-font-weight-normal or ofh-u-font-weight-bold to any other typographic class or element to change the font weight.
- Use bold in body content sparingly. It can be used to highlight critical information that users need to refer to, such as a reference number. But overuse of bold will make it difficult for users to know which parts of your content they need to pay the most attention to.
+ You can add ofh-u-font-weight-normal for regular text or ofh-u-font-weight-bold for semi-bold text (600) to any other typographic class or element.
+ Use semi-bold in body content sparingly. It can be used to highlight critical information that users need to refer to, such as a reference number. But overuse will make it difficult for users to know which parts of your content they need to pay the most attention to.
{{ designExample({
group: "styles",
@@ -248,6 +219,7 @@
Lists
Use lists to make blocks of text easier to read, and to break information into manageable chunks.
+ The list styles use their own responsive token shown in the matrix above, and in the current scale those values align with the default body copy.
{{ designExample({
group: "styles",
@@ -281,7 +253,7 @@
You can use the ofh-section-break classes on an <hr> element to create a thematic break between sections of content. ofh-section-break has class-based modifiers for different size margins.
By default ofh-section-break is only visible by its margin. You can add the ofh-section-break--visible class to make it visible with a separator line.
- Colour Variants
+ Colour variants
@@ -296,7 +268,7 @@
Text alignment
Text is left-aligned by default.
The straight edge of left-aligned text helps people who magnify their screen. It saves them having to search around the screen for the next line or item. They may miss things that are not left-aligned.
- Some people with cognitive differences have difficulty with blocks of text that are ‘justified’ – so that they are aligned to both the left and right margins. Justifying text creates wider spaces between words, which can make the text harder to read.
+ Some people with cognitive differences have difficulty with blocks of text that are justified, so that they are aligned to both the left and right margins. Justifying text creates wider spaces between words, which can make the text harder to read.
Only centre-align or fully justify text if you can show a clear user need.
Text alignment override classes
@@ -310,5 +282,4 @@
htmlOnly: true
}) }}
-
{% endblock %}
diff --git a/packages/site/views/design-system/styles/typography/weight/index.njk b/packages/site/views/design-system/styles/typography/weight/index.njk
index 048db3b40..e6919367b 100644
--- a/packages/site/views/design-system/styles/typography/weight/index.njk
+++ b/packages/site/views/design-system/styles/typography/weight/index.njk
@@ -1,2 +1,2 @@
-ofh-u-font-weight-normal
-ofh-u-font-weight-bold
+Regular (400) using ofh-u-font-weight-normal
+Semi-bold (600) using ofh-u-font-weight-bold
+ 
- 
+