Example Agency

Alert

Mon, 01 Jan 0001 00:00:00 +0000

Usage

{{< alert type="warning" title="Check your version" >}}
Body copy, written as **markdown**.
{{< /alert >}}

Check your version

Body copy, written as markdown.

Parameters

Parameter	Values	Default
`type`	info, warning, error, success, emergency	info
`title`	any text	none
`slim`	true	false
`no_icon`	true	false

When to use which

Reach for slim only when the message is one short line — the variant has no heading slot and halves the padding, so a wrapped paragraph looks unbalanced in it.

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

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.

Our mission

Mon, 01 Jan 0001 00:00:00 +0000

Use the side navigation to skip between sections of a page.

Side navigation

Mon, 01 Jan 0001 00:00:00 +0000

Where it comes from

Nothing declares this menu. It is the content directory: every page under the top-level section, ordered by weight, nested exactly as the directories are. Add a folder with an _index.md and it appears.

The nav is rooted at the top of the tree rather than at the page’s parent. Rooted at the parent, this page would list only its two siblings, and the rest of the documentation would disappear the moment you opened a subsection.

Accordion

Mon, 01 Jan 0001 00:00:00 +0000

An accordion is two shortcodes: a wrapper that carries the group’s options, and one item per panel.

{{< accordion bordered="true" multiselectable="true" heading_level="h3" >}}
{{< accordion-item title="First question" expanded="true" >}}
Body copy.
{{< /accordion-item >}}
{{< /accordion >}}

It draws a border around each panel. Use it when the accordion sits directly on the page background rather than inside a card.

Breadcrumb

Mon, 01 Jan 0001 00:00:00 +0000

The trail is built from the page’s ancestors, so it needs no configuration. The current page is a span carrying aria-current="page", never a link — a link to the page you are on is a dead end.

At the top level the breadcrumb renders nothing at all. A trail with one entry is noise.

Every trail also emits schema.org BreadcrumbList metadata, which costs nothing at render time and is what produces the trail shown under a search result. Turn it off with:

Theming

Mon, 01 Jan 0001 00:00:00 +0000

Colors and type

Set values under [params.uswds.theme]. They are passed into Sass through the hugo:vars module, so no .scss file needs to change.

Going further

If you need a setting that is not exposed, create assets/uswds/_settings.scss in your own project. Hugo’s union filesystem gives your file precedence over the theme’s, so the theme itself stays untouched and upgrades cleanly.

Blog and news

Mon, 01 Jan 0001 00:00:00 +0000

Any section of dated pages behaves as a news section — there is no separate layout to opt into. The /news/ section on this site is an ordinary content directory; everything below comes from front matter and config.

Article front matter

---
title: "Section 508 audit results published"
date: 2026-06-30
author: "Digital Services"
tags: ["Accessibility", "Performance"]
description: "Findings from the annual audit, with remediation dates."
image: "img/og-news.png"
imageAlt: "Example Agency news"
---

date, author and tags render as a byline under the title. Each is optional and the byline disappears entirely when all three are absent, which is why documentation pages — like this one — do not show one.

In-page navigation

Mon, 01 Jan 0001 00:00:00 +0000

Turning it on

It is front matter, not a shortcode:

in_page_nav: true
in_page_nav_headings: "h2"

A shortcode can only render inside main, and this component has to be a sibling of main for the two to lay out side by side. Front matter is the only place the decision can be made in time.

Choosing which headings

USWDS scans h2 and h3 by default, which sweeps up headings that belong to components — a summary box’s h3 shows up as if it were a section of the document. On a page using components, narrow it to h2.

Process list

Mon, 01 Jan 0001 00:00:00 +0000

Use a process list only when order genuinely matters. A sequence the reader can do in any order is an unordered list, and numbering it implies a dependency that is not there.

{{< process-list heading_level="h3" >}}
{{< process-step heading="Install" >}}
Body copy, including code blocks.
{{< /process-step >}}
{{< /process-list >}}

Write the step heading as an action

“Install the dependencies”, not “Dependencies”.
Keep the body to what happens in this step

Anything that applies to the whole sequence belongs above the list.

Accessibility office hours open to all agency teams

Tue, 28 Jul 2026 00:00:00 +0000

Teams working through Section 508 findings can now book a weekly drop-in session with the accessibility practice. Bring a page, a component, or an audit finding you are stuck on.

Sessions run for an hour and are recorded for teams in other time zones.

Fiscal year 2027 grant applications open

Mon, 20 Jul 2026 00:00:00 +0000

Applications for the fiscal year 2027 funding cycle are open. Eligible organizations may apply through October 31.

Applicants who received an award in a prior cycle still need to submit a complete application.

Performance dashboard refreshed for the third quarter

Tue, 14 Jul 2026 00:00:00 +0000

Third-quarter figures are now published, including two agency priority goals that were added after the mid-year review.

Definitions for every measure are published alongside the figures.

Updated plain language guidance for public notices

Wed, 08 Jul 2026 00:00:00 +0000

The revised guidance covers the notices people are most likely to act on: deadlines, eligibility, and how to appeal a decision.

Teams publishing notices should review the checklist before their next release.

New accessibility guidance published

Thu, 02 Jul 2026 00:00:00 +0000

Updated guidance on meeting Section 508 requirements across digital services.

Section 508 audit results published

Tue, 30 Jun 2026 00:00:00 +0000

The annual audit covered every public-facing service. Findings are published in full, along with the date each one is scheduled to be remediated.

Two services were re-tested after fixes landed and are now conformant.

Records request processing times improve

Mon, 22 Jun 2026 00:00:00 +0000

The median processing time for a records request fell to 18 days this quarter, down from 26 days a year ago.

The backlog of requests older than a year is now in single figures.

Agency publishes quarterly performance update

Mon, 15 Jun 2026 00:00:00 +0000

Progress updates for both cross-agency priority goals and agency priority goals.

Search

Mon, 01 Jan 0001 00:00:00 +0000

Example Agency

Alert

Usage

Check your version

Parameters

When to use which

Getting started

Section heading (h2)

Our mission

Side navigation

Where it comes from

Accordion

What does bordered change?

Breadcrumb

Theming

Colors and type

Going further

Blog and news

Article front matter

In-page navigation

Turning it on

Choosing which headings

Process list

Write the step heading as an action

Keep the body to what happens in this step

Accessibility office hours open to all agency teams

Fiscal year 2027 grant applications open

Performance dashboard refreshed for the third quarter

Updated plain language guidance for public notices

New accessibility guidance published

Section 508 audit results published

Records request processing times improve

Agency publishes quarterly performance update

Search