Typography Tokens

Typography tokens define the font system for the Lufa Design System, including font sizes, weights, line heights, and font families.

Font Families

Token	CSS Variable	Value
sans	--lufa-primitive-typography-font-family-sans	System font stack
mono	--lufa-primitive-typography-font-family-mono	Monospace font stack

System Font Stack

The design system uses native system fonts for optimal performance and familiarity:

--lufa-primitive-typography-font-family-sans:
  -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;

--lufa-primitive-typography-font-family-mono: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, monospace;

Font Sizes

Semantic font size tokens based on usage:

Token	CSS Variable	Size (Desktop)	Fluid Range	Usage
xs	--lufa-primitive-typography-font-size-xs	12px	Static	Captions, labels
sm	--lufa-primitive-typography-font-size-sm	14px	Static	Small body text
base	--lufa-primitive-typography-font-size-body	16px	Static	Default body text
lg	--lufa-primitive-typography-font-size-lg	18px	Static	Large body text
xl	--lufa-primitive-typography-font-size-xl	20px	Static	Small headings
2xl	--lufa-primitive-typography-font-size-2xl	24px	20px → 24px	Medium headings
3xl	--lufa-primitive-typography-font-size-3xl	30px	24px → 30px	Large headings
4xl	--lufa-primitive-typography-font-size-4xl	36px	28px → 36px	XL headings
5xl	--lufa-primitive-typography-font-size-5xl	48px	32px → 48px	Hero headings
6xl	--lufa-primitive-typography-font-size-6xl	60px	40px → 60px	Hero headlines, featured
7xl	--lufa-primitive-typography-font-size-7xl	72px	48px → 72px	Marketing hero, landing
8xl	--lufa-primitive-typography-font-size-8xl	96px	64px → 96px	Display text, brand impact ⚠️

Fluid Typography

Heading sizes (2xl-8xl) use CSS clamp() for responsive scaling between mobile and desktop viewports. Body text sizes (xs-xl) remain static for optimal readability.

Note about 8xl: The largest size (8xl) has special behavior - it remains at 64px on viewports below 400px, then scales fluidly to 96px on larger screens. This is intentional, as display typography is designed for larger screens and marketing contexts.

Font Weights

Semantic font weight tokens:

Token	CSS Variable	Value	Usage
regular	--lufa-primitive-typography-font-weight-regular	400	Body text
medium	--lufa-primitive-typography-font-weight-medium	500	Emphasized text
semibold	--lufa-primitive-typography-font-weight-semibold	600	Headings, labels
bold	--lufa-primitive-typography-font-weight-bold	700	Strong emphasis

Line Heights

Line height tokens for different text contexts:

Token	CSS Variable	Value	Usage
tight	--lufa-primitive-typography-line-height-tight	1.25	Headings
base	--lufa-primitive-typography-line-height-base	1.5	Body text
relaxed	--lufa-primitive-typography-line-height-relaxed	1.75	Long-form content

Letter Spacing

Letter-spacing tokens for fine-tuning typography:

Token	CSS Variable	Value	Usage
tighter	--lufa-primitive-typography-letter-spacing-tighter	-0.04em	Display text, extra large headings
tight	--lufa-primitive-typography-letter-spacing-tight	-0.02em	Large headings (H1-H3)
normal	--lufa-primitive-typography-letter-spacing-normal	0	Body text (default)
wide	--lufa-primitive-typography-letter-spacing-wide	0.05em	Small text, uppercase labels
wider	--lufa-primitive-typography-letter-spacing-wider	0.1em	All-caps headings, button text

Usage

Letter-spacing is not automatically applied by components. Use it explicitly via CSS when needed:

.hero-title {
  font-size: var(--lufa-primitive-typography-font-size-5xl);
  letter-spacing: var(--lufa-primitive-typography-letter-spacing-tight);
}

.uppercase-label {
  font-size: var(--lufa-primitive-typography-font-size-sm);
  letter-spacing: var(--lufa-primitive-typography-letter-spacing-wide);
  text-transform: uppercase;
}

Usage in Components

CSS Modules

.heading {
  font-family: var(--lufa-primitive-typography-font-family-sans);
  font-size: var(--lufa-primitive-typography-font-size-2xl);
  font-weight: var(--lufa-primitive-typography-font-weight-semibold);
  line-height: var(--lufa-primitive-typography-line-height-tight);
}

.body {
  font-family: var(--lufa-primitive-typography-font-family-sans);
  font-size: var(--lufa-primitive-typography-font-size-body);
  font-weight: var(--lufa-primitive-typography-font-weight-regular);
  line-height: var(--lufa-primitive-typography-line-height-base);
}

TypeScript/JavaScript

import tokens from '@grasdouble/lufa_design-system-tokens';

const styles = {
  fontSize: tokens.fontSize.body,
  fontWeight: tokens.fontWeight.regular,
  lineHeight: tokens.lineHeight.base,
};

Text Component Variants

The Text component provides pre-configured typography variants:

import { Text } from '@grasdouble/lufa_design-system';

