Merge pull request #114 from GSA/gh-pages-staging

[Release]: Update to 0.2.4
GSA · Sep 6, 2016 · 3a9e9c1 · 3a9e9c1
2 parents de04bce + 0e161c0
commit 3a9e9c1
Show file tree

Hide file tree

Showing 296 changed files with 3,574 additions and 10,749 deletions.
diff --git a/.gitignore b/.gitignore
@@ -37,6 +37,12 @@ dist/
 #       we should see if it is possible to do so by using web hooks or an integration
 #       provider to perform the Jekyll build and Gulp commands.
 #
+#       See /src/js/vendor/uswds/start.js for notes on why it is being kept. Do not
+#       delete this file or its parent folder.
+#
+/src/stylesheets/lib
+/src/js/vendor/
+!/src/js/vendor/uswds/start.js
 # /assets/
 # !assets/img
 # !assets/css/homepage.scss

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,25 @@
-# Welcome!
+<ul>
+  <li><a href="#welcome">Welcome</a></li>
+  <li>
+    <a href="#guidelines">Guidelines</a>
+    <ul>
+      <li><a href="#submitting-issues">Submitting issues and recommendations</a></li>
+      <li><a href="#submitting-prs">Submitting pull requests</a></li>
+      <li><a href="#building-gulp">Building the site locally with gulp</a></li>
+      <li><a href="#what-to-change">What do I change?</a></li>
+    </ul>
+  </li>
+  <li><a href="#prioritization">Prioritization</a></li>
+  <li>
+    <a href="#licenses">Licenses and attribution</a>
+    <ul>
+      <li><a href="#not-public-domain">A few parts of this project are not in the public domain</a></li>
+      <li><a href="#public-domain">The rest of this project is in the public domain</a></li>
+    </ul>
+  </li>
+</ul>
+
+<h1 id="welcome">Welcome!</h1>
 
 We're so glad you're thinking about contributing! If you're unsure about anything, just ask — or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We appreciate all friendly contributions.
 
