|
|
|
Stub page for Generic UWDS information |
|
|
\ No newline at end of file |
|
|
|
**Overview**
|
|
|
|
|
|
|
|
Per the 21st Century Integrated Digital Experience Act (P.L. 115-336 § 3(e)), federal websites are required to use the U.S. Web Design System (USWDS) maturity model to deliver a great digital experience:
|
|
|
|
|
|
|
|
- Integrate design principles.
|
|
|
|
- Follow user experience guidance.
|
|
|
|
- Use USWDS code.
|
|
|
|
|
|
|
|
The U.S. Web Design System is a library of design guidelines and code to help government developers and designers quickly create trustworthy, accessible, and consistent digital government services.
|
|
|
|
|
|
|
|
This base theme focuses on refining Drupal's markup so that it will work with the USWDS library. Some CSS is added to deal with unavoidable Drupal quirks, but only as a last resort.
|
|
|
|
|
|
|
|
**Installation**
|
|
|
|
|
|
|
|
**Main configuration**
|
|
|
|
|
|
|
|
Go to https://www.drupal.org/project/uswds for the USWDS Drupal theme. The preferred methodology is to install using composer so that it can be tracked properly. The command to install using composer is: `composer require 'drupal/uswds'`
|
|
|
|
|
|
|
|
Alternatively, you can load this theme through the Drupal user interface, /admin/theme/install using this url, https://ftp.drupal.org/files/projects/uswds-8.x-2.0.tar.gz
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**My Subtheme configuration**
|
|
|
|
|
|
|
|
An examples subtheme directory is provided in the USWDS theme. You can copy this directory, /themes/uswds/examples/my_subtheme as a foundation. You will need to copy this theme to your themes directory and rename it ‘Nameofyoursubtheme’ so you end up with, themes/nameofyoursubtheme. You will also need to rename the file, my_subtheme.info.yml to nameofyoursubtheme.info.yml. This file is very important because it specifies the regions, where the sass file is compiling the css and the libraries.
|
|
|
|
|
|
|
|
**Customizing**
|
|
|
|
|
|
|
|
The theme makes no assumptions about how you would like to add site-specific CSS. You can either:
|
|
|
|
|
|
|
|
**1. Use the pre-compiled USWDS library**
|
|
|
|
|
|
|
|
f you would like to use the pre-compiled USWDS library, download the zip file, extract and rename the folder to "assets", and place it in your theme folder. Afterwards, this should be a valid path inside your subtheme folder: assets/css/uswds.css
|
|
|
|
|
|
|
|
**2. Use npm to include the USWDS Sass source files**
|
|
|
|
|
|
|
|
Finally you will need an assets directory in your Commerce subtheme. This directory is very important because it contains all the necessary files such images, fonts and especially JavaScript components which power this subtheme. You need to first run the command: `npm install` which will give you a node_modules directory. This give you added JavaScript functionality to power this website.
|
|
|
|
|
|
|
|
After doing this, you can set up your assets by copying them from node_modules/uswds/dist, and then running a basic npm script, npm run build:watch (watch allows npm to continuously watch uswds.scss for any changes) to compile the CSS. The commands to do all of this are:
|
|
|
|
|
|
|
|
- `npm install` (adds a node_modules directory in the commerce subtheme)
|
|
|
|
- `cp -r node_modules/uswds/dist assets`
|
|
|
|
- `drush pm-install uswds` enables the main theme
|
|
|
|
- `drush pm-install commerce` enables the subtheme
|
|
|
|
- `npm run build:watch` (:watch allows npm to continuously watch uswds.scss for any changes)
|
|
|
|
|
|
|
|
**Menus**
|
|
|
|
|
|
|
|
In USWDS there are four styles of menus: Primary menu, Secondary menu (upper right, by "Search"), Footer menu, and Sidenav. You can implement these menus simply by placing a menu block into the appropriate region. (Eg, you would put the menu block for your primary menu in the "Primary menu" region.) There is also an optional "Mobile menu" region where you can specify the menu to be used for mobile. If left empty, it defaults to whatever you have in your primary and secondary menus.
|
|
|
|
|
|
|
|
**Configuration**
|
|
|
|
|
|
|
|
After installation, see the theme settings inside Drupal for various customizations, mostly involving the header and the footer.
|
|
|
|
|
|
|
|
**Complex components via Paragraphs**
|
|
|
|
|
|
|
|
A separate project providing some Paragraph types is available here: USWDS Paragraphs.
|
|
|
|
|
|
|
|
**CKEditor's "Style" dropdown**
|
|
|
|
|
|
|
|
To add some USWDS-specific entries into the CKEditor "Style" dropdown, follow this procedure:
|
|
|
|
|
|
|
|
Drupal 8: Configure your text formats and add this (customized to your liking) in the "Styles dropdown" section:
|
|
|
|
- a.usa-button|Button
|
|
|
|
- a.usa-button.usa-button-gray|Button - Gray
|
|
|
|
- a.usa-button.usa-button-outline|Button - Outline
|
|
|
|
- a.usa-button.usa-button-outline-inverse|Button - Outline Inverse
|
|
|
|
- a.usa-button.usa-button-big|Button - Big
|
|
|
|
- a.usa-button.usa-button-secondary|Button - Secondary
|
|
|
|
- table.usa-table-borderless|Borderless Table
|
|
|
|
- p.usa-font-lead|Lead font
|
|
|
|
|
|
|
|
**Resources**
|
|
|
|
|
|
|
|
- An invaluable YouTube video, www.youtube.com/watch?v=7_6Q7rqHCVY&t=1106s, by the original tech lead for the USWDS v01 theme, Brock Fanning called “Put the U.S. Web Design Standards to work in your next Drupal project” takes you through the steps described above.
|
|
|
|
- USWDS was created by a collaborative team at 18F and the U.S. Digital Service. Here is the website that describes the specifications used for the USWDS base theme for Drupal: https://designsystem.digital.gov/
|
|
|
|
|
