Typography

Typography in Storybook

Examples

Check out the Usage section for details about how to use the typography component properly, and the different configuration options we provide.

Basic example

You can use the typography component to flag content with a semantic label that determines its formatting and html tag.

<Typography variant="body-medium">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</Typography>

Variant example

You can use the variant prop to apply different styles and html tags to the text.

<Typography variant="blockquote-medium">
    This is a blockquote.
</Typography>

All variant examples

Tag example

You can use the tag prop to set which HTML tag to use instead of letting the typography variant determine the tag.

Warning: When selecting an alternate tag, ensure that the selected tag maintains semantic meaning and supports accessible HTML practices.

For more information, see the usage guidelines.

In this example, the text is wrapped in a span tag and formatted to have small text.

<Typography variant="body-small" tag="span">
    This is a span that is formatted to have small text.
</Typography>

Usage

Overview

The typography component is a foundational element of the design system that ensures consistent and semantically correct text rendering. It separates the visual appearance (defined by variant) from the semantic meaning (defined by tag), which provides flexibility while maintaining accessibility.

Key properties:

• variant: Controls the visual styling of the text, such as font size, weight, line height, color. Examples include heading-1, heading-2, body-large, and label-medium.
• tag: Overrides the underlying HTML semantic element to ensure proper document structure and accessibility. Examples include h1, h2, p, and span.

By default, each variant is associated with a specific HTML tag. However, the tag property allows you to override this default. This gives you the flexibility to adjust the visual prominence of text while maintaining a logical semantic structure. For example, you can make a heading visually subtle without changing its structural importance.

For a complete list of default tags, see the Variant options tables. For more examples of this technique, see the section on Separating style from semantics.

When to use

Use the typography component for all text elements within the application, including:

• Headings: For titles and section headings.
  • Example: Use a heading variant, such as heading-1.
• Body: For paragraphs and other long-form content.
  • Example: Use a body variant, such as body-medium.
• Labels: For shorter, descriptive text, such as form field labels.
  • Example: Use a label variant, such as label-small.
• Eyebrow: For introductory text that sits above a main heading to provide context.
  • Example: Use an eyebrow variant, such as eyebrow-1.
• Hero: For large, high-impact text in hero sections or marketing headlines.
  • Example: Use a hero variant, such as hero-1.
• Block quotes: For styling text that is quoted from an external source.
  • Example: Use a blockquote variant, such as blockquote-medium.
• Captions: For descriptive text accompanying images or figures.
  • Example: Use a figcaption variant, such as figcaption-medium.
• Code: For displaying inline or block-level code snippets.
  • Example: Use a code variant, such as code-medium.
• Any text requiring consistent styling and semantic meaning.

When not to use

Avoid using the typography component for standalone elements whose primary role is to be a button or a link. Instead, use the dedicated Button or Link components, which are built to handle interactive states, focus management, and accessibility roles correctly.

Example usage

1. Hero variant: This is the main headline of the page.
2. Eyebrow variant: This text provides context for the heading below it.
3. Heading variant (section title): This heading-2 serves as the primary heading for the "Add a driver" section.
4. Heading variant (sub-section title): This is a case of separating visual style from semantic meaning. The text is visually smaller than the main section heading (using a heading-4 variant), but it is marked up as an h3 to create a correct nested structure for screen readers (h2 → h3).
5. Body variant: This is a standard paragraph providing instructional text.
6. Label variant: This text describes a form input.

Separating style from semantics

The following examples show how to use the variant and tag properties to create a visual appearance that is different from the underlying semantic structure of the text.

Example: Subtle section heading

This is useful when a heading is semantically necessary for the document outline but needs to be visually understated.

• Variant: body-medium
• Tag: h2
• Justification: This heading is semantically important for screen readers navigating the page structure, but the body-medium variant makes it visually blend in with paragraph text, avoiding unnecessary prominence.

The following example demonstrates this principle in practice:

Example: Visually prominent quote

This is for text that needs high visual impact but is not a structural heading.

• Variant: heading-3
• Tag: blockquote
• Justification: Here, a blockquote is given the visual weight of a heading-3 to make it stand out. Using the blockquote tag ensures it is read correctly by assistive technology as a quote, rather than incorrectly as a structural section heading.

The following example demonstrates this principle in practice:

General guidelines

• Maintain hierarchy: Always use headings (h1 through h6) in a logical, nested order. An h2 must follow an h1, and an h3 must follow an h2, even if the visual variant is different. Don't skip heading levels (for example, h1 directly followed by h4).
• Semantic correctness: Prioritize the tag property for semantic accuracy. The variant is for visual presentation; the tag is for meaning.
• Consistency: Use the predefined variant values consistently throughout the application to maintain a cohesive visual language.

