diff --git a/Gemfile b/Gemfile index 075cfc0d8..f6bfcd370 100644 --- a/Gemfile +++ b/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 diff --git a/Gemfile.lock b/Gemfile.lock index 01f3d9e5d..2551dc49a 100644 --- a/Gemfile.lock +++ b/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 diff --git a/_config.yml b/_config.yml index fed7aea86..432aefe17 100644 --- a/_config.yml +++ b/_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 diff --git a/src/_about/whats-new.md b/src/_about/whats-new.md index df1aac894..f1de0fac4 100644 --- a/src/_about/whats-new.md +++ b/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 diff --git a/src/_components/accordion.md b/src/_components/accordion.md index 0e8765920..cd069e811 100644 --- a/src/_components/accordion.md +++ b/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) \ No newline at end of file diff --git a/src/_components/additional-info.md b/src/_components/additional-info.md index 77f2eff97..360e879be 100644 --- a/src/_components/additional-info.md +++ b/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 case study on structuring complex health care questions for healthcare.gov 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. diff --git a/src/_components/alert.md b/src/_components/alert.md index cc4de8182..cacd8fc18 100644 --- a/src/_components/alert.md +++ b/src/_components/alert.md @@ -133,7 +133,7 @@ By default use the standard Alert variation. Use the background-only variation f View content for messages -Review the error messages pattern +Review the help users to recover from errors pattern ## Accessibility considerations diff --git a/src/_components/banner/maintenance.md b/src/_components/banner/maintenance.md index c494e4964..57eab7d9a 100644 --- a/src/_components/banner/maintenance.md +++ b/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. + + \ No newline at end of file diff --git a/src/_components/card.md b/src/_components/card.md index a74dc52eb..b2cc1b49a 100644 --- a/src/_components/card.md +++ b/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 diff --git a/src/_components/form/index.md b/src/_components/form/index.md index cdb24a9d6..382898f31 100644 --- a/src/_components/form/index.md +++ b/src/_components/form/index.md @@ -69,7 +69,7 @@ The HTML for a typical error is: ``` -Review the error messages pattern +Review the help users to recover from errors pattern ## Hint text diff --git a/src/_components/link/index.md b/src/_components/link/index.md index dd6e8fb22..5177769b8 100644 --- a/src/_components/link/index.md +++ b/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 diff --git a/src/_content-style-guide/error-messages/access.md b/src/_content-style-guide/error-messages/access.md index 3916557a9..a26fbe350 100644 --- a/src/_content-style-guide/error-messages/access.md +++ b/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 diff --git a/src/_content-style-guide/error-messages/engagement.md b/src/_content-style-guide/error-messages/engagement.md index b3ec70d65..6bc4c9b41 100644 --- a/src/_content-style-guide/error-messages/engagement.md +++ b/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 diff --git a/src/_content-style-guide/error-messages/feedback.md b/src/_content-style-guide/error-messages/feedback.md index fc7134db1..e1e7f1740 100644 --- a/src/_content-style-guide/error-messages/feedback.md +++ b/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 diff --git a/src/_content-style-guide/error-messages/index.md b/src/_content-style-guide/error-messages/index.md index 0a92908b8..b890093c9 100644 --- a/src/_content-style-guide/error-messages/index.md +++ b/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: -Review the error messages pattern +Review the help users to recover from errors pattern ## Messages dictionary diff --git a/src/_content-style-guide/error-messages/system.md b/src/_content-style-guide/error-messages/system.md index 3b73b6169..b6bf50f01 100644 --- a/src/_content-style-guide/error-messages/system.md +++ b/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 diff --git a/src/_includes/_site-content-nav.html b/src/_includes/_site-content-nav.html index b90708f28..cb62f7aea 100644 --- a/src/_includes/_site-content-nav.html +++ b/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 %} \ No newline at end of file diff --git a/src/_includes/_site-side-nav-patterns-list.html b/src/_includes/_site-side-nav-patterns-list.html new file mode 100644 index 000000000..147426289 --- /dev/null +++ b/src/_includes/_site-side-nav-patterns-list.html @@ -0,0 +1,20 @@ + diff --git a/src/_includes/_site-side-nav-patterns.html b/src/_includes/_site-side-nav-patterns.html new file mode 100644 index 000000000..bce052e25 --- /dev/null +++ b/src/_includes/_site-side-nav-patterns.html @@ -0,0 +1,20 @@ + \ No newline at end of file diff --git a/src/_includes/_site-top-nav.html b/src/_includes/_site-top-nav.html index b5ee8eed2..006b6de4c 100644 --- a/src/_includes/_site-top-nav.html +++ b/src/_includes/_site-top-nav.html @@ -16,6 +16,9 @@
  • Patterns
  • +
  • + Templates +
  • \ No newline at end of file diff --git a/src/_includes/components-patterns-templates.md b/src/_includes/components-patterns-templates.md index bc70bdad8..d75cafc6c 100644 --- a/src/_includes/components-patterns-templates.md +++ b/src/_includes/components-patterns-templates.md @@ -2,16 +2,14 @@ ### Components -[Components]({{ site.baseurl }}/components/) are design elements that define a visual style and/or micro-interaction. A component is the smallest unit of measure within a design system. They can be considered concrete, a finite list: Button, accordion, table, etc. +[Components]({{ site.baseurl }}/components/) are design elements that define a visual style and/or micro-interaction. A component is the smallest unit of measure within a design system. They can be considered concrete, a finite list: Button, accordion, table, etc. ### Templates or Page layouts -[Templates]({{ site.baseurl }}/patterns/templates/), or page layouts, compose components within a single page. A layout can contain multiple variations of a component depending on the context. - -We've added Templates to our Patterns section because a template can be thought of as a pattern, even though it is limited to a single page. +[Templates]({{ site.baseurl }}/templates/), or page layouts, compose components within a single page. A layout can contain multiple variations of a component depending on the context. ### Patterns -**Patterns** incorporate one or more page layouts and components to create an interaction that can span multiple pages, a short or long time span, and potentially even multiple channels. Patterns might be unique to a site or an application and may evolve with changes in technology or after competitive analysis. +[Patterns]({{ site.baseurl }}/patterns/) incorporate one or more page layouts and components to create an interaction that can span multiple pages, a short or long time span, and potentially even multiple channels. Patterns might be unique to a site or an application and may evolve with changes in technology or after competitive analysis. A pattern is more than the sum of its parts. Patterns are solutions. In the Design System, patterns demonstrate how design, content strategy, reusable components, and accessibility can be put together to solve common problems that all Veterans may experience on VA.gov. diff --git a/src/_layouts/pattern.html b/src/_layouts/pattern.html index c8e895866..fa431419a 100644 --- a/src/_layouts/pattern.html +++ b/src/_layouts/pattern.html @@ -1,14 +1,11 @@ - {% include head.html %} - {% if site.analytics == "production" %} - + {% endif %} @@ -29,7 +26,17 @@

    {{ collection_name }}

    + {% if page.sub-section %} +

    + {{ page.sub-section | replace: "-", " " | capitalize }}… +

    + {% endif %}

    {{ page.title }}

    + {% if page.aka %} +

    + Also known as: {{ page.aka }} +

    + {% endif %} {% if page.status %} {% include _status.html %} {% endif %} diff --git a/src/_patterns/forms/all-or-none-of-the-above.md b/src/_patterns/ask-users-for/a-mutually-exclusive-answer.md similarity index 90% rename from src/_patterns/forms/all-or-none-of-the-above.md rename to src/_patterns/ask-users-for/a-mutually-exclusive-answer.md index e2042f552..a34f463df 100644 --- a/src/_patterns/forms/all-or-none-of-the-above.md +++ b/src/_patterns/ask-users-for/a-mutually-exclusive-answer.md @@ -1,8 +1,11 @@ --- layout: pattern -permalink: /patterns/forms/all-or-none-of-the-above -has-parent: /patterns/forms/ -title: All or none of the above +title: A mutually exclusive answer +permalink: /patterns/ask-users-for/a-mutually-exclusive-answer +redirect_from: + - /patterns/forms/all-or-none-of-the-above +aka: All or none of the above +sub-section: ask-users-for intro-text: "In some questions, either none of the options or all of them may apply to the user. Here is how to design responses for that instance." status: use-deployed anchors: diff --git a/src/_patterns/ask-users-for/addresses.md b/src/_patterns/ask-users-for/addresses.md new file mode 100644 index 000000000..825fa08d8 --- /dev/null +++ b/src/_patterns/ask-users-for/addresses.md @@ -0,0 +1,115 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/addresses +sub-section: ask-users-for +title: Addresses +intro-text: "Follow this pattern to ask a user for an address." +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build + - anchor: Content considerations +--- + +## Usage + +### When to use this pattern + +* **Asking for an address.** For example, the address for a military base, home, or mailing address. + +## Examples + +### Single address +![contact information single address template]({{site.baseurl}}/images/patterns/ask-users-for/addresses/single-address.png) + +### Mailing address +![contact information mailing address template]({{site.baseurl}}/images/patterns/ask-users-for/addresses/mailing-address.png) + +### Home address + +![contact information home address template]({{site.baseurl}}/images/patterns/ask-users-for/addresses/home-address.png) + +## How to design and build + +### Layout details + +#### Single address +Here is the content structure for asking a user for a single address: + +- Checkbox for military address (if applicable) +- Additional info component (if applicable) +- Country select box +- Street address text input +- Street address line 2 text input +- Street address line 3 text input (if applicable) +- City text input +- State/Province/Region select box +- Postal code text input + +#### Multiple addresses + +Here is the content structure for asking a user for multiple addresses: + +- Header - Mailing or Home Address +- Relevant information regarding this form and the user’s address (if applicable) +- Checkbox for military address (if applicable) +- Additional info component (if applicable) +- Country select box +- Street address text input +- Street address line 2 text input +- Street address line 3 text input (if applicable) +- City text input +- State/Province/Region select box +- Postal code text input +- Radio button component for mailing address same as home address (this is on mailing address page only) + +### How this pattern works + +#### Single address +- **If required, include a checkbox for United States military base address.** Under the additional information component, there should be an explanation: + U.S. military bases are considered a domestic address and a part of the United States. When the checkbox is checked, the country select box becomes disabled. +- **If asking for only one address on a form, be clear with the user which address (mailing or home) you’re asking for.** We recommend asking for a mailing address if you need to only ask for one address. +- **Street address Line 3 can be omitted.** Sometimes partner databases do not support a third line of address. + +#### Multiple addresses: Mailing and Home addresses + +Follow this guidance when asking for both mailing and home addresses. In some forms, we ask for both addresses because some veterans live in different homes depending on the time of year. + +- **Add guidance on where users can go to edit their account information on all VA accounts.** Let the user know that when filling out contact information, they will have to edit their profile information. An example message is: *Any updates you make here to your contact information will only apply to this application. To update your contact information for all of your VA accounts, go to your profile page (link to profile).* +- **The mailing address always comes before home address.** We ask for a mailing address before home address because the majority of VA's correspondence is over mail. +- **On the mailing address form, ask users if the home address is the same as the mailing address.** If the user chooses “Yes”, they can skip the home address form. + +## Content considerations + +* If you need to display an address after it has been collected, then [follow content style guidelines on addresses](/content-style-guide/dates-and-numbers#addresses). + +### Error message templates for addresses + +**When a user doesn’t enter a street address:** + +Say 'Please enter a street address' + +**When a user doesn’t enter a city:** + + Say 'Please enter a city' + +**When a user doesn’t enter a state:** + +Say 'Please enter a state' + +**When a user doesn’t enter a postal code:** + +Say 'Please enter a postal code' + +**When a postal code is entered incorrectly:** + +Say 'Please enter a valid 5- or 9-digit postal code (dashes allowed)' + +**When a postal code can’t be correct:** + +Say 'Please provide a valid postal code' + +**When a user doesn’t select a state or province:** + +Say 'Please select a state or province' \ No newline at end of file diff --git a/src/_patterns/ask-users-for/contact-preferences.md b/src/_patterns/ask-users-for/contact-preferences.md new file mode 100644 index 000000000..2e8ad0520 --- /dev/null +++ b/src/_patterns/ask-users-for/contact-preferences.md @@ -0,0 +1,28 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/contact-preferences +sub-section: ask-users-for +title: Contact preferences +intro-text: Follow this pattern when you want to ask a user how they’d like to be contacted. +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build +--- + +## Usage + +### When to use this pattern + +* **When needed and you would like to offer a method of contact.** Method of contact is form-dependent. Work with your stakeholders on whether your form needs a method of contact. + +## Examples + +![contact information method of contact template]({{site.baseurl}}/images/patterns/ask-users-for/contact-preferences/method-of-contact.png) + +## How to design and build + +### How this pattern works + +- **Give users the opportunity to pick one method of contact.** Provide contact information methods in radio button list form. \ No newline at end of file diff --git a/src/_patterns/ask-users-for/dates.md b/src/_patterns/ask-users-for/dates.md new file mode 100644 index 000000000..41d1029ad --- /dev/null +++ b/src/_patterns/ask-users-for/dates.md @@ -0,0 +1,84 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/dates +sub-section: ask-users-for +title: Dates +intro-text: "Use this pattern to collect dates from a person." +status: use-deployed +anchors: + - anchor: Usage + - anchor: How to design and build + - anchor: Content considerations +--- + +## Usage + +### When to use this pattern + +Follow this pattern whenever you need a person to provide a date on a form. + +Dates you may need people to provide include: +- Dates a person knows, like a date of birth or marriage anniversary. +- Dates a person can approximate, like February 2021. +- Date ranges, like service history dates. + +### Dates a person knows + +Use the [Memorable date]({{ site.baseurl }}/components/form/memorable-date) component for dates a person is likely to have memorized such as a date of birth or marriage anniversary. + +You can also use the standard [date]({{ site.baseurl }}/components/form/date) component: + +![date input for memorized dates: month day and year]({{site.baseurl}}/images/patterns/ask-users-for/dates/date-input.png) + +#### Date of birth + +Follow this pattern whenever you need to ask for a user’s date and place of birth. + +![applicant information birth information template]({{site.baseurl}}/images/patterns/ask-users-for/dates/birth-info.png) + +### Dates a user can approximate + +Use the [month/year date]({{ site.baseurl }}/components/form/date-input#monthyear) component variation for dates that a user may struggle to remember. For example: *When did you receive your high school diploma or equivalency certificate?* + +![date input for approximate dates: month and year]({{site.baseurl}}/images/patterns/ask-users-for/dates/date-input-month-year.png) + +### Date ranges + +Use one of the aforementioned components depending on the question being asked. For example: Service history dates. + +![date ranges: service start date and service end date]({{site.baseurl}}/images/patterns/ask-users-for/dates/date-ranges.png) + +## How to design and build + +### How this pattern works + +- **Write clear form labels for date ranges** Do not use “From” and “To” to when labeling form labels for date ranges. Make it clear what dates you’re asking for. Example: “Obligation start date” and “Obligation end date” +- **Spell out full month names in the selected state** The month select box should have the full month’s name. Example: January +- **Validate date inputs.** You should validate date inputs so you can let users know if they have entered one incorrectly. A general validation message for an incorrect date: *Please enter a valid date* +- **Use the date input field for date of birth.** Writing out the label for each birth date string and separating them into three fields instead of one eliminates potential format confusion. +- **Use one text input for Place of birth.** This format is easier to fill out for both Veterans born outside the United States and for Veterans who were born United States citizens. + +## Content considerations + +### Error message templates for dates + +**If nothing is entered** +Say 'Please enter a date' + +**If the date entered can’t be correct** +Say ‘Please provide a valid date' + +**If the date entered is in a month year format and can’t be correct** +Say 'Please enter a valid month and year' + +**If the year needed to be within a specific range** +Say 'Please enter a year between [minimum year] and [maximum year]' + +**For a date range, if the date must be after another date** +Say 'To date must be after From date' + +**If the date is in the past when it needs to be today or in the future** +Say 'Please provide a valid current or future date' + +**If the date is in the future when it needs to be past date or current date** +Say 'Please enter a valid current or past date' \ No newline at end of file diff --git a/src/_patterns/forms/direct-deposit.md b/src/_patterns/ask-users-for/direct-deposit.md similarity index 73% rename from src/_patterns/forms/direct-deposit.md rename to src/_patterns/ask-users-for/direct-deposit.md index 9aeb42fbb..99cc3ad33 100644 --- a/src/_patterns/forms/direct-deposit.md +++ b/src/_patterns/ask-users-for/direct-deposit.md @@ -1,42 +1,53 @@ --- layout: pattern -permalink: /patterns/forms/direct-deposit -has-parent: /patterns/forms/ +permalink: /patterns/ask-users-for/direct-deposit +sub-section: ask-users-for title: Direct deposit -intro-text: "The current implementation for collecting direct deposit information on VA.gov forms." +intro-text: "Follow this pattern to ask users for their banking information in order to enable direct deposit." status: use-deployed anchors: - - anchor: Input - - anchor: Review + - anchor: Usage + - anchor: Examples + - anchor: How to design and build + - anchor: Content considerations --- -## Input - -![Direct deposit input state]({{site.baseurl}}/images/direct_deposit_update.png) +## Usage ### When to use this pattern -Apply this pattern when Veterans are asked to provide banking information to receive funds electronically. +* **Provide banking information.** Apply the [input pattern](#how-to-design-and-build---input) when Veterans are asked to provide banking information to receive funds electronically. +* **Review and change banking information.** Follow this [review pattern](#how-to-design-and-build---review) to provide Veterans with the ability to change their bank account information. This direct deposit information is pre-populated because the Veteran already filled these bank details beforehand. + +## Examples + +![Direct deposit input state]({{site.baseurl}}/images/patterns/ask-users-for/direct-deposit/direct_deposit_update.png) + +### Production example + +[VA Form 22-10203 (Application for Edith Nourse Rogers STEM Scholarship)](https://www.va.gov/education/other-va-education-benefits/stem-scholarship/apply-for-scholarship-form-22-10203/introduction) + +## How to design and build - Input -#### Direct deposit card name +### Direct deposit card name Under the form name and chapter title, begin the card with a heading level 3 of “Direct deposit information” -#### Card description +### Card description Under the card name have a short description on how VA only accepts direct deposit and what their direct deposit information is going to be used for. Example: *We make payments only through direct deposit, also called electronic funds transfer (EFT).* -#### Check image +### Check image The check image provides a guide for Veterans to find their account and routing numbers from a check when filling out direct deposit information. -#### Check image caption +### Check image caption Provides a caption for the check image, which is used to provide supplemental information for the image. -### Form controls +### Anatomy - Form controls #### Account type Present the account type as a radio button group since the Veteran has only two options to choose from: checking and savings. @@ -51,7 +62,7 @@ The bank routing number text input is required for this form pattern. The routin The bank account number text input is required for this form pattern. #### “I don’t want to use direct deposit” checkbox -![Direct deposit checkbox]({{site.baseurl}}/images/Direct-deposit-checkbox-small.png) +![Direct deposit checkbox]({{site.baseurl}}/images/patterns/ask-users-for/direct-deposit/Direct-deposit-checkbox-small.png) Underneath the direct deposit input card, give the Veteran the option to not give their direct deposit information. When the checkbox is checked, the direct deposit input card above will disappear. @@ -72,16 +83,10 @@ Example of additional information that can be displayed: To get started, call one of the participating banks or credit unions listed on the VBBP website. Be sure to mention the Veterans Benefits Banking Program. Note: The Department of the Treasury requires us to make electronic payments. If you don’t want to use direct deposit, you’ll need to call the Department of the Treasury at **888-224-2950**. Ask to talk with a representative who handles waiver requests. They can answer any questions or concerns you may have.* -**Live application examples:** - -[VA Form 22-10203 (Application for Edith Nourse Rogers STEM Scholarship)](https://www.va.gov/education/other-va-education-benefits/stem-scholarship/apply-for-scholarship-form-22-10203/introduction) - -## Review +## How to design and build - Review -![Direct deposit review state]({{site.baseurl}}/images/Direct-deposit-review-state-small.png) +![Direct deposit review state]({{site.baseurl}}/images/patterns/ask-users-for/direct-deposit/Direct-deposit-review-state-small.png) -### When to use this pattern -Follow this pattern to provide Veterans with the ability to change their bank account information. This direct deposit information is pre-populated because the veteran already filled these bank details beforehand. #### Bank account information card The direct deposit information will live in the bank account information card. The card will have a short description on what the information below means, *“This is the bank account information we have on file for you. This is where we’ll send your payments.”* @@ -91,7 +96,9 @@ Mask the routing and account number but leave the 4 last digits. This masking is #### Call to action When the “update account information” button is clicked, the bank account information card will turn into an interactive card in which the review state will revert back into the input state. -#### Error message templates for direct deposit +## Content considerations + +### Error message templates for direct deposit **When a user doesn’t enter a bank account number:** diff --git a/src/_patterns/ask-users-for/email-address.md b/src/_patterns/ask-users-for/email-address.md new file mode 100644 index 000000000..7375867da --- /dev/null +++ b/src/_patterns/ask-users-for/email-address.md @@ -0,0 +1,46 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/email-address +sub-section: ask-users-for +title: Email address +intro-text: "Follow this pattern to ask a user for an email address." +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build + - anchor: Content considerations +--- + +## Usage + +### When to use this pattern + +* **When you need to collect an email address.** For example, for contact information. + +## Examples + +![contact information email address template]({{site.baseurl}}/images/patterns/ask-users-for/email-address/email-address.png) + +## How to design and build + +### How this pattern works + +- **If possible, tell users why you want their email address.** Users need to know that the VA won’t abuse their email and which email they’d like to provide. An example message is: *Please enter your contact information so we can get in touch with you if we have questions about your application.* +- **Validate email addresses.** You should validate email addresses so you can let users know if they have entered one incorrectly. A validation message for when a user forgets the “@”: *Please enter a valid email address.* A validation message for when a user doesn’t use the same email in the “Confirm email address” field: *This email doesn't match the one you entered above.* + +## Content considerations + +### Error message templates for email addresses + +**When a user doesn’t enter an email address:** + +Say 'Please enter an email address' + +**When a user doesn’t enter an email address in the correct format:** + +Say 'Please enter an email address using this format: X@X.com' + +**When a user doesn’t use the same email in the “Confirm email address” field:** + +Say ‘This email doesn’t match the one you entered above’. \ No newline at end of file diff --git a/src/_patterns/feedback.md b/src/_patterns/ask-users-for/feedback.md similarity index 85% rename from src/_patterns/feedback.md rename to src/_patterns/ask-users-for/feedback.md index f391e15d9..183fd575f 100644 --- a/src/_patterns/feedback.md +++ b/src/_patterns/ask-users-for/feedback.md @@ -1,6 +1,10 @@ --- layout: pattern title: Feedback +permalink: /patterns/ask-users-for/feedback +redirect_from: + - /patterns/feedback +sub-section: ask-users-for intro-text: VA asks users of VA.gov for feedback via a feedback button and form provided by Medallia. contributors: Ian McCullough (VSP Contact Center) status: use-deployed @@ -20,7 +24,7 @@ anchors: ## Examples -{% include component-example.html alt="About VA health benefits page screenshot with call-outs." file="/images/patterns/feedback/feedback-anatomy.png" caption="Page anatomy showing the placement for the feedback button." width="50%" %} +{% include component-example.html alt="About VA health benefits page screenshot with call-outs." file="/images/patterns/ask-users-for/feedback/feedback-anatomy.png" caption="Page anatomy showing the placement for the feedback button." width="50%" %} 1. **Main Content**. Content, including any left or right rail sections, within the main content of the page between the header and footer, but above the Back to Top/Last Updated/Feedback section. 2. **Back to Top Button**. Button that scrolls the user back to the top of the page when clicked. This button does not appear on all VA.gov pages. @@ -29,7 +33,7 @@ anchors: ### Feedback form in modal -{% include component-example.html alt="The Medallia feedback form." file="/images/patterns/feedback/feedback-form.png" caption="A 3 question form which appears in a modal after a user clicks the Feedback button and quickly allows the user to provide feedback." width="50%" %} +{% include component-example.html alt="The Medallia feedback form." file="/images/patterns/ask-users-for/feedback/feedback-form.png" caption="A 3 question form which appears in a modal after a user clicks the Feedback button and quickly allows the user to provide feedback." width="50%" %} ## How to design and build @@ -66,7 +70,7 @@ To better establish user expectations of location, appropriate space will be pro Manage your VA debt – Desktop - {% include component-example.html alt="The Medallia feedback button shown on a snippet of a desktop width page." file="/images/patterns/feedback/feedback-example-desktop-1.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a page." %} + {% include component-example.html alt="The Medallia feedback button shown on a snippet of a desktop width page." file="/images/patterns/ask-users-for/feedback/feedback-example-desktop-1.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a page." %}
    @@ -74,7 +78,7 @@ To better establish user expectations of location, appropriate space will be pro All articles in: VA account and profile – Desktop
    - {% include component-example.html alt="The Medallia feedback button shown on a snippet of a desktop width search page." file="/images/patterns/feedback/feedback-example-desktop-2.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a search results page." %} + {% include component-example.html alt="The Medallia feedback button shown on a snippet of a desktop width search page." file="/images/patterns/ask-users-for/feedback/feedback-example-desktop-2.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a search results page." %}
    @@ -88,7 +92,7 @@ To better establish user expectations of location, appropriate space will be pro Manage your VA debt – Mobile - {% include component-example.html alt="The Medallia feedback button shown on a snippet of a mobile width page." file="/images/patterns/feedback/feedback-example-mobile-1.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a page in a mobile viewport." %} + {% include component-example.html alt="The Medallia feedback button shown on a snippet of a mobile width page." file="/images/patterns/ask-users-for/feedback/feedback-example-mobile-1.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a page in a mobile viewport." %}
    @@ -96,7 +100,7 @@ To better establish user expectations of location, appropriate space will be pro All articles in: VA account and profile – Mobile
    - {% include component-example.html alt="The Medallia feedback button shown on a snippet of a desktop width search page." file="/images/patterns/feedback/feedback-example-mobile-2.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a search results page in a mobile viewport." %} + {% include component-example.html alt="The Medallia feedback button shown on a snippet of a desktop width search page." file="/images/patterns/ask-users-for/feedback/feedback-example-mobile-2.png" caption="An example of the placement of the feedback button at the bottom of a snippet of a search results page in a mobile viewport." %}
    diff --git a/src/_patterns/forms/file-upload.md b/src/_patterns/ask-users-for/files.md similarity index 71% rename from src/_patterns/forms/file-upload.md rename to src/_patterns/ask-users-for/files.md index 23b7be0fc..3948ffbdd 100644 --- a/src/_patterns/forms/file-upload.md +++ b/src/_patterns/ask-users-for/files.md @@ -1,19 +1,32 @@ --- layout: pattern -permalink: /patterns/forms/file-upload -has-parent: /patterns/forms/ -title: File upload +title: Files +permalink: /patterns/ask-users-for/files +redirect_from: + - /patterns/forms/file-upload +aka: File upload +sub-section: ask-users-for intro-text: "Follow this pattern to help users select and upload a file." status: use-deployed anchors: - - anchor: Structure - - anchor: Loading state - - anchor: Review state - anchor: Usage - - anchor: Error message templates for file upload + - anchor: How to design and build + - anchor: Content considerations --- -## Structure +## Usage + +### When to use this pattern + +* **Required documentation.** When a user must upload a file in order to provide required documentation. + +### When not to use this pattern + +8 **Don’t ask if it does not affect the delivery of a service.** You should only ask users to upload documents if absolutely necessary. + +## How to design and build + +### Layout details Here is the structure for asking a user to upload a file: @@ -24,28 +37,29 @@ Here is the structure for asking a user to upload a file: **Note:** This content will vary depending on what you’re asking the user to upload. Work with your content specialist with how to ask for certain documents. -![file upload input state]({{site.baseurl}}/images/file-upload-input.png) +![file upload input state]({{site.baseurl}}/images/patterns/ask-users-for/files/file-upload-input.png) -## Loading state +### How this pattern works + +- **Avoid error states by listing out what types and sizes of files are accepted.** The types of files accepted depend on the form. Most forms accept pdf, jpg, jpeg, and png. +- **Validate file uploads.** A validation message for when a user skips uploading a required document: *Please upload a file.* When there needs to be at least one required document: *Please upload at least one file* +- **Do not italicize information regarding file sizes.** Long strings of italicized text can be difficult to read for some users with low vision or reading disabilities. + +#### Loading state The upload button will be replaced by a gray card with a [standard progress bar component]({{ site.baseurl }}/components/progress-bar) to indicate the progress of the document upload. The user will see the name of the file, as well as, have the option to cancel the upload. -![file upload loading state]({{site.baseurl}}/images/file-upload-loading.png) +![file upload loading state]({{site.baseurl}}/images/patterns/ask-users-for/files/file-upload-loading.png) -## Review state +#### Review state When a document has successfully uploaded, the card will have the uploaded file name bolded and there will be an option to delete the file. Depending on the type of form, there can be a dropdown of selecting document types. Underneath the card there will be a secondary button to give the user the option of adding more document uploads. -![file upload review state]({{site.baseurl}}/images/file-upload-review.png) - -## Usage +![file upload review state]({{site.baseurl}}/images/patterns/ask-users-for/files/file-upload-review.png) -- **Don’t ask if it does not affect the delivery of a service.** You should only ask users to upload documents if absolutely necessary -- **Avoid error states by listing out what types and sizes of files are accepted.** The types of files accepted depend on the form. Most forms accept pdf, jpg, jpeg, and png. -- **Validate file uploads.** A validation message for when a user skips uploading a required document: *Please upload a file.* When there needs to be at least one required document: *Please upload at least one file* -- **Do not italicize information regarding file sizes.** Long strings of italicized text can be difficult to read for some users with low vision or reading disabilities. +## Content considerations -## Error message templates for file upload +### Error message templates for file upload **When a user doesn’t upload a required document:** diff --git a/src/_patterns/ask-users-for/gender.md b/src/_patterns/ask-users-for/gender.md new file mode 100644 index 000000000..f848add4c --- /dev/null +++ b/src/_patterns/ask-users-for/gender.md @@ -0,0 +1,32 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/gender +sub-section: ask-users-for +title: Gender +intro-text: Follow this pattern whenever you need to ask Veterans their gender. +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build +--- + +## Usage + +### When to use this pattern + +- **Don’t ask if it does not benefit the user experience.** You should only ask users about gender when absolutely necessary. + +**Note:** Many forms are based off of paper forms with limited fields for gender. Work with your stakeholder to expand the fields. + +## Examples + +![applicant information gender template]({{site.baseurl}}/images/patterns/ask-users-for/gender/gender.png) + +## How to design and build + +### How this pattern works + +- **Give Veterans the option of picking more than one gender they could identify with.** Always use checkboxes so that Veterans can identify with multiple descriptions. +* **Provide a way to self-describe.** Selecting this checkbox should reveal a text field that allows the Veteran to use their own preferred terminology. +* **Provide a way to opt-out of answering.** A checkbox labeled "Prefer not to answer" should be provided. diff --git a/src/_patterns/ask-users-for/multiple-responses.md b/src/_patterns/ask-users-for/multiple-responses.md new file mode 100644 index 000000000..9d5de5cd7 --- /dev/null +++ b/src/_patterns/ask-users-for/multiple-responses.md @@ -0,0 +1,34 @@ +--- +layout: pattern +title: Multiple responses +permalink: /patterns/ask-users-for/multiple-responses +redirect_from: + - /patterns/forms/list-and-loop +aka: List & Loop +sub-section: ask-users-for +intro-text: "Follow this pattern in forms when we need to collect more than one response from a user." +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples +--- + +## Usage + +### When to use this pattern + +Some questions in forms only have one answer, such as "What is the city and state of your birth?". Other questions can have an unknown amount of answers, such as "list all the cities and states you've lived within." This pattern appears in forms when we don't know how many responses to a question a user will provide, but we need to collect a number between 1 and "n," where "n" is all possible responses. This pattern appears in both simple and complex ways. + +## Examples + +### Simple + +A simple example of the pattern would include a small number of entry fields, such as one or two text fields in a single line. For a question like "Please list all the cities in which you've lived," a user would list a single city, be given the option to add another city, and could continue adding additional cities until all cities were entered. Then the user would choose to either continue to the next step in the form process or simply submit the completed form if they were at the end of the process. + +This diagram outlines the basic components and flow required for each state of this pattern. + +{% include component-example.html alt="Simple example of asking for multiple responses." file="/images/patterns/ask-users-for/multiple-responses/contents.png" caption="Diagram of the 5 states of this pattern." %} + +### Complex + +Complex multiple response designs include multiple inputs and conditionals. Consider the question "What are the addresses of all locations where you served?" The associated inputs, such as street address, city, state, and zip code would need to be repeated for each additional address of services. However, there are going to be changes in fields and form input rules based on whether or not the address is in the United States or international, such as the elimination/variation of "state" fields or variations on how zip codes are validated. You can see an example of a more complex version of this pattern in [service history documentation]({{ site.baseurl }}/patterns/ask-users-for/service-history) \ No newline at end of file diff --git a/src/_patterns/ask-users-for/names.md b/src/_patterns/ask-users-for/names.md new file mode 100644 index 000000000..34bc41544 --- /dev/null +++ b/src/_patterns/ask-users-for/names.md @@ -0,0 +1,43 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/names +sub-section: ask-users-for +title: Names +intro-text: "Follow this pattern whenever you need to ask for a person's name for an application." +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build + - anchor: Content considerations +--- + +## Usage + +### When to use this pattern + +* **When you need to collect a person's name.** For example, for contact information or to complete an application. + +**Note:** These fields are not on every form. Work with your stakeholders to determine what fields are necessary for your application. + +## Examples + +![applicant information name template]({{site.baseurl}}/images/patterns/ask-users-for/names/names.png) + +## How to design and build + +### How this pattern works +- **First name and last name are required fields.** Middle name and suffix fields are optional. Mother’s maiden name field is not on every form. +- **Make sure name fields work for most veterans.** Fields must be long enough to accommodate the names of your users. Do not restrict the types of characters users can enter in any of these fields. Names can include characters outside the standard Roman alphabet. + +## Content considerations + +### Error message templates for names + +**When a user doesn’t enter their first name** + +Say 'Please enter a first name' + +**When a user doesn’t enter their last name** + +Say 'Please enter a last name' \ No newline at end of file diff --git a/src/_patterns/ask-users-for/phone-numbers.md b/src/_patterns/ask-users-for/phone-numbers.md new file mode 100644 index 000000000..a47645bde --- /dev/null +++ b/src/_patterns/ask-users-for/phone-numbers.md @@ -0,0 +1,49 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/phone-numbers +sub-section: ask-users-for +title: Phone numbers +intro-text: Follow this pattern when you want to ask for a phone number. +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build + - anchor: Content considerations +--- + +## Usage + +### When to use this pattern + +* **When you need to collect a phone number.** For example, for contact information. + +## Examples + +![contact information phone number template]({{site.baseurl}}/images/patterns/ask-users-for/phone-numbers/phone-numbers.png) + +## How to design and build + +### Layout details + +### How this pattern works + +- **If possible, tell users why you want their phone number.** An example message is: *Please enter your contact information so we can get in touch with you if we have questions about your application.* This message can be at the top of the page if asking for any other contact information. +- **Validate phone numbers.** Users must provide at least a 10 digit phone number with or without dashes. Example of acceptable formats: 703-123-4567, 7031234567, 1+703-123-4567. A validation message for when a user forgets to enter the phone number: *Please enter your phone number.* A validation message for when a user’s phone number is too short: *This field should be at least 10 character(s).* +- **If a user chooses a home or mobile phone number as their method of contact, phone numbers are required fields.** If a user chooses email or mail as their preferred method then a phone number field won’t be validated. (Note: Method of contact field is form dependent) +- **“Mobile phone number” is a required field if the user checks (I would like to receive text messages from VA about my [ ] benefits).** An example of this is on the [VA Form 22-10203 (Application for Edith Nourse Rogers STEM Scholarship)](https://www.va.gov/education/other-va-education-benefits/stem-scholarship/apply-for-scholarship-form-22-10203/introduction) + +## Content considerations + +- **Do not use primary or secondary phone numbers as field labels.** Home and mobile phone numbers are more plain language-focused. +* If you need to display a phone number after it has been collected, then [follow content style guidelines on phone numbers]({{ site.baseurl }}/content-style-guide/dates-and-numbers#phone-numbers). + +### Error message templates for phone numbers + +**When a user doesn’t enter a phone number:** + +Say 'Please enter a phone number' + +**If the telephone number is not in the correct format:** + +Say 'Please enter a 10-digit phone number (with or without dashes)' diff --git a/src/_patterns/ask-users-for/race-ethnicity-or-origin.md b/src/_patterns/ask-users-for/race-ethnicity-or-origin.md new file mode 100644 index 000000000..3b52d8cac --- /dev/null +++ b/src/_patterns/ask-users-for/race-ethnicity-or-origin.md @@ -0,0 +1,29 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/race-ethnicity-or-origin +sub-section: ask-users-for +title: Race, ethnicity, or origin +intro-text: Follow this pattern whenever you need to ask veterans for their race, ethnicity, or origin. +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build +--- + +## Usage + +### When to use this pattern + +- **Don’t ask if it does not benefit the user experience.** Only collect users’ information on this topic if you are going to use the data. + +## Examples + +![applicant information race template]({{site.baseurl}}/images/patterns/ask-users-for/race-ethnicity-or-origin/race.png) + +## How to design and build + +### How this pattern works + +* **Give users the option of picking more than one ethnic group.** Always use checkboxes so that users can identify with multiple ethnicities. +* **Provide a way to opt-out of answering.** A checkbox labeled "Prefer not to answer" should be provided. \ No newline at end of file diff --git a/src/_patterns/forms/service-history.md b/src/_patterns/ask-users-for/service-history.md similarity index 69% rename from src/_patterns/forms/service-history.md rename to src/_patterns/ask-users-for/service-history.md index a998cbc94..1f90653b7 100644 --- a/src/_patterns/forms/service-history.md +++ b/src/_patterns/ask-users-for/service-history.md @@ -1,27 +1,39 @@ --- layout: pattern -permalink: /patterns/forms/service-history -has-parent: /patterns/forms/ +permalink: /patterns/ask-users-for/service-history +sub-section: ask-users-for title: Service history intro-text: "Follow this pattern to ask a user about their service/military history." status: use-deployed anchors: - - anchor: Service periods - - anchor: Service under another name - - anchor: Reserves and National Guard - - anchor: Federal Orders - - anchor: POW Status and Severance Pay + - anchor: Usage - anchor: Examples + - anchor: How to build + - anchor: Usage - Service under another name + - anchor: Usage - Reserves and National Guard and Federal Orders + - anchor: Usage - Prisoner of War (POW) --- -**Note:** Service history content varies from form to form. Let this pattern be your starting point and decide what needs to be on your form. +## Usage -## Service periods +### When to use this pattern -Follow this pattern whenever you need to ask for a user’s periods of service in the military. +* **Service periods.** Follow this pattern whenever you need to ask for a Veteran's periods of service in the military. +* **Use the multiple response pattern for adding multiple service periods.** This is an example of a complex list and loop pattern with multiple form inputs to gather multiple pieces of information. Read more about the [multiple responses]({{ site.baseurl }}/patterns/ask-users-for/multiple-responses) pattern. +* **Some forms will only require the last branch of service.** The healthcare application is an example of a form where they do not need the multiple entries of service periods, so we do not use the list and loop pattern there. -### Structure +## Examples + +- [VA Form 21P-527EZ - Application for Pension Benefits](https://www.va.gov/pension/application/527EZ/introduction) +- [VA Form 21-526EZ - Application for Disability Compensation and Related Compensation Benefits](https://www.va.gov/disability/file-disability-claim-form-21-526ez/introduction) +- [VA Form 10-10EZ - Application for Health Benefits](https://staging.va.gov/health-care/apply/application/introduction) +- [VA Form 22-1990N - Application for VA Education Benefits Under the National Call to Service (NCS) Program](https://www.va.gov/education/apply-for-education-benefits/application/1990N/introduction) + +## How to design and build +### Service periods + +#### Structure - Heading - Branch of service text input - Service start date input @@ -30,19 +42,17 @@ Follow this pattern whenever you need to ask for a user’s periods of service i - Character of service -- this can also be Character of discharge -- text input (if applicable) - ‘Add another service period’ secondary button -![pension-serviceperiods-1]({{site.baseurl}}/images/list-and-loop.png) - -![pension-serviceperiods-2]({{site.baseurl}}/images/list-and-loop3.png) +![pension-serviceperiods-1]({{site.baseurl}}/images/patterns/ask-users-for/service-history/list-and-loop.png) -### Usage +![pension-serviceperiods-2]({{site.baseurl}}/images/patterns/ask-users-for/service-history/list-and-loop3.png) -- **Use the list and loop pattern for adding multiple service periods.** This is an example of a complex list and loop pattern with multiple form inputs. You can read more in depth about the [list and loop pattern]({{ site.baseurl }}/patterns/forms/list-and-loop) above. -- **Some forms will only require the last branch of service.** The healthcare application is an example of a form where they do not need the multiple entries of service periods, so we do not use the list and loop pattern there. - -## Service under another name +## Usage - Service under another name Follow this pattern whenever you need to ask a user if they served under another name. +- **The name template fields are conditional fields that are revealed when a user selects “yes.”** Conditional fields are used in forms to reveal form elements that become relevant based on a user's response to a question. The blue border should be used to create a visual relationship between the parent question and conditional fields it reveals, and should overlap the top and bottom of parent and children. +- **Use the list and loop pattern for adding multiple names.** The user will be able to add multiple names they’ve served under. Read more about the [multiple responses]({{ site.baseurl }}/patterns/ask-users-for/multiple-responses) pattern. + ### Structure - ‘Did you serve under another name’ radio buttons @@ -51,14 +61,9 @@ Follow this pattern whenever you need to ask a user if they served under another - ‘Add another name’ secondary button - ‘Place of last or anticipated separation from service’ text input -![service under another name]({{site.baseurl}}/images/service-name.png) - -### Usage +![service under another name]({{site.baseurl}}/images/patterns/ask-users-for/service-history/service-name.png) -- **The name template fields are conditional fields that are revealed when a user selects “yes.”** Conditional fields are used in forms to reveal form elements that become relevant based on a user's response to a question. The blue border should be used to create a visual relationship between the parent question and conditional fields it reveals, and should overlap the top and bottom of parent and children. -- **Use the list and loop pattern for adding multiple names.** The user will be able to add multiple names they’ve served under. You can read more in depth about the [list and loop pattern](#listandloop) above. - -## Reserves and National Guard and Federal Orders +## Usage - Reserves and National Guard and Federal Orders Follow this pattern whenever you need to ask for a user’s Reserve or National Guard information. Persons in the Reserve or National Guard are not full-time active duty military personnel, although they can be deployed at any time should the need arise. @@ -67,7 +72,7 @@ Follow this pattern whenever you need to ask for a user’s Reserve or National - Obligation end date input - Unit name text input -![reserves and national guard disability form structure]({{site.baseurl}}/images/reserves-disability.png) +![reserves and national guard disability form structure]({{site.baseurl}}/images/patterns/ask-users-for/service-history/reserves-disability.png) ### Structure - Reserves and National Guard Pension @@ -78,7 +83,7 @@ Follow this pattern whenever you need to ask for a user’s Reserve or National - Unit phone number (if applicable) - Service start date input -![reserves and national guard pension form structure]({{site.baseurl}}/images/reserve-pension.png) +![reserves and national guard pension form structure]({{site.baseurl}}/images/patterns/ask-users-for/service-history/reserve-pension.png) ### Structure - Federal Orders Disability @@ -87,12 +92,15 @@ Follow this pattern whenever you need to ask for a user’s Reserve or National - Activation start date input - Expected separation date input (This could also be Anticipated separation date) -![federal orders]({{site.baseurl}}/images/federal-orders.png) +![federal orders]({{site.baseurl}}/images/patterns/ask-users-for/service-history/federal-orders.png) -## Prisoner of War (POW) +## Usage - Prisoner of War (POW) Follow this pattern whenever you need to ask for a user’s POW information. Former prisoners of war (POW) are Veterans who, during active military service, were forcibly detained or interned in the line of duty by an enemy government or its agents or a hostile force. +- **Don’t ask if it does not benefit the user experience.** You should only ask users about POW information when absolutely necessary. +- **Depending on the form, use the List and Loop pattern to add multiple confinement periods.** An example of adding multiple confinement periods is in the [File for disability compensation form](https://staging.va.gov/disability/file-disability-claim-form-21-526ez/introduction). + ### Structure - POW Status and Severance Pay - ‘Are you a former POW?’ radio buttons @@ -105,16 +113,5 @@ Follow this pattern whenever you need to ask for a user’s POW information. For - ‘Pay type’ radio buttons - ‘Amount’ number input -![prisoner of war and severance pay]({{site.baseurl}}/images/pow-status.png) - -### Usage - -- **Don’t ask if it does not benefit the user experience.** You should only ask users about POW information when absolutely necessary. -- **Depending on the form, use the List and Loop pattern to add multiple confinement periods.** An example of adding multiple confinement periods is in the [File for disability compensation form](https://staging.va.gov/disability/file-disability-claim-form-21-526ez/introduction). - -## Examples +![prisoner of war and severance pay]({{site.baseurl}}/images/patterns/ask-users-for/service-history/pow-status.png) -- [VA Form 21P-527EZ - Application for Pension Benefits](https://www.va.gov/pension/application/527EZ/introduction) -- [VA Form 21-526EZ - Application for Disability Compensation and Related Compensation Benefits](https://www.va.gov/disability/file-disability-claim-form-21-526ez/introduction) -- [VA Form 10-10EZ - Application for Health Benefits](https://staging.va.gov/health-care/apply/application/introduction) -- [VA Form 22-1990N - Application for VA Education Benefits Under the National Call to Service (NCS) Program](https://www.va.gov/education/apply-for-education-benefits/application/1990N/introduction) diff --git a/src/_patterns/forms/signature.md b/src/_patterns/ask-users-for/signature.md similarity index 63% rename from src/_patterns/forms/signature.md rename to src/_patterns/ask-users-for/signature.md index c2243e380..62d241822 100644 --- a/src/_patterns/forms/signature.md +++ b/src/_patterns/ask-users-for/signature.md @@ -1,20 +1,32 @@ --- layout: pattern -permalink: /patterns/forms/signature -has-parent: /patterns/forms/ +permalink: /patterns/ask-users-for/signature +sub-section: ask-users-for title: Signature -intro-text: "Use this pattern on the review section of the form when you need a user to provide their signature as a statement of truth." +intro-text: "Use this pattern when you need a user to provide their signature as a statement of truth." status: use-deployed anchors: - - anchor: Structure - anchor: Usage - - anchor: Error message templates + - anchor: Examples + - anchor: How to design and build + - anchor: Content considerations --- -![form signature pattern]({{site.baseurl}}/images/form-signature.png) +## Usage + +### When to use this pattern + +* **Certification statement or statement of truth.** Some forms will require the user to certify their submission by signature. + +## Examples + +![form signature pattern]({{site.baseurl}}/images/patterns/ask-users-for/form-signature.png) +## How to design and build -## Structure +This patterns is used at the end of a form review page. + +### Layout details - Instructions for the user around signing the certification - Card @@ -24,13 +36,16 @@ anchors: - Text input for signature - Checkbox for certification -## Usage +### How this pattern works - **Place the pattern underneath the accordions on the review section.** Do not hide this component inside an accordion. - **Signature pattern does not exist in every form.** If your form needs a certification statement or statement of truth, we recommend using this pattern. - **When using this pattern, do not add the privacy policy checkbox at the end of the form.** The user does not need to check another checkbox for privacy policy. -## Error message templates + +## Content considerations + +### Error message templates **When a user doesn’t enter the name they entered previously in the form** diff --git a/src/_patterns/ask-users-for/social-security-number.md b/src/_patterns/ask-users-for/social-security-number.md new file mode 100644 index 000000000..c25e14273 --- /dev/null +++ b/src/_patterns/ask-users-for/social-security-number.md @@ -0,0 +1,60 @@ +--- +layout: pattern +permalink: /patterns/ask-users-for/social-security-number +sub-section: ask-users-for +title: Social security or VA file number +intro-text: "Follow this pattern whenever you need to collect a person's Social Security or VA file number for an application." +status: use-deployed +anchors: + - anchor: Usage + - anchor: Examples + - anchor: How to design and build + - anchor: Content considerations +--- + +## Usage + +### When to use this pattern + +* **When you need to collect a person's Social Security or VA file number.** For example, for an application for identity purposes. + +## Examples + +![applicant information important numbers template]({{site.baseurl}}/images/patterns/ask-users-for/social-security-number/important-numbers.png) + +![social security number masked]({{site.baseurl}}/images/patterns/ask-users-for/social-security-number/ssn-masked-update.png) + +## How to design and build + +### How this pattern works + +A Social Security Number (SSN) consists of nine digits, commonly written as three fields separated by hyphens: AAA-GG-SSSS. The first three-digit field is called the "area number". The central, two-digit field is called the "group number". The final, four-digit field is called the "serial number". + +A VA file number is how a Veteran’s claim is tracked through the compensation system and how documents and other evidence are associated with a Veteran’s file in the VA’s electronic database. + +- **Use a single text input for each field.** +- **Do not abbreviate.** Use ‘Social Security number’. Do not use abbreviations, such as SSN. +- **When asking for both Social Security and VA file numbers, one or the other may be provided.** VA file numbers are not on every form.If the form asks for a Social Security number and VA file number make sure to note in the VA file number label or helper text, "must have this or a Social Security number". +- **Mask Social Security number by default.** All but the last 4 numbers are masked when input loses focus. When input is in focus, the input shows the valid numbers. +- **Give user flexibility in entering their Social Security number.** A user can enter the Social Security number however they like: with spaces, without spaces, dashes, or without dashes. When the user enters their number and the input loses focus, the number will appear masked with dashes. +- **Validate Social Security numbers.** See [content considerations](#content-considerations) for the appropriate validation messages. + +## Content considerations + +### Error message templates for Social Security number and VA file number: + +**If nothing is entered for Social Security number** + +Say 'Please enter a Social Security number' + +**When a a Social Security number is entered incorrectly** + +Say 'Please enter a valid 9 digit Social Security number (dashes allowed)' + +**If nothing is entered for VA file number** + +Say 'Please enter a VA file number' + +**When a VA file number is entered incorrectly** + +Say 'Your VA file number must be between 7 to 9 digits' \ No newline at end of file diff --git a/src/_patterns/content-presentation.md b/src/_patterns/content-presentation.md deleted file mode 100644 index bd884feb8..000000000 --- a/src/_patterns/content-presentation.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: pattern -title: Content presentation -status: use-deployed -into-text: "Describes how to choose the appropriate components for presenting content in certain contexts." -anchors: - - anchor: Featured content - - anchor: Expandable content ---- - -## Featured content - -[Featured content]({{ site.baseurl }}/components/featured-content) components are light blue boxes that call attention to important information. - -{% include storybook-preview.html height="250px" story="components-va-featured-content--default" %} - -## Expandable content - -### Accordions - -Use [accordions]({{ site.baseurl }}/components/accordion) to hold chunks of sibling content. They can be used in forms in review screens, but for additional context, please use [AdditionalInfo](#additionalinfo). - -### Additional info - -Use [additional info]({{ site.baseurl }}/components/additional-info) components in forms to provide additional context. 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. - -### How to Choose? - -- **Is this content closely tied to a particular message or input on this screen?** Use Additional info -- **Is it more tangentially related?** Use accordions diff --git a/src/_patterns/forms/applicant-information.md b/src/_patterns/forms/applicant-information.md deleted file mode 100644 index 9dc56bce9..000000000 --- a/src/_patterns/forms/applicant-information.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -layout: pattern -permalink: /patterns/forms/applicant-information -has-parent: /patterns/forms/ -title: Applicant information -intro-text: "The current implementation of applicant information on VA.gov forms." -status: use-deployed -anchors: - - anchor: Name - - anchor: Important numbers - Social security number & VA file number - - anchor: Birth information - - anchor: Gender - - anchor: Race, ethnicity, or origin ---- - - -**Note:** These fields are not on every form. Work with your stakeholders to determine what fields are necessary for your application. - -## Name -Follow this pattern whenever you need to ask for a user’s name for an application. - -![applicant information name template]({{site.baseurl}}/images/Applicant-info-name.png) - -### Usage - -- **Make sure name fields work for most veterans.** Fields must be long enough to accommodate the names of your users. Do not restrict the types of characters users can enter in any of these fields. Names can include characters outside the standard Roman alphabet. -- **First name and last name are required fields.** Middle name and suffix fields are optional. Mother’s maiden name field is not on every form. - -### Error message templates for names - -**When a user doesn’t enter their first name** - -Say 'Please enter a first name' - -**When a user doesn’t enter their last name** - -Say 'Please enter a last name' - - -## Important numbers: Social security number & VA file number -Follow this pattern whenever you need to ask for a social security number or VA file number. - -A Social Security Number (SSN) consists of nine digits, commonly written as three fields separated by hyphens: AAA-GG-SSSS. The first three-digit field is called the "area number". The central, two-digit field is called the "group number". The final, four-digit field is called the "serial number". -A VA file number is how a veteran’s claim is tracked through the compensation system and how documents and other evidence are associated with a veteran’s file in the VA’s electronic database. - -![applicant information important numbers template]({{site.baseurl}}/images/Applicant-info-important-numbers.png) - -![social security number masked]({{site.baseurl}}/images/ssn-masked-update.png) - - -### Usage -- **Use a single text input for social security and VA file number.** Label the text input ‘Social Security number.’ Do not use abbreviations, such as SSN. -- **VA file numbers are not on every form.** If the form asks for a Social Security number and VA file number make sure to note in the VA file number helper text, “must have this or a Social Security number.” -- **Mask Social Security number by default.** All but the last 4 numbers are masked when input loses focus. When input is in focus, the input shows the valid numbers. -- **Give user flexibility in entering their Social Security number.** A user can enter the Social Security number however they like: with spaces, without spaces, dashes, or without dashes. When the user enters their number and the input loses focus, the number will appear masked with dashes. -- **Validate Social Security numbers.** A validation message for when the Social Security number is required: *Please enter a Social Security number.* A validation message for when a Social Security number is entered incorrectly: *Please enter a valid 9 digit Social Security number (dashes allowed).* - -### Error message templates for Social Security number and VA file number: - -**If nothing is entered for Social Security number** - -Say 'Please enter a Social Security number' - -**When a a Social Security number is entered incorrectly** - -Say 'Please enter a valid 9 digit Social Security number (dashes allowed)' - -**If nothing is entered for VA file number** - -Say 'Please enter a VA file number' - -**When a VA file number is entered incorrectly** - -Say 'Your VA file number must be between 7 to 9 digits' - -### Birth information - -Follow this pattern whenever you need to ask for a user’s date and place of birth. - -![applicant information birth information template]({{site.baseurl}}/images/Applicant-info-birth-info.png) - -### Usage - -- **Use the date input field for date of birth.** Writing out the label for each birth date string and separating them into three fields instead of one eliminates the format confusion. -- **Place of birth information is one text input.** This format is easier to fill out for both veterans born outside the United States and for veterans who were born United States citizens. - -## Gender - -Follow this pattern whenever you need to ask veterans their gender. - -![applicant information gender template]({{site.baseurl}}/images/Applicant-info-gender.png) - -### Usage - -- **Don’t ask if it does not benefit the user experience.** You should only ask users about gender when absolutely necessary. -- **Use checkboxes.** Give veterans the ability to check more than one gender they could identify with. - -**Note:** Many forms are based off of paper forms with limited fields for gender. Work with your stakeholder and see if you can expand the fields. - -## Race, ethnicity, or origin - -Follow this pattern whenever you need to ask veterans for their race, ethnicity, or origin. - -![applicant information race template]({{site.baseurl}}/images/Applicant-info-race.png) - -### Usage -- **Don’t ask if it does not benefit the user experience.** Only collect users’ information on this topic if you are going to use the data. -- **Give users the option of picking more than one ethnic group.** Always use checkboxes so that users can identify with multiple ethnicities. \ No newline at end of file diff --git a/src/_patterns/forms/contact-information.md b/src/_patterns/forms/contact-information.md deleted file mode 100644 index affbebb11..000000000 --- a/src/_patterns/forms/contact-information.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -layout: pattern -permalink: /patterns/forms/contact-information -has-parent: /patterns/forms/ -title: Contact information -intro-text: "The current implementation of contact information on VA.gov forms." -status: use-deployed -anchors: - - anchor: Addresses - - anchor: Email address - - anchor: Phone numbers - - anchor: Preferred method of contact (if applicable) ---- - -## Addresses - -Follow these patterns whenever you need to ask for a user’s address. - -### Single address - -Here is the content structure for asking a user for a single address: - -- Checkbox for military address (if applicable) -- Additional info component (if applicable) -- Country select box -- Street address text input -- Street address line 2 text input -- Street address line 3 text input (if applicable) -- City text input -- State/Province/Region select box -- Postal code text input - -![contact information single address template]({{site.baseurl}}/images/Address.png) - -### Usage - -- **If required, include a checkbox for United States military base address.** Under the additional information component, there should be an explanation: - U.S. military bases are considered a domestic address and a part of the United States. When the checkbox is checked, the country select box becomes disabled. -- **If asking for only one address on a form, be clear with the user which address (mailing or home) you’re asking for.** We recommend asking for a mailing address if you need to only ask for one address. -- **Street address Line 3 can be omitted.** Sometimes partner databases do not support a third line of address. - -### Multiple addresses: Mailing and Home addresses - -Follow this pattern when asking for both mailing and home addresses. In some forms, we ask for both addresses because some veterans live in different homes depending on the time of year. - -Here is the content structure for asking a user for multiple addresses: -- Header - Mailing or Home Address -- Relevant information regarding this form and the user’s address (if applicable) -- Checkbox for military address (if applicable) -- Additional info component (if applicable) -- Country select box -- Street address text input -- Street address line 2 text input -- Street address line 3 text input (if applicable) -- City text input -- State/Province/Region select box -- Postal code text input -- Radio button component for mailing address same as home address (this is on mailing address page only) - -**Mailing address** - -![contact information mailing address template]({{site.baseurl}}/images/Mailing-address.png) - -**Home address** - -![contact information home address template]({{site.baseurl}}/images/Home-address.png) - -### Usage - -- **Add guidance on where users can go to edit their account information on all VA accounts.** Let the user know that when filling out contact information, they will have to edit their profile information. An example message is: *Any updates you make here to your contact information will only apply to this application. To update your contact information for all of your VA accounts, go to your profile page (link to profile).* -- **The mailing address always comes before home address.** We ask for a mailing address before home address because the majority of VA's correspondence is over mail. -- **On the mailing address form, ask users if the home address is the same as the mailing address.** If the user chooses “Yes”, they can skip the home address form. - -### Error message templates for addresses - -**When a user doesn’t enter a street address:** - -Say 'Please enter a street address' - -**When a user doesn’t enter a city:** - - Say 'Please enter a city' - -**When a user doesn’t enter a state:** - -Say 'Please enter a state' - -**When a user doesn’t enter a postal code:** - -Say 'Please enter a postal code' - -**When a postal code is entered incorrectly:** - -Say 'Please enter a valid 5- or 9-digit postal code (dashes allowed)' - -**When a postal code can’t be correct:** - -Say 'Please provide a valid postal code' - -**When a user doesn’t select a state or province:** - -Say 'Please select a state or province' - -## Email address - -Follow this pattern when you want to ask for an email address. -![contact information email address template]({{site.baseurl}}/images/contact-info-email-address.png) - -### Usage - -- **If possible, tell users why you want their email address.** Users need to know that the VA won’t abuse their email and which email they’d like to provide. An example message is: *Please enter your contact information so we can get in touch with you if we have questions about your application.* -- **Validate email addresses.** You should validate email addresses so you can let users know if they have entered one incorrectly. A validation message for when a user forgets the “@”: *Please enter a valid email address.* A validation message for when a user doesn’t use the same email in the “Confirm email address” field: *This email doesn't match the one you entered above.* - -### Error message templates for email addresses - -**When a user doesn’t enter an email address:** - -Say 'Please enter an email address' - -**When a user doesn’t enter an email address in the correct format:** - -Say 'Please enter an email address using this format: X@X.com' - -**When a user doesn’t use the same email in the “Confirm email address” field:** - -Say ‘This email doesn’t match the one you entered above’. - -## Phone numbers - -Follow this pattern when you want to ask for a phone number. -![contact information phone number template]({{site.baseurl}}/images/contact-info-phone-number.png) - -### Usage - -- **If possible, tell users why you want their phone number.** An example message is: *Please enter your contact information so we can get in touch with you if we have questions about your application.* This message can be at the top of the page if asking for any other contact information. -- **Validate phone numbers.** Users must provide at least a 10 digit phone number with or without dashes. Example of acceptable formats: 703-123-4567, 7031234567, 1+703-123-4567. A validation message for when a user forgets to enter the phone number: *Please enter your phone number.* A validation message for when a user’s phone number is too short: *This field should be at least 10 character(s).* -- **If a user chooses a home or mobile phone number as their method of contact, phone numbers are required fields.** If a user chooses email or mail as their preferred method then a phone number field won’t be validated. (Note: Method of contact field is form dependent) -- **“Mobile phone number” is a required field if the user checks (I would like to receive text messages from VA about my [ ] benefits).** An example of this is on the [VA Form 22-10203 (Application for Edith Nourse Rogers STEM Scholarship)](https://www.va.gov/education/other-va-education-benefits/stem-scholarship/apply-for-scholarship-form-22-10203/introduction) -- **Do not use primary or secondary phone numbers as field labels.** Home and mobile phone numbers are more plain language-focused. - -### Error message templates for phone numbers - -**When a user doesn’t enter a phone number:** - -Say 'Please enter a phone number' - -**If the telephone number is not in the correct format:** - -Say 'Please enter a 10-digit phone number (with or without dashes)' - -## Method of contact - -Follow this pattern when you want to ask a user how they’d like to be contacted. -![contact information method of contact template]({{site.baseurl}}/images/contact-info-method-of-contact.png) - -### Usage - -- **This field is dependent on the form.** Method of contact is form-dependent. Work with your stakeholders on whether your form needs a method of contact. -- **Give users the opportunity to pick one method of contact.** Provide contact information methods in radio button list form. \ No newline at end of file diff --git a/src/_patterns/forms/dates.md b/src/_patterns/forms/dates.md deleted file mode 100644 index 2c687a04b..000000000 --- a/src/_patterns/forms/dates.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: pattern -permalink: /patterns/forms/dates -has-parent: /patterns/forms/ -title: Dates -intro-text: "The current implementation for collecting dates on VA.gov forms." -status: use-deployed -anchors: - - anchor: When to use this pattern - - anchor: Usage - - anchor: Error message templates for dates ---- - -## When to use this pattern - -Follow this pattern whenever you need users to provide a date on a form. - -Dates you may need users to provide include: -- Dates a user knows, like a date of birth or marriage -- Dates a user can approximate , like February 2021 -- Date ranges, like service history dates - -### Dates a user knows - -Use the month/day/year date input component for most dates, particularly memorized dates. - -![date input for memorized dates: month day and year]({{site.baseurl}}/images/date-input.png) - -### Dates a user can approximate - -Use the month/year date input component for dates that a user may struggle to remember. For example: *When did you receive your high school diploma or equivalency certificate?* - -![date input for approximate dates: month and year]({{site.baseurl}}/images/date-input-month-year.png) - -### Date ranges - -Use month/day/year inputs or month/year inputs depending on the question being asked. For example: Service history dates - -![date ranges: service start date and service end date]({{site.baseurl}}/images/date-ranges.png) - -## Usage - -- **Write clear form labels for date ranges** Do not use “From” and “To” to when labeling form labels for date ranges. Make it clear what dates you’re asking for. Example: “Obligation start date” and “Obligation end date” -- **Spell out full month names in the selected state** The month select box should have the full month’s name. Example: January -- **Validate date inputs.** You should validate date inputs so you can let users know if they have entered one incorrectly. A general validation message for an incorrect date: *Please enter a valid date* - -## Error message templates for dates - -**If nothing is entered** -Say 'Please enter a date' - -**If the date entered can’t be correct** -Say ‘Please provide a valid date' - -**If the date entered is in a month year format and can’t be correct** -Say 'Please enter a valid month and year' - -**If the year needed to be within a specific range** -Say 'Please enter a year between [minimum year] and [maximum year]' - -**For a date range, if the date must be after another date** -Say 'To date must be after From date' - -**If the date is in the past when it needs to be today or in the future** -Say 'Please provide a valid current or future date' - -**If the date is in the future when it needs to be past date or current date** -Say 'Please enter a valid current or past date' \ No newline at end of file diff --git a/src/_patterns/forms/list-and-loop.md b/src/_patterns/forms/list-and-loop.md deleted file mode 100644 index 546779865..000000000 --- a/src/_patterns/forms/list-and-loop.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: pattern -permalink: /patterns/forms/list-and-loop -has-parent: /patterns/forms/ -title: List and loop -intro-text: "List and loop is a pattern that appears in forms when we don't know how many responses to a question a user will provide." -status: use-deployed -anchors: - - anchor: When to use this pattern - - anchor: Simple - - anchor: Complex ---- - -## When to use this pattern - -Some questions in forms only have one answer, such as "what is the city and state of your birth?". Other questions can have an unknown amount of answers, such as "list all the cities and states you've lived within." List and loop is a pattern that appears in forms when we don't know how many responses to a question a user will provide, but we need to collect a number between 1 and "n," where "n" is all possible responses. This pattern appears in both simple and complex ways. - -## Simple - -A simple example of the pattern would include a small number of entry fields, such as one or two text fields in a single line. For a question like "Please list all the cities in which you've lived," a user would list a single city, be given the option to add another city, and could continue adding additional cities until all cities were entered. Then the user would choose to either continue to the next step in the form process or simply submit the completed form if they were at the end of the process. - -This diagram outlines the basic components required for each state of a list and loop pattern. - -![list-and-loop-diagram]({{site.baseurl}}/images/list-and-loop-contents.png) - -## Complex - -Complex list and loop designs include multiple inputs and conditionals. Consider the question "What are the addresses of all locations where you served?" The associated inputs, such as street address, city, state, and zip code would need to be repeated for each additional address of services. However, there are going to be changes in fields and form input rules based on whether or not the address is in the United States or international, such as the elimination/variation of "state" fields or variations on how zip codes are validated. You can see an example of a complex list and loop pattern in [service history documentation]({{ site.baseurl }}/patterns/forms/service-history) diff --git a/src/_patterns/forms/review.md b/src/_patterns/forms/review.md deleted file mode 100644 index c8393fe62..000000000 --- a/src/_patterns/forms/review.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: pattern -permalink: /patterns/forms/review -has-parent: /patterns/forms/ -title: Review -intro-text: "Follow this pattern to help users review their information before submitting the form." -status: use-deployed -anchors: - - anchor: Structure - - anchor: Usage ---- - -## Structure - -- Show the progress bar along with the chapter title: Review application.Screen Shot 2021-03-30 at 10 26 40 AM -- Use bordered, multi-selectable accordions -- When an accordion is open, each section within a chapter should have a secondary “Edit” button in the top right. -- Underneath the accordions include the note: -Note: According to federal law, there are criminal penalties, including a fine and/or imprisonment for up to 5 years, for withholding information or for providing incorrect information (See 18 U.S.C. 1001). -and -- Privacy agreement -- Button pair: Secondary button labeled “Back” and Default blue button labeled “Submit application” -- Last saved application date and time in green background color only alert style -- Finish this application later default link - -**Note:** This content will vary depending on your form. Work with your content specialist or check out the form labels. - -## Usage - -- Each chapter should be its own accordion. -- List chapters in chronological order. -- ‘File upload’ and ‘Add another’ sections should be in the gray card style. -- ‘Add another’ primary button should be placed at the bottom left on cards that allow users to add information. -Screen Shot 2021-03-30 at 10 30 42 AM -- ‘Delete file’ secondary button should be placed at the bottom left on cards that allow users to upload files - -Screen Shot 2021-03-30 at 10 25 40 AM - diff --git a/src/_patterns/forms/check-a-service-is-suitable.md b/src/_patterns/help-users-to/check-a-service-is-suitable.md similarity index 85% rename from src/_patterns/forms/check-a-service-is-suitable.md rename to src/_patterns/help-users-to/check-a-service-is-suitable.md index 6c04797aa..3a9c370ef 100644 --- a/src/_patterns/forms/check-a-service-is-suitable.md +++ b/src/_patterns/help-users-to/check-a-service-is-suitable.md @@ -1,9 +1,11 @@ --- layout: pattern -title: Check a service is suitable -intro-text: "Helps a user to determine if they can or should use a service." +permalink: /patterns/help-users-to/check-their-eligibility +title: Check their eligibility +sub-section: help-users-to +intro-text: "Helps a user to determine if they are eligible to apply or use a service." draft: true -research-title: check-a-service-is-suitable +research-title: check-their-eligibility status: use-with-caution-available anchors: - anchor: Usage diff --git a/src/_patterns/help-users-to/check-answers.md b/src/_patterns/help-users-to/check-answers.md new file mode 100644 index 000000000..69f4ba48a --- /dev/null +++ b/src/_patterns/help-users-to/check-answers.md @@ -0,0 +1,49 @@ +--- +layout: pattern +title: Check answers +permalink: /patterns/help-users-to/check-answers +redirect_from: + - /patterns/forms/review +sub-section: help-users-to +intro-text: "Follow this pattern to help users check their answers before submitting a form." +status: use-deployed +anchors: + - anchor: Usage + - anchor: How to design and build +--- + +## Usage + +### When to use this pattern + +* **At the end of a form flow.** Allowing users to check their answers before submitting their form allows them an opportunity to catch any mistakes they have made and allows for them to reconsider their answers. + +## How to design and build + +### How this pattern works + +- Each chapter should be its own accordion. +- List chapters in chronological order. +- ‘File upload’ and ‘Add another’ sections should be in the gray card style. +- ‘Add another’ primary button should be placed at the bottom left on cards that allow users to add information. +- ‘Delete file’ secondary button should be placed at the bottom left on cards that allow users to upload files + +### Layout details + +- Show the [Progress bar - Segmented]({{ site.baseurl }}/components/form/progress-bar-segmented) along with the chapter title: Review application. +- Use bordered, multi-selectable [accordions]({{ site.baseurl }}/components/accordion). +- When an accordion is open, each section within a chapter should have a secondary “Edit” button in the top right. +- Underneath the accordions include the note: +> Note: According to federal law, there are criminal penalties, including a fine and/or imprisonment for up to 5 years, for withholding information or for providing incorrect information (See 18 U.S.C. 1001). +- Following the note also include the Privacy agreement. +- [Button pair]({{ site.baseurl }}/components/button/button-pair): Secondary button labeled “Back” and Default blue button labeled “Submit application” +- Last saved application date and time in green background color only alert style +- Finish this application later default link + +**Note:** This content will vary depending on your form. Work with your content specialist or check out the form labels. + +### Components used in this pattern + +* [Accordion]({{ site.baseurl }}/components/accordion) +* [Button pair]({{ site.baseurl }}/components/button/button-pair) +* [Progress bar - Segmented]({{ site.baseurl }}/components/form/progress-bar-segmented) \ No newline at end of file diff --git a/src/_patterns/authenticated-info-list.md b/src/_patterns/help-users-to/check-personal-information.md similarity index 85% rename from src/_patterns/authenticated-info-list.md rename to src/_patterns/help-users-to/check-personal-information.md index 1f9064ec9..9d48ce83d 100644 --- a/src/_patterns/authenticated-info-list.md +++ b/src/_patterns/help-users-to/check-personal-information.md @@ -1,6 +1,11 @@ --- layout: pattern -title: Authenticated info list +title: Check personal information +permalink: /patterns/help-users-to/check-personal-information +redirect_from: + - /patterns/authenticated-info-list +aka: Authenticated info list +sub-section: help-users-to intro-text: "This pattern helps users quickly see a list of items related to their own personal information, as well as quickly navigate to answers to the questions they might have." status: use-with-caution-available contributors: Shawna Hein, Kevin Stachura @@ -13,8 +18,6 @@ anchors: - anchor: Research --- - - ## Purpose The purpose of this pattern is: @@ -26,7 +29,7 @@ The purpose of this pattern is: ## Example -![image]({{site.baseurl}}/images/experimental-design/auth-info-list-authenticated-list-tool.jpeg) +![image]({{site.baseurl}}/images/patterns/help-users-to/check-personal-information/auth-list-tool.jpeg) 1. **'On this page' component.** This section should link to the associated content on the page. It should 'jump' to that section when the user clicks it. @@ -39,15 +42,15 @@ The purpose of this pattern is: #### Typical layout -![image]({{site.baseurl}}/images/experimental-design/auth-info-list-apple-tool-first-mock-3.jpeg) +![image]({{site.baseurl}}/images/patterns/help-users-to/check-personal-information/apple-tool.jpeg) #### Layout with consolidated additional information (FAQs section) -![image]({{site.baseurl}}/images/experimental-design/auth-info-list-apple-tool-consolidated-faq-3.jpeg) +![image]({{site.baseurl}}/images/patterns/help-users-to/check-personal-information/apple-tool-consolidated-faq-3.jpeg) ### Mobile -![image]({{site.baseurl}}/images/experimental-design/auth-info-list-apple-tool-mobile-3.jpeg) +![image]({{site.baseurl}}/images/patterns/help-users-to/check-personal-information/apple-tool-mobile-3.jpeg) ### Usage @@ -66,7 +69,7 @@ The on this page component should start with a link to the list itself, and then #### Integrating contextual questions in the cards Overall questions should be in a content area accessed by the "on this page" component, but more contextual questions can be "additional info" components on the cards themselves. Example provided. -![image]({{site.baseurl}}/images/experimental-design/auth-info-list-additional-info.png) +![image]({{site.baseurl}}/images/patterns/help-users-to/check-personal-information/additional-info.png) #### Items on the card and optional card elements Make sure to not overload elements on the cards. If you're finding you need to let the user know about a fair amount of information about a single card, link to a details page with more detail. diff --git a/src/_patterns/forms/sub-task.md b/src/_patterns/help-users-to/complete-a-sub-task.md similarity index 93% rename from src/_patterns/forms/sub-task.md rename to src/_patterns/help-users-to/complete-a-sub-task.md index 3f590bdf7..f618d5299 100644 --- a/src/_patterns/forms/sub-task.md +++ b/src/_patterns/help-users-to/complete-a-sub-task.md @@ -1,8 +1,11 @@ --- layout: pattern -title: Sub-task -permalink: /patterns/forms/sub-task -has-parent: /patterns/forms/ +permalink: /patterns/help-users-to/complete-a-sub-task +redirect_from: + - /patterns/forms/sub-task +sub-section: help-users-to +title: Complete a sub task +aka: Sub-task, Wizard intro-text: "Helps users complete a shorter task before, or within, a larger process or flow." research-title: sub-task sketch-link: https://www.sketch.com/our-workspace-the-pattern-library/specific-page-for-this-pattern @@ -27,7 +30,7 @@ The sub-task pattern provides guidance on how to "keep it simple". This pattern All of the use cases below are valid uses for this pattern. -* **Task before a flow.** Sometimes, the eligibility for a VA benefit or resource is so complex that it has multiple access pathways, depending on a user's specific needs or circumstances. Users may experience consequences (e.g. not getting the benefit or limiting benefit options), if they misunderstand eligibility content or choose the wrong pathway. Use this pattern to guide users down an optimal pathway for their circumstances. This is also known as [branching eligibility choices]({{ site.baseurl }}/patterns/benefit-applications#f-optional-sub-task-pattern-for-branching-eligibility-choices). +* **Task before a flow.** Sometimes, the eligibility for a VA benefit or resource is so complex that it has multiple access pathways, depending on a user's specific needs or circumstances. Users may experience consequences (e.g. not getting the benefit or limiting benefit options), if they misunderstand eligibility content or choose the wrong pathway. Use this pattern to guide users down an optimal pathway for their circumstances. This is also known as [branching eligibility choices]({{ site.baseurl }}/patterns/help-users-to/navigate-benefit-applications#f-optional-help-users-to-complete-a-sub-task-pattern-for-branching-eligibility-choices). * **Task within a flow.** Use this pattern when we need the user to complete a shorter task, one that can be accomplished with a few questions, within a larger process that may span touchpoints. #### Design principles @@ -43,7 +46,7 @@ That one decision or question may require more than one input from the user as t ### When not to use this pattern -* **In place of a standard form flow.** This pattern does not replace a standard form flow and layout. This pattern exists within a larger flow or process, not by itself. Thus it would be inappropriate to create a stand-alone form flow that does not have a [Progress bar - Segmented]({{ site.baseurl }}/components/form/progress-bar-segmented), [Button pair]({{ site.baseurl }}/components/button/button-pair), and other components found in a typical [form flow]({{ site.baseurl }}/patterns/forms/#the-structure-of-a-form). +* **In place of a standard form flow.** This pattern does not replace a standard form flow and layout. This pattern exists within a larger flow or process, not by itself. Thus it would be inappropriate to create a stand-alone form flow that does not have a [Progress bar - Segmented]({{ site.baseurl }}/components/form/progress-bar-segmented), [Button pair]({{ site.baseurl }}/components/button/button-pair), and other components found in a typical [form flow]({{ site.baseurl }}/templates/forms/#the-structure-of-a-form). ### When to use caution @@ -53,14 +56,14 @@ That one decision or question may require more than one input from the user as t ### Pre-check-in experience -{% include component-example.html alt="Check-in experience sub-task example." file="/images/patterns/forms/sub-task/Check-in-sub-task.png" caption="Pre-check-in sub-task." %} +{% include component-example.html alt="Check-in experience sub-task example." file="/images/patterns/help-users-to/complete-a-sub-task/Check-in-sub-task.png" caption="Pre-check-in sub-task." %} * An example of a task that helps determine if current information on file for a Veteran is correct before checking in at a facility. This example shows the success path. * Note that this example features a [Button pair]({{ site.baseurl }}/components/button/button-pair) for Yes/no which has some [accessibility considerations](#accessibility-considerations). ### VA Online Scheduling (VAOS) Vaccine sub-task -{% include component-example.html alt="VA Online Scheduling sub-task example." file="/images/patterns/forms/sub-task/VAOS-vaccine-sub-task.png" caption="VA Online Scheduling vaccine sub-task." %} +{% include component-example.html alt="VA Online Scheduling sub-task example." file="/images/patterns/help-users-to/complete-a-sub-task/VAOS-vaccine-sub-task.png" caption="VA Online Scheduling vaccine sub-task." %} * An example of a short task within a larger process, the questions related to vaccination status are a sub-task that results in either the user moving forward in the process or reaching a stopping point. This is sometimes also referred to as a "screener question", in that it screens out users from continuing along the larger process. * Step 4 in this sub-task shows an example of an [end point](#define-clear-end-points). diff --git a/src/_patterns/show-more-options.md b/src/_patterns/help-users-to/navigate-a-long-list.md similarity index 66% rename from src/_patterns/show-more-options.md rename to src/_patterns/help-users-to/navigate-a-long-list.md index 591fc5c19..212f7e485 100644 --- a/src/_patterns/show-more-options.md +++ b/src/_patterns/help-users-to/navigate-a-long-list.md @@ -1,9 +1,14 @@ --- layout: pattern -title: Show more options +title: Navigate a long list +permalink: /patterns/help-users-to/navigate-a-long-list +redirect_from: + - /patterns/show-more-options +aka: Show more options +sub-section: help-users-to contributors: Peter Russo (VAOS) added: 7/5/2022 -intro-text: Allows users to progressively display the available options in a long list as needed. This helps the user process a long list in smaller chunks. +intro-text: Allows users to navigate and process a long list of items by progressively displaying additional items as needed. research-title: Show more options sketch-link: https://www.sketch.com/s/610156b6-f281-4497-81f3-64454fc72156/p/AC70760E-54B7-41E1-982A-26E3B29049DF status: use-with-caution-candidate @@ -28,29 +33,31 @@ anchors: ## Examples -{% include component-example.html alt="Show more options screen example from the VA Online Scheduling application." file="/images/patterns/show-more-options/vaos-choose-location.png" caption="The VA Online Scheduling application uses the Show more options pattern for choosing VA facility locations." width="50%" %} +{% include component-example.html alt="Show more options screen example from the VA Online Scheduling application." file="/images/patterns/help-users-to/navigate-a-long-list/vaos-choose-location.png" caption="The VA Online Scheduling application uses this pattern for choosing VA facility locations." width="50%" %} + +{% include component-example.html alt="Help users to navigate a long list example from the VA Claim Status tool." file="/images/patterns/help-users-to/navigate-a-long-list/claim-status-tool.gif" caption="The VA Claim Status tools uses this pattern for navigating a long list of older updates to a claim." width="75%" %} ## How to design and build ### Anatomy or layout details -{% include component-example.html alt="Show more options mock-up screen examples." file="/images/patterns/show-more-options/interactions.png" caption="The anatomy of the Show more options pattern." %} +{% include component-example.html alt="Show more options mock-up screen examples." file="/images/patterns/help-users-to/navigate-a-long-list/interactions-v2.png" caption="The anatomy of the help users to navigate a long list pattern." %} 1. **Default state**. A mobile screen of a page in a VA.gov form flow. The form question consists of a list with ten total options. 5 options are displayed. A link underneath reads "+ show 5 more options" 2. **Default state - sorter**. A dropdown labeled "Sort these options". 3. **Default state - radio options**. Five generic radio buttons. -4. **Default state - show more link**. Show more link exists between the options nad the navigation buttons. +4. **Default state - show more button or link**. Show more button or link exists between the options and the navigation buttons. 5. **State when all options are showing**. A mobile screen of a page in a VA.gov form flow. Same as the first except 10 radio buttons are showing, and the link is not. -6. **State when there are only 5 total options**. A mobile screen of a page in a VA.gov form flow. Same as the first except there is no link to show more options. +6. **State when there are only 5 total options**. A mobile screen of a page in a VA.gov form flow. Same as the first except there is no link or button to show more options. ### How this pattern works * Given a long list of options, only the first 5 options are displayed. -* A link below the options acts as a trigger for revealing additional options. - * This link does not appear if there are 5 or less options. -* Clicking the link displays more options, 5 at a time. -* Once all options are displayed, the link disappears. -* Once the additional options are revealed, there is no need and thus no mechanism to hide them. +* A button or link below the options acts as a trigger for revealing additional options. + * This button or link does not appear if there are 5 or less options. +* Clicking the button or link displays more options, 5 at a time. +* Once all options are displayed, the button or link disappears, or changes label ("Hide options"). +* Once the additional options are revealed, there may be no need, and thus no mechanism, to hide them. ### Components used in this pattern @@ -59,6 +66,7 @@ anchors: ### Page templates available for this pattern * This pattern exists in VA Online Scheduling (VAOS) on the facility and provider sections of the "Start scheduling" flow. +* This pattern also exists in the VA Claim Status tool. ## Content considerations diff --git a/src/_patterns/benefit-applications.md b/src/_patterns/help-users-to/navigate-benefit-applications.md similarity index 82% rename from src/_patterns/benefit-applications.md rename to src/_patterns/help-users-to/navigate-benefit-applications.md index 691caadeb..1abb9ec61 100644 --- a/src/_patterns/benefit-applications.md +++ b/src/_patterns/help-users-to/navigate-benefit-applications.md @@ -1,6 +1,11 @@ --- layout: pattern -title: Benefit applications +title: Navigate benefit applications +permalink: /patterns/help-users-to/navigate-benefit-applications +redirect_from: + - /patterns/benefit-applications +aka: Benefit applications +sub-section: help-users-to status: use-deployed intro-text: "Users can apply for benefits in any of the benefit hubs on VA.gov. The policies and regulations around these benefits are very complex, and users often have difficulty determining if they are eligible, what they need to provide, and what to expect after they've submitted their application. For these reasons, Benefit applications, as a pattern, is divided into four distinct \"epics\" that help users navigate the process from start to finish." anchors: @@ -35,7 +40,7 @@ The hierarchy of the eligibility pattern allows it to be flexible enough to cove The eligibility page consists of the following elements: -![eligibility_page_heirarchy](/images/eligibility_page_heirarchy.png) +![eligibility_page_heirarchy]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/eligibility_page_heirarchy.png) #### A. Title and statement of intent The title should be “Eligibility for (Most Commonly Used Benefit Name).” The statement of intent should state the job the page will do for the user, by stating something like “Find out if you are eligible for (most commonly requested benefits, described in plain language). This allows a user to quickly assess if they are in the right place, and it helps search engines highly rank these pages for appropriate searches. @@ -49,14 +54,14 @@ The featured content component is used to present the user with the most commonl

    Do

    Use a single featured component for the most common scenario.

    -![eligibility_page_heirarchy](/images/featured-content-do.png) +![eligibility_page_heirarchy]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/featured-content-do.png)

    Don’t

    Use two or more featured components for multiple scenarios, because there can't be more than one that is the most common. Use other page elements for this purpose.

    -![eligibility_page_heirarchy](/images/featured-content-dont.png) +![eligibility_page_heirarchy]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/featured-content-dont.png)
    @@ -67,7 +72,7 @@ The featured content component is used to present the user with the most commonl Benefit eligibility or requirements information that is more nuanced than the summary placed inside the Common scenario overview (featured content component), including different requirements for sub-audiences, application assistance, etc. Group prerequisites logically by benefit type, and order benefit types from most common to less common. -![eligibility_prerequisites](https://user-images.githubusercontent.com/50150810/58469821-3a6ec380-8138-11e9-85bf-0bd2f6292aec.png) +![eligibility_prerequisites]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/additional-eligibility.png) #### D. Optional: Eligibility change announcement @@ -81,10 +86,10 @@ When time sensitive content about a benefit — such as a new benefit being made A brief heading should precede and call attention to the sub-task link or action link. This heading can be followed by an optional single sentence of text or phrase if necessary. -If your page uses a [sub-task pattern]({{ site.baseurl }}/patterns/forms/sub-task), use a [secondary action link]({{ site.baseurl }}/components/link/action#secondary). If the page does not have a sub-task pattern and you want to direct your user to the application flow, use a [primary action link]({{ site.baseurl }}/components/link/action#primary). This action link is a visually prominent link that will bring the user to another page. +If your page uses the [Help users to complete a sub-task pattern]({{ site.baseurl }}/patterns/help-users-to/complete-a-sub-task), use a [secondary action link]({{ site.baseurl }}/components/link/action#secondary). If the page does not have a help users to complete a sub-task pattern and you want to direct your user to the application flow, use a [primary action link]({{ site.baseurl }}/components/link/action#primary). This action link is a visually prominent link that will bring the user to another page. Having an action link on the page helps the user follow the most logical path. -Note: Avoid putting more than one action link on the page. If you have a page that requires multiple benefit form links, use the [sub-task pattern]({{ site.baseurl }}/patterns/forms/sub-task) to create branching logic to get the correct benefit application (or prevent a user from applying to the wrong benefit). +Note: Avoid putting more than one action link on the page. If you have a page that requires multiple benefit form links, use the [pattern for helping users to complete a sub-task]({{ site.baseurl }}/patterns/help-users-to/complete-a-sub-task) to create branching logic to get the correct benefit application (or prevent a user from applying to the wrong benefit). The action link can be followed by item 6, Additional Benefit-Eligibility-Specific Relevant Content, if necessary. @@ -92,9 +97,9 @@ The action link can be followed by item 6, Additional Benefit-Eligibility-Specif Screen reader users can’t scan a page visually to immediately know that there is content below any particular action item such as an action link. So, if they come across a key call to action, there is no guarantee or certainty that they will know that more information, that may be important to that call to action, could exist beyond that call to action. Therefore, please be mindful about placing important content below the key call to action. -#### F. Optional: Sub-task pattern for branching eligibility choices +#### F. Optional: Help users to complete a sub-task pattern for branching eligibility choices -In the case where there are multiple benefit options, the [Sub-task pattern]({{ site.baseurl }}/patterns/forms/sub-task) allows a user to branch into the appropriate benefit application from the eligibility page. +In the case where there are multiple benefit options, the [pattern for helping users to complete a sub-task]({{ site.baseurl }}/patterns/help-users-to/complete-a-sub-task) allows a user to branch into the appropriate benefit application from the eligibility page. The text of the action link should represent the job the sub-task is performing, such as "Find your education benefits form". @@ -127,12 +132,12 @@ The introduction describes what the page is about. For the “How to apply” pa * SEO keywords (See [Writing for SEO]({{ site.baseurl }}/content-style-guide/seo).) ### Preparing to apply (informational callout) -On the “How to apply” page, use the [informational callout]({{ site.baseurl }}/patterns/content-presentation) box to present chunked, scannable snippets of critical information needed by the majority of applicants. For example, +On the “How to apply” page, use the [featured content]({{ site.baseurl }}/components/featured-content) component to present chunked, scannable snippets of critical information needed by the majority of applicants to apply. For example, * Describe what a user needs to do before they begin the application * List items needed to complete the application (SSN, military history, etc.). Required items should be called out. -Note: The blue [informational callout]({{ site.baseurl }}/patterns/content-presentation) box should only be used for the most important information on the page. Since it includes critical information, the callout should appear near the top of the page. +Note: The [featured content]({{ site.baseurl }}/components/featured-content) component should only be used for the most important information on the page. Since it includes critical information, featured content should appear near the top of the page. ### How do I apply? The “How do I apply" section lists possible application methods. It should emphasize the optimal path for Veterans, (which may be how to get help from a human instead of online help.) Some common application methods are: @@ -191,13 +196,13 @@ At the top of the introduction page, is a sign in message. There are two differe - Blue CTA button *Sign in to start your application* - Link to fill out the application without signing in. (For all online applications except for Disability Compensation) -![how-to-apply_unauth-message](/images/benefit-apps-unauth-message.png) +![how-to-apply_unauth-message]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/unauth-message.png) **Message when a user is signed in:** - Lets applicant know they are signed in and can save their work as they go -- Primary (green) action link +- [Primary action link]({{ site.baseurl }}/components/link/action#primary) -![how-to-apply_unauth-message](/images/benefit-apps-action-link.png) +![how-to-apply_unauth-message]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/action-link.png) ### Subway map [Subway or process map]({{ site.baseurl }}/components/process-list) shows the steps the users needs to take to apply for a benefit. The headings are action words, short and concise, and consistent across forms. @@ -244,7 +249,7 @@ Depending on the type of benefit, an [alert]({{ site.baseurl }}/components/alert This is an optional component and should only be used if there is an important benefit or application process to call out to the applicant. -![apply-now-alert-box](/images/apply-now-alert-box.png) +![apply-now-alert-box]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/apply-now-alert-box.png) ### Live page examples [File for disability compensation introduction page](https://www.va.gov/disability/file-disability-claim-form-21-526ez/introduction)
    @@ -271,15 +276,15 @@ This section appears as card or [gray alert]({{ site.baseurl }}/components/alert **Health care:** -![after-you-apply-health-care](/images/after-you-apply-health-care-decision.png) +![after-you-apply-health-care]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-health-care-decision.png) **Education:** -![after-you-apply-edu](/images/after-you-apply-edu-decision.png) +![after-you-apply-edu]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-edu-decision.png) **Disability compensation:** -![after-you-apply-disability](/images/after-you-apply-disability-decision.png) +![after-you-apply-disability]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-disability-decision.png) ### Optional: Other components on the "After you apply" page @@ -291,7 +296,7 @@ Below is a list of optional components that appear on the "After you apply" page [View the subway map component]({{ site.baseurl }}/components/process-list). **Health care:** -![after-you-apply-subway-map](/images/after-you-apply-subway-map.png) +![after-you-apply-subway-map]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-subway-map.png) ### Accordions @@ -299,7 +304,7 @@ Below is a list of optional components that appear on the "After you apply" page **Health care:** -![after-you-apply-accordions](/images/after-you-apply-accordions.png) +![after-you-apply-accordions]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-accordions.png) ### Call-to-action button or action link @@ -312,4 +317,4 @@ Use a button for a clickable action on the page. Use the action link if you are **Disability compensation:** -![after-you-apply-cta-button](/images/after-you-apply-cta-button.png) +![after-you-apply-cta-button]({{ site.baseurl }}/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-cta-button.png) diff --git a/src/_patterns/messaging-error-messages.md b/src/_patterns/help-users-to/recover-from-errors.md similarity index 89% rename from src/_patterns/messaging-error-messages.md rename to src/_patterns/help-users-to/recover-from-errors.md index cda6a1f41..b879b21aa 100644 --- a/src/_patterns/messaging-error-messages.md +++ b/src/_patterns/help-users-to/recover-from-errors.md @@ -1,6 +1,11 @@ --- layout: pattern -title: Error messages +title: Recover from errors +permalink: /patterns/help-users-to/recover-from-errors +redirect_from: + - /patterns/messaging-error-messages +aka: Error messages +sub-section: help-users-to intro-text: "Details the structure, style, and tone for error and informational messages." status: use-deployed anchors: @@ -18,7 +23,7 @@ anchors: Every error message will have **up to** 3 parts: -{% include component-example.html alt="Structure of an Alert." file="/images/patterns/error-messages/diagram.png" caption="The 3 parts of every error message: Title, description, call-to-action button or action link." reverse=true width="75%" %} +{% include component-example.html alt="Structure of an Alert." file="/images/patterns/help-users-to/recover-from-errors/diagram.png" caption="The 3 parts of every error message: Title, description, call-to-action button or action link." reverse=true width="75%" %} ### 1.Title @@ -90,7 +95,7 @@ Create a brief title documenting the task that was successfully completed, follo #### Saved -{% include component-example.html alt="Success alert for saving." file="/images/patterns/error-messages/saved-001.png" caption="We saved the information you've entered so far." reverse=true width="50%" %} +{% include component-example.html alt="Success alert for saving." file="/images/patterns/help-users-to/recover-from-errors/saved-001.png" caption="We saved the information you've entered so far." reverse=true width="50%" %} ### Error alerts @@ -98,13 +103,13 @@ Include exactly what failed in the title, followed by a brief apology, reiterati #### Your form didn't save -{% include component-example.html alt="Error alert for form didn't save." file="/images/patterns/error-messages/saved-error-002.png" caption="We're sorry. We couldn't save your form. Please try again." width="50%" %} +{% include component-example.html alt="Error alert for form didn't save." file="/images/patterns/help-users-to/recover-from-errors/saved-error-002.png" caption="We're sorry. We couldn't save your form. Please try again." width="50%" %} Consider whether there is additional information, including a time estimate for resolution and/or a call to action button, that should be included. #### Please save this application and try again -{% include component-example.html alt="Error alert for please save and try again." file="/images/patterns/error-messages/saved-error-003.png" caption="We're sorry. Your application didn't go through. We're working to fix the problem, but it may take us a while. Please save your application, and try again tomorrow." width="50%" %} +{% include component-example.html alt="Error alert for please save and try again." file="/images/patterns/help-users-to/recover-from-errors/saved-error-003.png" caption="We're sorry. Your application didn't go through. We're working to fix the problem, but it may take us a while. Please save your application, and try again tomorrow." width="50%" %} ### Informational messages and warnings @@ -116,11 +121,11 @@ This information should be presented as succinctly as possible in the title and #### Informational example -{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/error-messages/down-004.png" caption="We’ll be doing some work on VA.gov on [DATE] between [TIME] and [TIME]. If you have trouble using the site during that time, please check back soon." reverse=true width="75%" %} +{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/help-users-to/recover-from-errors/down-004.png" caption="We’ll be doing some work on VA.gov on [DATE] between [TIME] and [TIME]. If you have trouble using the site during that time, please check back soon." reverse=true width="75%" %} #### Warning example -{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/error-messages/warning-005.png" caption="We’re doing some work on VA.gov right now. You should still be able to use the site applications and tools. If you have any trouble, please check back soon." reverse=true width="75%" %} +{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/help-users-to/recover-from-errors/warning-005.png" caption="We’re doing some work on VA.gov right now. You should still be able to use the site applications and tools. If you have any trouble, please check back soon." reverse=true width="75%" %} ### 2. Does the user need to take action, or do we want the user to take action? @@ -128,13 +133,13 @@ When action is required, frame required information as a need. #### We need your help to finish reviewing your claim -{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/error-messages/continue-006.png" caption="We need you to provide more evidence (supporting documents) so we can finish reviewing your claim." reverse=true width="50%" %} +{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/help-users-to/recover-from-errors/continue-006.png" caption="We need you to provide more evidence (supporting documents) so we can finish reviewing your claim." reverse=true width="50%" %} When we want to prompt the user to take action, frame the prompt as a question to engage the user. #### Want to make your VA.gov account more secure? -{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/error-messages/secure-007.png" caption="You can add an optional extra layer of security (called 2-factor authentication) to your account. This helps to make sure that no one but you can access your account—even if they get your password." reverse=true width="50%" %} +{% include component-example.html alt="Info alert for site maintenance." file="/images/patterns/help-users-to/recover-from-errors/secure-007.png" caption="You can add an optional extra layer of security (called 2-factor authentication) to your account. This helps to make sure that no one but you can access your account—even if they get your password." reverse=true width="50%" %} ## Messages dictionary diff --git a/src/_patterns/index.md b/src/_patterns/index.md index c4f26961a..e555d9bc1 100644 --- a/src/_patterns/index.md +++ b/src/_patterns/index.md @@ -2,18 +2,21 @@ layout: default index: true title: Patterns +intro-text: "Patterns are solutions and researched best practices for solving user-focused tasks and recurring user interface design problems:" --- -# Patterns +

    {{ page.title }}

    - Patterns are solutions and researched best practices that solve recurring user interface design problems: + {{ page.intro-text }}
    * How do you build complex, multi-part web forms? * How do you provide navigational context? * How do you handle progressive disclosure? +All of the patterns in this section show or cite examples from VA.gov and were researched, designed, developed, and tested by teams creating applications on our platform. + {% include components-patterns-templates.md %} ## Create or update a pattern diff --git a/src/_patterns/sitewide-banners.md b/src/_patterns/sitewide-banners.md deleted file mode 100644 index d57941d05..000000000 --- a/src/_patterns/sitewide-banners.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: pattern -title: Sitewide maintenance banners -status: use-with-caution-candidate -intro-text: "Sitewide maintenance banners are used when we need to let Veterans know about system maintenance affecting the availability of applications and services on VA.gov." -draft: true -anchors: - - anchor: When we use them - - anchor: Guidance ---- - -## When we use them - -Sitewide maintenance banners combine the full-width banner alert component with standardized messaging text. It’s used when all (or most) unauthenticated and authenticated applications, tools, or sign in experiences across the entire site are affected (e.g., vets-api). - -1. Before the site maintenance -2. During the site maintenance - -### Upcoming site maintenance banner: Before downtime -The ‘before downtime’ banner helps users know when the downtime will take place, so they can plan accordingly. - -There are 2 versions of the upcoming message: one for typical downtimes, and another for when a downtime spans multiple days or is 24 hours or longer in duration. Refer to [scheduled downtime notifications messaging]({{ site.baseurl }}/content-style-guide/error-messages/system#scheduled-downtime-notifications) in the error messaging dictionary for the multi-day/24 hours+ downtime text. - -Information in {brackets} show customizable details. - -#### Upcoming site maintenance - -We’ll be doing some work on VA.gov. The maintenance will last {x hour}. During that time, you won’t be able to sign in or use tools. - -**Date:** {Day, Date, Year} - -**Start/End time:** {0:00 a.m./p.m. to 0:00 a.m./p.m. ET} - -[View the Before Maintenance React component on storybook]({{ site.baseurl }}/storybook/?path=/docs/components-banners-maintenancebanner--before-maintenance) - -### During site maintenance banner: During downtime - -The ‘during downtime’ banner lets users know that services and tools are affected. It helps them know when the downtime will be completed and tools and services will be available normally again. - -Information in {brackets} show customizable details. - -#### Site maintenance - -We’re working on VA.gov right now. If you have trouble signing in or using tools, check back after we’re finished. Thank you for your patience. - -**Date:** {Day, Date, Year} - -**Start/End time:** {0:00 a.m./p.m. to 00:00 a.m./p.m. ET} - -[View the During Maintenance React component on storybook]({{ site.baseurl }}/storybook/?path=/docs/components-banners-maintenancebanner--during-maintenance) - -## Guidance - -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 dismissable 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 FE logic will prioritize the display order of banners like this: - -1. Emergency homepage banner - -2. Sitewide maintenance banner - -3. Any other Veteran-action required banner diff --git a/src/_patterns/template.md b/src/_patterns/template.md index f0ec5e381..7036e3247 100644 --- a/src/_patterns/template.md +++ b/src/_patterns/template.md @@ -9,7 +9,7 @@ status: use-with-caution-available anchors: - anchor: Usage - anchor: Examples - - anchor: How to build + - anchor: How to design and build - anchor: Content considerations - anchor: Accessibility considerations --- @@ -30,7 +30,6 @@ May contain: #### Design principles - Design principles to consider - ### When not to use this pattern Criteria for when the pattern is inappropriate. diff --git a/src/_patterns/templates/index.md b/src/_patterns/templates/index.md deleted file mode 100644 index b905fbf4d..000000000 --- a/src/_patterns/templates/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: pattern -title: Templates -inner-title: Overview -permalink: /patterns/templates/ -status: use-deployed -intro-text: "Templates for specific pages that provide guidance on their layout and use." -sub-pages: - - sub-page: Email - - sub-page: Hub - - sub-page: Signed out vs. signed in ---- - -{% include _site-in-this-section.html %} - -Also available are the: -* [Forms review page template]({{ site.baseurl }}/patterns/forms/review) -* [Forms confirmation page template]({{ site.baseurl }}/patterns/forms/confirmation) -* Code details in [page layouts]({{ site.baseurl }}/foundation/layout/page-layouts) \ No newline at end of file diff --git a/src/_patterns/waivers.md b/src/_patterns/waivers.md deleted file mode 100644 index 14e08fb26..000000000 --- a/src/_patterns/waivers.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Waivers -draft: true ---- - -# Waivers - -This is placeholder for waivers. diff --git a/src/_patterns/wizards.md b/src/_patterns/wizards.md index 08f0a462b..15f3d2899 100644 --- a/src/_patterns/wizards.md +++ b/src/_patterns/wizards.md @@ -14,9 +14,9 @@ anchors: ## Status -The [Wizard pattern is now deprecated](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues/399) and replaced by the the [Sub-task pattern]({{ site.baseurl }}/patterns/forms/sub-task). +The [Wizard pattern is now deprecated](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues/399) and replaced by the the [help users complete a sub-task pattern]({{ site.baseurl }}/patterns/help-users-to/complete-a-sub-task). -You should not create any new instances of the Wizard pattern and should instead speak with the Design System Council or CollabCycle team who can direct you. You may attempt to [retrofit an existing instance of the Wizard pattern](#retrofit-this-pattern) until the Sub-task pattern is more widely in use. +You should not create any new instances of the Wizard pattern and should instead speak with the Design System Council or CollabCycle team who can direct you. You may attempt to [retrofit an existing instance of the Wizard pattern](#retrofit-this-pattern) until the help users to complete a sub-task pattern is more widely in use. ## Purpose @@ -27,7 +27,7 @@ You should not create any new instances of the Wizard pattern and should instead ## Examples -![gif demonstrating a form wizard for VA Education]({{site.baseurl}}/images/Wizard-Education-normal.gif) +![gif demonstrating a form wizard for VA Education]({{site.baseurl}}/images/patterns/wizard/Wizard-Education-normal.gif) - **Education Wizard:** [Find your benefits education form]() ([code](https://github.com/department-of-veterans-affairs/vets-website/tree/master/src/applications/gi)). _You may need to scroll down to find the wizard._ This wizard is used to help guide users to the correct education benefits form. @@ -40,7 +40,7 @@ You should not create any new instances of the Wizard pattern and should instead ## Where to place wizards -The wizard should live *on the page* on both the **Eligibility** and **How to Apply** pages for an application. The wizards begin under blue [featured content]({{ site.baseurl }}/components/featured-content) eligibility boxes but before [accordions]({{ site.baseurl }}/patterns/content-presentation#accordions) or additional information. +The wizard should live *on the page* on both the **Eligibility** and **How to Apply** pages for an application. The wizards begin under blue [featured content]({{ site.baseurl }}/components/featured-content) eligibility boxes but before [accordions]({{ site.baseurl }}/component/accordion) or [additional information]({{ site.baseurl }}/components/additional-info). ## Specifics of the pattern @@ -49,17 +49,17 @@ The wizard should live *on the page* on both the **Eligibility** and **How to Ap - **Questions**: Questions appear one at a time under the button, using an expanding blue vertical left bar as new questions are added. Questions are conditional, based on previous answers. Structure the logic tree for wizard questions to get users to gather information from users in as few questions as possible, while still directing them to the best next step for their circumstances. - **Warning alerts in the wizard.** Show a [warning alert]({{ site.baseurl }}/components/alert#warning-alert) if a user answers a question in a way that is uncommon, or if they need to first do some other process that cannot be accessed via the wizard. For example, in the Education Form wizard, Show the Warning Alert immediately after the question, and provide concrete next steps and directions. -![gif demonstrating a form wizard for VA Education featuring a users that answers a specific question that triggers a warning]({{site.baseurl}}/images/Wizard-Education-warning.gif) +![gif demonstrating a form wizard for VA Education featuring a users that answers a specific question that triggers a warning]({{site.baseurl}}/images/patterns/wizard/Wizard-Education-warning.gif) - **Error alerts in the wizard**. Show an [error alert]({{ site.baseurl }}/components/alert#error-alert) if a user answers a question in a way that would render them ineligible to complete any of the forms serviced by the wizard. Instead, they may need to stop what they are doing and follow a different process on a different page or website. For example, in the Disability Claim wizard (shown below), a user who is still active duty needs to complete a completely different form on EBenefits, and completing an application on VA.gov would be a waste of time. Show the Error Alert immediately after the question, and provide concrete next steps and directions. - ![screenshot of wizard with an error]({{site.baseurl}}/images/wizard-with-error.png) + ![screenshot of wizard with an error]({{site.baseurl}}/images/patterns/wizard/wizard-with-error.png) - **Editable answers**: Users can scroll up to see all of their previous answers and make changes at any time. If a user makes a change to the answer to an earlier question, hide all previous answers and show only the next appropriate question in the series, based on the user's answer. Note: For both alert cases, a user can still change their answer in the wizard to access and complete the form. We do not block users from accessing a form completely based on their answers to the wizard questions because there is always an edge case. Theoretically, we want to make the BEST thing they can do the EASIEST thing to do, based on the information the user has provided. So, if we hypothesize that they are ineligible based on how they answered the wizard questions, we should be making the easiest next step to do the next best thing that they can do. -![gif demonstrating a form wizard for VA Disability]({{site.baseurl}}/images/Wizard-Disability.gif) +![gif demonstrating a form wizard for VA Disability]({{site.baseurl}}/images/patterns/wizard/Wizard-Disability.gif) ## Research and Accessibility rationale - We show questions one at a time for accessibility/universal design reasons: we try not to show irrelevant content to users. diff --git a/src/_patterns/templates/email.md b/src/_templates/email.md similarity index 94% rename from src/_patterns/templates/email.md rename to src/_templates/email.md index 3691d5d9f..175471510 100644 --- a/src/_patterns/templates/email.md +++ b/src/_templates/email.md @@ -1,7 +1,6 @@ --- layout: pattern -permalink: /patterns/templates/email -has-parent: /patterns/templates/ +permalink: /templates/email title: Email status: use-deployed intro-text: "The email template is used to communicate with Veterans through email." @@ -12,7 +11,7 @@ anchors: ## Example -![email template]({{site.baseurl}}/images/email-template.png) +![email template]({{site.baseurl}}/images/templates/email/email-template.png) ## Guidance diff --git a/src/_patterns/forms/confirmation.md b/src/_templates/forms/confirmation.md similarity index 86% rename from src/_patterns/forms/confirmation.md rename to src/_templates/forms/confirmation.md index 60fec9f87..1fe49a3f8 100644 --- a/src/_patterns/forms/confirmation.md +++ b/src/_templates/forms/confirmation.md @@ -1,7 +1,7 @@ --- layout: pattern -permalink: /patterns/forms/confirmation -has-parent: /patterns/forms/ +permalink: /templates/forms/confirmation +has-parent: /templates/forms/ title: Confirmation status: use-deployed intro-text: "The form confirmation page gives users information about what they can expect after they submit an online application. This page also provides users with a summary of the benefit they applied for, a confirmation number, and the date they submitted their claim." @@ -15,7 +15,7 @@ Our current confirmation pages vary in format and content. Below are some of the ## Example -![form confirmation template]({{site.baseurl}}/images/Form-confirmation-mini-template.png) +![form confirmation template]({{site.baseurl}}/images/templates/forms/confirmation/mini-template.png) The form confirmation page consists of: @@ -39,7 +39,7 @@ File for disability compensation (Form 21-526EZ) ### Success alert -![success alert]({{ site.baseurl }}/images/success-alert.png) +![success alert]({{ site.baseurl }}/images/templates/forms/confirmation/success-alert.png) Use a [success alert]({{ site.baseurl }}/components/alert#success-alert) to let your user know that they’ve successfully submitted their form. Content for the success alert will depend on the form. @@ -50,7 +50,7 @@ Once we’ve reviewed your application, a Caregiver Support Coordinator will con ### Print this page pattern -![print this page pattern]({{site.baseurl}}/images/print-this-page.png) +![print this page pattern]({{site.baseurl}}/images/templates/forms/confirmation/print-this-page.png) The print this page pattern consists of the [Featured content component]({{ site.baseurl }}/components/featured-content), content, and a “Print this page” [default blue button]({{ site.baseurl }}/components/button). @@ -76,13 +76,13 @@ Some examples of other content or questions are: ### Action link -![confirmation page action link]({{site.baseurl}}/images/confirmation-page-action-link.png) +![confirmation page action link]({{site.baseurl}}/images/templates/forms/confirmation/action-link.png) The [action link]({{ site.baseurl }}/components/link/action) guides the user back to the VA.gov homepage. ### Helpful content -![need help content]({{site.baseurl}}/images/need-help.png) +![need help content]({{site.baseurl}}/images/templates/forms/confirmation/need-help.png) Helpful content will vary depending on the form. Use the H3 highlight for the title and always label it “Need help?”. The content usually points the user to a number they can call if they need help with their form. diff --git a/src/_patterns/forms/index.md b/src/_templates/forms/index.md similarity index 93% rename from src/_patterns/forms/index.md rename to src/_templates/forms/index.md index eaac73b94..5d3cc1b52 100644 --- a/src/_patterns/forms/index.md +++ b/src/_templates/forms/index.md @@ -2,37 +2,27 @@ layout: pattern title: Forms inner-title: Overview -permalink: /patterns/forms/ +permalink: /templates/forms/ +redirect_from: + - /patterns/forms/ contributors: "Shawna Hein (VSA Design Lead), Jonathan Nelson, Liz Lantz, Christian Valla, Becca Walsh, Chris Valarida, Peggy Gannon" status: use-deployed intro-text: "Common form structures and designs used on VA.gov" sub-pages: - - sub-page: All or none of the above - - sub-page: Applicant information - sub-page: Confirmation - - sub-page: Contact information - - sub-page: Dates - - sub-page: Direct deposit - - sub-page: File upload - - sub-page: List and loop - - sub-page: Review - - sub-page: Service history - - sub-page: Signature - - sub-page: Sub-task --- {% include _site-in-this-section.html %} +## The structure of a form -## The Structure of a Form - -{% include component-example.html alt="Representative pages of a form flow for VA.gov." file="/images/patterns/forms/flow.png" caption="The anatomy of a form flow." %} +{% include component-example.html alt="Representative pages of a form flow for VA.gov." file="/images/templates/forms/flow.png" caption="The anatomy of a form flow." %} 1. **[Content landing page](#content-landing-page).** A page built in Drupal that outlines eligibility requirements and/or how to apply. Also, provides information about the benefit. 1. **[Introduction page](#introduction-page).** Includes a call-to-action to login if relevant and a subway map / timeline of what the user can expect when filling out the form. 1. **[Main form pages](#main-form-pages).** The majority of a form, these pages are laid out in chapters. Each chapter may have multiple pages. -1. **[Review page]({{ site.baseurl }}/patterns/forms/review).** Allows the user to review information and make edits if necessary. -1. **[Confirmation page]({{ site.baseurl }}/patterns/forms/confirmation).** Gives users information about what they can expect after they submit an online application. +1. **[Review page]({{ site.baseurl }}/patterns/help-users-to/check-answers).** Allows the user to review information and make edits if necessary. +1. **[Confirmation page]({{ site.baseurl }}/templates/confirmation).** Gives users information about what they can expect after they submit an online application. ## Pages @@ -41,9 +31,9 @@ sub-pages: A page that a user can read before entering an online form where they learn about eligibility and how to apply. This page can contain several elements: -* Sub-task pattern -* Process list -* Application status widget that links to the form +* [Help users to complete a sub-task]({{ site.baseurl }}/patterns/help-users-to/complete-a-sub-task) pattern +* [Process list]({{ site.baseurl }}/components/process-list) +* [Application status widget](#application-status-widget) that links to the form #### Examples * [https://www.va.gov/health-care/how-to-apply/](https://www.va.gov/health-care/how-to-apply/) @@ -79,7 +69,8 @@ Some examples start here (use the right arrow key to navigate through): [https:/ ## Patterns -* [List and loop]({{ site.baseurl }}/patterns/forms/list-and-loop) +* [Ask users for multiple responses]({{ site.baseurl }}/patterns/ask-users-for/multiple-responses) +* [Help users to check answers]({{ site.baseurl }}/patterns/help-users-to/check-answers) ## Components diff --git a/src/_patterns/templates/hub.md b/src/_templates/hub.md similarity index 96% rename from src/_patterns/templates/hub.md rename to src/_templates/hub.md index d7eb36c99..112431017 100644 --- a/src/_patterns/templates/hub.md +++ b/src/_templates/hub.md @@ -1,7 +1,6 @@ --- layout: pattern -permalink: /patterns/templates/hub -has-parent: /patterns/templates/ +permalink: /templates/hub title: Hub status: use-deployed intro-text: "Hub pages serve as a landing page for particular benefits." @@ -23,10 +22,10 @@ A hub page page does the following: ## Example -![Image of va.gov housing assistance hub page]({{site.baseurl}}/images/hub-housing assistance.png) +![Image of va.gov housing assistance hub page]({{site.baseurl}}/images/templates/hub/housing-assistance.png) The hub page pattern can be broken down into an ordered set of components: -![Image of va.gov housing assistance hub page]({{site.baseurl}}/images/hub-housing assistance markup.png) +![Image of va.gov housing assistance hub page]({{site.baseurl}}/images/templates/hub/housing-assistance-markup.png) ## Hierarchy diff --git a/src/_templates/index.md b/src/_templates/index.md new file mode 100644 index 000000000..d7bc73ef7 --- /dev/null +++ b/src/_templates/index.md @@ -0,0 +1,18 @@ +--- +layout: default +index: true +title: Templates +intro-text: "Templates, or page layouts, compose components within a single page. A layout can contain multiple variations of a component depending on the context." +--- + +

    {{ page.title }}

    + +
    + {{ page.intro-text }} +
    + +{% include components-patterns-templates.md %} + +## Code usage + +* Code details in [page layouts]({{ site.baseurl }}/foundation/layout/page-layouts) \ No newline at end of file diff --git a/src/_patterns/templates/signed-out-signed-in.md b/src/_templates/signed-out-signed-in.md similarity index 68% rename from src/_patterns/templates/signed-out-signed-in.md rename to src/_templates/signed-out-signed-in.md index 50caa15dd..a68225245 100644 --- a/src/_patterns/templates/signed-out-signed-in.md +++ b/src/_templates/signed-out-signed-in.md @@ -1,7 +1,6 @@ --- layout: pattern -permalink: /patterns/templates/signed-out-vs-signed-in -has-parent: /patterns/templates/ +permalink: /templates/signed-out-vs-signed-in title: Signed out vs. signed in status: use-deployed intro-text: "If a user has not signed in to VA.gov, we know very little information about the user. When the user signs in and verifies their identity, we know who the user is. In either case, we display the most relevant content, features, and calls to action." @@ -21,11 +20,11 @@ When users sign in, the Sign In button is replaced by a link displays the user's

    Signed out

    - signed out header on desktop + signed out header on desktop

    Signed in

    - signed in header on desktop + signed in header on desktop
    @@ -36,11 +35,11 @@ When users are signed into the site on a smaller device, the Sign In link is rep

    Signed out

    - signed out view of mobile header + signed out view of mobile header

    Signed in

    - Signed in view of mobile header + Signed in view of mobile header
    @@ -49,11 +48,11 @@ When users are signed in and have opened the menu, **My VA** and **My Health** a

    Signed out

    - screenshot of menu open when signed out + screenshot of menu open when signed out

    Signed in

    - screenshot of menu open when signed in + screenshot of menu open when signed in
    @@ -83,11 +82,11 @@ Use the green alert component when the user is required to do something before t

    Signed out

    - create account screenshot + create account screenshot

    Signed in

    - verify identity screen shot + verify identity screen shot
    @@ -95,12 +94,12 @@ Use the green alert component when the user is required to do something before t Use the blue informational alert component when the call to action is beneficial, but not required to proceed. Usually, it is a better experience when the user is signed in, so the prompting the user to sign in first is the primary action. -![call to action screenshot](/images/pattern-cta-sign-in.png) +![call to action screenshot]({{ site.baseurl }}/images/templates/auth/cta-sign-in.png) #### Error Use a red alert component when the user is blocked from continuing a process. Always offer at least one way for the user to resolve the error. -![verify identity error](/images/pattern-verify-identity-error.png) +![verify identity error]({{ site.baseurl }}/images/templates/auth/verify-identity-error.png) diff --git a/src/assets/stylesheets/_components/_sidenav.scss b/src/assets/stylesheets/_components/_sidenav.scss index 131fbbe7f..9b3bd3e43 100644 --- a/src/assets/stylesheets/_components/_sidenav.scss +++ b/src/assets/stylesheets/_components/_sidenav.scss @@ -4,6 +4,12 @@ margin: 4rem 0 0 4rem; background-color: var(--color-white); + &__sub-section { + margin: 0; + padding: 2rem 0rem 1rem 1.5rem; + color: var(--color-base); + } + .usa-accordion { .usa-accordion-button { padding: $padding-override; diff --git a/src/images/Direct-deposit-input-state-small.png b/src/images/Direct-deposit-input-state-small.png deleted file mode 100644 index e71ab8678..000000000 Binary files a/src/images/Direct-deposit-input-state-small.png and /dev/null differ diff --git a/src/images/Mailing-address.png b/src/images/Mailing-address.png deleted file mode 100644 index 1129812cc..000000000 Binary files a/src/images/Mailing-address.png and /dev/null differ diff --git a/src/images/Home-address.png b/src/images/patterns/ask-users-for/addresses/home-address.png similarity index 100% rename from src/images/Home-address.png rename to src/images/patterns/ask-users-for/addresses/home-address.png diff --git a/src/images/mailing-address.png b/src/images/patterns/ask-users-for/addresses/mailing-address.png similarity index 100% rename from src/images/mailing-address.png rename to src/images/patterns/ask-users-for/addresses/mailing-address.png diff --git a/src/images/Address.png b/src/images/patterns/ask-users-for/addresses/single-address.png similarity index 100% rename from src/images/Address.png rename to src/images/patterns/ask-users-for/addresses/single-address.png diff --git a/src/images/contact-info-method-of-contact.png b/src/images/patterns/ask-users-for/contact-preferences/method-of-contact.png similarity index 100% rename from src/images/contact-info-method-of-contact.png rename to src/images/patterns/ask-users-for/contact-preferences/method-of-contact.png diff --git a/src/images/Applicant-info-birth-info.png b/src/images/patterns/ask-users-for/dates/birth-info.png similarity index 100% rename from src/images/Applicant-info-birth-info.png rename to src/images/patterns/ask-users-for/dates/birth-info.png diff --git a/src/images/date-input-month-year.png b/src/images/patterns/ask-users-for/dates/date-input-month-year.png similarity index 100% rename from src/images/date-input-month-year.png rename to src/images/patterns/ask-users-for/dates/date-input-month-year.png diff --git a/src/images/date-input.png b/src/images/patterns/ask-users-for/dates/date-input.png similarity index 100% rename from src/images/date-input.png rename to src/images/patterns/ask-users-for/dates/date-input.png diff --git a/src/images/date-ranges.png b/src/images/patterns/ask-users-for/dates/date-ranges.png similarity index 100% rename from src/images/date-ranges.png rename to src/images/patterns/ask-users-for/dates/date-ranges.png diff --git a/src/images/Direct-deposit-checkbox-small.png b/src/images/patterns/ask-users-for/direct-deposit/Direct-deposit-checkbox-small.png similarity index 100% rename from src/images/Direct-deposit-checkbox-small.png rename to src/images/patterns/ask-users-for/direct-deposit/Direct-deposit-checkbox-small.png diff --git a/src/images/Direct-deposit-review-state-small.png b/src/images/patterns/ask-users-for/direct-deposit/Direct-deposit-review-state-small.png similarity index 100% rename from src/images/Direct-deposit-review-state-small.png rename to src/images/patterns/ask-users-for/direct-deposit/Direct-deposit-review-state-small.png diff --git a/src/images/direct_deposit_input.png b/src/images/patterns/ask-users-for/direct-deposit/direct_deposit_input.png similarity index 100% rename from src/images/direct_deposit_input.png rename to src/images/patterns/ask-users-for/direct-deposit/direct_deposit_input.png diff --git a/src/images/direct_deposit_update.png b/src/images/patterns/ask-users-for/direct-deposit/direct_deposit_update.png similarity index 100% rename from src/images/direct_deposit_update.png rename to src/images/patterns/ask-users-for/direct-deposit/direct_deposit_update.png diff --git a/src/images/contact-info-email-address.png b/src/images/patterns/ask-users-for/email-address/email-address.png similarity index 100% rename from src/images/contact-info-email-address.png rename to src/images/patterns/ask-users-for/email-address/email-address.png diff --git a/src/images/patterns/feedback/feedback-anatomy.png b/src/images/patterns/ask-users-for/feedback/feedback-anatomy.png similarity index 100% rename from src/images/patterns/feedback/feedback-anatomy.png rename to src/images/patterns/ask-users-for/feedback/feedback-anatomy.png diff --git a/src/images/patterns/feedback/feedback-example-desktop-1.png b/src/images/patterns/ask-users-for/feedback/feedback-example-desktop-1.png similarity index 100% rename from src/images/patterns/feedback/feedback-example-desktop-1.png rename to src/images/patterns/ask-users-for/feedback/feedback-example-desktop-1.png diff --git a/src/images/patterns/feedback/feedback-example-desktop-2.png b/src/images/patterns/ask-users-for/feedback/feedback-example-desktop-2.png similarity index 100% rename from src/images/patterns/feedback/feedback-example-desktop-2.png rename to src/images/patterns/ask-users-for/feedback/feedback-example-desktop-2.png diff --git a/src/images/patterns/feedback/feedback-example-mobile-1.png b/src/images/patterns/ask-users-for/feedback/feedback-example-mobile-1.png similarity index 100% rename from src/images/patterns/feedback/feedback-example-mobile-1.png rename to src/images/patterns/ask-users-for/feedback/feedback-example-mobile-1.png diff --git a/src/images/patterns/feedback/feedback-example-mobile-2.png b/src/images/patterns/ask-users-for/feedback/feedback-example-mobile-2.png similarity index 100% rename from src/images/patterns/feedback/feedback-example-mobile-2.png rename to src/images/patterns/ask-users-for/feedback/feedback-example-mobile-2.png diff --git a/src/images/patterns/feedback/feedback-form.png b/src/images/patterns/ask-users-for/feedback/feedback-form.png similarity index 100% rename from src/images/patterns/feedback/feedback-form.png rename to src/images/patterns/ask-users-for/feedback/feedback-form.png diff --git a/src/images/patterns/feedback/feedback-thank-you.png b/src/images/patterns/ask-users-for/feedback/feedback-thank-you.png similarity index 100% rename from src/images/patterns/feedback/feedback-thank-you.png rename to src/images/patterns/ask-users-for/feedback/feedback-thank-you.png diff --git a/src/images/file-upload-input.png b/src/images/patterns/ask-users-for/files/file-upload-input.png similarity index 100% rename from src/images/file-upload-input.png rename to src/images/patterns/ask-users-for/files/file-upload-input.png diff --git a/src/images/file-upload-loading.png b/src/images/patterns/ask-users-for/files/file-upload-loading.png similarity index 100% rename from src/images/file-upload-loading.png rename to src/images/patterns/ask-users-for/files/file-upload-loading.png diff --git a/src/images/file-upload-review.png b/src/images/patterns/ask-users-for/files/file-upload-review.png similarity index 100% rename from src/images/file-upload-review.png rename to src/images/patterns/ask-users-for/files/file-upload-review.png diff --git a/src/images/Applicant-info-gender.png b/src/images/patterns/ask-users-for/gender/gender.png similarity index 100% rename from src/images/Applicant-info-gender.png rename to src/images/patterns/ask-users-for/gender/gender.png diff --git a/src/images/list-and-loop-contents.png b/src/images/patterns/ask-users-for/multiple-responses/contents.png similarity index 100% rename from src/images/list-and-loop-contents.png rename to src/images/patterns/ask-users-for/multiple-responses/contents.png diff --git a/src/images/Applicant-info-name.png b/src/images/patterns/ask-users-for/names/names.png similarity index 100% rename from src/images/Applicant-info-name.png rename to src/images/patterns/ask-users-for/names/names.png diff --git a/src/images/contact-info-phone-number.png b/src/images/patterns/ask-users-for/phone-numbers/phone-numbers.png similarity index 100% rename from src/images/contact-info-phone-number.png rename to src/images/patterns/ask-users-for/phone-numbers/phone-numbers.png diff --git a/src/images/Applicant-info-race.png b/src/images/patterns/ask-users-for/race-ethnicity-or-origin/race.png similarity index 100% rename from src/images/Applicant-info-race.png rename to src/images/patterns/ask-users-for/race-ethnicity-or-origin/race.png diff --git a/src/images/federal-orders.png b/src/images/patterns/ask-users-for/service-history/federal-orders.png similarity index 100% rename from src/images/federal-orders.png rename to src/images/patterns/ask-users-for/service-history/federal-orders.png diff --git a/src/images/list-and-loop.png b/src/images/patterns/ask-users-for/service-history/list-and-loop.png similarity index 100% rename from src/images/list-and-loop.png rename to src/images/patterns/ask-users-for/service-history/list-and-loop.png diff --git a/src/images/list-and-loop1.png b/src/images/patterns/ask-users-for/service-history/list-and-loop1.png similarity index 100% rename from src/images/list-and-loop1.png rename to src/images/patterns/ask-users-for/service-history/list-and-loop1.png diff --git a/src/images/list-and-loop2.png b/src/images/patterns/ask-users-for/service-history/list-and-loop2.png similarity index 100% rename from src/images/list-and-loop2.png rename to src/images/patterns/ask-users-for/service-history/list-and-loop2.png diff --git a/src/images/list-and-loop3.png b/src/images/patterns/ask-users-for/service-history/list-and-loop3.png similarity index 100% rename from src/images/list-and-loop3.png rename to src/images/patterns/ask-users-for/service-history/list-and-loop3.png diff --git a/src/images/pow-status.png b/src/images/patterns/ask-users-for/service-history/pow-status.png similarity index 100% rename from src/images/pow-status.png rename to src/images/patterns/ask-users-for/service-history/pow-status.png diff --git a/src/images/reserve-pension.png b/src/images/patterns/ask-users-for/service-history/reserve-pension.png similarity index 100% rename from src/images/reserve-pension.png rename to src/images/patterns/ask-users-for/service-history/reserve-pension.png diff --git a/src/images/reserves-disability.png b/src/images/patterns/ask-users-for/service-history/reserves-disability.png similarity index 100% rename from src/images/reserves-disability.png rename to src/images/patterns/ask-users-for/service-history/reserves-disability.png diff --git a/src/images/service-name.png b/src/images/patterns/ask-users-for/service-history/service-name.png similarity index 100% rename from src/images/service-name.png rename to src/images/patterns/ask-users-for/service-history/service-name.png diff --git a/src/images/form-signature.png b/src/images/patterns/ask-users-for/signature/form-signature.png similarity index 100% rename from src/images/form-signature.png rename to src/images/patterns/ask-users-for/signature/form-signature.png diff --git a/src/images/Applicant-info-important-numbers.png b/src/images/patterns/ask-users-for/social-security-number/important-numbers.png similarity index 100% rename from src/images/Applicant-info-important-numbers.png rename to src/images/patterns/ask-users-for/social-security-number/important-numbers.png diff --git a/src/images/ssn-masked-update.png b/src/images/patterns/ask-users-for/social-security-number/ssn-masked-update.png similarity index 100% rename from src/images/ssn-masked-update.png rename to src/images/patterns/ask-users-for/social-security-number/ssn-masked-update.png diff --git a/src/images/experimental-design/auth-info-list-additional-info.png b/src/images/patterns/help-users-to/check-personal-information/additional-info.png similarity index 100% rename from src/images/experimental-design/auth-info-list-additional-info.png rename to src/images/patterns/help-users-to/check-personal-information/additional-info.png diff --git a/src/images/experimental-design/auth-info-list-apple-tool-consolidated-faq-3.jpeg b/src/images/patterns/help-users-to/check-personal-information/apple-tool-consolidated-faq-3.jpeg similarity index 100% rename from src/images/experimental-design/auth-info-list-apple-tool-consolidated-faq-3.jpeg rename to src/images/patterns/help-users-to/check-personal-information/apple-tool-consolidated-faq-3.jpeg diff --git a/src/images/experimental-design/auth-info-list-apple-tool-mobile-3.jpeg b/src/images/patterns/help-users-to/check-personal-information/apple-tool-mobile-3.jpeg similarity index 100% rename from src/images/experimental-design/auth-info-list-apple-tool-mobile-3.jpeg rename to src/images/patterns/help-users-to/check-personal-information/apple-tool-mobile-3.jpeg diff --git a/src/images/experimental-design/auth-info-list-apple-tool-first-mock-3.jpeg b/src/images/patterns/help-users-to/check-personal-information/apple-tool.jpeg similarity index 100% rename from src/images/experimental-design/auth-info-list-apple-tool-first-mock-3.jpeg rename to src/images/patterns/help-users-to/check-personal-information/apple-tool.jpeg diff --git a/src/images/experimental-design/auth-info-list-authenticated-list-tool.jpeg b/src/images/patterns/help-users-to/check-personal-information/auth-list-tool.jpeg similarity index 100% rename from src/images/experimental-design/auth-info-list-authenticated-list-tool.jpeg rename to src/images/patterns/help-users-to/check-personal-information/auth-list-tool.jpeg diff --git a/src/images/patterns/forms/sub-task/Check-in-sub-task.png b/src/images/patterns/help-users-to/complete-a-sub-task/Check-in-sub-task.png similarity index 100% rename from src/images/patterns/forms/sub-task/Check-in-sub-task.png rename to src/images/patterns/help-users-to/complete-a-sub-task/Check-in-sub-task.png diff --git a/src/images/patterns/forms/sub-task/VAOS-vaccine-sub-task.png b/src/images/patterns/help-users-to/complete-a-sub-task/VAOS-vaccine-sub-task.png similarity index 100% rename from src/images/patterns/forms/sub-task/VAOS-vaccine-sub-task.png rename to src/images/patterns/help-users-to/complete-a-sub-task/VAOS-vaccine-sub-task.png diff --git a/src/images/patterns/help-users-to/navigate-a-long-list/claim-status-tool.gif b/src/images/patterns/help-users-to/navigate-a-long-list/claim-status-tool.gif new file mode 100644 index 000000000..70b9f6136 Binary files /dev/null and b/src/images/patterns/help-users-to/navigate-a-long-list/claim-status-tool.gif differ diff --git a/src/images/patterns/help-users-to/navigate-a-long-list/interactions-v2.png b/src/images/patterns/help-users-to/navigate-a-long-list/interactions-v2.png new file mode 100644 index 000000000..bb86e01d8 Binary files /dev/null and b/src/images/patterns/help-users-to/navigate-a-long-list/interactions-v2.png differ diff --git a/src/images/patterns/show-more-options/interactions.png b/src/images/patterns/help-users-to/navigate-a-long-list/interactions.png similarity index 100% rename from src/images/patterns/show-more-options/interactions.png rename to src/images/patterns/help-users-to/navigate-a-long-list/interactions.png diff --git a/src/images/patterns/show-more-options/vaos-choose-location.png b/src/images/patterns/help-users-to/navigate-a-long-list/vaos-choose-location.png similarity index 100% rename from src/images/patterns/show-more-options/vaos-choose-location.png rename to src/images/patterns/help-users-to/navigate-a-long-list/vaos-choose-location.png diff --git a/src/images/benefit-apps-action-link.png b/src/images/patterns/help-users-to/navigate-benefit-applications/action-link.png similarity index 100% rename from src/images/benefit-apps-action-link.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/action-link.png diff --git a/src/images/patterns/help-users-to/navigate-benefit-applications/additional-eligibility.png b/src/images/patterns/help-users-to/navigate-benefit-applications/additional-eligibility.png new file mode 100644 index 000000000..8349cd208 Binary files /dev/null and b/src/images/patterns/help-users-to/navigate-benefit-applications/additional-eligibility.png differ diff --git a/src/images/after-you-apply-accordions.png b/src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-accordions.png similarity index 100% rename from src/images/after-you-apply-accordions.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-accordions.png diff --git a/src/images/after-you-apply-cta-button.png b/src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-cta-button.png similarity index 100% rename from src/images/after-you-apply-cta-button.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-cta-button.png diff --git a/src/images/after-you-apply-disability-decision.png b/src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-disability-decision.png similarity index 100% rename from src/images/after-you-apply-disability-decision.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-disability-decision.png diff --git a/src/images/after-you-apply-edu-decision.png b/src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-edu-decision.png similarity index 100% rename from src/images/after-you-apply-edu-decision.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-edu-decision.png diff --git a/src/images/after-you-apply-health-care-decision.png b/src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-health-care-decision.png similarity index 100% rename from src/images/after-you-apply-health-care-decision.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-health-care-decision.png diff --git a/src/images/after-you-apply-preneed-decision.png b/src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-preneed-decision.png similarity index 100% rename from src/images/after-you-apply-preneed-decision.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-preneed-decision.png diff --git a/src/images/after-you-apply-subway-map.png b/src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-subway-map.png similarity index 100% rename from src/images/after-you-apply-subway-map.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/after-you-apply-subway-map.png diff --git a/src/images/apply-now-alert-box.png b/src/images/patterns/help-users-to/navigate-benefit-applications/apply-now-alert-box.png similarity index 100% rename from src/images/apply-now-alert-box.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/apply-now-alert-box.png diff --git a/src/images/eligibility_page_heirarchy.png b/src/images/patterns/help-users-to/navigate-benefit-applications/eligibility_page_heirarchy.png similarity index 100% rename from src/images/eligibility_page_heirarchy.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/eligibility_page_heirarchy.png diff --git a/src/images/featured-content-do.png b/src/images/patterns/help-users-to/navigate-benefit-applications/featured-content-do.png similarity index 100% rename from src/images/featured-content-do.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/featured-content-do.png diff --git a/src/images/featured-content-dont.png b/src/images/patterns/help-users-to/navigate-benefit-applications/featured-content-dont.png similarity index 100% rename from src/images/featured-content-dont.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/featured-content-dont.png diff --git a/src/images/benefit-apps-unauth-message.png b/src/images/patterns/help-users-to/navigate-benefit-applications/unauth-message.png similarity index 100% rename from src/images/benefit-apps-unauth-message.png rename to src/images/patterns/help-users-to/navigate-benefit-applications/unauth-message.png diff --git a/src/images/patterns/error-messages/continue-006.png b/src/images/patterns/help-users-to/recover-from-errors/continue-006.png similarity index 100% rename from src/images/patterns/error-messages/continue-006.png rename to src/images/patterns/help-users-to/recover-from-errors/continue-006.png diff --git a/src/images/patterns/error-messages/diagram.png b/src/images/patterns/help-users-to/recover-from-errors/diagram.png similarity index 100% rename from src/images/patterns/error-messages/diagram.png rename to src/images/patterns/help-users-to/recover-from-errors/diagram.png diff --git a/src/images/patterns/error-messages/down-004.png b/src/images/patterns/help-users-to/recover-from-errors/down-004.png similarity index 100% rename from src/images/patterns/error-messages/down-004.png rename to src/images/patterns/help-users-to/recover-from-errors/down-004.png diff --git a/src/images/patterns/error-messages/saved-001.png b/src/images/patterns/help-users-to/recover-from-errors/saved-001.png similarity index 100% rename from src/images/patterns/error-messages/saved-001.png rename to src/images/patterns/help-users-to/recover-from-errors/saved-001.png diff --git a/src/images/patterns/error-messages/saved-error-002.png b/src/images/patterns/help-users-to/recover-from-errors/saved-error-002.png similarity index 100% rename from src/images/patterns/error-messages/saved-error-002.png rename to src/images/patterns/help-users-to/recover-from-errors/saved-error-002.png diff --git a/src/images/patterns/error-messages/saved-error-003.png b/src/images/patterns/help-users-to/recover-from-errors/saved-error-003.png similarity index 100% rename from src/images/patterns/error-messages/saved-error-003.png rename to src/images/patterns/help-users-to/recover-from-errors/saved-error-003.png diff --git a/src/images/patterns/error-messages/secure-007.png b/src/images/patterns/help-users-to/recover-from-errors/secure-007.png similarity index 100% rename from src/images/patterns/error-messages/secure-007.png rename to src/images/patterns/help-users-to/recover-from-errors/secure-007.png diff --git a/src/images/patterns/error-messages/warning-005.png b/src/images/patterns/help-users-to/recover-from-errors/warning-005.png similarity index 100% rename from src/images/patterns/error-messages/warning-005.png rename to src/images/patterns/help-users-to/recover-from-errors/warning-005.png diff --git a/src/images/Wizard-Disability.gif b/src/images/patterns/wizard/Wizard-Disability.gif similarity index 100% rename from src/images/Wizard-Disability.gif rename to src/images/patterns/wizard/Wizard-Disability.gif diff --git a/src/images/Wizard-Education-normal.gif b/src/images/patterns/wizard/Wizard-Education-normal.gif similarity index 100% rename from src/images/Wizard-Education-normal.gif rename to src/images/patterns/wizard/Wizard-Education-normal.gif diff --git a/src/images/Wizard-Education-warning.gif b/src/images/patterns/wizard/Wizard-Education-warning.gif similarity index 100% rename from src/images/Wizard-Education-warning.gif rename to src/images/patterns/wizard/Wizard-Education-warning.gif diff --git a/src/images/wizard-with-error.png b/src/images/patterns/wizard/wizard-with-error.png similarity index 100% rename from src/images/wizard-with-error.png rename to src/images/patterns/wizard/wizard-with-error.png diff --git a/src/images/ssn-masked.png b/src/images/ssn-masked.png deleted file mode 100644 index bcb04fa62..000000000 Binary files a/src/images/ssn-masked.png and /dev/null differ diff --git a/src/images/pattern-cta-sign-in-create-account.png b/src/images/templates/auth/cta-sign-in-create-account.png similarity index 100% rename from src/images/pattern-cta-sign-in-create-account.png rename to src/images/templates/auth/cta-sign-in-create-account.png diff --git a/src/images/pattern-cta-sign-in.png b/src/images/templates/auth/cta-sign-in.png similarity index 100% rename from src/images/pattern-cta-sign-in.png rename to src/images/templates/auth/cta-sign-in.png diff --git a/src/images/pattern-cta-verify-identity.png b/src/images/templates/auth/cta-verify-identity.png similarity index 100% rename from src/images/pattern-cta-verify-identity.png rename to src/images/templates/auth/cta-verify-identity.png diff --git a/src/images/pattern-header-signed-in.png b/src/images/templates/auth/header-signed-in.png similarity index 100% rename from src/images/pattern-header-signed-in.png rename to src/images/templates/auth/header-signed-in.png diff --git a/src/images/pattern-header-signed-out.png b/src/images/templates/auth/header-signed-out.png similarity index 100% rename from src/images/pattern-header-signed-out.png rename to src/images/templates/auth/header-signed-out.png diff --git a/src/images/pattern-small-header-signed-in.png b/src/images/templates/auth/small-header-signed-in.png similarity index 100% rename from src/images/pattern-small-header-signed-in.png rename to src/images/templates/auth/small-header-signed-in.png diff --git a/src/images/pattern-small-header-signed-out.png b/src/images/templates/auth/small-header-signed-out.png similarity index 100% rename from src/images/pattern-small-header-signed-out.png rename to src/images/templates/auth/small-header-signed-out.png diff --git a/src/images/pattern-small-menu-open-signed-in.png b/src/images/templates/auth/small-menu-open-signed-in.png similarity index 100% rename from src/images/pattern-small-menu-open-signed-in.png rename to src/images/templates/auth/small-menu-open-signed-in.png diff --git a/src/images/pattern-small-menu-open-signed-out.png b/src/images/templates/auth/small-menu-open-signed-out.png similarity index 100% rename from src/images/pattern-small-menu-open-signed-out.png rename to src/images/templates/auth/small-menu-open-signed-out.png diff --git a/src/images/pattern-verify-identity-error.png b/src/images/templates/auth/verify-identity-error.png similarity index 100% rename from src/images/pattern-verify-identity-error.png rename to src/images/templates/auth/verify-identity-error.png diff --git a/src/images/email-template.png b/src/images/templates/email/email-template.png similarity index 100% rename from src/images/email-template.png rename to src/images/templates/email/email-template.png diff --git a/src/images/confirmation-page-action-link.png b/src/images/templates/forms/confirmation/action-link.png similarity index 100% rename from src/images/confirmation-page-action-link.png rename to src/images/templates/forms/confirmation/action-link.png diff --git a/src/images/Form-confirmation-mini-template.png b/src/images/templates/forms/confirmation/mini-template.png similarity index 100% rename from src/images/Form-confirmation-mini-template.png rename to src/images/templates/forms/confirmation/mini-template.png diff --git a/src/images/need-help.png b/src/images/templates/forms/confirmation/need-help.png similarity index 100% rename from src/images/need-help.png rename to src/images/templates/forms/confirmation/need-help.png diff --git a/src/images/print-this-page.png b/src/images/templates/forms/confirmation/print-this-page.png similarity index 100% rename from src/images/print-this-page.png rename to src/images/templates/forms/confirmation/print-this-page.png diff --git a/src/images/success-alert.png b/src/images/templates/forms/confirmation/success-alert.png similarity index 100% rename from src/images/success-alert.png rename to src/images/templates/forms/confirmation/success-alert.png diff --git a/src/images/patterns/forms/flow.png b/src/images/templates/forms/flow.png similarity index 100% rename from src/images/patterns/forms/flow.png rename to src/images/templates/forms/flow.png diff --git a/src/images/hub-housing assistance markup.png b/src/images/templates/hub/housing-assistance-markup.png similarity index 100% rename from src/images/hub-housing assistance markup.png rename to src/images/templates/hub/housing-assistance-markup.png diff --git a/src/images/hub-housing assistance.png b/src/images/templates/hub/housing-assistance.png similarity index 100% rename from src/images/hub-housing assistance.png rename to src/images/templates/hub/housing-assistance.png diff --git a/src/index.html b/src/index.html index ce74f84e5..e4c177ca9 100644 --- a/src/index.html +++ b/src/index.html @@ -79,7 +79,7 @@

    Components and utilities can be combined to solve recurring user needs. Here, we provide design samples and code for our design patterns.

    -

    Templates

    +

    Templates

    Page template examples for specific page types include hubs, emails, and authentication.