wdfn-viz

WMA Water Data for the Nation USGS visual identity package

WDFN Viz provides stylesheets, fonts and images that can be used when creating web pages that can be used to meet USGS visual identity standards. You can choose either to use a prebuilt css stylesheet or build your own app specific style sheet by starting with the available Sass style sheets. The repo as provides a javacript bundle which includes the USWDS javascript along with a load function that can be used to include your application's custom javascript. The stylesheets and javascript bundles use the US Web Design System (USWDS).

Installation

Before starting we recommend becoming familiar with USWDS This package can be installed in an existing project by installing via npm.

npm install wdfn-viz --save-exact

We recommend pinning the version of wdfn-viz in your package.json. We try to update this package everytime USWDS publishes a new version. Changes will be recorded in CHANGELOG.md. Before updating to a new version of wdfn-viz we recommend checking the release notes for the corresponding updated version of USWDS (if it has been updated).

To install the latest development snapshot (containing the current state of the master branch):

npm install wdfn-viz@snapshot

Usage

The package provides both style sheets and javascript that must be used in order for your markup to work as desired. Below are instructions on how to include these in your html markup.

Using the prebuilt css files

If your project is not building stylesheets using Sass and you would rather just load a prebuilt style sheet, then we have two options. If you want to automatically include all of USWDS, then load the wdfnviz-all.css. Doing this allows your page to use USWDS markup and utility classes and if you are not building your own style sheets we strongly recommend that you use this.

If your project only needs to use the USGS/USWDS headers, navigation and footers and will not be using USWDS for the rest of the markup, you can use the second style sheet, wdfnviz.css, which includes only the USWDS style needed to style the header, navigation, and footer.

Once you choose which prebuilt style sheet to use, place the chosen style sheet from ./node_modules/wdfn-viz/dist/ in the directory where your assets are served and add a link tag to your markup in the header.

Using the Sass files to build a custom style sheet

We recommend building the stylesheets with Dart sass (npm install sass). Please note that the use of @import is now deprecated in favor of using the @use syntax to include Sass files. The main wdfn-viz Sass stylesheet should be included (using @use 'wdfnviz') in the application's Sass file.

In order to use USWDS mixins and variables you will need to add '@use uswds or if you want to optimize your stylesheet to include only the parts of USWDS that you need then use the @forward directive to include the parts of USWDS that you need. The USWDS 3.0.0 migration guide, part 6 has a wealth of information that will help guide you to what needs to be done based on the needs of your application.

You will also likely need to at least set some of the USWDS theme variables. The most common ones that will need to be set are $theme-font-path and $theme-image-path. These need to be set relative to where the assets are served, typically your dist directory. Below are two examples of setting these theme variables. Others would go in the same section

For example to automatically include all of USWDS components, mixins, variables, and utility classes:

@use 'uswds-core' with (
  $theme-font-path: './fonts',
  $theme-image-path: './img'
);
@use 'wdfnviz';
@use 'uswds';
#main-content {
    @include uswds.grid-container;
}

If you choose to optimize your build then you would write something like this:

//The line below sets the namespace to uswds, sets any USWDS theme variables and allows access to USWDS variables and mixins
@use 'uswds-core' as uswds with (
  $theme-font-path: './fonts',
  $theme-image-path: './img'
);
@use 'wdfnviz';

// Add @forward for those parts of USWDS that you need. You do not need to repeat the ones in src/styles/wdfnviz.scss but it is not harmful to do so.
@forward 'usa-alert';
@forward 'usa-list';

When building the style sheet these three directories, node_modules/wdfn-viz/dist/sass, node_modules/@uswds/uswds/src/stylesheets, and node_modules/@uswds/uswds/packages, should be specified on the --load-path option along with the need USWDS style sheets.

Once a stylesheet is produced, it should be further processed by postcss using autoprefixer and postcss-csso using a postcss.config.js file:

const autoprefixerOptions = [
    '> 2%',
    'Last 2 versions',
    'IE 11',
    'not dead'
];