Content

General writing guidelines

• Clarity and conciseness: Write clearly and get straight to the point. Avoid jargon and overly complex sentences.
• Active voice: Prefer active voice over passive voice for stronger, more direct communication.
• Plain language: Use language that is easy for your target audience to understand.
• Consistency in terminology: Use consistent terms for features, actions, and concepts throughout the application.
• Tone of voice: Maintain a consistent and appropriate tone of voice that aligns with our brand. For more information, see Voice and tone.
• Proofread: Always proofread text for grammatical errors, spelling mistakes, and typos.
• Microcopy: Pay attention to small pieces of text like button labels, error messages, and tooltips. They are crucial for user experience.

Accessibility

Component compliance

The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.

This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.

Authoring guidelines

Semantic HTML (tag property): This is the most critical aspect for accessibility. Screen readers and other assistive technologies rely on semantic HTML tags (for example, h1-h6, p, and blockquote) to understand the structure and meaning of the content. Always choose the most appropriate tag for the content's role.

Heading hierarchy: Ensure a logical heading structure (for example, h1 followed by h2, not h4). This allows screen reader users to navigate content efficiently. For more detailed guidance, refer to the W3C's tutorial on headings.

Theming

The typography component inherits its styles from the application's theme by default. However, you can customize typographic elements like color, font families, and the scale of sizes and weights to meet specific branding needs.

Learn more about theming with design tokens

Code

<Typography>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</Typography>

Import statement

import { Typography } from '@jutro/components';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

childrenrequired

Type

node

Description

The children to render as typography text content.

className

Type

string

Description

CSS class name for this component.

variant

Type

See variant options

Description

A flag that determines the typography variant to apply to the element. This will determine the style of the text element and, if not overridden by the tag property, the HTML tag it uses.

Default value

'body-medium'

tag

Type

See tag options

Description

HTML tag to be used for the typography element. If not provided, it will be determined based on the variant.

Variant options

This tables below show the accepted values for the variant property and their default HTML tag. To see a demonstration of how each are formatted, go to the examples section.

Hero variants

Variant string	Default HTML Tag
'hero-1'	h1
'hero-2'	h2
'hero-3'	h3

Heading variants

Variant string	Default HTML Tag
'heading-1'	h1
'heading-2'	h2
'heading-3'	h3
'heading-4'	h4
'heading-5'	h5
'heading-6'	h6

Eyebrow variants

Variant string	Default HTML Tag
'eyebrow-1'	h1
'eyebrow-2'	h2
'eyebrow-3'	h3

Label variants

Variant string	Default HTML Tag
'label-large-stronger'	label
'label-large-strong'	label
'label-large'	label
'label-medium-stronger'	label
'label-medium-strong'	label
'label-medium'	label
'label-small-stronger'	label
'label-small-strong'	label
'label-small'	label
'label-xsmall-stronger'	label
'label-xsmall-strong'	label
'label-xsmall'	label

Body variants

Variant string	Default HTML Tag
'body-large'	p
'body-medium'	p
'body-small'	p
'body-xsmall'	p

Code variants

Variant string	Default HTML Tag
'code-large'	code
'code-medium'	code
'code-small'	code
'code-xsmall'	code

Blockquote variants

Variant string	Default HTML Tag
'blockquote-large'	blockquote
'blockquote-medium'	blockquote
'blockquote-small'	blockquote
'blockquote-xsmall'	blockquote

Figcaption variants

Variant string	Default HTML Tag
'figcaption-large'	figcaption
'figcaption-medium'	figcaption
'figcaption-small'	figcaption
'figcaption-xsmall'	figcaption

Tag options

The following strings can be used as values for the tag property.

Warning: When selecting an alternate tag, ensure that the selected tag maintains semantic meaning and supports accessible HTML practices.

For more information, see the usage guidelines.

Heading tags

• 'h1'
• 'h2'
• 'h3'
• 'h4'
• 'h5'
• 'h6'

Text body tags

• 'p'
• 'blockquote'
• 'code'
• 'span'
• 'div'

Caption and label tags

• 'label'
• 'legend'
• 'blockquote'
• 'figcaption'

Hooks

No hooks are available for typography.

Translation keys

There are no translations for typography.

For information on how to manage translations, see our section about Internationalization.

Escape hatches

For more information, see our documentation about escape hatches.

Changelog

10.11.0

Typography component added.