USWDS Jekyll

USWDS Jekyll is a Jekyll theme that wraps the U.S. Web Design System (USWDS) into a ready-made site skeleton for Jekyll-based government and public-sector websites. It takes a Jekyll site with YAML data files and front matter as input and outputs a static HTML site styled with USWDS CSS and JavaScript. The theme is developed by 18F, an office within the General Services Administration (GSA) Technology Transformation Services (TTS), and is distributed as a Ruby Gem. The repository is currently in maintenance mode, accepting only fixes while TTS plans its microsite strategy.

What is USWDS Jekyll?

USWDS Jekyll is a Jekyll theme that integrates the U.S. Web Design System (USWDS) into a Jekyll site, providing a set of layouts, includes, and configuration options to build standards-compliant federal and public-sector websites. It takes a Jekyll site with YAML data files and front matter as input and outputs a static HTML site styled with USWDS CSS and JavaScript. The theme is developed by 18F, an office within the General Services Administration (GSA) Technology Transformation Services (TTS), and is distributed as a Ruby Gem. The repository is currently in maintenance mode, accepting only fixes while TTS plans its microsite strategy.

Key Features

• USWDS integration — The theme bundles the USWDS stylesheet (uswds.min.css) and JavaScript (uswds.min.js) and includes them automatically unless overridden by project-level styles and scripts configuration.
• Prebuilt layouts — Six layouts are included: default, page, home, post, project, and team-member, mapping to USWDS page templates such as the landing page and document page templates.
• Data-driven navigation — Named navigation lists live in _data/navigation.yml and can be referenced by the header, sidebar, or other components; links support external URLs, CSS classes, and collapsible submenus.
• Component overrides — Every include and layout can be overridden by placing a file with the same name in the site's _includes or _layouts directory, and low-level component templates are separated from concrete implementations for flexible customization.
• Asset management — Stylesheets and scripts can be configured at the site, layout, or page level in front matter, with support for media attributes and async loading.
• Analytics options — Google Analytics (via UA code) and the Digital Analytics Program (DAP) are both supported through simple _config.yml keys.
• Search.gov integration — Search functionality is provided through Search.gov by adding a search_site_handle to the configuration.
• Theme customization — USWDS theme settings and design tokens can be added to _sass/_uswds-theme-settings.scss, and custom Sass goes in _sass/_uswds-theme-custom-styles.scss.

Who is it for?

• Government agencies — Build public-facing websites that follow the U.S. Web Design System without writing the front-end from scratch.
• 18F and TTS project teams — Use the theme to create project portfolio sites, team member pages, and documentation hubs with consistent government branding.
• Jekyll developers — Developers who want a USWDS-compliant starting point and the ability to override any layout or include with their own markup.

What can you do with USWDS Jekyll?

• Launch a government landing page — The home layout implements the USWDS landing page template with hero, callout, graphics list, and tagline intro sections driven by YAML front matter.
• Create a documentation site — The page layout supports side navigation and per-page subnavigation, with hash links that work with Kramdown's auto-generated heading IDs.
• Showcase projects and people — The project and team-member layouts render detail pages from front matter fields, and project-list.html and team-list.html includes display aggregations.
• Publish a blog or news section — The post layout is identical to page and can be used with Jekyll's standard post workflow.

How does USWDS Jekyll work?

Install the gem by adding gem 'uswds-jekyll' to your Gemfile, run bundle, then set theme: uswds-jekyll in _config.yml. The theme reads configuration from _config.yml and data files in _data/ (such as header.yml, navigation.yml, and identifier.yml) and builds a static site with bundle exec jekyll serve. Development workflows use npm scripts to sync USWDS assets and Sass into the theme directories.

FAQ

Is USWDS Jekyll free?

Yes. The theme is open source and distributed as a Ruby Gem on RubyGems, with source code on GitHub under the 18F organization. There are no paid tiers or license fees.

What version of Jekyll does USWDS Jekyll require?

USWDS Jekyll 5.x is only compatible with Jekyll 4.0 and higher. Earlier versions of the theme support older Jekyll releases.

How do I customize the colors and fonts?

Color and font configuration is handled in _data/theme.yml, which maps USWDS theme tokens to component variables. For advanced changes, you can add USWDS theme settings files to _sass/_uswds-theme-settings.scss and custom Sass to _sass/_uswds-theme-custom-styles.scss.

Does the theme support search?

Yes. Search is provided via Search.gov. You create a Search.gov account, configure your website there, then set the search_site_handle key in _config.yml. The theme also supports Google Analytics and the Digital Analytics Program for traffic measurement.

Can I use USWDS Jekyll for a non-government site?

Yes. While the theme is built around the U.S. Web Design System and used primarily by federal agencies, any Jekyll site can use it. All the layouts, components, and configuration options are generic and not restricted to government domains.