Patterns IA restructuring

Gemfile

@@ -25,6 +25,7 @@ gem "minima", "~> 2.0"
 group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.6"
   gem "jekyll-last-modified-at"
+  gem 'jekyll-redirect-from'
 end
 
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem

Gemfile.lock

@@ -35,6 +35,8 @@ GEM
     jekyll-last-modified-at (1.3.0)
       jekyll (>= 3.7, < 5.0)
       posix-spawn (~> 0.3.9)
+    jekyll-redirect-from (0.16.0)
+      jekyll (>= 3.3, < 5.0)
     jekyll-sass-converter (2.2.0)
       sassc (> 2.0.1, < 3.0)
     jekyll-seo-tag (2.8.0)
@@ -82,6 +84,7 @@ DEPENDENCIES
   jekyll (~> 4.2.2)
   jekyll-feed (~> 0.6)
   jekyll-last-modified-at
+  jekyll-redirect-from
   minima (~> 2.0)
   sass-embedded (~> 1.0.0.pre.beta.4)
   tzinfo-data

_config.yml

@@ -39,6 +39,7 @@ markdown: kramdown
 highlighter: none
 plugins:
   - jekyll-last-modified-at
+  - jekyll-redirect-from
 
 source: src
 
@@ -64,6 +65,9 @@ collections:
   patterns:
     output: true
     permalink: /:collection/:title
+  templates:
+    output: true
+    permalink: /:collection/:title
 
 includes:
   - /components/code

src/_about/whats-new.md

@@ -46,7 +46,7 @@ New component symbols:
 
 ### Pattern updates
 
-* [Show more options]({{ site.baseurl }}/patterns/show-more-options) (documentation and Sketch library)
+* [Help users to navigate a long list]({{ site.baseurl }}/patterns/help-users-to/navigate-a-long-list) (aka Show more options) - documentation and Sketch library.
 
 ## June 2022
 
@@ -70,12 +70,10 @@ New component symbols:
   - The "Design" section was renamed "Foundation".
   - Utilities and Layout moved into the Foundation section.
 - [Maturity scale]({{ site.baseurl }}/about/maturity-scale): We've introduced a maturity scale to track the lifecycle of components and patterns. This allows experimental design elements to come into the system and have visibility in the Components and Patterns sections. Each component and pattern has been assigned a maturity level on the scale which is indicated by a tag and dot in the side navigation.
-- Section pages: Top-level navigation sections, such as Patterns and Foundation, now have sub-sections that group similar elements. For example, [Patterns > Forms]({{ site.baseurl }}/patterns/forms/) groups form patterns where each form pattern has a distinct page and a similar page structure. These new section pages will also have general guidance that applies to everything in that section. This will allow us to grow the system. 
+- Section pages: Top-level navigation sections, such as Patterns and Foundation, now have sub-sections that group similar elements. These new section pages will also have general guidance that applies to everything in that section. This will allow us to grow the system. 
   - New sections:
     - [Foundation > Layout]({{ site.baseurl }}/foundation/layout/) 
     - [Foundation > Utilities]({{ site.baseurl }}/foundation/utilities/) 
-    - [Patterns > Forms]({{ site.baseurl }}/patterns/forms/) 
-    - [Patterns > Templates]({{ site.baseurl }}/patterns/templates/) 
 - Table web component
 
 ## March 2022

src/_components/accordion.md

@@ -39,20 +39,16 @@ anchors:
 
 ### When to use accordions
 
-Use an accordion:
-
-* When users only need to access a few pieces of related information within a content-heavy page.
-* To organize related content in a small space.
+* **Organizing related sections of content to condense and chunk the content.** When you need to organize related sections of content into a smaller space use accordions to condense and group the content.
+* **A series of content**: If you have a series of content in the body of a page and outside of a form or tool. For example, if you have a series of questions as part of an FAQ section or a set of options for payment that each have additional details. 
+* **Reveal and compare relevant information.** When users need to reveal and compare relevant and related information accordions can make this easier.
 
 ### When to consider something else
 
