Remove "Usage" section of design.login.gov

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - USWDS is upgraded to the latest version, from v2.9.0 to v2.11.2.
   - The bordered and large styles of checkboxes and radio buttons have updated guidance to improve compatibility with the [USWDS tile style](https://designsystem.digital.gov/components/radio-buttons/). The classes `usa-radio-bordered`, `usa-radio-large`, `usa-checkbox-bordered`, and `usa-checkbox-large` have been removed. Instead, add `usa-radio__input--bordered`, `usa-radio__input--tile`, `usa-checkbox__input-bordered`, `usa-checkbox__input--tile` respectively as modifiers to the element with the class `usa-radio__input` or `usa-checkbox__input`.
+- The Accordion component no longer includes a "Close" button. Remove any instances of `<button class="usa-accordion__close-button">` in your project, or references to the `accordionCloseButton` exported member of the JavaScript package.
 
 ## 5.1.0
 
@@ -111,7 +112,7 @@
 
 ### New Features
 
-- The published NPM package can now be imported into a project. Bundlers that support dead-code elimination (Webpack, etc.) can automatically remove unused code to optimize bundle size. See [Usage guide](https://design.login.gov/usage/) for more information. Existing usage of JavaScript code from `dist/assets/` is unaffected by these changes.
+- The published NPM package can now be imported into a project. Bundlers that support dead-code elimination (Webpack, etc.) can automatically remove unused code to optimize bundle size. Existing usage of JavaScript code from `dist/assets/` is unaffected by these changes.
 
 ### Bug Fixes
 

README.md

@@ -1,10 +1,14 @@
 # Login.gov Design System
 
-## Installation and usage
+This repository contains the code for the Login.gov Design System. The documentation in here includes resources for both how to install locally, but also in various development environments.
 
-See [the documentation](https://design.login.gov/) for installation and usage instructions.
+1. [Installation](#installation-local)
+1. [Testing](#testing)
+1. [Deploying documentation updates](#deploying-documentation-updates)
+1. [Publishing a release to `npm`](#releases)
+1. [Usage](#usage)
 
-## Configuring for development
+## Installation (Local)
 
 The following dependencies are required to build the documentation and assets within this repository:
 
@@ -24,7 +28,9 @@ In development, build the documentation site with assets, watch source files for
 npm start
 ```
 
-## Linting
+## Testing
+
+### Linting
 
 [Lint](https://en.wikipedia.org/wiki/Lint_(software)) JavaScript and Sass files in `src/` by running:
 
@@ -38,7 +44,7 @@ This project uses [Prettier](https://prettier.io/) to format code. When running
 npm run lint -- --fix
 ```
 
-## Visual regression tests
+### Visual regression testing
 
 When a pull request is submitted, a visual regression test will be automatically run to check for any visual changes between the working copy of the branch and the live documentation site. These will be reported as the `ci/circleci: visual-regression` GitHub status check.
 
@@ -55,7 +61,7 @@ Documentation deploys are performed automatically upon merging to `main` by [Fed
 
 More information can be found in Federalist’s [How Builds Work](https://federalist-docs.18f.gov/pages/how-federalist-works/how-builds-work/).
 
-## Publishing a release to `npm`
+## Releases
 
 When you're ready to release a new version of the `identity-style-guide` package there are just a few steps to take.
 
@@ -81,3 +87,139 @@ Before starting, make sure that all changes intended for release should be merge
    - The release version should match the version just published to `npm` (for example, `v2.1.5`).
    - Use the version name as the release title.
    - Use the release notes to link to any important issues or pull requests that were addressed in the release. You may copy this from `CHANGELOG.md`.
+
+## Usage
+
+Below are various ways to use the Login.gov Design System throughout our various products.
+
+### Ruby on Rails (Rails)
+
+ The SCSS files natively support `asset-path()` out-of-the-box for ease of use with the Rails Asset Pipeline. To use with Rails, configure Rails to look for assets in both `node_modules` and the identity-style-guide module:
+
+ ```ruby
+ # config/initializers/assets.rb
+
+ Rails.application.config.assets.paths << Rails.root.join('node_modules')
+ Rails.application.config.assets.paths << Rails.root.join('node_modules/identity-style-guide/dist/assets')
+ ```
+
+ Finally, import the styles into your main stylesheet:
+
+ ```scss
+ // app/assets/stylesheets/application.css.scss
+
+ $font-path: 'fonts';
+ $image-path: 'img';
+
+ @import 'identity-style-guide/dist/assets/scss/styles';
+ ```
+
+ If you're using Sprockets and precompiling assets you'll need to update your
+ Sprockets manifest to include the images and fonts for production:
+
+ ```js
+ // app/assets/config/manifest.js
+
+ //= link_tree ../../../node_modules/identity-style-guide/dist/assets/img
+ //= link_tree ../../../node_modules/identity-style-guide/dist/assets/fonts
+ ```
+
+ Unfortunately, this results in the assets being saved under paths that include
+ everything after the `node_modules` directory, so a helper method is useful in
+ cleaning up the views:
+
+ ```ruby
+ # app/helpers/assets_helper.rb
+
+ module AssetsHelper
+   def login_design_asset_path(path)
+     "identity-style-guide/dist/assets/#{path}"
+   end
+ end
+ ```
+
+ ```erb
+ # app/views/foo.html.erb
+
+ <%= image_tag login_design_asset_path('img/us_flag_small.png'), ... %>
+
+ # app/views/layouts/application.html.erb
+
+ <head>
+   ...
+   <%= favicon_link_tag identity_asset_path('img/favicons/favicon.ico') %>
+ </head>
+ ```
+
+ Finally, if you're using Webpacker you'll need to reference the JS files in the
+ default pack:
+
+ ```js
+ // app/javascript/packs/application.js
+
+ require("identity-style-guide/dist/assets/js/main")
+ ```
+
+### JavaScript package
+
+  If you're already using a JavaScript bundler in your project, you can import specific component implementations from the `identity-style-guide` package. Most modern bundlers that support dead-code elimination will automatically optimize the bundle size to include only the code necessary in your project.
+
+  ```js
+  import { accordion } from 'identity-style-guide';
+
+  accordion.on();
+  ```
+
+  Note that unlike the pre-built JavaScript assets found in the `dist/assets` directory, importing the package from NPM will not automatically initialize the components on the page or include polyfills necessary to support older browsers. You will have to call the `on()` method for each component you import.
+
+  If you need support for older browsers in your project, it's suggested you import polyfills shipped with the `uswds` package and import it before any components:
+
+  ```
+  npm install uswds
+  ```
+
+  ```js
+  import 'uswds/src/js/polyfills';
+  import { accordion } from 'identity-style-guide';
+  ```
+
+### Jekyll
+
+If you’re using Jekyll, a simple plugin can help copy this file during your build process to keep your assets up-to-date. First, add this file to `_plugins/`:
+
+```ruby
+# _plugins/copy_to_destination.rb
+
+module Jekyll
+  module CopyToDestination
+    class CopyGenerator < Generator
+      def generate(site)
+        folders = site.config['copy_to_destination'] || []
+
+        static_files = folders.map do |relative_path|
+          absolute_path = File.join(site.source, relative_path)
+          folder_path = File.dirname(absolute_path)
+          entries = Dir.glob(File.join(absolute_path, '**', '*'))
+          files = entries.select { |f| File.file?(f) }
+
+          files.map do |file|
+            relative_directory = File.dirname(file).sub(folder_path, '')
+            filename = File.basename(file)
+            StaticFile.new(site, folder_path, relative_directory, filename)
+          end
+        end.flatten
+
+        site.static_files.concat(static_files)
+      end
+    end
+  end
+end
+```
+
+Then, configure it to copy the compiled assets to your site output folder:
+
+```yaml
+# _config.yml
+
+copy_to_destination:
+  - node_modules/identity-style-guide/dist/assets

docs/_components/accordions.md

@@ -20,7 +20,6 @@ Before using an accordion, consider if their use would hinder usability. If ther
     <div class="usa-accordion__content usa-prose">
       <p>Follow this example! Mark the <code>.usa-accordion__button</code> with <code>aria-expanded="true"</code> to indicate that the content referenced with the ID listed in <code>aria-controls</code> is expanded by default, and omit the <code>hidden</code> attribute on the related <code>.usa-accordion__content</code>.</p>
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 
   <h2 class="usa-accordion__heading">
@@ -32,7 +31,6 @@ Before using an accordion, consider if their use would hinder usability. If ther
     <div class="usa-accordion__content usa-prose">
       <p>Do not mark any attributes, other than linking a header and content body by <code>aria-controls="unique-id"</code> and <code>id="unique-id"</code>. This ensures the content is accessible should JavaScript fail to load.</p>
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 
   <h2 class="usa-accordion__heading">
@@ -44,7 +42,6 @@ Before using an accordion, consider if their use would hinder usability. If ther
     <div class="usa-accordion__content usa-prose">
       <p>On the wrapping <code>.usa-accordion</code>, add the <code>aria-multiselectable="true"</code> attribute.</p>
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 </div>
 {% endcapture %}

docs/_components/form-fields.md

@@ -314,7 +314,6 @@ Follow the same pattern of applying `.usa-input--error` to the effected input an
 {% endcapture %}
 {% include helpers/code-example.html code=example %}
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 
   <h3 class="usa-accordion__heading">
@@ -347,7 +346,6 @@ Follow the same pattern of applying `.usa-input--error` to the effected input an
 {% endcapture %}
 {% include helpers/code-example.html code=example %}
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 
   <h3 class="usa-accordion__heading">
@@ -369,7 +367,6 @@ Follow the same pattern of applying `.usa-input--error` to the effected input an
 {% endcapture %}
 {% include helpers/code-example.html code=example %}
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 </div>
 
@@ -407,7 +404,6 @@ For radio buttons and checkboxes, simply add an error message directly after the
 {% endcapture %}
 {% include helpers/code-example.html code=example %}
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 
   <h3 class="usa-accordion__heading">
@@ -439,6 +435,5 @@ For radio buttons and checkboxes, simply add an error message directly after the
 {% endcapture %}
 {% include helpers/code-example.html code=example %}
     </div>
-    <button class="usa-accordion__close-button">Close</button>
   </div>
 </div>

docs/_data/nav.yml

@@ -1,5 +1,4 @@
 primary:
-  - href: /usage/
   - href: /brand/
   - href: /content/
   - href: /images/

docs/index.md

@@ -14,7 +14,7 @@ lead: >
           The key to a strong brand <br>is <span class="text-accent-cool">consistency</span>.
         </div>
         <p class="usa-intro">{{ page.lead }}</p>
-        <a href="{{ site.baseurl }}/usage/" class="usa-button usa-button--big">See usage instructions</a>
+        <a href="https://github.com/18F/identity-style-guide#installation-local" class="usa-button usa-button--big">See install instructions on GitHub</a>
       </div>
     </div>
   </div>