uswds/uswds-elements | Repo of the Day

Work on the next version of USWDS will happen here. This is interesting as it is the exploratory repo for experimental stuff. This next version of the uswds utilizes web components, rollup, vite, and vitest. Web components are built in vanilla js and utilize lit for building the components out.

Summary

USWDS Elements is the pre-release, Web Component-based version of the U.S. Web Design System, kept separate from the current USWDS Core. It exposes components like usa-banner, usa-link, and usa-alert as standard custom elements, and only the Banner is stable enough to satisfy a federal legal mandate.

What it is useful for

This repo is for engineers maintaining U.S. federal sites who want to swap USWDS Core 3.x markup for native Web Components incrementally. The Banner specifically matters because Federal Website Standards require it under the 21st Century IDEA Act and OMB Memo M-23-22.

Outside that mandate, the repo is useful as a sandbox to evaluate Web Component theming or to contribute to a public domain component library. Each component's current state lives in a docs.mdx file under packages/elements/src/components/[usa-component-name].

Documented limits to plan around:

Only usa-banner is at Beta. usa-link and usa-alert are pre-alpha proof-of-concepts "not intended as direction, or even for release."
The README recommends adopting USWDS Core 3 instead of waiting if you are not already on it.
Supported browsers are limited to the newest versions of Chrome, Firefox, and Safari via a "2% rule" tracked from analytics.usa.gov.
Theming shifts accessibility responsibility onto the integrator; the project aims for WCAG 2.2 and Section 508, but carves out a known exception for input mask components.
The contribution review process prioritizes USWDS Open Source Community members and partners.

How engineers can use it

The README documents a Node and npm workflow:

Install Node at the version pinned in .nvmrc.
Run npm install -S @uswds/elements.

Import in a JS module:

import { UsaBanner } from "@uswds/elements";

Add the element to HTML:
```
<usa-banner></usa-banner>
```

Override appearance with CSS custom properties on the element itself:

<style>
  usa-banner {
    --usa-banner-background-color: #d9e8f6;
  }
</style>

The repo is an npm workspaces monorepo. The root is a private orchestrator that is not itself published; the publishable workspaces are packages/elements (as @uswds/elements) and packages/tokens (as @uswds/tokens), released independently through Changesets and GitHub Actions when a changeset lands on main. For deeper reference, including live theming examples, point engineers at the docs.mdx file in each component directory, and use the Cloud.gov Pages Storybook rather than the USWDS docs site, since the README notes those sources can drift out of sync.