Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

Download Code View on GitHub

Typography

Notice:

Typography sizing updates!

We've updated typography sizing variables and class names to make them more agnostic. Read about how you can update.

Headings

The design system doesn't style base HTML typography elements (like h1, h2, p, etc) in order to avoid conflicting with any existing site styles. You should instead use one of the base typography classes below to apply styling:

.ds-text-heading--5xl

We the People of the United States

.ds-text-heading--4xl

We the People of the United States

.ds-text-heading--3xl

We the People of the United States

.ds-text-heading--2xl

We the People of the United States

.ds-text-heading--xl

We the People of the United States

.ds-text-heading--lg

We the People of the United States

.ds-text-heading--md

We the People of the United States

.ds-text-heading--sm

We the People of the United States

Code snippet
<section class="example-list">
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--5xl
    </code>
    <h1 class="ds-text-heading--5xl ds-display">
      We the People of the United States
    </h1>
  </article>
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--4xl
    </code>
    <h1 class="ds-text-heading--4xl ds-title">
      We the People of the United States
    </h1>
  </article>
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--3xl
    </code>
    <h1 class="ds-text-heading--3xl ds-h1">
      We the People of the United States
    </h1>
  </article>
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--2xl
    </code>
    <h1 class="ds-text-heading--2xl ds-h2">
      We the People of the United States
    </h1>
  </article>
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--xl
    </code>
    <h1 class="ds-text-heading--xl ds-h3">
      We the People of the United States
    </h1>
  </article>
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--lg
    </code>
    <h1 class="ds-text-heading--lg ds-h4">
      We the People of the United States
    </h1>
  </article>
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--md
    </code>
    <h1 class="ds-text-heading--md ds-h5">
      We the People of the United States
    </h1>
  </article>
  <article>
    <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
      .ds-text-heading--sm
    </code>
    <h1 class="ds-text-heading--sm ds-h6">
      We the People of the United States
    </h1>
  </article>
</section>

Body

.ds-text-body--lg

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

Code snippet
<p class="ds-text-body--lg">
  We the People of the United States, in Order to form a more perfect Union,
  establish Justice, insure domestic Tranquility, provide for the common
  defence, promote the general Welfare, and secure the Blessings of Liberty to
  ourselves and our Posterity, do ordain and establish this Constitution for the
  United States of America.
</p>

.ds-text-body--md

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

Code snippet
<p class="ds-text-body--md">
  We the People of the United States, in Order to form a more perfect Union,
  establish Justice, insure domestic Tranquility, provide for the common
  defence, promote the general Welfare, and secure the Blessings of Liberty to
  ourselves and our Posterity, do ordain and establish this Constitution for the
  United States of America.
</p>

.ds-text-body--sm

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

Code snippet
<p class="ds-text-body--sm">
  We the People of the United States, in Order to form a more perfect Union,
  establish Justice, insure domestic Tranquility, provide for the common
  defence, promote the general Welfare, and secure the Blessings of Liberty to
  ourselves and our Posterity, do ordain and establish this Constitution for the
  United States of America.
</p>

List

Lists organize written information for users.

When to use

  • Use an ordered list when you need to display text in some ranking, hierarchy, or series of steps.
  • Use unordered lists to display text in no specific order.

When to consider alternatives

  • If you need to communicate long lists of narrative text.

Usage

  • Use sentence case and begin lists with a capital letter.
  • Use punctuation appropriate to the text. Do not leave sentences without periods.

Accessibility

  • When a list has a heading, consider adding an id attribute to the heading element, and an aria-labelledby attribute to the list element. Screen readers will then announce the heading text when users navigate to the list.

Learn more

Unordered list

.ds-c-list
  • List item 1
  • List item 2
Code snippet
<article>
  <h2 class="ds-h6" id="unordered-list-id">Unordered list</h2>
  <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">.ds-c-list</code>
  <ul class="ds-c-list" aria-labelledby="unordered-list-id">
    <li>List item 1</li>
    <li>List item 2</li>
  </ul>
</article>

Ordered list

.ds-c-list
  1. List item 1
  2. List item 2
Code snippet
<article>
  <h2 class="ds-h6" id="ordered-list-id">Ordered list</h2>
  <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">.ds-c-list</code>
  <ol class="ds-c-list" aria-labelledby="ordered-list-id">
    <li>List item 1</li>
    <li>List item 2</li>
  </ol>
</article>

Unstyled list

.ds-c-list .ds-c-list--bare
  • List item 1
  • List item 2
Code snippet
<article>
  <h2 class="ds-h6" id="unstyled-list-id">Unstyled list</h2>
  <code class="ds-u-margin-y--0 ds-u-margin-bottom--1">
    .ds-c-list .ds-c-list--bare
  </code>
  <ul class="ds-c-list ds-c-list--bare" aria-labelledby="unstyled-list-id">
    <li>List item 1</li>
    <li>List item 2</li>
  </ul>
</article>

Links connect users to a different page or further information.

The only base HTML element the design system applies styling to is the <a> element. You can also use .ds-c-link and .ds-c-link--inverse for styling links.

When to use

  • Navigating to a new page or view in your application
  • Navigating to a different web page, e.g. external documentation
  • Note: Warn the user if links open a new window or downloads a file (PDF, for example).

When to consider alternatives

  • Opening or closing a modal or dialog
  • Triggering a dropdown menu
  • Submitting data to the server

Your link should always describe where it will take users. Users tend to scan text online, and elements that stand out (like links) grab attention. Clear links can help users navigate more quickly.

For example, instead of:

Learn more

Use:

Learn how to reset your passphrase

Never use a link to say “click here.” A nondescript link forces users to backtrack and read the surrounding text for more context. This is even more problematic for those who rely on screen readers, which can list links for quicker navigation. A list of “click here” isn’t helpful for anyone.

Accessibility

  • Users should be able to tab to navigate between links.
  • Users should be able to activate a link when pressing ‘Enter’ on their keyboard.
  • Users should be able to identify links without relying on color alone.
  • Users should be able to activate hover and focus states with both a mouse and a keyboard.

This is a text link on a light background.

This is a visited link.

This is a text link on a dark background.

This is a visited link on a dark background.

Code snippet
<p>
  <a href="javascript:void(0);">This is a text link</a>
  on a light background.
</p>
<p>
  <a href="/styles/typography/">This is a visited link</a>
  .
</p>
<div class="ds-base ds-base--inverse ds-u-padding--1">
  <p>
    <a href="javascript:void(0);">This is a text link</a>
    on a dark background.
  </p>
  <p>
    <a href="/styles/typography/">This is a visited link</a>
    on a dark background.
  </p>
</div>

Responsive typography

The .ds-type-heading-3xl, ds-type-heading-2xl, and ds-type-heading-xl classes are responsive by default. To apply responsive typography elsewhere, use the font size utility class. Since the base typography margins and line height is measured in em units, they'll automatically adjust as you change the font size.

Code snippet

Customization

The following Sass variables can be overridden to change the type sizes:

  • $font-size-5xl
  • $font-size-4xl
  • $font-size-3xl
  • $font-size-2xl
  • $font-size-xl
  • $font-size-lg
  • $font-size-md, uses $base-font-size
  • $font-size-sm