Components

Typography

Government websites need clear and consistent headings, highly legible body paragraphs, clear labels, and easy-to-use input fields. Our default typefaces are designed for legibility and can adapt to a variety of visual tones.

Typesetting with USWDS

Typesetting controls the readability of a text with the size, style, and spacing of its type. It’s a function of microtypography (how text is styled within a text block) and macrotypography (how content elements are arranged on the page). The more readable a text the more easily users can understand its content. Text with poor readability turns off readers and can make it challenging for them to stay focused.

In USWDS we control typesetting values with a token system. You can read more about typesetting tokens in the Typesetting tokens section and in the Utilities section.

Accessibility for Teams also provides good guidance around typesetting.

Font size

  • Use a comfortable reading size for body text. For most text, including body copy, use at least an effective size of 16px (font-size 5). Smaller and larger text can be used sparingly for special purposes (like headings, captions, photo credits, footnotes, data tables, or specialized UI).
  • Font size tokens:
    • Use tokens between font-size 5 and font-size 8 for most running text.
    • Tokens smaller than font-size 5 should be used more sparingly — for shorter companion text like captions, footnotes, photo credits, or specialized UI.

Text alignment

While right-aligned, centered, and justified text have their place, most websites benefit from a consistent use of left-aligned text. Justified text, common in print, does not yet display well enough in a web browser to be considered a best practice.

  • Set type flush left. Type set flush left provides the eye a constant starting point for each line, making text easier to read.
  • Alignment tokens: none

Measure (line length)

Controlling the length of lines of text (also known as measure) helps readers’ attention flow easily from one line to the next, making reading more natural and comfortable.

  • Most lines of text should be 45-90 characters. Somewhere between 45 (measure 1) and 90 characters per line (measure 5) is broadly considered to be a readable line length, with 66 characters (measure 2) considered a comfortable target for long texts.
  • Text with greater line height can have a longer measure. Since of the functions of measure is to help readers move from one line of text to another more naturally, the effects of a long measure can be lessened by increasing the space between lines. Thus, text with more space between lines can have somewhat longer line length.
  • Short passages can have measure outside the ideal range. Contexts in which users will not be reading long passages of text (such as footnotes or alerts) can safely be set with somewhat longer or shorter lines than usual.
  • Large text can have a shorter measure. Since larger text takes up more screen real estate, it can make sense to assign it a relatively small measure.
  • Measure tokens:
    • Use tokens between measure 2 and measure 5 for most long running text
    • The measure 6 token can be appropriate for shorter blocks of text, like captions of fewer than three lines — or for text that isn’t meant for longform reading
    • The measure 1 token can be appropriate for helper text (no longer than a paragraph or two) or for larger text (like a subheading or intro text).

Line height

