Base theme utilizing the United States Web Design System.
https://designsystem.digital.gov
Current USWDS compatibility: 3.13.0 (Click for github release info)
A Note on USWDS Versions
If you notice uswds_base isn't perfectly synced with the latest digital.gov release number, don't worry—that is actually by design! This theme is built to be simple and unopinionated so that you can upgrade the USWDS library on your own timeline without waiting for a theme maintainer to clear it.
We recommend testing new USWDS versions within your own environment before upgrading. I check in on new USWDS releases regularly to see if structural changes are needed here, but if you spot something missing in the main templates, feel free to open an issue!
uswds_base Drupal Theme to official USWDS minimal version required
uswds_base
uswds
Information | ||
|---|---|---|
| 3.12.1 | 3.12.0 | Quick fix for missing variable error on D11 |
| 3.12.0 | 3.12.0 | No changes |
| 3.11.1 | 3.11.0 | Quick fix for missing variable error on D11 |
| 3.11.0 | 3.11.0 | CSS label adjustments and deprecation clean-up |
| 3.10.0 | 3.10.0 | No changes |
| 3.9.0 | 3.9.0 | No changes |
| 3.8.1 | 3.8.1 | Drupal 11 compatibility added |
| 3.8.0 | 3.8.0 | Small clean-up fixes - Check USWDS release for 3.8.0 information |
| 3.7.1 | 3.7.1 | Twitter icon now X |
| 3.7.0 | 3.7.0 | No Changes |
| 3.6.1 | 3.6.1 | No Changes |
| 3.6.0 | 3.6.0 | No Changes |
| 3.5.0 | 3.5.0 | Minor change to pagination |
| 3.4.1 | 3.4.1 | No changes |
| 3.3.0 | 3.3.0 | No changes |
| 3.2.0 | 3.2.0 | Minor aria changes to gov banner |
| 3.1.0 | 3.1.0 | Submit buttons need type, new LinkedIn setting/icon |
| 3.0.2 | 3.0.2 | Schema update to sub theme |
| 3.0.1 | 3.0.1 | D10 Ready - See notes |
| 3.0.0 | 3.0.0 | New version! |
| 2.15 | 2.13 | D10 Ready - See notes |
| 2.14 | 2.13 | Missing fix for nolink |
| 2.13 | 2.13 | New search icon / file input |
| 2.12 | 2.12 | New features |
| 2.11 | 2.11 | Instagram link |
| 2.4+ | 2.8+ | New bookmarks style |
| <= 2.3 | 2.x | Any version of 2.x |
USWDS 3.x
New USWDS version...
From USWDS: Most of the source code now lives in /@uswds/uswds/packages but some compiled assets and some backward-compatible helper files still live in /dist.
Upgrade to 10
*** Will be part of 3.0.1 and may require custom twig changes in your subtheme. Please see https://www.drupal.org/project/uswds_base/issues/3306685... Change core_version_requirement: ^9 || ^10 in your custom subtheme info yml
2.15... Change core_version_requirement: ^9 || ^10 in your custom subtheme info yml if you're hopefully on 9+ and remove core: 8.x
Documentation
Please take a look at the documentation. You will find things like an example of how to add a "Hero" type banner to your USWDS theme. Also instructions for the extended/mega menu and big footer. (column menus) Fixes and any CSS for Drupal will also be included in documentation / example sub-themes but not included in the primary theme folder.
Rules for this theme:
- Starting 3.x, major and minor version of this theme will always reflect the version of digital.gov USWDS.
- I'll do my best to line up the patch version with the official USWDS.
- Drupal Core items that need class tags will only receive USWDS related tags.
- No CSS or JS will be added to this theme. Only necessary items to apply USWDS style to core items. (Do your own in a subtheme)
- Will try to keep all settings/code for this theme at a minimum.
Content Delivery Network (CDN)
From the time of first install, there is a default option enabled using a CDN for remote USWDS assets. Of course, This should never be used for production. This was added to provide an ability to quickly see the theme in action. Also, you could utilize this and adjusting the URLs to test newer versions of USWDS.
Other USWDS Drupal related efforts
Advanced abilities:
USWDS CKEditor Integration
USWDS Paragraph Components
Why use this theme and not that other Drupal USWDS theme?
Drupal uswds vs uswds_base theme: uswds_base is a minimalist approach to Drupal USWDS integration without using a Drupal Core base theme. No extra JS/CSS is added in the primary uswds_base theme. Some setting abilities are provided, but more of a minimal approach that still works for most implementations directly after install.
Other Projects:
Describe images for 508 compliance.
Project information
1,636 sites report using this theme- Created by mferanda on , updated
Stable releases for this project are covered by the security advisory policy.
Look for the shield icon below.
Releases
3.12.1
released 13 May 2026
released 13 May 2026
Works with Drupal: ^10 || ^11
Fix for D11 variable missing
Install:
Development version: 3.12.x-dev updated 13 May 2026 at 19:42 UTC
