@18f/identity-design-system

v9.4.0

Published

2 months ago

The global style of Login.gov

Downloads

8,670

Login.gov Design System

The Login.gov Design System is an extension of the U.S. Web Design System used on Login.gov sites to consistently identify the Login.gov brand.

This documentation describes how to use the Login.gov Design System in a new project. Read CONTRIBUTING.md to learn more about contributing to the design system itself.

Installation

Node.js is required to use the Login.gov Design System. You should install this first if it's not already available.

Next, install the package using NPM from your project's directory:

npm install @18f/identity-design-system

Usage

As an extension of the U.S. Web Design System (USWDS), the Getting started for developers guide can be a useful resource. The Login.gov Design System aims to be a drop-in replacement for the USWDS, so that all of its documentation would apply for the Login.gov Design System. The only change you're required to make is to update any references of @uswds/uswds with @18f/identity-design-system.

Styles

The Login.gov Design System uses Sass to generate stylesheets. While you can use any Sass compilation process, we recommend @18f/identity-build-sass, since it supports any environment where Node.js is already available, and it comes prebundled with default behaviors which are well-suited for the design system.

Here's an example stylesheet that imports the design system:

@use 'uswds-core';
@forward 'uswds';

The only requirements for Sass compilation are:

Your Sass load paths must include node_modules/@18f/identity-design-system/packages
You must be using the Dart Sass implementation of Sass

If you're using @18f/identity-build-sass, the following command will compile a CSS file to build/styles.css:

npx build-sass path/to/styles.css.scss --out-dir=build

Browser-Ready CSS Bundles

While it's recommended to import the Login.gov Design System as a Sass module to support optimization options, a precompiled CSS bundle is made available for convenience or for projects where it's not possible to include a Sass build process.

These files are found within dist/assets/css of the published NPM package. When installed locally, this is found at node_modules/@18f/identity-design-system.

<html>
  <head>
    <!-- ... -->
    <link rel="stylesheet" href="/path/to/identity-design-system/dist/assets/css/styles.css">
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

JavaScript

As an NPM package, you can import the Login.gov Design System anywhere in your projects imports:

import '@18f/identity-design-system';

By default, this will include JavaScript for every component, which can increase load times for users and build times for developers. Refer to the Options section below to learn how to optimize JavaScript imports.

Browser-Ready JavaScript Bundles

While it's recommended to import the Login.gov Design System as an NPM package to support optimization options, a precompiled JavaScript bundle is made available for convenience or for projects where it's not possible to include a JavaScript build process.

These files are found within dist/assets/js of the published NPM package. When installed locally, this is found at node_modules/@18f/identity-design-system.

<html>
  <head>
    <!-- ... -->
    <script src="/path/to/identity-design-system/dist/assets/js/init.js"></script>
  </head>
  <body>
    <!-- ... -->
    <script src="/path/to/identity-design-system/dist/assets/js/main.js"></script>
  </body>
</html>

Options

Optimization

If your project is not using every component of the design system, it is recommended that you optimize your build by cherry-picking the individual components that you are using.

In Sass, you can do this by replacing the forwarded 'uswds' module with the packages of the individual components:

@use 'uswds-core';
- @forward 'uswds';
+ @forward 'usa-accordion';

You can find the package name on each component's documentation (e.g. Accordion → Package).

In JavaScript, you can import named members of the JavaScript package. If you are using a bundler which supports dead code elimination, any unused components will be removed from the compiled output. Each named import includes a on method to initialize the component on the page.

- import '@18f/identity-design-system';
+ import { accordion } from '@18f/identity-design-system';
+ accordion.on();

Theme Variables

The Login.gov Design System configures USWDS theme variables to provide defaults designed to be used across all Login.gov sites. These should almost always work well out-of-the-box, and not require further configuration.

If needed, you can extend these using the documented process for configuring settings, providing variables when importing the uswds-core package:

- @use 'uswds-core';
+ @use 'uswds-core' with (
+   $theme-body-font-size: 'sm'
+ );

License

See LICENSE for licensing information.