Getting started

The page heading communicates the main focus of the page. Make it descriptive and keep it succinct.

Section heading (h2)

These headings introduce sections and subsections within your body copy. Be succinct, descriptive, and precise.

Body copy carries the usual inline marks: bold for emphasis you would say out loud, italic for terms being introduced, inline code for anything a reader will type, strikethrough for superseded guidance, and links to the source. Keep links descriptive — “read the USWDS documentation” tells a screen reader user where they are going; “click here” does not.

Content is the reason people visit a government site. Everything else on the page is there to help them find it, read it, and act on it.

Subsection heading (h3)

Begin with the information that’s most important to your users, then present information of less importance.

Requirements

Hugo Extended ships LibSass, which cannot compile USWDS 3. The sass-embedded package provides a real Dart Sass binary; put node_modules/.bin on PATH so Hugo can find it.

Installation

1. Install the dependencies

   Run npm install to fetch @uswds/uswds and the build toolchain.

   npm install @uswds/uswds@3 sass-embedded
   

2. Declare the mounts

   Copy the [module] block from exampleSite/hugo.toml. Declaring any mount replaces every default, so all of them must be listed.

   [[module.mounts]]
     source = "node_modules/@uswds/uswds/dist"
     target = "assets/uswds-dist"
   

3. Build

   Run hugo — the first build compiles Sass and is slower; later builds are cached.

Presets

A preset decides which USWDS components get compiled. Every site pays for the components it lists and nothing else.¹

• minimal Smallest — chrome and prose only.
• standard Default — adds the content components most sites use.
• full — everything upstream ships, equivalent to stock USWDS.
• custom — your own assets/uswds/_manifest.scss.

Switching preset is one line in hugo.toml. Nothing else in the site changes:

[params.uswds]
  preset = "standard"

Preset

Which components compile. Changes the CSS you ship.

Theme settings

Colors, type and layout, under [params.uswds.theme]. Changes how those components look.

Utilities

The utility class families emitted. Trimming them is safe — npm run check reports anything a template still uses.

Writing content

Ordinary markdown is the input. Unordered lists work as you would expect, and nest one level where a point genuinely has sub-points:

• Write in the second person, and say what the reader should do.
• Front-load the sentence.
  • Put the action first.
  • Put the qualification second.
• Cut every word that survives its own deletion.

Ordered lists carry sequence, so use them only when order matters:

1. Draft the page against a real user task.
2. Read it aloud.
3. Delete a third of it.

Task lists track work that is not finished yet:

• Site chrome and content components
• Landing and documentation templates
• Form controls and advanced interaction

A fenced block with no language set stays plain, which suits output and file trees:

exampleSite/
  content/
  hugo.toml

Everything above is rendered by the theme’s own templates. Components that markdown has no syntax for are shortcodes — alert, accordion, process-list, summary-box, tag and icon are all on this page.

Frequently asked questions