18f / identity-design-system

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

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

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.

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.

identity-design-system's Issues

Implement page partial templates.

The Templates pages in the documentation scaffolding seem to be relating to Form Templates in the U.S. Web Design System, and will need discovery of what they are, and implementation in the style guide.

Page layouts, and the Layout documentation page.

The documentation site should define whole page layouts that are common for use within login.gov, similar to the U.S. Web Design System’s Page Templates.

Additionally, the documentation site should use those layouts, once they are completed. The documentation site currently has no footer and a pretty weak header, just because they were never properly implemented.

Add Hound CI to catch css syntax errors

As annoying as hound is, I think it is a really effective way of ensuring that our css code remains clean. A good example of this implementation is the 18F site:

• .hound.yml
• circle.yml
• .scss-lint.yml

The lint file should probably be updated from the 18F/frontend repo:

https://github.com/18F/frontend/blob/master/.scss-lint.yml

Components in Figma asset missing from codebase

Howdy 👋

I'm an Engineer at MO Studio working on a project for the VA related to In-Person Identity Proofing for Login.gov accounts. We're using this design system on top of USWDS for our prototype.

Our designers have access to the 2023-10-VA_Request-LGDS_Design_Assets project in Figma and have used these two components in mockups that we can't identify in the library code. They are the "Step Indicator" and "List Link Item" components screen captured below:

The step indicator works with USWDS styling but seems to be missing LGDS styles to extend it. The List Link seems like its unique to LGDS. Can you point us to any docs or examples of these components? Even just the CSS for them would help us implement them as custom components for now.

Thanks for reviewing and for all the work that goes into building and maintaining this project!

~ Mateo

Stick sidebar navigation.

One of @rtwell’s pet-peeves about the US Web Design System styles was/is that the sidebar navigation on the left of pages isn’t accessible as you’re navigating through pages.

We should be able to apply .position-sticky to that to get it to stick nicely… right? Right. I couldn’t get it working, even though it’s covered in the U.S. Web Design System documentation.

We’ll have to make sure that the bottom of longer menus are still accessible for longer menus on shorter height screens.

Additional gem required to run

Two additional steps to help run the style guide that might be useful to add to documentation:

1. install bundler
2. run bundler

styleguide demo appears to be down

https://federalist-proxy.app.cloud.gov/site/18f/identity-style-guide/

Ideally, this is available so that i can potentially use it on a govt project similar login UI.

Implement form styles, documentation.

Implemented in #32, but documented here for completeness.

Implement styles and documentation for:

• Text inputs and areas
• Dates
• Dropdowns
• Radio buttons
• Checkboxes
• Fieldsets
• Validation errors

Adjust page structure on style guide site (change H1 to H2, etc.)

Note: At the moment, this is in the blocked / waiting column. The issue was originally created without any additional context beyond the issue/subject line. Will need to investigate more

SASS Syntax in focus stylesheet

Possible bug in the syntax for function roundable-focus-outline-box-shadows in _focus.scss
This code:

Generates this error:

The function is likely expecting an argument declaration, like so:
@function roundable-focus-outline-box-shadows () { @return 0 0 0 $theme-focus-offset color('white'), 0 0 0 $theme-focus-width + $theme-focus-offset color($theme-focus-color); }
The above syntax makes the error disappear.

Implement tooltips.

As specified in login-gov_styleguide_v1.9.3.sketch:

The content in tooltips should remain accessible to those navigating by keyboards and to those on phones, as well as screen readers.

Implement progress indicators.

As specified in login-gov_styleguide_v1.9.3.sketch:

I suspect we’ll want to implement this as something like .usa-progress-indeterminate.

A partial implementation of this is visible while setting up a security key, but I’m not sure if this is the desired animation.

Additionally, the scaffolding for the Progress indicator documentation suggests there is a determinate style for these progress indicators as well, but they are not included in the Sketch specification.

Write home page.

The home page should cover at least:

• How to install the style guide.
• Usage instructions for using the compiled assets.
• Usage instructions for including the source files (Sass, JavaScript modules) into your build process.
• That it is based on the U.S. Web Design System v2, so this documentation can be supplemented by that documentation.
• Probably other things?

Write selectors with hyphens instead of underscores

SCSS Linters raise issues on selectors like usa-checkbox__label using underscores and requests using hyphens instead. Several selectors in the design system use underscores which creates multiple linter issues.

