About

Motivation

The USWDS has played an incredible role unifying the federal government’s digital experience since 2015, simplifying both design and development to create consistent, maintainable products. However, frontend development evolves rapidly, and as I worked with USWDS, its reliance on older tools and approaches like BEM style naming, SCSS, Gulp, and manually installed fonts and icons began to feel like they were slowing me down.

Given the USWDS’s existing utility classes, I saw an opportunity to modernize it by using Tailwind CSS, which offers similar functionality out of the box. This project is an experiment combining Tailwind’s utility-first approach with the USWDS’s design tokens.

Earlier versions used Alpine.js directives. The current packages use Zag state machines through Vanilla JavaScript and React adapters; Alpine is not a current dependency. See the JavaScript guide for initialization.

My hope is that this project makes working with the USWDS a simpler, easier, and more efficient tool for developers, and therefore users.

Tailwind CSS

Efficiency and Performance

Tailwind optimizes our projects by generating only the necessary CSS, significantly reducing the CSS footprint compared to SCSS functions and nesting. This leads to faster load times and improved performance for end users by minimizing the resources they need to download.

The CSS your application ships depends on the components and utilities it uses. Tailwind generates styles from the classes present in your source.

Enhanced Developer Experience

I’ve got to say it: the USWDS has some really complicated SCSS. This makes it particularly difficult to work with and extend.

The USWDS relies heavily on BEM and nested styles which creates issues with CSS specificity. For example, a utility class like “.text-white” is always going to have a lower specificity than “.usa-footer__secondary-link a” which means you won’t be able to alter any predefined styles using a utility class. Building with only utilities allows us to avoid this problem altogether.

Advanced DevTools Integration

We leverage Tailwind’s powerful DevTools, including class sorting, linting, and autocomplete, which streamline development even with our custom configuration.

Utility-First Flexibility

Tailwind’s extensive utility classes make it easy to implement unique design requirements, such as adjusting spacing or overriding font colors, with minimal effort.

While there are plenty of good utilities in the USWDS, I’m often in need of ones that don’t exist: .space-y-4, .column-count-4, .gap-2, etc. While these could be added, accounting for all these use cases would make the USWDS’s generated CSS even bigger!

Wide Adoption and Excellent Documentation

As the most widely used styling system globally, Tailwind benefits from a large community and comprehensive documentation. This reduces the learning curve for new developers and minimizes the need for internal documentation.

Iconify

Seamless Integration with Tailwind

Iconify complements Tailwind by allowing effortless addition of new icons, similar to changing font colors. Its robust library supports extensive icon options without increasing the project’s complexity.

Optimized Rendering

Iconify generates SVGs directly in our CSS, ensuring immediate rendering by browsers and eliminating the need for additional network requests for images or icon sprites (which come with their own, specific challenges).

Simplified Icon Management

Dynamic generation of icons with Iconify removes the burden of managing icon libraries, optimizing SVGs, or creating icon sprites, ensuring cross-browser compatibility effortlessly.

Fontsource

Reliable Self-Hosting

Fontsource enables us to self-host fonts, providing greater control over font updates and rollbacks on a per-project basis without relying on external dependencies or manual downloads.

Enhanced Flexibility

By installing fonts within projects, we’re able to have greater flexibility over how we manage, update, or rollback fonts. Relying on updates from the USWDS means we’re forced to update all or nothing. This puts extra stress on individual teams and on USDWS maintainers when consuming and publishing updates.

Build tooling

The component packages are built with tsdown. The documentation site uses Astro and Tailwind CSS. Your application can use its own build tooling; follow the Vanilla getting-started guide or React getting-started guide for the packages and styles to install.

JavaScript behavior

The Vanilla package binds state machines to authored HTML, while React components render the corresponding machine state. Use the Vanilla getting-started guide or React getting-started guide for the current setup. Per-component availability and release limitations are documented in the JavaScript guide.

Component examples

Component documentation is written in MDX. Vanilla examples show HTML markup, while React examples show runnable TSX. Each preview includes its source so you can copy the example or open it in StackBlitz.