Merge pull request #3418 from department-of-veterans-affairs/3239-Ale…

…rt-sign-in-documentation

3239 alert sign in guidance

src/_components/alert/alert-expandable.md

@@ -89,6 +89,6 @@ The alert was tested as part of a usability study with 9 participants. The alert
 ## Related
 
 * [Additional info]({{ site.baseurl }}/components/additional-info)
-* [Alert - Background only]({{ site.baseurl}}/components/alert/background-only)
+* [Alert]({{ site.baseurl}}/components/alert/alert)
 
 {% include _component-checklist.html component_name=page.web-component %}

src/_components/alert/alert-sign-in.md

@@ -0,0 +1,99 @@
+---
+layout: component
+permalink: /components/alert/alert-sign-in/
+has-parent: /components/alert/
+title: Alert - Sign-in
+github-title: va-alert-sign-in
+intro-text: An alert component with specific content focused on helping users complete the sign in process.
+figma-link: https://www.figma.com/design/JDFpGLIojfuQwANXScQjqe/VADS-Component-Examples?node-id=5359-436
+status: use-with-caution-candidate
+web-component: va-alert-sign-in
+anchors:
+  - anchor: Examples
+  - anchor: Usage
+  - anchor: Behavior
+  - anchor: Content considerations
+  - anchor: Accessibility considerations
+  - anchor: Related
+  - anchor: Component checklist
+---
+
+## Examples
+
+### Required sign-in (Verified)
+{% include component-example.html alt="An example of a sign-in alert for all products that require sign-in with a verified account." file="/images/components/alert-sign-in/required-sign-in-verified.png" caption="An example of a sign-in alert for all products that require sign-in with a verified account" reverse=true %}
+
+### Optional sign-in (Verified)
+{% include component-example.html alt="An example of a sign-in alert for forms that support optional sign-in with a verified account." file="/images/components/alert-sign-in/verify-with-idme.png" caption="An example of a sign-in alert for forms that support optional sign-in with a verified account." reverse=true %}
+
+### Verify with ID.me
+{% include component-example.html alt="An example of a sign-in alert for unverified ID.me accounts" file="/images/components/alert-sign-in/verify-with-idme.png" caption="An example of a sign-in alert for unverified ID.me accounts" reverse=true %}
+
+### Verify with Login.gov
+{% include component-example.html alt="An example of a sign-in alert for unverified Login.gov accounts." file="/images/components/alert-sign-in/verify-with-logingov.png" caption="An example of a sign-in alert for unverified Login.gov accounts." reverse=true %}
+
+### Sign-in with another account
+{% include component-example.html alt="An example of a sign-in alert for unverified My HealtheVet accounts." file="/images/components/alert-sign-in/verify-with-logingov.png" caption="An example of a sign-in alert for unverified My HealtheVet accounts." reverse=true %}
+
+## Usage
+
+### When to use Alert - Sign-in
+
+* **Static pages with entry points to online tools.** The sign-in alert appears on a static unauthenticated VA.gov page and serves as the entry point to the tool's authenticated experience. The Office of the Chief Technology Officer's content/information architecture/accessibility team (CAIA) team manages these pages in Drupal. Here's an example of a static page with a sign-in alert (note that alert is an older content variation). Work with CAIA to add the alert to the correct page.
+* **Form intro pages.** The sign-in alert goes on the form intro page that the product team creates and manages. The URL for this page ends in /introduction. Here's example of a form intro page with a sign-in alert (note that alert is an older content variation).
+  **Exception:** If your form is only accessible after signing in (meaning there is no unauthenticated state of the intro page), the sign-in alert must appear on the static unauthenticated page that serves as the entry point. Currently, this only applies to 2 forms in the /my-health section: the 1010EZR and the order form for CPAP and hearing aid supplies.
+
+### Placement
+* **For entry points to online tools**, work with CAIA to determine placement on the static page. Placement may vary depending on the page structure. Always place the alert directly under a header that makes it clear what the user is signing in to do (for example, "Check your claim status online").
+* **On form intro pages**, place the alert directly after the process list or "what to know" section of the intro page. (Some forms have a process list and some have "what to know.")
+
+## Behavior
+
+### Selecting variations for the sign-in pattern in your product
+**All products that require or allow sign in with verified accounts only must use 1 of these 2 sign-in variations:**
+
+**Sign-in alert for all products that require sign-in with a verified account**
+* Your product requires people to sign in, **and**
+* Your product only accepts verified (LOA3 or IAL2) accounts
+
+**Sign-in alert for forms that support optional sign-in with a verified account**
+
+When these are true:
+* Your product is a form that gives people the option to sign in, **and**
+* Your form only accepts verified (LOA3 or IAL2) accounts, **and**
+* Your form supports prefill and save-in-progress
+
+**Verification alert for unverified Login.gov or ID.me accounts**
+
+When these are true:
+* Person is signed in with an unverified (LOA1 or IAL1) Login.gov or ID.me account, **and**
+* Your product only accepts verified (LOA3 or IAL2) accounts
+
+**Verification alert for unverified My HealtheVet accounts**
+
+When these are true:
+* Person is signed in with an unverified (LOA1 or IAL1) My HealtheVet account, **and**
+* Your product only accepts verified (LOA3 or IAL2) accounts
+
+{% include component-docs.html component_name=page.web-component %}
+
+## Content considerations
+If your product fits one of these descriptions, you may need to adjust the standard sign-in alert component content for your situation:
+
+* A product that either requires or allows sign-in, but accepts unverified accounts
+* An online form that allows sign-in but does not support prefill
+* An online form that allows sign-in and offers a different reason to sign in—like generating an automatic Intent to File (ITF)
+* A health tool that requires registration with My HealtheVet (currently only applies to messages, medications, and medical records tools)
+
+Work with the Office of the CAIA and identity teams to adjust the content in this component for your product.
+
+## Accessibility considerations
+
+{% include a11y/alerts.md %}
+
+## Related
+
+* [Alert]({{ site.baseurl}}/components/alert/alert)
+* [Pattern - Help users to sign in]({{ site.baseurl}}/patterns/help-users-to/sign-in)
+
+{% include _component-checklist.html component_name=page.web-component %}

