Heading font family
Core uses Open Sans for all headings.The design system doesn't style base HTML typography elements (like h1
, h2
, p
, etc.) unless they're inside an element with the ds-content class. Instead, it provides heading classes (available on this page) corresponding to visual sizes. These classes can be applied to any heading elements, irrespective of their semantic heading level (h1
to h6
). This approach allows teams to first choose the semantic heading level that make the most sense for the document and its accessibility and then choose a visual heading size class that fits the page's visual hierarchy.
Responsive typography
.ds-text-heading-5xl
, ds-text-heading-4xl
, and ds-text-heading-3xl
classes are responsive by default.
To apply responsive typography elsewhere, use the font size utility class.
Since the base typography margins and line height is measured in em
units,
they'll automatically adjust as you change the font size.
CSS class | Figma token | Example |
---|---|---|
ds-text-heading--sm | Headings/Small | Tuscaloosa |
ds-text-heading--md | Headings/Medium | Tuscaloosa |
ds-text-heading--lg | Headings/Large | Tuscaloosa |
ds-text-heading--xl | Headings/XL | Tuscaloosa |
ds-text-heading--2xl | Headings/2xl/2xl | Tuscaloosa |
ds-text-heading--3xl | Headings/3xl/3xl - MD-SM | Tuscaloosa |
ds-text-heading--4xl | Headings/4xl/4xl - MD-SM | Tuscaloosa |
ds-text-heading--5xl | Headings/5xl/5xl - SM | Tuscaloosa |
CSS class | Figma token | Example |
---|---|---|
ds-text-heading--3xl | Headings/3xl/3xl - MD-SM | Tuscaloosa |
ds-text-heading--4xl | Headings/4xl/4xl - MD-SM | Tuscaloosa |
ds-text-heading--5xl | Headings/5xl/5xl - MD | Tuscaloosa |
CSS class | Figma token | Example |
---|---|---|
ds-text-heading--3xl | Headings/3xl/3xl - LG | Tuscaloosa |
ds-text-heading--4xl | Headings/4xl/4xl - LG | Tuscaloosa |
ds-text-heading--5xl | Headings/5xl/5xl - LG | Tuscaloosa |
CSS Class | 545px and below | 545px to 768px | 768px and above |
---|---|---|---|
.ds-text-heading-5xl | 36px | 48px | 60px |
.ds-text-heading-4xl | 36px | 36px | 48px |
.ds-text-heading-3xl | 30px | 30px | 36px |
Headings Links
Links nested within elements styled with heading tags, or styled directly as headings, will render as links in the appropriate size and weight. There is no additional CSS class to apply, but Figma contains tokens specific to rendering links. Medium breakpoints are given as an example below.
Please note that in Figma, the color token is separate from the font token and needs to be applied independently.
CSS class | Figma token | Example |
---|---|---|
ds-text-heading--sm | Links/Headings/Small | Tuscaloosa |
ds-text-heading--md | Links/Headings/Medium | Tuscaloosa |
ds-text-heading--lg | Links/Headings/Large | Tuscaloosa |
ds-text-heading--xl | Links/Headings/XL | Tuscaloosa |
ds-text-heading--2xl | Links/Headings/2xl/2xl | Tuscaloosa |
ds-text-heading--3xl | Links/Headings/3xl/3xl - MD-SM | Tuscaloosa |
ds-text-heading--4xl | Links/Headings/4xl/4xl - MD-SM | Tuscaloosa |
ds-text-heading--5xl | Links/Headings/5xl/5xl - SM | Tuscaloosa |
CSS class | Figma token | Example |
---|---|---|
ds-text-heading--3xl | Links/Headings/3xl/3xl - MD-SM | Tuscaloosa |
ds-text-heading--4xl | Links/Headings/4xl/4xl - MD-SM | Tuscaloosa |
ds-text-heading--5xl | Links/Headings/5xl/5xl - MD | Tuscaloosa |
CSS class | Figma token | Example |
---|---|---|
ds-text-heading--3xl | Links/Headings/3xl/3xl - LG | Tuscaloosa |
ds-text-heading--4xl | Links/Headings/4xl/4xl - LG | Tuscaloosa |
ds-text-heading--5xl | Links/Headings/5xl/5xl - LG | Tuscaloosa |
Specific examples
On dark background
Eyebrow/Eyelash header
In some cases, it is better to group header elements into a header component. This can be referred to as the Eyelash/Eyebrow header where you have the main header and an optional top header (eyebrow) or bottom header (eyelash) header.
This is an optional header design.
Code
First and last children
The design system heading styles have alternate margins for headings that are the first or last child of their parent element. Headings that are the first child have no top margin, and headings that are last children have no bottom margin. Some examples of what we mean:
<main>
<h1>I'm the first child of my parent.</h1>
<h2>I'm not the first child of my parent</h2>
<div>
<h2>
I'm actually the first child of my parent even though I'm not the first heading on the page
</h2>
<h2>I'm the last child of my parent</h2>
</div>
<h2>I'm also the last child of my parent</h2>
</main>
Style customization
The following CSS variables can be overridden to change the type sizes:
--font-size-5xl
--font-size-4xl
--font-size-3xl
--font-size-2xl
--font-size-xl
--font-size-lg
--font-size-md
, uses--font-size-base
--font-size-sm
Guidance
The ds-content
class
For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels, consider using the ds-content
class.
Layout dos and don'ts
There should always be a parent/child relationship between headers and content on the page. Every header should have a relationship to something else on the page. This can apply to many different relationships like a header and a form group or a header and list of links. Stray headers or content should be reevaluated.
- Paragraph styles should never be used as a parent to another text element.
- Header elements should never have equal or smaller font size than the paragraph element.
- Not all paragraphs need a header, but all headers need children.
- Every page should have one heading 1 (H1)
- Headings style appearing under H1 should follow a logical order for information design and supporting various assistive technology devices/software.
- Don't use a smaller header font size than the body font size
- Don't use stray headers