module.exports = ctx => ({
    map: Object.assign({}, ctx.options.map, {inline: false}),
    parser: ctx.options.parser,
    plugins: {
        autoprefixer: autoprefixerOptions,
        'postcss-csso': {
            forceMediaMerge: false
        }
    }
});

You may also want to include postcss-flexbugs-fixes plugin as is done for building wdfn-viz.

Below is an example of the process:

% sass --load-path node_modules/wdfn-viz/dist/sass --load-path node_modules/@uswds/uswds/src/stylesheets --load-path node_modules/@uswds/uswds/packages src/styles.main.css dist/main.css
% postcss dist/main.css  -o dist/main.css

Postcss generates internal sourcemaps by default. You may want to consider using the --map option to create external map files or if you want to minimize your css assets, you may want to disable entirely by using --no-map

Collecting the images and fonts

When building the assets, the images should be collected in a directory, 'img', that is the at the same place where your final style sheet resides (typically a dist directory). This should include the images in wdfn-viz/src/img that provide the USGS favicon, logos and USWDS images. The images include a usgs_favicon.ico that can be used for the page's favicon by adding the following line within the

section:

<link rel="shortcut icon" type="image/ico" href="{{ url for 'img/usgs_favicon.ico'}}">

The fonts should also be collected in a directory, 'fonts', that is in the same place where your final style sheet resides (typically a dist directory). Below are examples of commands that could be used to collect the image and font assets.

% mkdir -p dist/img && cp -r node_modules/wdfn-viz/dist/img/* dist/img
% mkdir -p dist/fonts && cp -r node_modules/wdfn-viz/dist/fonts/* dist/fonts

Including uswds-init.min.js

Regardless of whether you are using the prebuilt javascript bundle or will be bundling your own javascript with wdfn-viz, you will need to load, uswds-init.min.js. This should be loaded before loading your style sheet within the

tag. You will need to copy the file, located at node_modules/wdfn-viz/uswds-init.min.js, to the directory where your assets are served. Below is an example (where you would use a prebuilt style sheet or your sass generated style sheet)

<head>
    <script src="uswds-init.min.js"></script>
    <link rel="stylesheet" href="wdfnviz-all.css"
</head>

Building custom javascript bundle

The javascript should be imported and provides USWDS javascript as well as the ability to log unhandled exceptions to Google Analytics if window.ga is defined. In order to use, a loading function should be defined which will be executed when the page loads. Below is a simple example:

import wdfnviz from 'wdfn-viz';

const load = function () {
    null;  // Add code that should get executed when the page is loaded
}

wdfnviz.main(load);

The javascript bundle that is created (which will contain your project specific javascript as well as the USWDS javascript) should be loaded inside the body tag. We recommend that this is done as the last tag in the body.

Example html templates for the header and footer can be found here: src/templates. To implement the header and footers add the markup in those templates to your pages, adjusting the image url in the header.html template as needed for the USGS logo and federal government logos. This includes the script for uswds-init.min.js which should be retrieved before loading the css files as is done in the example header.html.

Using prebuilt javascript bundle

In order for some USWDS components to work as expected including the header, you must include the prebuilt javascript bundle if you are not building your own javascript bundle. Simply copy the prebuilt bundle, node_modules/wdfnviz/dist/wdfnviz.js to the directory where your assets are served and add the script to the body tag in your markup, preferably as the last tag before the body tag is closed.

Publishing this repo to npm

Gitlab CI is configured to publish to the wdfn-viz npm package when merging commits to the main branch.

To make a release, merge a commit that sets the version attribute in package.json to the appropriate value. When merging work that is not intended for release, append -snapshot to the upcoming version. Snapshot releases will be tagged in the form 0.1.10-snapshot.6738b77, where 6738b77 is the corresponding git commit. Generally, once a release is published, the version number should be incremented to the next minor release number with -snapshot appended and the change committed to the main branch.