Typography

Fonts

Font sizing

Font sizes must use relative units (rem or em), not pixels. While pixels scale with page zoom, they don’t respond to user-set default font sizes in browser settings. Relative units respect these preferences, which is required for WCAG 2.2 AA SC 1.4.4 Resize Text.

When to use rem

Use rem for most font sizes. Rem units are relative to the root element’s font size, so they provide consistent sizing across the page regardless of nesting. This is the right choice for headings, body text, and any text that should maintain a predictable size.

When to use em

Use em for font sizes that should scale relative to their parent element. This can be useful for components that need to scale proportionally where all text should grow or shrink together based on a single parent size setting. We currently prefer rem to em in the codebase.

Spacing and font sizing

For spacing-related values (margins, padding, gaps), use the spacing unit tokens rather than hardcoded values. When custom spacing values are needed, use rem to maintain accessible scaling.

Headings

<h1>Headline H1</h1>
<h2>Headline H2</h2>
<h3>Headline H3</h3>
<h4>Headline H4</h4>
<h5>Headline H5</h5>
<h6>Headline H6</h6>

Headings and accessibility

Always use semantic headings, logically nested in the proper order. Do not use improper nesting to achieve a different font size. In other words, an h1 should never be followed by an h3; it should only be followed by an h2. Use the font-size utility to change the font size of a semantic heading instead.

<h1>Main heading</h1>

<p>Some text</p>

<h2 class="vads-u-font-size--h3">Secondary heading</h2>

<h1>Main heading</h1>

<p>Some text</p>

<h3>Secondary heading</h3>

Avoid turning headers into links in most contexts

Why avoid headers as links?

• Cognitive load and user expectations. Headings serve as structural elements that help users with assistive technologies understand page organization. When a heading is also a link, it creates dual functionality that can confuse users. Screen reader users may not expect headings to be actionable.
• Challenging keyboard navigation. Keyboard users tab through links as a primary navigation method. Headers that are links can be accidentally activated during normal page exploration.
• Confusing screen reader announcements. Screen readers announce headings and links differently. Combining them results in unclear announcements like “Heading level 2, link, Text,” making it harder to understand the element’s purpose.
• Unnecessary redundancy. The linked text in a heading is often repeated elsewhere on the page, creating distracting duplication.

When it’s appropriate to use links in headers

An exception can be made in the Card component, where:

• Space is limited, and combining the heading and link reduces visual clutter
• The card functions as a single actionable unit (such as linking to a detail page)
• The design makes the linked heading the primary call-to-action in the card, minimizing confusion

When it’s not appropriate

• In normal page content where headings primarily serve as organizational aids
• When multiple links are associated with the heading, making the primary action unclear
• When the link in the heading duplicates another visible link that immediately follows it

Monospace fonts

Use monospace fonts sparingly. Monospace fonts can be difficult to read, especially at small sizes or with poor color contrast. Use monospace fonts for numerical data in tables, code examples, or when precise horizontal alignment is needed. For body text, choose a sans serif typeface.

Eyebrow

<h1>
  <span class="vads-c-eyebrow">Eyebrow Title</span>
  Headline H1
</h1>

Card with Eyebrow

<va-card>
  <h3>
    <span class="vads-c-eyebrow">Disability Benefits</span>
    Compensation Claim
  </h3>
  <p>Your claim for compensation benefits has been received and is being processed.</p>
  <p><a href="#" class="vads-c-action-link--blue">Review your claim</a></p>
</va-card>

The eyebrow sits above a heading and provides a label for a sequence of pages in a process or for groups of related content, such as multiple cards. The eyebrow component renders its text in uppercase through styling. Authors should still always enter label text in sentence case, not in ALL CAPS. Refer to Capitalization for guidance on when we permit all caps.

When to use

• Use the eyebrow when you implement the Help users to complete a sub task pattern.
• Use the eyebrow to indicate content type or category across related cards or pages.
• Use the eyebrow to provide high-level context that helps users compare or scan multiple cards.

When to use something else

• Use Tag - Status above the header to indicate status.

Note: This component has been tested indirectly with success.

Paragraphs

<!-- Intro text -->
<p class="va-introtext">VA Intro Text has the class 'va-introtext'. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean venenatis laoreet augue scelerisque sollicitudin.</p>

<!-- Regular paragraph -->
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean venenatis laoreet augue scelerisque sollicitudin.</p>

• Paragraphs should not exceed vads-size-line-length-5 (72ex) and should use our line-length design tokens when appropriate to further constrain their width. Some elements that are not yet using our line-length design tokens will use 77ch as their max-width which is also acceptable.

Typography tokens

Primitive typography tokens

Related

• List