Develop an initial content style guide page

Why: By consistently practicing language in an intentional way, we can provide content that supports login.gov users’ needs and improve their experience on our sites and materials.

Stories:

• As a login.gov team member, I would like to use design.login.gov as a go-to reference when writing login materials, which would help us write clear and consistent content across teams and channels
• [Possible story] As a journalist/writer reporting on login.gov, I would like to use the content style guide to help me understand common login acronyms and terms. Also, how to format them via word list

Steps

• Use Login.gov Content Guidelines 🔒 to develop the initial page
• Determine where it should be located in design.login.gov
• Have team members to review
• Publish it live and share it via #login channel
• Create additional issues as needed if there are actions beyond developing an initial content style guide page

Additional resources:

• login.gov content style guide from 2017
• Inspiration: VA.gov content style guide

Notes:

• Issue #47 is related, which we can determine whether this current issue answers that issue or not (and close if needed)

Code blocks difficult to distinguish.

The implementation into developers.login.gov is the first time we have a lot of inline code snippets:

Inline code

… as well as block-level code:

Block code

… that’s integrated into a lot of written text. I think it’s hard to distinguish where the code blocks start and end, since we’re relying only on font family changes.

Additionally, for single-line code blocks, the scrollbar appears over the text, making it impossible to use:

Scrollbar issue

Create list style for data views

Consider a data list view format in the Design System to support indexing of data, with sorting options and entity actions.

Create a dropdown action button with menu options

Design a dropdown action button that follows the design system styles for interactive states and is flexible for adding submenu option for options possible from the action menu.

Add punctuation style to toast

For consistency, add a content style guide item for punctuation of toast messages. They are short but should include periods at the end of sentences.

Create utility class that breaks text to new lines

a utility class that can be used when necessary that breaks text to new lines so it can be applied globally to all tables

Add max-width to list items within .usa-prose.

There seems to be no max line length set on <li> elements within .usa-prose

Improve disabled button state

Our current disabled buttons are not meeting accessibility contrast requirements and disabled buttons may or may not be very accessible at all. Moving forward we should either consider increasing our contrast or electing to not include them in the system.

Focus styles.

We’re currently using the default USWDS focus outline colors and styles — we’ll probably want to adjust the color to fit into our color palette and perhaps adjust the shapes of the outlines around some of the form controls (most notably the radio buttons and checkboxes).

Add documentation to Color page.

The color page currently lists colors appropriately, but doesn‘t explain that they can be used via utility classes. The documentation should indicate that, and reference the U.S. Web Design System’s documentation on the matter.

Fix 404 error - Email template page

Currently, the email template page on design.login.gov is 404-ing, which leads to Federalist default 404 message

Email template page

Federalist 404 error page

Accordion styles apply to header banner incorrectly.

Introduced in #27.

Link to implementation documentation broken

