Typography is a critical part of the MD3 Expressive system, providing a clear hierarchy and consistent voice across your application. It features 30 distinct styles powered by Google Sans Flex.

Introduction

The MD3 Expressive Typography system is designed for maximum readability and brand expression. It leverages the Google Sans Flex variable font, which includes a unique ROND (Roundness) axis. By default, this axis is set to its maximum value, giving the typeface a friendly, modern, and organic feel that perfectly matches the MD3 Expressive aesthetic.

Type Hierarchy

The system is organized into five primary groups, each with three sizes (Small, Medium, Large) and two emphasis variants (Baseline and Emphasized):

• Display: For high-impact, expressive text on landing pages or headers.
• Headline: For primary section headings.
• Title: For secondary headings and UI labels.
• Body: For the main content text.
• Label: For small UI annotations, captions, and buttons.

Features

Variable Font Axes

Google Sans Flex allows you to fine-tune the character of your typography. The ROND axis controls the roundness of the glyphs, allowing you to transition from a sharp, technical look to a friendly, rounded aesthetic.

Adaptive HTML Mapping

The Text component automatically selects the most semantic HTML tag based on the chosen variant (e.g., DisplayLarge maps to h1, while BodyMedium maps to p), though this can be overridden using the as prop.

Usage

Basic Usage

import { Text } from "@bug-on/m3-expressive";

<Text variant="display-lg">Welcome back</Text>
<Text variant="body-md">This is your dashboard.</Text>

Customizing Typography

You can customize the global typography settings in the MD3ThemeProvider:

<MD3ThemeProvider 
  fontFamily="'Inter', sans-serif" 
  fontVariationAxes={{ ROND: 50 }}
>
  <App />
</MD3ThemeProvider>

Local Overrides

Use the TypographyProvider to override styles for a specific section of your app:

<TypographyProvider fontFamily="'Serif', serif">
  <article>
    <Text variant="title-lg">Article Title</Text>
    {/* ... */}
  </article>
</TypographyProvider>

Best Practices

Do

• Use Display and Headline variants for high-level information and page headers.
• Maintain a consistent hierarchy by following the established variant sizes.
• Use Emphasized variants sparingly for text that needs significant attention.
• Ensure that your chosen font family and axes maintain high readability across all devices.

Don't

• Don't mix too many different font families; stick to one or two complementary ones.
• Avoid using very small Label variants for long blocks of text.
• Don't override typography styles on a per-element basis if they can be handled by the global theme.

Accessibility

• Legibility: MD3 Expressive styles are pre-configured with optimal line heights and letter spacing.
• Semantics: The Text component helps maintain a correct document structure for screen readers.
• Scaling: All styles use relative units (rem/em) to respect user-level font size preferences.

API Reference

Text

The primary component for rendering typography.

MD3ThemeProvider Typography Props