Line height controls the vertical rhythm and density of a block of text. It is written as a unitless multiplier of the text’s font size — for instance, a line height of 1.5 on 16px text results in a line height of 24px.

  • Longer texts require more line height. Headings and other content elements no longer than a line or two can have a line height between 1 (line-height 1) and 1.35 (line-height 3). Longer texts should have a line height of at least 1.5 (line-height 4).
  • Longer lines usually require more line height. It can be difficult to distinguish between lines of text when the eye has to travel from the end of one long line to the beginning of the next. Using more line height makes it easier to distinguish individual lines. Though, somewhat counterintuitively, very long lines of text can benefit from slightly less line height than usual, as too much line height can make each individual line appear too prominent.
  • Readable text has a medium density. Strive for text that appears neither very dense or very loose. The reader typically shouldn’t notice the space between lines of text.
  • Line height tokens:
    • line-height 1: most buttons and other short UI elements. (This improves vertical alignment.)
    • line-height 2: most headings and introductory text no longer than 1-2 sentences.
    • line-height 3: short text (under a paragraph), captions, and very long lines.
    • line-height 4: when your chunks of running text are a paragraph or two long, especially when using a short measure (like measure 1 or measure 2
    • line-height 5: most reading text, especially text meant for extended reading.
    • line-height 6: shorter text (around 1-2 paragraphs) meant to be distinguished from other page text, like pullquotes.

Whitespace

The space around your content elements affects the relationship between these elements. Use less whitespace to group elements and more whitespace to distinguish them from each other.

  • Don’t indent paragraphs, use whitespace before. While most longform print design uses indented lines to distinguish paragraphs, it’s more conventional on the web to use unindented paragraphs separated by whitespace.
  • Use at least 1em of whitespace between paragraphs. To properly separate paragraphs from one other, use the equivalent of one blank line of whitespace between them. Using more than 1.5em disturbs the flow of the text and using less than 0.5em doesn’t provide enough separation.
  • Use at least 0.5em of whitespace between list items. List items should also be separated by whitespace, but they need less space than paragraphs because the list item indicator also helps distinguish adjacent items.
  • Headings should be closer to the text they introduce than the text that preceeds them. It’s important that headings are more visually connected to the text for which they’re the heading than the text of the previous section to reduce ambiguity and cognitive dissonance. Use at least 1.5 times the amount of whitespace above the heading as below it.
  • Text should have sufficient margin on the left and right. Running text requires right and left margin proportional to the width of the viewport. Use at least 1 unit of margin between the text and the edge of the viewport at mobile widths and at least 2 units on a tablet. Desktop widths can require as much as 4-5 units of minimum horizontal margin between the body of the text and any adjacent elements.

Font style

The style of a typeface affects its readability. In general, serif typefaces are more appropriate for long blocks of text and sans serif typefaces are more appropriate for user interfaces — but this is not a hard-and-fast rule. The conventions of the web are more forgiving of longer, sans serifed texts and serif UIs are not out of the question for sites of a certain tone.

  • Serif faces can be a good choice for long texts. Serif typefaces tend to be designed for readability. While they are most useful for true extended longform reading like novels, nonfiction, and essays, any site that requires long stretches of continuous reading could benefit from using a serif body typeface.
  • Neutral faces can be a good choice for interfaces. User interfaces are the practical expression of a site’s organization and functionality. A straightforward and neutral typeface can help the user focus on using the interface as a tool.
  • Avoid long sections of italic or bold text. Both italic and bold text can degrade readability. Both are best used for limited sections of contrast. Consider replacing long sections of bold or italic text with a callout box, a section header, or some other technique that avoids extended stretches of styled text.
  • Avoid long sections of uppercase text. Uppercase text has a serious negative effect on readability. Unless mandated by law, consider other type treatments for any uppercase text longer than just a few words.

Letterspacing

Letterspacing is the spacing between individual letterforms in a block of text. Typically, this is defined by the type designer and shouldn’t be modified. However, certain specific situations can call for letterspacing adjustments.

Included typefaces

Source Sans Pro

Source Sans Pro, designed by Paul D. Hunt, is an open-source sans serif typeface created for legibility in UI design. With a variety of weights that read easily at all sizes, Source Sans Pro provides clear headers as well as highly-readable body text.

Inspired by twentieth-century American gothic typeface design, its slender but open letters offer a clean and friendly simplicity. Advanced hinting allows Source Sans Pro to render well on Windows systems which run Cleartype, and across browsers and devices. Moreover, it supports a variety of languages and alphabets, including Western and European language, Vietnamese, pinyin Romanization of Chinese, and Navajo.

Aa

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z

0 1 2 3 4 5 6 7 8 9

Merriweather

Merriweather, designed by Sorkin Type, is an open-source serif typeface designed for on-screen reading. This font is ideal for text-dense design: the letterforms have a tall x-height but remain relatively small, making for excellent readability across screen sizes while not occupying extra horizontal space.

The combination of thin and thick weights gives the typeface stylistic range while conveying a desirable mix of classic, yet modern, simplicity. Merriweather communicates warmth and credibility at both large and small font sizes.

Aa

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z

0 1 2 3 4 5 6 7 8 9

Public Sans

Public Sans is an open-source sans serif typeface designed and maintained by USWDS and derived from Libre Franklin. It is a strong, neutral, principles-driven typeface for text or display based on a traditional American form. (The Franklin form is most noticeable in the two-story design of the “g” character.) It uses metrics similar to common system fonts for smoother progressive enhancement. It has a plain, straightforward style, appropriate for interfaces and running text. Its large x-height makes it legible at small sizes. It features a broad range of weights — and its heavier weights have tighter letterspacing than its lighter weights, meaning running text (which tends to be relatively small) is spaced more generously and headings (which tend to be relatively large) are more compact. It has tabular numerals for aligning numbers in tables.

Aa

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z

0 1 2 3 4 5 6 7 8 9

Roboto Mono

Roboto Mono, designed by Christian Robinson, is a monospaced addition to the Roboto type family. Like the other members of the Roboto family, the fonts are optimized for readability on screens across a wide variety of devices and reading environments.

Special consideration is given to glyphs important for reading and writing code. Letters with similar shapes are easy to tell apart.

Aa

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z

0 1 2 3 4 5 6 7 8 9

Prose

Format a block of running text.

Line length

75 characters (68ex) max-width: Yosemite National Park is set within California’s Sierra Nevada mountains. It’s famed for its giant, ancient sequoias, and for Tunnel View, the iconic vista of towering Bridalveil Fall and the granite cliffs of El Capitan and Half Dome.

Spacing

Page heading

Great Smoky Mountains National Park straddles the border of North Carolina and Tennessee.

Section heading

Section of the page

The sprawling landscape encompasses lush forests and an abundance of wildflowers that bloom year-round. Streams, rivers and waterfalls appear along hiking routes that include a segment of the Appalachian Trail.

Subsection of the page

World renowned for its diversity of plant and animal life, the beauty of its ancient mountains, and the quality of its remnants of Southern Appalachian mountain culture, this is America's most visited national park.

Right now scientists think that we only know about 17 percent of the plants and animals that live in the park, or about 17,000 species of a probable 100,000 different organisms.

Subsection of the page

Entrance to Great Smoky Mountains National Park is free. The park is one of the few national parks where no entrance fees are charged.

  • Unordered list item
  • Unordered list item
  • Unordered list item

Right now scientists think that we only know about 17 percent of the plants and animals that live in the park, or about 17,000 species of a probable 100,000 different organisms.

  1. Ordered list item
  2. Ordered list item
  3. Ordered list item
Bordered table
Document title Description Year
Declaration of Independence Statement adopted by the Continental Congress declaring independence from the British Empire. 1776
Bill of Rights The first ten amendments of the U.S. Constitution guaranteeing rights and freedoms. 1791
Declaration of Sentiments A document written during the Seneca Falls Convention outlining the rights that American women should be entitled to as citizens. 1848
Emancipation Proclamation An executive order granting freedom to slaves in designated southern states. 1863
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
<div class="usa-prose">
  <div class="usa-line-length-example usa-prose">
    <h6 class="usa-heading-alt">Line length</h6>
    <section class="typography-example usa-prose margin-top-1">
      <p><strong>75 characters (68ex) max-width:</strong> Yosemite National Park is set within California’s Sierra Nevada mountains. It’s famed for its giant, ancient sequoias, and for Tunnel View, the iconic vista of towering Bridalveil Fall and the granite cliffs of El Capitan and Half Dome.</p>
    </section>
  </div>

  <h6 class="usa-heading-alt">Spacing</h6>
  <section class="example-spacing usa-prose margin-top-1 font-sans-sm measure-3 bg-primary-lighter">
    <h1>Page heading</h1>
    <p class="usa-intro">Great Smoky Mountains National Park straddles the border of North Carolina and Tennessee.</p>

    <h2>Section heading</h2>

    <h3>Section of the page</h3>
    <p>The sprawling landscape encompasses lush forests and an abundance of wildflowers that bloom year-round. Streams, rivers and waterfalls appear along hiking routes that include a segment of the Appalachian Trail.</p>

    <h4>Subsection of the page</h4>
    <p>World renowned for its diversity of plant and animal life, the beauty of its ancient mountains, and the quality of its remnants of Southern Appalachian mountain culture, this is America's most visited national park.</p>
    <p>Right now scientists think that we only know about 17 percent of the plants and animals that live in the park, or about 17,000 species of a probable 100,000 different organisms.</p>

    <h5>Subsection of the page</h5>
    <p>Entrance to Great Smoky Mountains National Park is free. The park is one of the few national parks where no entrance fees are charged.</p>

    <ul>
      <li>Unordered list item</li>
      <li>Unordered list item</li>
      <li>Unordered list item</li>
    </ul>

    <p>Right now scientists think that we only know about 17 percent of the plants and animals that live in the park, or about 17,000 species of a probable 100,000 different organisms.</p>

    <ol>
      <li>Ordered list item</li>
      <li>Ordered list item</li>
      <li>Ordered list item</li>
    </ol>

    <table>
      <caption>Bordered table</caption>
      <thead>
        <tr>
          <th scope="col">Document title</th>
          <th scope="col">Description</th>
          <th scope="col">Year</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th scope="row">Declaration of Independence</th>
          <td>Statement adopted by the Continental Congress declaring independence from the British Empire.</td>
          <td>1776</td>
        </tr>
        <tr>
          <th scope="row">Bill of Rights</th>
          <td>The first ten amendments of the U.S. Constitution guaranteeing rights and freedoms.</td>
          <td>1791</td>
        </tr>
        <tr>
          <th scope="row">Declaration of Sentiments</th>
          <td>A document written during the Seneca Falls Convention outlining the rights that American women should be entitled to as citizens.</td>
          <td>1848</td>
        </tr>
        <tr>
          <th scope="row">Emancipation Proclamation</th>
          <td>An executive order granting freedom to slaves in designated southern states.</td>
          <td>1863</td>
        </tr>
      </tbody>
    </table>
  </section>
</div>

<style scoped>
  .example-spacing * {
    background-color: white;
  }
</style>

Implementation

  • usa-prose is meant for blocks of text where it’s more difficult to add custom classes to individual elements, like a blog post where the content is coming out of markdown or a CMS.
  • Adding usa-prose to any container adds USWDS default heading and body text styling to the following direct-child elements:
    • h1-h6
    • p
    • ul and ol, plus child li
    • table, plus child thead, th, td, and caption
  • You can change the measure of elements styled with usa-prose in _uswds-theme-typography.scss with the following variables. Each accepts a measure token:
    • $theme-text-measure
    • $theme-lead-measure

Lists

Lists organize information into discrete sequential sections.

Unordered list
  • Unordered list item
  • Unordered list item
  • Unordered list item
Ordered list
  1. Ordered list item
  2. Ordered list item
  3. Ordered list item
Unstyled list
  • Unstyled list item
  • Unstyled list item
  • Unstyled list item
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<div class="grid-row grid-gap">
    <div class="mobile-lg:grid-col-4">
      <h6 class="margin-0">Unordered list</h6>
      <ul class="usa-list">
        <li>Unordered list item</li>
        <li>Unordered list item</li>
        <li>Unordered list item</li>
      </ul>
    </div>

    <div class="mobile-lg:grid-col-4 margin-top-4 mobile-lg:margin-top-0">
      <h6 class="margin-0">Ordered list</h6>
      <ol class="usa-list">
        <li>Ordered list item</li>
        <li>Ordered list item</li>
        <li>Ordered list item</li>
      </ol>
    </div>

    <div class="mobile-lg:grid-col-4 margin-top-4 mobile-lg:margin-top-0">
      <h6 class="margin-0">Unstyled list</h6>
      <ul class="usa-list usa-list--unstyled">
        <li>Unstyled list item</li>
        <li>Unstyled list item</li>
        <li>Unstyled list item</li>
      </ul>
    </div>
  </div>

When to use the list component

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

When to consider something different

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

Usability guidelines

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

Implementation

  • For unstyled lists, use either the .usa-list.usa-list--unstyled classes or the unstyled list mixin: @include unstyled-list;.