Getting started for engineers

Overview of the theme

The Code for America, U. S. Web Design System (USWDS) theme extends the USWDS to replace the Honeycrisp Ruby gem. On this site, engineers can reference the theme installation, customization, and usage documentation for component replacements (written in the Thymeleaf and ERB template languages).

Migrating from Honeycrisp

Migration requires changes in installation and how components are written in applications. For each component documentation page, you will find.

• The necessary HTML markup and CSS selectors needed to render each component.

• A preview of how the markup should be rendered.

• If applicable, description of JavaScript required to make the component functional.

• Code snippets for Thymeleaf template fragments (Java Spring) and Embedded Ruby (ERB) partials (Ruby on Rails).

Enabling the theme in the Form Flow Builder

The theme is already available in the Code for America Form Flow Builder Library and Starter Application. To enable the theme, follow these steps:

1. Follow the setup instructions for the Form Flow Builder Starter Application.

2. Change the design system configuration setting in your application.yaml file. Enabling this property sets template resolution to use the theme templates and an updated head template linking to precompiled styles and scripts.

You may override default USWDS templates with your own if you need to add your own theme and customize the appearance of components.

Gradle tasks

Build tasks using Gradle will be activated when the application is configured to use the theme. They will automatically install it from NPM and compile the source Dart Sass and ES JavaScript to production-ready CSS and JavaScript. Other tasks include migrating static USWDS assets, SVGs, and images, to the static output directory.

Source for Dart Sass and ES JavaScript can be found in the src/main/resources/static/assets/ directory. Once compiled, they will be placed into the generated/main/resources/static/assets/ directory.

Additional Gradle tasks for watching Sass and JavaScript files can be called. These will monitor changes to Sass files and recompile them. More details on all Gradle tasks can be found on the Form Flow Builder library repository.

Theme

The src/main/resources/static/assets/scss/styles.scss is the entry point for all of the local styles for the FFB. This is where Sass imports and theme settings can be managed. The default setup will provide the necessary styles for the theme.

@forward 'cfa-uswds'; // CfA USWDS theme
@forward 'uswds';     // USWDS component packages
@forward 'cfa';       // CfA component packages

If you want to modify a few theme settings, such as colors, you may extend the theme’s default settings with a Sass map.

// Modify CfA USWDS theme settings
@use 'cfa-uswds-theme' with (
  $cfa-focus-color: 'blue-warm-60v'
  // ... additional settings here ...
);
@forward 'cfa-uswds';  // CfA USWDS theme
@forward 'uswds';      // USWDS component packages
@forward 'cfa';        // CfA component packages

The theme uses a subset of USWDS settings (prefixed with $cfa-). Refer to the theme-level settings documentation on what can be configured.

There are many more that can be configured, however, directly with the USWDS. If you want to modify more or anything other than the theme settings, omit the @use 'cfa-uswds-theme' ... statement and extend the USWDS core with a new Sass map containing USWDS settings. Keep in mind this may require a larger settings block and should only be done if you are prepared to create your own theme or use the USWDS without the Code for America theme layer. Use the theme settings as a base and the USWDS documentation site for additional settings.

// Modify USWDS theme settings
@use 'uswds-core' with (
  $theme-focus-color: 'blue-warm-60v'
  $theme-focus-offset: 2
  // ... additional settings here ...
);
@forward 'uswds';      // USWDS component packages
@forward 'cfa';        // CfA component packages

There are a handful of settings used by the theme’s component packages. They can be modified by extending the CfA core with a new Sass map containing those settings. Refer to the package-level configuration documentation.

// Modify CfA USWDS theme settings
@use 'cfa-uswds-theme' with (
  $cfa-focus-color: 'blue-warm-60v'
  // ... additional settings here ...
);
@forward 'uswds';      // USWDS component packages
// Modify CfA component package settings
@use 'cfa-core' with (
  $cfa-details-background-color: 'secondary-lightest'
);
@forward 'cfa';        // CfA component packages