The link to the documentation for installation and usage instructions is pointed to a page that does not render well (https://federalist-proxy.app.cloud.gov/site/18f/identity-style-guide/).

Create tables styles

A great addition to the design system would be styles for tables, including those with top and side headers, and tables with no outlines.

Design side navigation option

As content grows in scope and depth, several products have a need for a navigation option that will allow for deeper taxonomy and labels that may be longer than the average width current top navigation system is set up for.
A side navigation option is needed that will support web applications as well. These tend to have a toolbar to support user actions and global navigation nodes horizontally across the top. A side navigation would complement that type of information architecture.

Create a figcaption style

Why: As a user looking at screenshots, illustrations, etc., I want to better understand what I am looking at via captions (HT: Karla R.)

Use case example: Captions for screenshots in How to create an account

Notes:

• Use USWDS Typesetting to inform how we build it
• Research browser compatibility for <figcaption>, including <figure>

AC:

• Is accessible via contrast checker
• Is browser compatible for majority of our userbase
• Is added and documented on login.gov design system - typography for wider use

Update: LG-2591 ticket created

Implement file uploads.

As specified in login-gov_styleguide_v1.9.3.sketch:

Unsure if we should do one or none of these:

• Implement this fully as a JavaScript component + styles (similar to things like Accordions).
• Implement the styles for this (.usa-input-file-large), but leave the JavaScript implementation up to the application consuming this.
• Implement parts of the styles for this (.usa-drop-target, .usa-file-preview), but not glue them together, and leave the JavaScript implementation up to the application consuming this.

implement password strength meter.

As specified in login-gov_styleguide_v1.9.3.sketch:

Unclear of the best implementation for this — if we should include JavaScript for this, or just the styles.

Consider / decide on icon set for standardization

The USWDS recommends using Font Awesome (FA).

Current Issue:
Meanwhile, Login does not have a standardized, default set option to pull from for the Login site/platform. Also, helpful for Login people to pull from for their slide decks.

This task is competed when:

• When Login Design and stakeholders have discussed on the pros and cons of having an icon set
  • If merited, then which icon set? Font Awesome? If not FA, then which set?
    • When decided, we'll include instructions to the style guide:
      • On implementation
      • On accessibility
      • On usability
  • If not merited, then how do we ensure that we have a consistent system of icons?

Include Autoprefixer for Ruby include in distributed package

The autoprefixer for rails is missing in the design system. The design systems vendor prefixer is currently is configure only in the gulp file, and it imports the configuration settings from https://github.com/uswds/uswds-gulp/blob/master/config/browsers.js.
Ruby apps need something like this autoprefixer include in the distributed package and a long term plan to set the .browserslistrc in tangent with the USWDS settings.

Add release notes to login design system

Proposal: Consider writing and adding release notes to design.login.gov site (Similar to USWDS' release notes)

Stories:

• As a designer, I want to inform our login team members, esp. developers, of new features (and fixes), to show them that the login design team is listening to their feedback and that we are actively working to improve the login design system
• As a login team member, I want to be kept in the loop with release notes. As the design system evolves over time, having a historical log of these changes, improvements, and fixes helps tell stories behind the system

Definition of Done:

• Discuss this proposal with login designers, developers and product to gauge interest
• If 👍, proceed to create initial draft of release notes and format
• Establish a review process from drafting to publishing on design.login.gov site
• Create a Release Notes page on design.login.gov site (Consider a subnav under Usage section)

Implement labels.

As specified in login-gov_styleguide_v1.9.3.sketch:

These should be an adaptation of Labels in the U.S. Web Design System.

There should be some documentation added about the appropriate uses for these labels as well. What are those uses?

Notifications of Design System version changes

Consider a way to communicate version changes to the Design System. This helps apps that may have a dependency to the design system in the package.json like this example:

"identity-style-guide": "^2.1.3"

Write or delete the Components Overview page.

The Components Overview page is currently blank.

Is there anything that should go there, or should we delete it? 🔮

Login.gov required form fields style

Please consider a required form fields style for the Login.gov design system. Partner forms have more optional fields than required fields, so a distinct style for required fields will assist the user in spotting the needed information both in filling out the form and identifying validation errors.

Consider using CSS classes for icons in the design system

Would it be worthwhile to create CSS classes that would include the path to the image along with styles such as height and width declaration, and color? That way code could be easily maintained and updated in fewer places when using images.

Add code styles documentation page.

As implemented in #30, code styles should be covered in the documentation, as login.gov will be using code styles as well downstream.

Add term glossary (content guide) for terms often used ambiguously.

It would be nice to have things like “backup codes” vs. “security codes” (etc) covered in the style guide.

Add colors to the style guide palette

On the data viz side, it would be awesome to have:

1. A color for Column Charts, Line Graph
2. 4-6 colors for Pie Chart, donut chart
3. A neutral gray/black for the axis and the labels
4. data tile (shows a statistic in large font size, with smaller sized label and description)
   For data tables:
5. color for data values
6. a color data labels
   Also would be great to consider colors for pills:
7. pill with a link
8. success pill
9. warning Pill
10. error pill
11. info pill
    *note on pills, common application would be on white background with white text inside colored pill

Additional items:

• Required field item *

Design a style for data

Would a style of key value pairs be a candidate for the Design System? As more data will be incorporated in the Partner's Dashboard this style would be helpful in displaying types of data and their values.

Create a style for code

Code samples is part of the content for Partners. Could we extend code formatting styles beyond markdown for styling code in Dashboard?

Add usage instructions to Buttons page.

The Buttons page currently has some placeholder text, which wasn’t originally written because I wasn’t aware of how the buttons should be used:

Use these button styles unless doing x and y, in which case, use other buttons.

These buttons should be used when x-ing and y-ing.

I still don’t know how those buttons should be used, but we should have a reason why those styles exist, or delete them.