-Consider another solution if:
-
-* Users need to see most or all of the information on the page at one time. Use well-formatted text with descriptive headings instead.
-* There is not enough content to warrant condensing. Accordions increase cognitive load and interaction cost, as users have to make decisions about which headers to click.
-* Users would benefit from seeing additional context for a discrete piece of content. Use the [Additional info]({{ site.baseurl }}/components/additional-info) component instead to leverage show/hide functionality, especially in a form. 
-
-See [Expandable content]({{ site.baseurl }}/patterns/content-presentation#expandable-content) for more accordion usage guidelines.
+* **Users need to see most or all of the information on the page at one time.** Use well-formatted text with descriptive headings instead.
+* **There is not enough content to warrant condensing.** Accordions increase cognitive load and interaction cost, as users have to make decisions about which headers to click.
+* **Users would benefit from seeing additional context for a discrete piece of content.** Use the [Additional info]({{ site.baseurl }}/components/additional-info) component instead to leverage show/hide functionality, especially in a form. 
+* **Required content**: If the majority of people need the content to accomplish the main task then it should not be hidden from view.
 
 ### Behavior
 
@@ -77,5 +73,4 @@ See [Expandable content]({{ site.baseurl }}/patterns/content-presentation#expand
 
 ## Related
 
-* [Additional info]({{ site.baseurl }}/components/additional-info)
-* [Expandable content]({{ site.baseurl }}/patterns/content-presentation#expandable-content)
+* [Additional info]({{ site.baseurl }}/components/additional-info)

src/_components/additional-info.md

@@ -32,6 +32,7 @@ anchors:
 
 * **Revealing helpful background information**: When you have additional information you want to convey about an application, process, or a step or question in a form that is not critical. This component should be used in instances where a more prominent [Alert]({{ site.baseurl }}/components/alert) would not be appropriate.
 * **Clarifying outcomes for an input**: In cases where a person's input can have large or complicated impact on outcomes we use contextual help in Additional info to locate expanded guidance next to the relevant interaction.
+* **Information closely tied to an input.** Use this component over an [Accordion]({{ site.baseurl }}/components/accordion) when the content is closely tied to a particular message or input on the screen. If the content is more tangentially related then use an Accordion.
 * **Clarifying a form question**: If a form question needs clarification, and that clarification is brief, use Additional info. The lighter design prevents breaking up the visual progression as the user navigates the form. These can also serve as alternative to where accordions feel too heavy. If a form is a conversation, Additional info would be considered an aside. (This <a href="https://blog.navapbc.com/structuring-a-complex-eligibility-form-for-healthcare-gov-37d79a5ad6">case study on structuring complex health care questions for healthcare.gov</a> goes into greater detail on how to structure your form as a conversation.)
 * **Information not applicable to all**: Additional info can hide details that may not be applicable to all users.
 

src/_components/alert.md

@@ -133,7 +133,7 @@ By default use the standard Alert variation. Use the background-only variation f
 
 <a class="vads-c-action-link--blue" href="{{ site.baseurl }}/content-style-guide/error-messages">View content for messages</a>
 
-<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/messaging-error-messages">Review the error messages pattern</a>
+<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/help-users-to/recover-from-errors">Review the help users to recover from errors pattern</a>
 
 ## Accessibility considerations
 

src/_components/banner/maintenance.md

@@ -26,13 +26,32 @@ anchors:
 
 ### When to use MaintenanceBanner
 
-* **System maintenance.** Before and during maintenance there are [specific system status messages]({{ site.baseurl }}/content-style-guide/error-messages/system) that we use to communicate the maintenance window to users. 
+* **System maintenance.** Before and during maintenance there are [specific system status messages]({{ site.baseurl }}/content-style-guide/error-messages/system) that we use to communicate the maintenance window to users. Maintenance messages are used when all (or most) unauthenticated and authenticated applications, tools, or sign in experiences across the entire site are affected (e.g., vets-api).
 
 ### When to consider something else
 
 * **Anything that is not a System status message.** This component is ONLY for site-wide [system status messages]({{ site.baseurl }}/content-style-guide/error-messages/system). There is no other appropriate use.
 
-### How to use MaintenanceBanner
+### Behavior
 
-- Add a headline, type, and visible prop to have the component display on the page.
-- If the banner should not be visible, have a button to be dismissible, or be dismissed to sessionStorage instead of localStorage additional props can be added to accommodate.
+The content and UX behavior of sitewide maintenance banners are standardized. Only the duration, dates, and times are customizable. 
+
+The Public Website Team (Office of the CTO Digital Experience) publishes downtime maintenance banners.
+
+- Specify custom dates and times. 
+- Specify custom duration (how many hours or minutes) in the upcoming/before message. 
+- Times are always given in ET.
+- Sitewide maintenance banners are always dismissible per session.
+- The ‘upcoming’ before message should be published at least 12 hours in advance. (Can be more in advance when the outage is unusually long or comprehensive.)
+- Banner expires and automatically removed when downtime is complete.
+- A maximum of 3 banners are allowed simultaneously. 
+
+<!--
+#### When there are multiple banners simultaneously on a page 
+
+The front-end logic will prioritize the display order of banners like this: 
+
+1. Emergency homepage banner
+2. Site-wide maintenance banner
+3. Any other Veteran-action required banner
+-->

src/_components/card.md

@@ -162,11 +162,11 @@ There are a few design elements that look like a Card but do not behave like a C
 
 The [Mobile App](https://apps.apple.com/us/app/va-health-and-benefits/id1559609596?platform=iphone) uses a Card-like container around an [active link]({{ site.baseurl }}/components/link/#active-link) to make the link a large tap target on mobile. This treatment should be thought of as a mobile-specific link variation rather than an instance of a Card.
 
-### Containers for List and Loop in forms
+### Containers for asking users for multiple responses (aka List and Loop) in forms
 
-{% include component-example.html alt="A container for an action in a form used in the List and Loop pattern." file="/images/components/card/not-a-card-list-and-loop.png" caption="Container for a button and title. Not a Card." width="50%" reverse=true %}
+{% include component-example.html alt="A container for an action in a form used in the Ask users for multiple responses (aka List and Loop) pattern." file="/images/components/card/not-a-card-list-and-loop.png" caption="Container for a button and title. Not a Card." width="50%" reverse=true %}
 
-The [List and Loop pattern]({{ site.baseurl }}/patterns/forms/list-and-loop) uses a Card-like container to enter the loop to edit or remove an item in the list. This treatment is specific to that pattern and should not be thought of as an instance of a Card.
+The [pattern for asking users for multiple responses]({{ site.baseurl }}/patterns/ask-users-for/multiple-responses) (aka List and Loop) uses a Card-like container to enter the loop to edit or remove an item in the list. This treatment is specific to that pattern and should not be thought of as an instance of a Card.
 
 ### Containers for radio button tiles and checkboxes
 

src/_components/form/index.md

@@ -69,7 +69,7 @@ The HTML for a typical error is:
 </span>
 ```
 
-<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/messaging-error-messages">Review the error messages pattern</a>
+<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/help-users-to/recover-from-errors">Review the help users to recover from errors pattern</a>
 
 ## Hint text
 

src/_components/link/index.md

@@ -31,7 +31,7 @@ anchors:
 {% include storybook-preview.html story="components-va-link--active" link_text="active va-link" %}
 
 - For links that have less hierarchy than an Action Link, we recommend using an Active Link. Active Links can be accompanied by a right-facing chevron icon for more emphasis. 
-- Active links can be seen on [Hub pages]({{ site.baseurl }}/patterns/templates/hub#example)
+- Active links can be seen on [Hub pages]({{ site.baseurl }}/templates/hub#example)
 - Active link text is bold.
 
 ### Download

src/_content-style-guide/error-messages/access.md

@@ -11,7 +11,7 @@ anchors:
   - anchor: Empty state
 ---
 
-***Note:** See [Error Messages](/patterns/error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See the [help users to recover from errors pattern]({{ site.baseurl }}/patterns/help-users-to/recover-from-errors#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ## System downtime
 

src/_content-style-guide/error-messages/engagement.md

@@ -6,7 +6,7 @@ title: Engagement messages
 intro-text: Nudges the user to enter or update data in the system. It can be initiated by either the system or another user.
 ---
 
-***Note:** See [Error Messages](/patterns/error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See [Error Messages](/patterns/help-users-to/recover-from-errors#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ## Prompt to complete a task or enter data
 

src/_content-style-guide/error-messages/feedback.md

@@ -6,7 +6,7 @@ title: Feedback messages
 intro-text: The application’s response when the user is interacting with it. The majority of create, read, update, delete (CRUD) actions will result in feedback messaging.
 ---
 
-***Note:** See [Error Messages](/patterns/error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See the [help users to recover from errors pattern]({{ site.baseurl }}/patterns/help-users-to/recover-from-errors#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ## Task completion success/failure
 

src/_content-style-guide/error-messages/index.md

@@ -13,7 +13,7 @@ sub-pages:
 
 Error messages mainly appear in interactive experiences such as tools, forms, and applications. This category of messaging has visual design and formatting that affects copy and thus you must: 
 
-<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/messaging-error-messages">Review the error messages pattern</a>
+<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/help-users-to/recover-from-errors">Review the help users to recover from errors pattern</a>
 
 ## Messages dictionary
 

src/_content-style-guide/error-messages/system.md

@@ -10,7 +10,7 @@ anchors:
   - anchor: Updates to user data (system initiated)
 ---
 
-***Note:** See [Error Messages]({{ site.baseurl }}/patterns/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See the [help users to recover from errors pattern]({{ site.baseurl }}/patterns/help-users-to/recover-from-errors#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ## Scheduled downtime notifications
 

src/_includes/_site-content-nav.html

@@ -12,7 +12,10 @@
     {% include _side-nav.html section=site.components name="components" %}
     {% assign collection_name = "Components" %}
   {% elsif page.url contains "/patterns/" %}
-    {% include _side-nav.html section=site.patterns name="patterns" %}
+    {% include _site-side-nav-patterns.html name="patterns" %}
     {% assign collection_name = "Patterns" %}
+  {% elsif page.url contains "/templates/" %}
+    {% include _side-nav.html section=site.templates name="templates" %}
+    {% assign collection_name = "Templates" %}
   {% endif %}
 </div>

src/_includes/_site-side-nav-patterns-list.html

@@ -0,0 +1,20 @@
+<ul class="usa-sidenav-list">
+  {% for p in include.section_list %}
+    {% assign is-current = false %}
+    {% if p.url == page.url %}
+      {% assign is-current = true %}
+    {% endif %}
+    {% unless p.index %}
+      {% unless p.draft and (p.url != page.url) %}
+        <li class="{% if is-current == true %}active-level{%- endif -%}">
+          <a class="{% if is-current == true %}usa-current{%- endif -%}" href="{{site.baseurl}}{{ p.url }}">
+            {{p.title}}
+              {%- if p.status -%}
+                {%- include _site-side-nav-status.html component-status=p.status -%}
+              {%- endif -%}
+          </a>
+        </li>
+      {% endunless %}
+    {% endunless %}
+  {% endfor %}
+</ul>

src/_includes/_site-side-nav-patterns.html

@@ -0,0 +1,20 @@
+<nav class="va-sidebarnav va-sidebarnav--{{include.name}}">
+  {% assign ask_users_for = site.patterns | where: "sub-section", "ask-users-for" %}
+  {% assign help_users_to = site.patterns | where: "sub-section", "help-users-to" %}
+  {% assign deprecated = site.patterns | where: "status", "dont-use-deprecated" %}
+
+  <h3 class="va-sidebarnav__sub-section">
+    Ask users for&hellip;
+  </h3>
+  {% include _site-side-nav-patterns-list.html section_list=ask_users_for %}
+
+  <h3 class="va-sidebarnav__sub-section">
+    Help users to&hellip;
+  </h3>
+  {% include _site-side-nav-patterns-list.html section_list=help_users_to %}
+
+  <h3 class="va-sidebarnav__sub-section">
+    Deprecated
+  </h3>
+  {% include _site-side-nav-patterns-list.html section_list=deprecated%}
+</nav>

src/_includes/_site-top-nav.html

@@ -16,6 +16,9 @@
       <li class="site-header__nav-item">
         <a class="site-header__nav-item__link {% if page.url contains "/patterns/" %} current {% endif %}" href="{{ site.baseurl }}/patterns">Patterns</a>
       </li>
+      <li class="site-header__nav-item">
+        <a class="site-header__nav-item__link {% if page.url contains "/templates/" %} current {% endif %}" href="{{ site.baseurl }}/templates">Templates</a>
+      </li>
     </ul>
   </nav>
 </div>