src/_components/alert/index.md

@@ -10,6 +10,7 @@ uswds-v3: default
 web-component: va-alert
 sub-pages:
   - sub-page: Alert - Expandable
+  - sub-page: Alert - Sign-In
 anchors:
   - anchor: Examples - Standard
   - anchor: Examples - Standard properties

src/_patterns/help-users-to/sign-in.md

@@ -0,0 +1,73 @@
+---
+layout: pattern
+permalink: /patterns/help-users-to/sign-in
+sub-section: help-users-to
+title: Sign-in
+intro-text: "Follow this pattern to help users sign in to access VA online services."
+status: use-with-caution-candidate
+research-title: Help users to sign in
+anchors:
+  - anchor: Usage
+  - anchor: Examples
+  - anchor: How to design and build
+  - anchor: Content considerations
+---
+
+## Usage
+
+### When to use this pattern
+
+When people must sign in or have the option to sign in to VA.gov or another VA online service.
+
+### When to consider something else
+
+If your product fits one of these descriptions, you may need to adjust the standard pattern for your situation:
+
+* A product that either requires or allows sign-in, but accepts unverified accounts
+* An online form that allows sign-in but does not support prefill
+* An online form that allows sign-in and offers a different reason to sign in—like generating an automatic Intent to File (ITF)
+* A health tool that requires registration with My HealtheVet (currently only applies to messages, medications, and medical records tools)
+
+Work with the Office of the Chief Technology Officer's content/information architecture/accessibility team (CAIA) and identity teams to adjust the pattern for your product.
+
+## How to design and build
+
+### How this pattern works
+This pattern works differently depending on the product and the account type a person uses to sign in.
+
+**To design and build, follow these steps:**
+
+1. Choose 1 of the 2 blue sign-in alert variations. If a person signs in with a verified account, they should only encounter an initial sign-in alert.
+  #### Required sign-in (Verified)
+  {% include component-example.html alt="An example of a sign-in alert for all products that require sign-in with a verified account." file="/images/components/alert-sign-in/required-sign-in-verified.png" caption="An example of a sign-in alert for all products that require sign-in with a verified account" reverse=true %}
+
+  #### Optional sign-in (Verified)
+  {% include component-example.html alt="An example of a sign-in alert for forms that support optional sign-in with a verified account." file="/images/components/alert-sign-in/optional-sign-in-verified.png" caption="An example of a sign-in alert for forms that support optional sign-in with a verified account." reverse=true %}
+
+2. Implement both of the yellow verification alerts. If a person signs in with an unverified account, they should encounter 1 of the 2 variations. One is for unverified **Login.gov** and **ID.me** accounts, and one is for unverified **My HealtheVet** accounts.
+  **Note:** This pattern is currently tailored to products that require verified (LOA3 or IAL2) accounts. If your product accepts unverified (LOA1 or IAL1) accounts, you'll need to adjust the content in the blue sign-in alert. And you won't need to implement the yellow verification alerts. Work with CAIA and the identity team to adjust for your situation.
+
+  #### Verify with ID.me
+  {% include component-example.html alt="An example of a sign-in alert for unverified ID.me accounts" file="/images/components/alert-sign-in/verify-with-idme.png" caption="An example of a sign-in alert for unverified ID.me accounts" reverse=true %}
+
+  #### Verify with Login.gov
+  {% include component-example.html alt="An example of a sign-in alert for unverified Login.gov accounts." file="/images/components/alert-sign-in/verify-with-logingov.png" caption="An example of a sign-in alert for unverified Login.gov accounts." reverse=true %}
+
+  #### Sign-in with another account
+  {% include component-example.html alt="An example of a sign-in alert for unverified My HealtheVet accounts." file="/images/components/alert-sign-in/verify-with-logingov.png" caption="An example of a sign-in alert for unverified My HealtheVet accounts." reverse=true %}
+
+**All teams should take these steps when using this pattern:**
+
+* Ask the identity team to review your pull request, so they can confirm you're implementing the pattern correctly on the back end.
+* Work with CAIA for a content review to confirm the standard alerts make sense for your product, or adjust content in the alerts if needed.
+* **If your product has /my-health in its URL**, work with the identity and cartography teams to identify the correct sign-in pattern for your product. You may need an additional registration step on the My HealtheVet national portal, and you may need to place your form or tool behind a /my-health route guard.
+
+**Components used in this pattern**
+
+* [Alert - sign-in]({{ site.baseurl}}/components/alert/alert-sign-in)
+
+## Content considerations
+
+* Don't change content in these alerts, unless you've worked with CAIA on a tailored version.
+* In most cases, the alerts in this pattern are the only sign-in-related content you'll need in your product. If you have other content related to sign-in, follow the style guide section for this topic. If you have questions, work with CAIA.
+  [Go to sign-in and identity verification in the content style guide](https://design.va.gov/content-style-guide/specific-topics-and-programs/sign-in-and-identity-verification)