JavaScript

The src/main/resources/static/assets/js/index.js file is the entry point for the FFB JavaScript. This is where ES module imports and component configuration and instantiation are handled. The default setup will provide the necessary functionality for the theme. Components for the USWDS typically follow this instantiation pattern:

import accordion from '@uswds/uswds/js/usa-accordion';
accordion.on(document.body);

USWDS JavaScript functionality may not need to be modified but there are a few documented methods that can be explored on the USWDS documentation site.

Components for the theme typically follow a slightly different instantiation pattern:

import Details from '@codeforamerica/uswds/packages/cfa-details/cfa-details.js';
new Details();

Theme JavaScript functionality may not need to be modified but some methods for each component class can be replaced and some classes accept a settings configuration object. For example, the File selector component is a utility wrapper around the Dropzone library. It accepts an argument of mock files to upload and a Dropzone options object directly passed to the Dropzone class. This will be necessary to configure in most cases as the utility only handles the user experience functionality of the Upload Document component.

Details on JavaScript-enabled components can be found on their respective component reference on this site.

Templates

Template fragments for the USWDS components will be served from a different directory than Honeycrisp template fragments. They can be found at resources/cfa-uswds-templates/. You may override templates and fragments in this path by placing a file with the same name and path in your application.

Installation using Node Package Manager (NPM)

$ npm install @codeforamerica/uswds

When not using the Form Flow Builder, the Code for America USWDS theme is most reasonably managed using NPM. This lets you compile the theme with your application’s CSS, JavaScript, SVGs, and other images. It also maintains a dependency link with the theme source to receive updates. Installing Node.js will install NPM at the same time. We recommend using Node Version Manager (NVM), but you may also install Node.js directly. Even if you are using the Form Flow Builder’s automated integration, it’s helpful to know how this installation works.

Quick start

Once NPM is available, you can add the theme to a new or existing project. If you do not have a package.json file in your project yet, you can run the init command where you would like the package.json to exist and where the corresponding node_modules/ directory is installed. This will walk you through the steps of creating a package.json file.

$ npm init

Once complete, run the installation command to add the theme to your project.

$ npm install @codeforamerica/uswds

This will add the theme package to the node_modules/@codeforamerica/uswds/ directory of your project. Precompiled static assets are available in the dist directory of the theme. These can be added as links in your HTML or project templates. The stylesheet can be added to the <head> tag.

<link rel="stylesheet" href="node_modules/@codeforamerica/uswds/dist/assets/css/styles.css">

The JavaScript can be added just before the closing </body> tag.

<script src="node_modules/@codeforamerica/uswds/dist/assets/js/default.js"></script>

These examples link the assets from the node_modules/ directory, however, you should move all of the static assets under dist/assets/ into the directory where you keep (or plan to keep) similar static assets. Refer to the directory diagram below for more information on available assets.

Custom installation and theming

To make simple modifications to the theme, such as colors, you must set up a front-end development environment for compiling the theme’s Sass and JavaScript. This is preferred if you want to use the theme components as a base and make simple updates to the color palette or other USWDS settings.

Code for America USWDS starter

The Code for America USWDS starter can be used to quickly set up an environment to start configuring the theme. It describes how to set up a simple NPM project with the theme as a dependency. It also describes how the theme’s Sass and Rollup scripts can be used to compile Sass and JavaScript and run them through the necessary transformations without programming your own Sass or Rollup scripts.

You may also follow the instructions on the USWDS documentation site to create your own USWDS theme for your project from scratch.

Building pages

Once the theme is installed, configured, and linked you can start building pages. The USWDS documentation site has several page templates that you can use to get started. Once you have created page templates you can start adding components using the rendered HTML in the component catalog. Or, use the Thymeleaf template fragments and ERB templates partial to render pre-built components in your Java Spring or Ruby on Rails application.