@@ -8,9 +29,9 @@ We encourage you to read this project's CONTRIBUTING policy (you are here), its
 
 If you have any questions or want to read more, check out the [18F Open Source Policy GitHub repository]( https://github.com/18f/open-source-policy), or just [shoot us an email](#).
 
-## Guidelines
+<h2 id="guidelines">Guidelines</h2>
 
-### Submitting an issue or recommendation
+<h3 id="submitting-issues">Submitting an issue or recommendation</h3>
 
 While it is not necessary to use this format, it would be helpful if, when submitting an issue, it contained the following:
 
@@ -26,7 +47,7 @@ While it is not necessary to use this format, it would be helpful if, when submi
 
 *Include any images, steps to recreate, notes, emojis, or whatever.*
 
-### Submitting a pull request
+<h3 id="submitting-prs">Submitting a pull request</h3>
 
 Here are a few guidelines to follow when submitting a pull request:
 
@@ -38,9 +59,9 @@ Here are a few guidelines to follow when submitting a pull request:
 1. Once you're ready to submit a pull request, push your branch up to the repo.
 1. Submit your pull request against the `gh-pages-staging` branch.
 
-Have questions or need help with setup? Open an issue here [https://github.com/joshbruce/sam-design-standards/issues](https://github.com/joshbruce/sam-design-standards/issues).
+Have questions or need help with setup? Open an issue here [https://github.com/gsa/sam-design-standards/issues](https://github.com/joshbruce/sam-design-standards/issues).
 
-### Building the project locally with gulp
+<h3 id="building-gulp">Building the site locally with gulp</h3>
 
 You've cloned the repository. Now, we just have to make sure your environment can do what it needs to in order to serve the site locally. 
 
@@ -110,7 +131,7 @@ Note: For a list of available gulp commands use:
 `$ gulp`
 
 
-### What do I change?
+<h3 id="what-to-change">What do I change?</h3>
 
 Anything. It will be up to the core team for the SAM Web Design Standards to determine whether to integrate the changes. 
 
@@ -126,15 +147,28 @@ Don't worry about breaking anything in the approved version. Until it is committ
 
 Go. Play!
 
-## Licenses and attribution
+<h2 id="prioritization">Prioritization of Issues</h2>
 
-### A few parts of this project are not in the public domain
+We would like to avoid accumulating technical debt; instead, we would like to build technical credit. Therefore, we have established an overarching prioritization strategy.
+
+When you consider taking on an issue, consider the following, in turn:
+
+1. Level 1 defect: We want to fix what is broken as soon as possible.
+2. Level 2 defect: We want to improve the experience for users before creating new experiences or features.
+3. Refactor and re-engineer: We want to improve the maintainability and increase reuse of the code.
+4. New features: We add new features based on requests from users and the community, and preferably *after* all known Level 1 and 2 defects are solved, refactored and re-engineered.
+
+Our goal is to only ship if there are no known Level 1 defects. The other three issue types are not fundamental to the functionality of the system or package.
+
+<h2 id="licenses">Licenses and attribution</h2>
+
+<h3 id="not-public-domain">A few parts of this project are not in the public domain</h3>
 
 The Standards inherit from the [U.S. Web Design Standards](https://standards.usa.gov) distributed by 18f. Thereby, inheriting the licenses and attributions of that project.
 
 Some files in ```/dist/fonts``` and ```/dist``` Standards incorporate [Font Awesome](http://fontawesome.io/) by Dave Gandy under the [SIL Open Font License 1.1](http://scripts.sil.org/OFL).
 
-### The rest of this project is in the public domain
+<h3 id="public-domain">The rest of this project is in the public domain</h3>
 
 The rest of this project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):
 

diff --git a/_docs/components/accordions.md b/_docs/components/accordions.md
@@ -6,4 +6,4 @@ type: component
 title: Accordions
 ---
 
-{% include components/accordions.html %}
+{% include styleguide/components/accordions.html %}
diff --git a/_docs/components/alerts.md b/_docs/components/alerts.md
@@ -6,4 +6,4 @@ type: component
 title: Alerts
 ---
 
-{% include components/alerts.html %}
+{% include styleguide/components/alerts.html %}
diff --git a/_docs/components/form-templates.md b/_docs/components/form-templates.md
@@ -7,14 +7,14 @@ title: Form templates
 lead: See <a class="usa-external_link" href="https://standards.usa.gov/form-templates/">US Web Design Standards</a> for details regarding when to use these components.
 ---
 
-{% include components/nameform.html %}
+{% include styleguide/components/nameform.html %}
 
-{% include components/addressform.html %}
+{% include styleguide/components/addressform.html %}
 
-{% include components/signinform.html %}
+{% include styleguide/components/signinform.html %}
 
-{% include components/registrationform.html %}
+{% include styleguide/components/registrationform.html %}
 
-{% include components/inlinefeedbackform_quick.html %}
+{% include styleguide/components/inlinefeedbackform_quick.html %}
 
-{% include components/supportform.html %}
+{% include styleguide/components/supportform.html %}
diff --git a/_docs/components/navigation.md b/_docs/components/navigation.md
@@ -7,10 +7,10 @@ title: Navigation
 lead: Allows users to orient themselves within the site and move between pages.
 ---
 
-{% include components/header.html %}
+{% include styleguide/components/header.html %}
 
-{% include components/sidenav.html %}
+{% include styleguide/components/sidenav.html %}
 
-{% include components/footers.html %}
+{% include styleguide/components/footers.html %}
 
-{% include components/pagination.html %}
+{% include styleguide/components/pagination.html %}
diff --git a/_docs/components/search.md b/_docs/components/search.md
@@ -6,6 +6,6 @@ type: component
 title: Search
 ---
 
-{% include components/searchbar.html %}
+{% include styleguide/components/searchbar.html %}
 
-{% include components/searchresult.html %}
+{% include styleguide/components/searchresult.html %}
diff --git a/_docs/components/tables.md b/_docs/components/tables.md
@@ -6,4 +6,4 @@ type: component
 title: Tables
 ---
 
-{% include elements/tables.html %}
+{% include styleguide/elements/tables.html %}
diff --git a/_docs/elements/actions-icons.md b/_docs/elements/actions-icons.md
@@ -6,6 +6,6 @@ type: element
 title: Actions & icons
 ---
 
-{% include elements/actions.html %}
+{% include styleguide/elements/actions.html %}
 
-{% include elements/icons.html %}
+{% include styleguide/elements/icons.html %}
diff --git a/_docs/elements/buttons.md b/_docs/elements/buttons.md
@@ -6,5 +6,5 @@ type: element
 title: Buttons
 ---
 
-{% include elements/buttons.html %}
+{% include styleguide/elements/buttons.html %}
 
diff --git a/_docs/elements/form-controls.md b/_docs/elements/form-controls.md
@@ -13,7 +13,7 @@ title: Form controls
         UI kit documentation
       </button>
       <div id="collapsible-2" class="usa-accordion-content" aria-hidden="true">
-        {% include partials/formcontroloverview.html %}
+        {% include code/partials/form-controls-overview.html %}
       </div>
     </li>    
   </ul>
@@ -26,6 +26,21 @@ title: Form controls
   </button>
   <div id="collapsible-0" aria-hidden="false" class="usa-accordion-content">
     <p class="usa-font-lead">See <a class="usa-external_link" href="https://playbook.cio.gov/designstandards/form-controls/">US Web Design Standards</a> for details regarding when to use these elements.</p>
+    <h4 class="usa-heading">Additions to the US Web Design Standards</h4>
+    <h5>Implementation</h5>
+    <ul>
+      <li>All form controls are required to have a label to aid assistive technology users.</li>
+      <li>All labels should identify the form control being referenced (using <code>for</code> and <code>id</code> attributes).</li>
+    </ul>
+
+    <h4 class="usa-heading">Required and optional markings</h4>
+    <p>It may be necessary to mark form controls within a form as &ldquo;required&rdquo; or &ldquo;optional&rdquo; using the <code>usa-additional_text</code> class. See the <a href="{{ site.baseurl }}/components/form-templates/#name-form">Name form</a> and <a href="{{ site.baseurl }}/components/form-templates/#address-form">Address form</a> for examles.</p>
+    <h5>When to use</h5>
+    <ul>
+      <li>If your form consists of all required fields, it is not necessary to mark fields as required or optional.</li>
+      <li>If your form consists of more required fields than optional fields, mark the optional fields, but not the required fields.</li>
+      <li>If your form consists of more optional fields than required, mark the required fields, but not the optional fields.</li>
+    </ul>
 
     <h4 class="usa-heading">Inline help (hint)</h4>
     <p>Eeach form control element is able to incorporate inline help text.</p>
@@ -44,13 +59,13 @@ title: Form controls
 
     <h5>Guidance</h5>
     <ul>
-      <li>Please set Instructional Text at a 132 Character Count.</li>
+      <li>Set Instructional Text at a 132 Character Count.</li>
     </ul>
   </div>
 </div>
 
-{% include elements/text-input.html %}
+{% include styleguide/elements/text-input.html %}
 
-{% include elements/select.html %}
+{% include styleguide/elements/select.html %}
 
-{% include elements/date-input.html %}
+{% include styleguide/elements/date-input.html %}
diff --git a/_docs/elements/tables.md b/_docs/elements/tables.md
@@ -6,4 +6,4 @@ type: element
 title: Tables
 ---
 
-{% include elements/tables.html %}
+{% include styleguide/elements/tables.html %}
diff --git a/_docs/elements/typography.md b/_docs/elements/typography.md
@@ -6,8 +6,8 @@ type: element
 title: Links, lists, & labels
 ---
 
-{% include elements/links.html %}
+{% include styleguide/elements/links.html %}
 
-{% include elements/lists.html %}
+{% include styleguide/elements/lists.html %}
 
-{% include elements/labels.html %}
+{% include styleguide/elements/labels.html %}
diff --git a/_docs/getting-started/developers.md b/_docs/getting-started/developers.md
@@ -31,7 +31,7 @@ Client-side languages, which are executed on the user’s device. Client-side sc
 
 <p>For more details see the <a class="usa-external_link" href="{{ site.repos[0].url }}">GitHub repository</a>.</p>
 
-{% include partials/mobile_first.html %}
+{% include styleguide/partials/mobile_first.html %}
 
 <h2 class="usa-heading" id="bandwidth"> Bandwidth and Processor Speeds</h2>
 
@@ -71,7 +71,7 @@ Further, when developing page addresses and URLs a user should be able to gain a
 
 A feature switch allows you to begin development of a feature, but only have it available in certain environments. Therefore, new features can be merged into the master codebase without negatively impacting continuous integration or deployment.
 
-{% include partials/grid_system.html %}
+{% include styleguide/partials/grid_system.html %}
 
 [^Section508]: [Quick Reference Guide to Section 508 Requirements and Standards 1194.22 (l)](http://www.section508.gov/content/learn/standards/quick-reference-guide#1194.22l)
 [^w3cProgressiveEnhancement]: [World Wide Web Consortium - Graceful degradation versus progressive enhancement](https://www.w3.org/wiki/Graceful_degradation_versus_progressive_enhancement)

diff --git a/_docs/getting-started/user-experience.md b/_docs/getting-started/user-experience.md
@@ -2,48 +2,7 @@
 permalink: /getting-started/user-experience/
 layout: styleguide
 category: Getting started
-title: For user experience designers
-lead: User experience design is the enchances user satisifaction by improving the usability, accessibility, and pleasure provided in the the interaction of a user with the product and includes human-computer interaction, extending it by addressing all aspects of a product or service incorporating cognitive psychology and feedback.
+title: UX Mindset
 ---
 
-## Information architecture
-
-There are two primary ways for a front-end user to find information. The first is through links from one page to another. The second is by searching for content and following links within those results. 
-
-When a front-end user is looking for high-level or general information, the front-end user should be able to navigate the site quickly via static menus. The front-end user may not know exactly where to go or what (s)he is looking for; the architecture can help guide the front-end user by starting broad (categories) and becoming more detailed (a specific notice, wage determination, program, and so on).
-
-When a front-end user knows the information (s)he is looking for, search becomes the better option; therefore, front-end users should be allowed to search using text with additional filtering capabilities within a given category.
-
-### Content
-
-Information Architecture, in terms of content, refers to how content is displayed. This could be the ordering of information within a block of content (chapters within a book, paragraphs within a chapter, sentences within a paragraph, and so on) or how sections of content are arranged within a page.
-
-For the purposes of the *SAM Web Standards* we recognize two primary types of content from a front-end user perspective: content and metadata. Content refers to titles of pages, body copy, attachments, and so on. Metadata refers to details related to *that* content; posting date, related category, and so on.
-
-Grouping content and metadata separately allows you to quickly discern the *content* of a page from the information *about* the content of a page. Further, content and metadata should be ordered, as much as possible, in a way that gives you what you are most likely concerned about first, with the details later. For reference, see the Inverted Pyramid[^InvertedPyramid] from journalism.
-
-### Content-focused and printable
-
-For content pages (as opposed to those designed as portals or navigation), the text-based content should not be overpowered by the surrounding navigation or branding (chrome). Normal operating distance from the screen should be considered (mobile versus tablet, versus lap- or desk-top). 
-
-To allow users the ability to adjust font sizes using their browser, front-end developers and designers should use relative font sizing. Increased leading (the space between lines) makes it easier for readers to discern one line of text from the next.
-
-On any given page, you should be able to print (or print to file) the content of that page and receive a well-formed (readable) document, without chrome elements. Print stylesheets can be used to facilitate this outcome by hiding the navigation elements, sidebars, footers (except copyright information if applicable), and so on. Further, the size of the printed page is usually unknown; therefore, it is important to remove (or override) any fixed width information and replace it with a percentage (usually 100%).
-
-Note: Printing a page should only include content considered public unless you add proper document handling, marking and labeling in accordance with Federal regulations.
-
-## Keep it simple
-
-As the joke goes:
-
-<blockquote>
-  <p>A user interface is like a joke. If you have to explain it, it&rsquo;s not that good.</p>
-  <p><cite><a class="usa-external_link" href="https://www.startupvitamins.com/products/startup-poster-a-user-interface-is-like-a-joke-if-you-have-to-explain-it-its-not-that-good">Poster from Startup Vitamins</a></cite></p>
-</blockquote>
-
-<ul>
-  <li>Keep the user interface and navigation as simple as possible based on user feedback.</li>
-  <li>Use workflows for complex actions to break the work down.</li>
-</ul>
-
-
+{% include documentation/pages/ux-mindset.html %}
diff --git a/_docs/getting-started/visual-style.md b/_docs/getting-started/visual-style.md
@@ -14,7 +14,7 @@ lead: See <a class="usa-external_link" href="https://standards.usa.gov/visual-st
 
 The Standards use the Source Sans Pro <a class="usa-external_link" href="https://standards.usa.gov/typography/#pairings-and-styles">pairing and style</a> and <a class="usa-external_link" href="https://standards.usa.gov/typography/#typesetting">typesetting</a> defined by the US Web Design Standards.
 
-{% include getting-started/typography.html %}
+{% include styleguide/partials/typography.html %}
 
 <h2 id="iconography" class="usa-heading">Iconography</h2>
 
@@ -46,6 +46,6 @@ See the <a class="usa-external_link" href="https://standards.usa.gov/colors/">US
 
 See the <a class="usa-external_link" href="https://standards.usa.gov/colors/">US Web Design Standards - Text accessibility</a>
 
-{% include partials/grid_system.html %}
+{% include styleguide/partials/grid_system.html %}
 
-{% include partials/mobile_first.html %}
+{% include styleguide/partials/mobile_first.html %}
diff --git a/_docs/microsite/overview.md b/_docs/microsite/overview.md
@@ -0,0 +1,9 @@
+---
+permalink: /microsite/
+layout: microsite-default
+category: Microsite
+type: microsite
+title: Microsite
+---
+
+{% include microsite/home.html %}
diff --git a/_docs/microsite/search.md b/_docs/microsite/search.md
@@ -0,0 +1,9 @@
+---
+permalink: /microsite/search
+layout: microsite-default
+category: Microsite
+type: microsite
+title: Search Results
+---
+
+{% include microsite/search.html %}
diff --git a/_docs/page-templates/overview.md b/_docs/page-templates/overview.md
@@ -16,8 +16,8 @@ lead: Page templates define the overall layout of a full page of content made up
 
 <p>Page templates go beyond the scope of the user interface kit(s). These examples do not represent recommended HTML patterns and are for reference only regarding which elements and components to use and their general position on the page.</p>
 
-{% include page-templates/default.html %}
+{% include styleguide/page-templates/default.html %}
 
-{% include page-templates/search.html %}
+{% include styleguide/page-templates/search.html %}
 
-{% include page-templates/support.html %}
+{% include styleguide/page-templates/support.html %}
diff --git a/_includes/code/components/footers-code.html b/_includes/code/components/footers-code.html
@@ -1,5 +1,4 @@
-{% capture code_preview %}
-  <h6 class="usa-heading-alt" id="big-footer">SAM footer</h6>
+{% capture microsite_footer %}
   <section id="iae-footer">
     <footer>
       <div class="usa-grid usa-footer-return-to-top">
@@ -37,6 +36,11 @@ <h4 class="m_T-0 iae-footer-head">About</h4>
   </section>'
 {% endcapture %}
 
+{% capture code_preview %}
+<h6 class="usa-heading-alt" id="big-footer">SAM footer</h6>
+{{ microsite_footer }}
+{% endcapture %}
+
 {% capture uikit-php %}
 // render unescaped HTML string
 echo SAMUIKit\Other::footer($config)