Merge pull request #361 from 18F/release-1.3.0

Release 1.3.0

.gitignore

@@ -7,3 +7,4 @@ node_modules/
 npm-debug.log
 .bundle/
 assets/
+.jekyll_get_cache/

Gemfile

@@ -3,11 +3,13 @@ source 'https://rubygems.org'
 gem 'jekyll'
 gem 'json'
 gem 'redcarpet'
-gem 'hash-joiner'
 gem 'open-uri-cached'
 gem 'jekyll-redirect-from'
 
 gem 'rouge', '1.9'
 gem 'scss_lint', require: false
 
 gem 'jekyll-compose', group: [:jekyll_plugins]
+
+gem 'rspec-core'
+gem 'rspec-expectations'

Gemfile.lock

@@ -4,10 +4,9 @@ GEM
     addressable (2.5.1)
       public_suffix (~> 2.0, >= 2.0.2)
     colorator (1.1.0)
+    diff-lcs (1.3)
     ffi (1.9.18)
     forwardable-extended (2.6.0)
-    hash-joiner (0.0.7)
-      safe_yaml
     jekyll (3.4.3)
       addressable (~> 2.4)
       colorator (~> 1.0)
@@ -44,6 +43,12 @@ GEM
       ffi (>= 0.5.0)
     redcarpet (3.3.4)
     rouge (1.9.0)
