MD3
Expressive
MATERIAL DESIGN 3 EXPRESSIVE

Typography

MD3 Expressive typography system powered by Google Sans Flex variable font with full 6-axis customization (ROND, opsz, GRAD, wght, wdth, slnt).

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.

Loading demo...

Introduction

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

[!WARNING] Google Sans Flex is required for variable axes to take visual effect. The ROND, opsz, GRAD, wght, wdth, and slnt variation axes only render when Google Sans Flex is loaded. To enable it:

  1. Import styles (recommended): Ensure @import "@bug-on/m3-expressive/index.css"; (or @bug-on/m3-expressive/typography.css) is included in your main stylesheet.
  2. Apply CSS class: Add the font-md3-expressive utility class to your root element (<html className="font-md3-expressive"> or <body className="font-md3-expressive">).

If you substitute a standard static font or a font that does not support these axes (such as generic system sans-serif), custom axes like ROND, opsz, and GRAD will have no visual effect.

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 is a full-featured variable typeface that allows you to fine-tune the character, weight, and density of your typography. The library natively supports six variable axes via fontVariationAxes:

AxisNameRangeDefaultDescription
RONDRoundness0 – 100100Signature corner roundness of MD3 Expressive. 0 = sharp corners, 100 = fully rounded.
wghtWeight100 – 1000400Overrides font weight dynamically along a continuous scale without separate weight files.
wdthWidth75 – 125100Glyph condensation (75) or expansion (125) for compact headers or wide editorial banners.
opszOptical Size6 – 14414Adjusts stroke thickness and spacing for text size. When overriding manually, pair with font-optical-sizing: none.
GRADGrade-200 – 1500Modifies optical weight without changing glyph metrics, advance widths, or line wrapping. Ideal for dark mode.
slntSlant-15 – 00Applies font-designed slant angle in degrees (-15 = 15° forward slant, 0 = upright).

All Axes Interactive Playground

Adjust all six variable axes simultaneously in real-time, test custom preview text, and copy generated CSS:

Loading demo...

Roundness (ROND) Focus

Loading demo...

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.

Loading demo...

Usage

Basic Usage

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

<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="'Google Sans Flex', system-ui, sans-serif" 
  fontVariationAxes={{
    ROND: 50,
    wght: 500,
    wdth: 105,
    opsz: 24,
    GRAD: 50,
    slnt: -10,
  }}
>
  <App />
</MD3ThemeProvider>

Local Overrides

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

<TypographyProvider 
  fontFamily="'Google Sans Flex', system-ui, sans-serif"
  fontVariationAxes={{ ROND: 0, slnt: -15 }}
>
  <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.

PropTypeDefaultDescription
variant"display-lg" | "display-md" | "display-sm" | "headline-lg" | "headline-md" | "headline-sm" | "title-lg" | "title-md" | "title-sm" | "body-lg" | "body-md" | "body-sm" | "label-lg" | "label-md" | "label-sm""body-md"The typography style variant (format: {role}-{size}).
asElementTypeautoOverride the rendered HTML element tag (e.g. "h1", "span", "p").
colorstring—Custom text color override.
weightnumber | string—Font weight override.
classNamestring—Custom CSS class names.

MD3ThemeProvider Typography Props

| Prop | Type | Default | Description | | fontVariationAxes | FontVariationAxes | { ROND: 100 } | Global variable font axes (ROND, wght, wdth, opsz, GRAD, slnt). |