// Headings
<Text variant="heading-8xl">Display Heading</Text>
<Text variant="heading-7xl">Marketing Hero</Text>
<Text variant="heading-6xl">Hero Headline</Text>
<Text variant="heading-5xl">Hero Heading</Text>
<Text variant="heading-4xl">XL Heading</Text>
<Text variant="heading-3xl">Large Heading</Text>
<Text variant="heading-2xl">Medium Heading</Text>
<Text variant="heading-xl">Small Heading</Text>

// Body text
<Text variant="body-lg">Large body text</Text>
<Text variant="body">Default body text</Text>
<Text variant="body-sm">Small body text</Text>

// Specialized
<Text variant="caption">Caption text</Text>
<Text variant="code">Monospace code</Text>
<Text variant="label">Form label</Text>

Accessibility

Typography tokens ensure readability and accessibility:

• Minimum size: 16px for body text (WCAG AAA for low vision)
• Line height: 1.5 for body text (WCAG Success Criterion 1.4.8)
• Color contrast: Minimum 4.5:1 for body text
• Responsive: Font sizes scale appropriately

Responsive Typography

Typography tokens adapt automatically across screen sizes using CSS clamp() for headings:

/* Heading tokens scale fluidly (2xl-8xl) */
.hero-heading {
  /* Automatically scales from 32px (mobile) to 48px (desktop) */
  font-size: var(--lufa-primitive-typography-font-size-5xl);
}

.marketing-hero {
  /* Automatically scales from 48px (mobile) to 72px (desktop) */
  font-size: var(--lufa-primitive-typography-font-size-7xl);
}

.display-title {
  /* Automatically scales from 64px (mobile) to 96px (desktop) */
  /* Note: Fluid scaling engages at 400px+ viewport */
  font-size: var(--lufa-primitive-typography-font-size-8xl);
}

.section-heading {
  /* Automatically scales from 24px (mobile) to 30px (desktop) */
  font-size: var(--lufa-primitive-typography-font-size-3xl);
}

/* Body text remains static for readability */
.body-text {
  font-size: var(--lufa-primitive-typography-font-size-body); /* Always 16px */
}

How Fluid Typography Works

The design system uses CSS clamp() for headings (2xl-8xl):

/* Example: 5xl token */
--lufa-primitive-typography-font-size-5xl: clamp(2rem, 1.5rem + 2vw, 3rem);
/*                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
/*                           min    preferred     max
/*                           32px   viewport-based 48px

/* Example: 8xl token (largest display size) */
--lufa-primitive-typography-font-size-8xl: clamp(4rem, 3rem + 4vw, 6rem);
/*                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
/*                           min    preferred     max
/*                           64px   viewport-based 96px

This provides smooth, automatic scaling without media queries. Body text (xs-xl) stays static at optimal reading sizes.

Extended Scale (6xl-8xl): The largest tokens (6xl, 7xl, 8xl) are designed for marketing hero sections, landing pages, and display typography. The 8xl token has special behavior where fluid scaling only engages at viewports 400px and above - this is intentional, as display typography is primarily for larger screens.

Best Practices

Extended Type Scale (6xl-8xl)

The extended scale tokens are designed for specific use cases:

6xl (60px): Hero headlines, featured content sections

.hero-headline {
  font-size: var(--lufa-primitive-typography-font-size-6xl);
  letter-spacing: var(--lufa-primitive-typography-letter-spacing-tight);
}

7xl (72px): Marketing hero sections, landing page titles

.marketing-hero {
  font-size: var(--lufa-primitive-typography-font-size-7xl);
  letter-spacing: var(--lufa-primitive-typography-letter-spacing-tighter);
  line-height: var(--lufa-primitive-typography-line-height-tight);
}

8xl (96px): Display text, brand impact moments, large metric displays

.display-title {
  font-size: var(--lufa-primitive-typography-font-size-8xl);
  letter-spacing: var(--lufa-primitive-typography-letter-spacing-tighter);
  line-height: 1.1;
}

/* Tip: Pair large display text with tighter letter-spacing */

Extended Scale Usage

The 6xl-8xl tokens are best suited for:

• Marketing and landing pages
• Hero sections with large imagery
• Brand-heavy campaigns
• KPI dashboards with prominent numbers
• Announcement banners

For standard UI and content pages, 2xl-5xl headings are usually sufficient.

8xl Special Behavior

The 8xl token (96px maximum) has intentional behavior where fluid scaling only engages at viewports 400px and above. On smaller mobile devices (320px-400px), it remains at 64px. This prevents excessive text size on small screens where display typography is less common.

General Typography Best Practices

Do ✅

• Use semantic tokens (e.g., font-size-body) for consistency
• Pair font sizes with appropriate line heights
• Use system fonts for better performance
• Test readability at different sizes
• Use extended scale (6xl-8xl) for marketing and hero sections
• Pair large display text with tighter letter-spacing for better aesthetics

Don't ❌

• Hardcode font values (e.g., font-size: 16px)
• Use decorative fonts for body text
• Set line-height below 1.25 for readability
• Ignore contrast requirements
• Use 8xl on small mobile screens (it's designed for larger viewports)
• Overuse extended scale tokens for standard UI content

Next Steps

• Text Component - Typography component with variants
• Color Tokens - Color palette and usage
• Spacing Tokens - Layout spacing system

Updated Documentation

The extended type scale (6xl-8xl) supports marketing, hero, and display typography. See the Typography story source for interactive examples and responsive behavior.