+    rspec-core (3.6.0)
+      rspec-support (~> 3.6.0)
+    rspec-expectations (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-support (3.6.0)
     safe_yaml (1.0.4)
     sass (3.4.23)
     scss_lint (0.50.2)
@@ -54,15 +59,16 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  hash-joiner
   jekyll
   jekyll-compose
   jekyll-redirect-from
   json
   open-uri-cached
   redcarpet
   rouge (= 1.9)
+  rspec-core
+  rspec-expectations
   scss_lint
 
 BUNDLED WITH
-   1.14.6
+   1.15.1

README.md

@@ -17,7 +17,7 @@ You will need to have the following installed on your machine before following t
 1. Ruby v2.2.2+, [Installation guides](https://www.ruby-lang.org/en/documentation/installation/)
 1. Node v4.2.3+, [Installation guides](https://nodejs.org/en/download/)
 1. Bundler v1.12.3+, [Installation guides](http://bundler.io/v1.13/guides/using_bundler_in_application.html#getting-started---installing-bundler-and-bundle-init)
-
+1. Chrome v59 or higher (v60 if on Windows)
 
 ### Building the documentation with gulp
 
@@ -43,7 +43,7 @@ Here are a few other utility commands you may find useful:
 
 - `npm run lint`: Runs `eslint` and `sass-lint` against JavaScript and Sass files.
 
-- `npm test`: Runs `npm run lint` and can also be used to run any tests.
+- `npm test`: Runs all tests and linters.
 
 - `npm run watch`: Runs a series of commands that watches for any changes in both the Standards node module and the root level asset folders in this repo.
 
@@ -76,6 +76,23 @@ https://federalist.fr.cloud.gov/preview/18f/web-design-standards-docs/develop/
 
 See the [`_posts` directory](_posts/#readme) for instructions on adding updates.
 
+### Dynamic content
+
+Some of the content on the documentation site is dynamically fetched from
+GitHub. If you want to ensure that its API won't rate-limit you, you
+may want to
+[create an access token](https://github.com/blog/1509-personal-api-tokens)
+and assign it to your `GITHUB_ACCESS_TOKEN` environment variable.
+
+The dynamic content is stored in the `.jekyll_get_cache` directory and
+won't be re-fetched once it's cached there. However, this means that your
+data can get stale over time, so if you want to ensure that your site
+is using the very latest data, you'll want to clear the cache by running:
+
+```
+rm -rf .jekyll_get_cache
+```
+
 ## Contributing
 
 Please read through our [contributing guidelines](CONTRIBUTING.md). These guidelines are directions for opening issues and submitting pull requests, and they also detail the coding and design standards we follow.

_components/buttons.md

@@ -30,7 +30,7 @@ lead: Use buttons to signal actions.
       <li><code>usa-button-big</code></li>
     </ul>
     <p>For example, a secondary button style would use the following code:
-    <code>&lt;a class="usa-button usa-button-secondary" href="/my-link"&gt;My button&lt;/a&gt;</code></p>
+    <code>&lt;a class="usa-button usa-button-secondary" href=&quot;/my-link"&gt;My button&lt;/a&gt;</code></p>
     <h4 class="usa-heading">Accessibility</h4>
     <ul class="usa-content-list">
       <li>Buttons should display a visible focus state when users tab to them.</li>

_components/form-controls/06-validation.md

@@ -0,0 +1,43 @@
+---
+title: Validation
+parent: Form controls
+maturity: alpha
+order: 06
+lead: Stating validation requirements up front, with live feedback, means users won't be left guessing.
+---
+
+{% include code/preview.html component="validation" %}
+{% include code/accordion.html component="validation" %}
+<div class="usa-accordion-bordered">
+  <button class="usa-button-unstyled usa-accordion-button"
+      aria-expanded="true" aria-controls="validation-docs">
+    Documentation
+  </button>
+  <div id="validation-docs" aria-hidden="false" class="usa-accordion-content">
+    <h4 class="usa-heading">Guidance</h4>
+    <ul class="usa-content-list">
+      <li>Input fields which have custom validation logic can automatically
+        provide helpful feedback to users if they are assigned a
+        <code>data-validation-element</code> attribute set to a
+        CSS selector that uniquely identifies a <code>.usa-checklist</code>,
+        e.g. <code>data-validation-element="#validate-code"</code>.</li>
+      <li>
+        For each kind of validation you'd like to provide feedback on:
+        <ol>
+          <li>Come up with a name for the validator, e.g.
+            <code>uppercase</code>. It shouldn't have any spaces in it.</li>
+          <li>On one of the list elements in the <code>.usa-checklist</code>,
+            set the <code>data-validator</code> attribute to the
+            name of the validator, e.g. <code>data-validator="uppercase"</code>.
+            This is the list item that will appear "checked" when the
+            validator's condition is met.</li>
+          <li>On the input field, add a field called
+            <code>data-validate-<em>validator name</em></code> and set
+            its value to a <a href="https://regexone.com/">regular
+            expression</a> that represents whether the validator's
+            condition is met, e.g. <code>data-validate-uppercase="[A-Z]"</code>.</li>
+        </ol>
+      </li>
+    </ul>
+  </div>
+</div>

_components/form-controls/form-controls.md

@@ -18,6 +18,8 @@ subnav:
   href: '#radio-buttons'
 - text: Date input
   href: '#date-input'
+- text: Validation
+  href: '#validation'
 ---
 
 {% include accessibility.html %}

_components/form-templates/04-password-reset-form.md

@@ -25,6 +25,8 @@ lead: A standard template for resetting a password
     <h5>Guidance</h5>
     <ul class="usa-content-list">
       <li>If users need a password to access your site, they will forget that password and need a way to reset it.</li>
+      <li>For guidance on the technical details of validation, see the
+        <a href="/components/form-controls/#validation">validation documentation</a>.</li>
       <li>State any password requirements (for example, “Must include one capital letter”) up front. Don’t leave users guessing about password requirements, only to hit them with an error message later.</li>
       <li>The requirements shown above are just provided as an example and should not be taken as recommendations.</li>
     </ul>

_components/page-templates/template-docs.html

@@ -55,7 +55,7 @@
           <button class="usa-menu-btn">Menu</button>
           <div class="usa-logo" id="logo">
             <em class="usa-logo-text">
-              <a href="#" title="Home" aria-label="Home">Federal <br>Agency Name</a>
+              <a href="#" title="Home" aria-label="Federal Agency Name Home">Federal <br>Agency Name</a>
             </em>
           </div>
         </div>

_components/page-templates/template-landing.html

@@ -54,7 +54,7 @@
         <button class="usa-menu-btn">Menu</button>
         <div class="usa-logo" id="logo">
           <em class="usa-logo-text">
-            <a href="#" title="Home" aria-label="Home">Federal Agency Name</a>
+            <a href="#" title="Home" aria-label="Federal Agency Name Home">Federal Agency Name</a>
           </em>
         </div>
       </div>

_components/typography/03-typesetting.md

@@ -20,7 +20,7 @@ order: 03
     <h4 class="usa-heading">Implementation</h4>
     <p>To get the max-width on body text, add the class <code>usa-content</code> to your document. Use at the specificity that best suits your project's needs.</p>
     <p>Lists must use <code>usa-content-list</code> for the above.</p>
-    <p>You can change the max-width value <code>$text-max-width</code> in <code>assets/_scss/core/<wbr>variables.scss</code>.</p>
+    <p>You can change the max-width value <code>$text-max-width</code> in <code>src/stylesheets/core/<wbr>_variables.scss</code>.</p>
     <h4 class="usa-heading">Usability</h4>
     <ul class="usa-content-list">
       <li>Alignment: Type set flush left provides the eye a constant starting point for each line, making text easier to read.</li>

_components/typography/05-lists.md

@@ -18,7 +18,7 @@ order: 05
   </button>
   <div id="list-docs" class="usa-accordion-content">
     <h4 class="usa-heading">Implementation</h4>
-    <p>Lists are styled by default. For unstyled lists, use either the <code>usa-unstyled-list</code> class or unstyled list mixin: <code>@include unstyled-list;</code>. Both are located in <code>assets/_scss/core/<wbr>utilities.scss</code>.</p>
+    <p>Lists are styled by default. For unstyled lists, use either the <code>usa-unstyled-list</code> class or unstyled list mixin: <code>@include unstyled-list;</code>. Both are located in <code>src/stylesheets/core/<wbr>_utilities.scss</code>.</p>
     <h4 class="usa-heading">Usability</h4>
     <h5>When to use</h5>
     <ul class="usa-content-list">

_config.yml

@@ -1,6 +1,5 @@
 # Site settings
 title:  U.S. Web Design Standards
-version: 1.1.0
 google_analytics_ua: UA-48605964-43
 
 # this is for pages that don't have a permalink (primarily posts)
@@ -11,13 +10,22 @@ future: true
 
 encoding: utf-8
 
+incremental_regeneration_fixer:
+  interdependent_files:
+    - "_components/colors/*"
+    - "_components/form-controls/*"
+    - "_components/form-templates/*"
+    - "_components/typography/*"
+
 jekyll_get:
   - data: releases
     json: 'https://api.github.com/repos/18F/web-design-standards/releases'
   - data: contributing
     json: 'https://api.github.com/repos/18F/web-design-standards/contents/CONTRIBUTING.md'
+    decode_content: true
   - data: standards-sites
     json: 'https://api.github.com/repos/18F/web-design-standards/contents/WHO_IS_USING_USWDS.md'
+    decode_content: true
 
 repos:
 - name: U.S. Web Design Standards

_data/implementations.yml

@@ -6,6 +6,15 @@
   version: 0.12.0
   notes: "This package provides access to the Standards in [Django](https://www.djangoproject.com/) applications."
 
+- name: Django
+  url: http://django-uswds-forms.readthedocs.io/en/latest/
+  author:
+    name: 18F
+    url: https://github.com/18F
+  version: 0.0.3
+  notes: |
+    This package provides Django Forms integration with the Standards.
+
 - name: Drupal
   url: https://www.drupal.org/project/uswds
   author:
@@ -14,6 +23,14 @@
   version: 1.x
   notes: "This base theme focuses on tweaking 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."
 
+- name: Jekyll
+  url: https://github.com/18f/uswds-jekyll
+  author:
+    name: 18F
+    url: https://github.com/18F
+  version: 1.1.1
+  notes: "A [Jekyll](https://jekyllrb.com/) theme for the Standards."
+
 - name: npm and node-sass
   url: https://github.com/openbrian/18f-contrib-web-design-standards
   author:

_includes/code/components/date-input.html

@@ -5,15 +5,15 @@
   <div class="usa-date-of-birth">
     <div class="usa-form-group usa-form-group-month">
       <label for="date_of_birth_1">Month</label>
-      <input class="usa-input-inline" aria-describedby="dobHint" class="usa-form-control" id="date_of_birth_1" name="date_of_birth_1" pattern="0?[1-9]|1[012]" type="number" min="1" max="12" value="">
+      <input class="usa-input-inline" aria-describedby="dobHint" id="date_of_birth_1" name="date_of_birth_1" pattern="0?[1-9]|1[012]" type="number" min="1" max="12" value="">
     </div>
     <div class="usa-form-group usa-form-group-day">
       <label for="date_of_birth_2">Day</label>
-      <input class="usa-input-inline" aria-describedby="dobHint" class="usa-form-control" id="date_of_birth_2" name="date_of_birth_2" pattern="0?[1-9]|1[0-9]|2[0-9]|3[01]" type="number" min="1" max="31" value="">
+      <input class="usa-input-inline" aria-describedby="dobHint" id="date_of_birth_2" name="date_of_birth_2" pattern="0?[1-9]|1[0-9]|2[0-9]|3[01]" type="number" min="1" max="31" value="">
     </div>
     <div class="usa-form-group usa-form-group-year">
       <label for="date_of_birth_3">Year</label>
-      <input class="usa-input-inline" aria-describedby="dobHint" class="usa-form-control" id="date_of_birth_3" name="date_of_birth_3" pattern="[0-9]{4}" type="number" min="1900" max="2000" value="">
+      <input class="usa-input-inline" aria-describedby="dobHint" id="date_of_birth_3" name="date_of_birth_3" pattern="[0-9]{4}" type="number" min="1900" max="2000" value="">
     </div>
   </div>
 </fieldset>

_includes/code/components/header-basic-mega.html

@@ -39,7 +39,7 @@
       <button class="usa-menu-btn">Menu</button>
       <div class="usa-logo" id="logo">
         <em class="usa-logo-text">
-          <a href="#" accesskey="1" title="Home" aria-label="Home">Department of <br>Web Standards</a>
+          <a href="#" accesskey="1" title="Home" aria-label="Department of Web Standards Home">Department of <br>Web Standards</a>
         </em>
       </div>
     </div>

_includes/code/components/header-basic.html

@@ -39,7 +39,7 @@
       <button class="usa-menu-btn">Menu</button>
       <div class="usa-logo" id="logo">
         <em class="usa-logo-text">
-          <a href="#" accesskey="1" title="Home" aria-label="Home">Department of <br>Web Standards</a>
+          <a href="#" accesskey="1" title="Home" aria-label="Department of Web Standards Home">Department of <br>Web Standards</a>
         </em>
       </div>
     </div>

_includes/code/components/header-extended-mega.html

@@ -38,7 +38,7 @@
     <button class="usa-menu-btn">Menu</button>
     <div class="usa-logo" id="logo">
       <em class="usa-logo-text">
-        <a href="#" accesskey="1" title="Home" aria-label="Home">Department of Web Standards</a>
+        <a href="#" accesskey="1" title="Home" aria-label="Department of Web Standards Home">Department of Web Standards</a>
       </em>
     </div>
   </div>

_includes/code/components/header-extended.html

@@ -38,7 +38,7 @@
     <button class="usa-menu-btn">Menu</button>
     <div class="usa-logo" id="logo">
       <em class="usa-logo-text">
-        <a href="#" accesskey="1" title="Home" aria-label="Home">Department of Web Standards</a>
+        <a href="#" accesskey="1" title="Home" aria-label="Department of Web Standards Home">Department of Web Standards</a>
       </em>
     </div>
   </div>

_includes/code/components/password-reset.html

@@ -18,7 +18,6 @@ <h3 class="usa-alert-heading">Passwords must:</h3>
     <label for="new-password">New password</label>
     <input id="new-password" name="password" type="password"
       aria-describedby="validate-password-reset"
-      class="js-validate_password"
       data-validate-length=".{8,}"
       data-validate-uppercase="[A-Z]"
       data-validate-numerical="\d"

_includes/code/components/template-docs.html

@@ -49,7 +49,7 @@
         <button class="usa-menu-btn">Menu</button>
         <div class="usa-logo" id="logo">
           <em class="usa-logo-text">
-            <a href="#" accesskey="1" title="Home" aria-label="Home">Federal <br>Agency Name</a>
+            <a href="#" accesskey="1" title="Home" aria-label="Federal Agency Name Home">Federal <br>Agency Name</a>
           </em>
         </div>
       </div>

_includes/code/components/template-landing.html

@@ -48,7 +48,7 @@
       <button class="usa-menu-btn">Menu</button>
       <div class="usa-logo" id="logo">
         <em class="usa-logo-text">
-          <a href="#" accesskey="1" title="Home" aria-label="Home">Federal Agency Name</a>
+          <a href="#" accesskey="1" title="Home" aria-label="Federal Agency Name Home">Federal Agency Name</a>
         </em>
       </div>
     </div>

_includes/code/components/validation.html

@@ -0,0 +1,24 @@
+<form class="usa-form">
+  <fieldset>
+    <legend class="usa-drop_text">Enter a code</legend>
+
+    <div class="usa-alert usa-alert-info">
+      <div class="usa-alert-body">
+        <h3 class="usa-alert-heading">Codes must:</h3>
+      </div>
+      <ul class="usa-checklist" id="validate-code">
+        <li data-validator="uppercase">Have at least 1 uppercase character</li>
+        <li data-validator="numerical">Have at least 1 numerical character</li>
+      </ul>
+    </div>
+
+    <label for="code">Code</label>
+    <input id="code" name="code" type="text"
+      aria-describedby="validate-code"
+      data-validate-uppercase="[A-Z]"
+      data-validate-numerical="\d"
+      data-validation-element="#validate-code">
+
+    <input type="submit" value="Submit code">
+  </fieldset>
+</form>