diff --git a/.github/ISSUE_TEMPLATE/DST-component_accessibility_review.md b/.github/ISSUE_TEMPLATE/DST-component_accessibility_review.md index 996685d22..0361cbb74 100644 --- a/.github/ISSUE_TEMPLATE/DST-component_accessibility_review.md +++ b/.github/ISSUE_TEMPLATE/DST-component_accessibility_review.md @@ -24,4 +24,4 @@ We need to conduct a full accessibility review of the [component name] component ## Acceptance Criteria - [ ] Component has been reviewed for accessibility issues -- [ ] Any accessibility issues have been addressed +- [ ] Any accessibility issues have been addressed or ticket has been written with issues that need to be fixed diff --git a/.github/ISSUE_TEMPLATE/DST-component_design.md b/.github/ISSUE_TEMPLATE/DST-component_design.md index d4de32b4a..b8364e5c8 100644 --- a/.github/ISSUE_TEMPLATE/DST-component_design.md +++ b/.github/ISSUE_TEMPLATE/DST-component_design.md @@ -2,7 +2,7 @@ name: "DST - Component design" about: INTERNAL DST USE ONLY title: "[component name] - Design" -labels: platform-design-system-team +labels: platform-design-system-team, DST-design assignees: babsdenney, danbrady, lwwright7 --- @@ -15,7 +15,7 @@ assignees: babsdenney, danbrady, lwwright7 - [ ] Delete this section once complete ## Description -Create design for [component name] and/or update Sketch artifacts for [component name] +Create design for [component name] and/or update Figma artifacts for [component name] If this is a pattern or component that is already in existence, conduct a small-scale audit (3-5 examples) to make sure there aren't design issues that need to be addressed. Also, check the Design System Team backlog for outstanding design issues. If you find any, link to them in a comment on this ticket. If possible, address any outstanding issues with this design and link to this issue from the original issue. If not, indicate that in the original issue. diff --git a/.github/ISSUE_TEMPLATE/DST_Experimental_request_design b/.github/ISSUE_TEMPLATE/DST_Experimental_request_design new file mode 100644 index 000000000..9a13267a9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/DST_Experimental_request_design @@ -0,0 +1,37 @@ +--- +name: "DST - Experimental request - design" +about: INTERNAL DST USE ONLY +title: "[experimental component name] - Design" +labels: platform-design-system-team +assignees: babsdenney, danbrady, lwwright7 + +--- + +## Configuring this issue +- [ ] Add issue to appropriate epic +- [ ] Add Design System component label (such as `va-alert`) +- [ ] Add `component-new` or `component-update` label, if applicable +- [ ] Complete sections below +- [ ] Delete this section once complete + +## Description +Create design and/or update Figma artifacts for [experimental design component name] + +## Details +[add links to experimental design request ticket or notes with details about the design] +[add links to any research documents related to the component] + +## Tasks +- [ ] Create designs for component +- [ ] Review designs with PO and DST designers +- [ ] Review designs with developers and accessibility specialist +- [ ] Address any comments from reviews, if necessary +- [ ] Comment on this ticket with any accessibility considerations engineers may need to know +- [ ] Comment on this ticket with content specifications (e.g. labels and error messages) +- [ ] Comment on this ticket with a link to the designs and post in DST Slack channel + +## Acceptance Criteria +- [ ] Component design is complete and has been reviewed +- [ ] Accessibility and development considerations have been added to this ticket, if necessary +- [ ] Content specifications have been added to this ticket, if necessary +- [ ] Link to design has been added to this ticket and shared in Slack diff --git a/.github/workflows/deploy-reusable.yml b/.github/workflows/deploy-reusable.yml new file mode 100644 index 000000000..ddbc96f42 --- /dev/null +++ b/.github/workflows/deploy-reusable.yml @@ -0,0 +1,84 @@ +on: + workflow_call: + inputs: + github-sha: + required: true + type: string + github-run-id: + required: true + type: string + github-event-number: + required: false + type: string + matrix-name: + required: true + type: string + matrix-bucket: + required: true + type: string + matrix-config: + required: true + type: string + secrets: + aws-access-key-id: + required: true + aws-secret-access-key: + required: true +jobs: + jekyll-deploy-reusable_workflow_job: + runs-on: ubuntu-latest + environment: + name: ${{ inputs.matrix-name }} + url: "https://${{ inputs.matrix-bucket }}" + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + - name: Use Node.js 16.x + uses: actions/setup-node@v2 + with: + node-version: 16.x + cache: 'yarn' + - uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.7.5 # Not needed with a .ruby-version file + bundler-cache: true # runs 'bundle install' and caches installed gems automatically + - run: yarn install + - run: yarn run build + - run: bundle exec jekyll build --config _config.yml,jekyll-configs/${{ inputs.matrix-config }} --baseurl /${{ inputs.github-event-number }} + - name: Make BUILD.txt file + # The -e flag enables the interpretation of the \n newline character + run: | + echo -e "REF=${{ inputs.github-sha }}\n\ + BUILD_ID=${{ inputs.github-run-id }}\n\ + BUILDTIME=$(date)" > _site/BUILD.txt + # We are taking these extra steps due to some differences between Jekyll and AWS S3. + # To access a .html file served from S3, the URL needs to have the .html extension. + # We're removing the extension to make the URLs prettier. + # More context: + # https://simpleit.rocks/ruby/jekyll/tutorials/having-pretty-urls-in-a-jekyll-website-hosted-in-amazon-s3/ + - name: Remove .html extension on non-index files + run: | + find _site/ -type f ! -iname 'index.html' -iname '*.html' \ + -print0 | while read -d $'\0' f; do mv "$f" "${f%.html}"; done + - uses: aws-actions/configure-aws-credentials@v4 + with: + aws-access-key-id: ${{ secrets.aws-access-key-id }} + aws-secret-access-key: ${{ secrets.aws-secret-access-key }} + aws-region: "us-gov-west-1" + - name: Sync extensionless html files with correct type + run: | + aws s3 sync _site s3://${{ inputs.matrix-bucket }} \ + --acl public-read \ + --delete \ + --exclude "storybook/*" \ + --exclude "*.*" \ + --content-type "text/html" + - name: Sync remaining files + run: | + aws s3 sync _site s3://${{ inputs.matrix-bucket }} \ + --acl public-read \ + --delete \ + --exclude "*" \ + --include "*.*" \ + --exclude "storybook/*" \ No newline at end of file diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 5d3a3eb15..111d59b5e 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -8,16 +8,16 @@ jobs: deploy: strategy: matrix: - environment: [{ bucket: dev-design.va.gov, config: dev.yml }, { bucket: staging-design.va.gov, config: staging.yml }, { bucket: design.va.gov, config: prod.yml }] + environment: [{ bucket: staging-design.va.gov, config: staging.yml }, { bucket: design.va.gov, config: prod.yml }] runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 with: fetch-depth: 0 - - name: Use Node.js 14.x + - name: Use Node.js 16.x uses: actions/setup-node@v2 with: - node-version: 14.x + node-version: 16.x cache: 'yarn' - uses: ruby/setup-ruby@v1 with: @@ -41,7 +41,7 @@ jobs: run: | find _site/ -type f ! -iname 'index.html' -iname '*.html' \ -print0 | while read -d $'\0' f; do mv "$f" "${f%.html}"; done - - uses: aws-actions/configure-aws-credentials@v1 + - uses: aws-actions/configure-aws-credentials@v4 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml new file mode 100644 index 000000000..aedde497e --- /dev/null +++ b/.github/workflows/preview.yml @@ -0,0 +1,25 @@ +name: Preview + +on: + pull_request: + types: + - opened + - reopened + - synchronize + +jobs: + dev-deploy-preview: + strategy: + matrix: + environment: [{ name: development, bucket: "dev-design.va.gov/${{ github.event.number }}", config: dev.yml }] + uses: ./.github/workflows/deploy-reusable.yml + with: + github-sha: ${{ github.sha }} + github-run-id: ${{ github.run_id }} + github-event-number: ${{ github.event.number }} + matrix-name: ${{ matrix.environment.name }} + matrix-bucket: ${{ matrix.environment.bucket }} + matrix-config: ${{ matrix.environment.config }} + secrets: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} \ No newline at end of file diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index d2cb32727..d6c499c70 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -7,16 +7,16 @@ jobs: build: strategy: matrix: - environment: [{ bucket: dev-design.va.gov, config: dev.yml }, { bucket: staging-design.va.gov, config: staging.yml }, { bucket: design.va.gov, config: prod.yml }] + environment: [ { bucket: design.va.gov, config: prod.yml }] runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 with: fetch-depth: 0 - - name: Use Node.js 14.x + - name: Use Node.js 16.x uses: actions/setup-node@v2 with: - node-version: 14.x + node-version: 16.x cache: 'yarn' - uses: ruby/setup-ruby@v1 with: diff --git a/.gitignore b/.gitignore index ad3117a6d..f1d2b06ed 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ .jekyll-metadata .sass-cache .vscode +*.code-workspace _site fonts node_modules diff --git a/.tool-versions b/.tool-versions new file mode 100644 index 000000000..a2e778299 --- /dev/null +++ b/.tool-versions @@ -0,0 +1 @@ +ruby 3.0.2 diff --git a/Gemfile.lock b/Gemfile.lock index 16e5a3924..77a049848 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -64,8 +64,7 @@ GEM rb-fsevent (0.11.1) rb-inotify (0.10.1) ffi (~> 1.0) - rexml (3.3.3) - strscan + rexml (3.3.9) rouge (3.29.0) safe_yaml (1.0.5) sass-embedded (1.0.21) @@ -73,11 +72,10 @@ GEM rake (>= 12.3.0) sassc (2.4.0) ffi (~> 1.9) - strscan (3.1.0) terminal-table (2.0.0) unicode-display_width (~> 1.1, >= 1.1.1) unicode-display_width (1.8.0) - webrick (1.7.0) + webrick (1.8.2) PLATFORMS ruby diff --git a/README.md b/README.md index 90d769fef..0d8d0b0ab 100644 --- a/README.md +++ b/README.md @@ -90,9 +90,39 @@ While `vets-design-system-documentation` is running and make further updates to 1. Commit this along with any updates to the documentation site and submit a PR. -## Deploying +## Deployments -Merges into `main` will automatically be deployed to `dev-design.va.gov`. Production is automatically deployed every weekday at 2pm. Deploys are executed by creating a release of vets-website via Jenkins. You can track the deployment in the Slack channel, #design-system. +Merges into `main` will automatically deploy to production `design.va.gov` after CI checks have completed. + +### Previewing Pull Requests + +When a PR is created, a preview of those changes will be available after the [Preview workflow](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/.github/workflows/preview.yml) has completed. There will be a "View deployment" button visible that will launch the preview environment when clicked: + +![The "view deployment" button on a pull request](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/src/images/readme/pr-view-deployment-button.png?raw=true) + +The preview link can also be accessed directly using this pattern: `https://dev-design.va.gov/PR_NUMBER`. For example, `https://dev-design.va.gov/3435` where `3435` is the unique PR number visible in the PR title. + +### Preview Troubleshooting + +#### Check the branch name + +A preview environment will generate only when the PR has been created from a direct branch from the main repository. It does not work if the PR was created from a fork. + +You can confirm if your PR was created from a fork by looking at the branch name at the top of the PR. If you see your Github username in front of your branch name, this means the PR was created from a fork and the preview will not generate. + +![The top of a PR showing the branch to be merged into main. There is a Github username at the front of a branch name which means the branch is from a fork](https://raw.githubusercontent.com/department-of-veterans-affairs/vets-design-system-documentation/refs/heads/main/src/images/readme/pr-branch-from-fork.png) + +If this was done because you don't have write access to this repository, you can request that access by submitting a support request in the #vfs-platform-support Slack channel. + +#### Re-running the preview workflow + +If the preview has stopped working (for example if you're only seeing a 403 Forbidden error or similar), re-run the preview workflow by clicking "Details" next to the Preview check: + +![A list of PR checks with an arrow pointing to the details link for the Preview workflow](https://raw.githubusercontent.com/department-of-veterans-affairs/vets-design-system-documentation/refs/heads/main/src/images/readme/pr-checks-preview-details.png) + +Then click the "Re-run all jobs" button at the top of the page: + +![The "Re-run all jobs" button for running a Github workflow again](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/src/images/readme/re-run-workflow-button.png?raw=true) ## Additional Testing diff --git a/jekyll-configs/dev.yml b/jekyll-configs/dev.yml index 7fc0c5174..3861a49a8 100644 --- a/jekyll-configs/dev.yml +++ b/jekyll-configs/dev.yml @@ -1 +1,2 @@ -storybook_path: "/storybook" +url: "https://dev-design.va.gov" # Base hostname & protocol for the preview site +storybook_path: "/storybook" \ No newline at end of file diff --git a/package.json b/package.json index 08c38f662..1b72c5ee7 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,7 @@ }, "homepage": "https://github.com/department-of-veterans-affairs/vets-design-system-documentation#readme", "devDependencies": { - "@department-of-veterans-affairs/component-library": "^44.0.0", + "@department-of-veterans-affairs/component-library": "^47.1.0", "gulp": "^4.0.2", "gulp-clean": "^0.4.0", "gulp-rename": "^2.0.0", @@ -38,7 +38,7 @@ }, "dependencies": { "@department-of-veterans-affairs/formation": "^11.0.12", - "@department-of-veterans-affairs/css-library": "^0.8.5" + "@department-of-veterans-affairs/css-library": "^0.12.2" }, "engines": { "npm": "6.14.8" diff --git a/src/_about/accessibility/accessibility-testing-for-design-system-components.md b/src/_about/accessibility/accessibility-testing-for-design-system-components.md new file mode 100644 index 000000000..64ceefed1 --- /dev/null +++ b/src/_about/accessibility/accessibility-testing-for-design-system-components.md @@ -0,0 +1,204 @@ +--- +layout: documentation +title: Accessibility testing for design system components +permalink: /about/accessibility/accessibility-testing-for-design-system-components +has-parent: /about/accessibility/ +anchors: + - anchor: Overview + - anchor: VFS team responsibilities + - anchor: Testing principles + - anchor: Testing methodology +--- + +## Overview + +Accessibility specialists on the [VA.gov](http://va.gov/) Platform team thoroughly test components before they are added or updated in the Design System. This accessibility testing plan outlines a comprehensive strategy to ensure that both our website and mobile application prioritize accessibility throughout the development lifecycle, incorporating best practices and industry standards to create an inclusive digital environment. + +## Responsibilities for teams building products on VA.gov + +Using design system components alone will not guarantee that your product is accessible. + +### Accessibility test your product + +VFS teams are responsible for testing their own products for accessibility and meeting the [VA.gov Experience Standards](https://design.va.gov/about/experience-standards/). Moreover, teams are required to complete [foundational accessibility testing](https://depo-platform-documentation.scrollhelp.site/collaboration-cycle/prepare-for-an-accessibility-staging-review#foundational-testing) as they prepare for a staging review, and are highly encouraged to complete [advanced accessibility testing](https://depo-platform-documentation.scrollhelp.site/collaboration-cycle/prepare-for-an-accessibility-staging-review#advanced-testing) as well. + +### Evaluate components' accessibility in your product + +Design system components are tested in isolation. While we try to ensure that no accessibility barriers exist in any given component, barriers can still be introduced when components are used in an unanticipated combination, or when components are placed in an unanticipated context within the page. + +#### Readability + +Readability of an individual component is highly dependent on the context around that component. When using a component, VFS teams should check: + +- Headings and sub-headings + - Do component headings fit into the overall heading hierarchy of the page? + - Is content in close proximity to the component grouped logically? +- Buttons and link text + - Is any text hardcoded into the component appropriate for your user flow? + - When adding your own text via component properties, is the text meaningful? Does it convey a purpose? +- Labels + - Are any labels hardcoded into the component appropriate for your user flow? + - When adding your own label text via component properties, are the labels clear, concise, and easy to understand? +- Plain language + - Do error messages clearly describe the error and provide a clear path for resolving the error? + +#### Color considerations + +When using a component, VFS teams should check: + +- Color contrast against against backgrounds and nearby or adjacent elements. + +### Report accessibility defects + +If you identify an accessibility defect in a component, please [submit an issue](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues/new/choose). + +## Testing principles + +### POUR + +Each component is tested for accessibility in the design system based on the four principles of accessibility. + +- **Perceivable** - Information and user interface components must be presentable to users in ways they can perceive. +- **Operable** - User interface components and navigation must be operable. +- **Understandable** - Information and the operation of user interface must be understandable. +- **Robust** - Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. + +### WCAG 2.2 AA + +These principles are the foundation of [Section 508 of the Rehabilitation Act](https://www.access-board.gov/ict/), which incorporates Web Content Accessibility Guidelines (WCAG) 2.0 Level AA success criteria. We aim to adhere to the latest version of WCAG Level AA, which at the time of writing is [WCAG 2.2](https://www.w3.org/TR/WCAG22/). We strive to not only meet those standards, but to go beyond compliance with thorough testing to ensure that we creating an inclusive and equitable experience for everyone. + +### Multiple types of assistive technologies + +Each component is also tested to ensure compatibility with common assistive technologies covering a broad set of common interaction modalities, including: + +- Screen readers (text to speech) +- Voice command/speech recognition (speech to text) +- Screen magnification +- Browser display settings (eg. zoom, text size) +- Device contrast themes +- Keyboard-only +- Mouse-only +- Touch-only +- Alternative input devices + +## Testing methodology + +### Code review + +Code reviews are essential for building inclusive and usable digital products for everyone. Well-written semantic HTML ensures that browsers faithfully convey design system components to users, and ensures maximum compatibility with assistive technologies. Here's what we look for in code: + +- [Valid HTML usage](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML "https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML") + - Are semantic HTML elements used properly? +- [Valid ARIA usage](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics "https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics") + - Are ARIA roles and attributes used properly? +- [Controls are labeled](https://www.w3.org/WAI/tutorials/forms/labels/ "https://www.w3.org/WAI/tutorials/forms/labels/") + - Are elements labeled using appropriate techniques? + +### Automated scans + +Automated accessibility testing tools are crucial for building accessible digital products because they provide a quick and efficient way to identify potential issues. Currently, each design system component goes through: + +- An aXe DevTools scan via Cypress for the default variation of the component. +- An aXe DevTools scan via the browser extension for each additional variation of the component. + +### Readability evaluation + +Readability is a key part of accessibility because it directly impacts how easily users can understand the content. We ensure the following are easy to understand: + +- [Headings and sub-headings](https://design.va.gov/content-style-guide/page-titles-and-section-titles "https://design.va.gov/content-style-guide/page-titles-and-section-titles") + - Are headings used in a hierarchical manner? + - Is the content grouped logically? +- [Button](https://design.va.gov/content-style-guide/button-labels "https://design.va.gov/content-style-guide/button-labels") and [link](https://design.va.gov/content-style-guide/links "https://design.va.gov/content-style-guide/links") text + - Is the text meaningful? + - Does the text convey a purpose? +- Labels + - Are labels clear, concise, and easy to understand? +- [Plain language](https://design.va.gov/content-style-guide/plain-language/ "https://design.va.gov/content-style-guide/plain-language/") + - Is all text consistent with our plain language standards? + +### Use of color + +Color plays a crucial role in accessibility because it significantly impacts how users perceive and interact with digital content, especially those with visual impairments. Here is what we test for: + +- Color contrast meets or exceeds [WCAG Level AA contrast ratios](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html). +- Information is not communicated through color alone. Relying solely on color for communication is an accessibility barrier for individuals with visual impairments. +- Use of [Windows contrast themes](https://learn.microsoft.com/en-us/windows/apps/design/accessibility/high-contrast-themes) (formerly High Contrast Mode) does not result in any use of color regressions from the default color presentation. + +### Text resizing, zoom, and magnification + +Testing text resizing, browser zoom levels, and screen magnifications is crucial for accessibility because it ensures that your website or application remains usable for individuals who need to adjust their browser's display settings or magnify parts of their screen. Here's what we test: + +- Browser font size options correctly resize the text of a component. +- Zoom levels of 200%, 300%, and 400% do not affect the usability of the component. +- Features are visible or discoverable when using [MacOS Zoom](https://support.apple.com/guide/mac-help/change-zoom-settings-for-accessibility-mh40579/mac), [Windows Magnifier](https://support.microsoft.com/en-us/windows/use-magnifier-to-make-things-on-the-screen-easier-to-see-414948ba-8b1c-d3bd-8615-0e5e32204198), and/or similar magnification tools. + +### Screen readers + +Screen reader testing is important for accessibility because it ensures each component is usable for users of assistive technology. We test with the following screen reader and browser combinations to ensure a consistent experience across devices: + +- [JAWS](https://www.freedomscientific.com/products/software/jaws/ "https://www.freedomscientific.com/products/software/jaws/") + Chrome on Windows +- [NVDA](https://www.nvaccess.org/download/ "https://www.nvaccess.org/download/") + Firefox on Windows +- [Narrator](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1 "https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1") + Edge on Windows +- [VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac "https://support.apple.com/guide/voiceover/welcome/mac") + Safari on MacOS +- [TalkBack](https://support.google.com/accessibility/android/answer/6283677?hl=en "https://support.google.com/accessibility/android/answer/6283677?hl=en") + Chrome on Android +- [VoiceOver](https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/ios "https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/ios") + Safari on iOS + +With each screen reader, here's what we test: + +- All meaningful content is announced to screen reader users in a logical order consistent with the visual presentation. +- All interactive elements have a unique accessible name. +- All interactive elements are announced with their element type, current value, and current state (as appropriate). +- Common screen reader interaction patterns are supported (eg. navigating a page by heading, navigating a page by landmark, etc). + +### Input and interaction methods + +Each component is tested to ensure it is usable for individuals who rely on different input methods. Input methods tested include: + +- Keyboard-only +- Mouse-only +- Touch-only (as appropriate, where interactions may be distinct from mouse-only) +- [Voice Control](https://support.apple.com/en-us/102225 "https://support.apple.com/en-us/102225") + Safari on MacOS +- [Dragon](https://www.nuance.com/dragon.html "https://www.nuance.com/dragon.html") + Edge or Chrome on Windows + +#### Alternative input devices + +Alternative input devices such as sip-and-puff switches or eye-tracking software are not directly tested. These devices typically map user interactions to specific keystrokes or mouse movements, so robust support for keyboard and mouse combined with well-tested standards-based code should ensure support for these devices. + +Likewise, we do not directly test with refreshable Braille displays or other nonvisual displays, but appropriate use of ARIA and semantic HTML should ensure support for these devices as well. + +#### Testing input methods + +For each input method, we test: + +- Touch and mouse compatibility, including: + + - Target sizes meet or exceed [WCAG Level AA target size requirements](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html "https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html"). + - Controls do not require multipoint or path-based gestures. + - Controls do not require specific click or tap patterns or timing. + +- Keyboard compatibility, including: + - All interactive elements are focusable using the keyboard. + - Focus indicators are fully visible and meet color contrast requirements. + - Form elements such as dropdowns, radio buttons, and sliders can be utilized with arrow keys. + - Interactive elements can be activated with the keyboard. + - Users can exit all interactive elements without being trapped. +- Voice command/speech recognition compatibility, including: + + - The accessible name of elements matches the visible label for the element; or, if not, the visible label supports a clear interaction path. + - Labels have a straightforward pronunciation. + +## Component checklists + +For each component, the results of our accessibility testing are displayed in the component checklist section, organized by the categories described in our testing methodology. Each category may be labeled as: + +- Pass +- Conditional pass +- Pass with exceptions +- Fail +- Not completed + +Additional notes are provided where appropriate. For example, if automated scans for a component indicate a color contrast violation but manual testing for use of color finds that the automated scan result was a false positive, the component checklist may read: + +> **Automated scans** +> +> Pass with exceptions - Axe testing shows a false positive on color contrast for the default variation diff --git a/src/_about/accessibility/focus-management.md b/src/_about/accessibility/focus-management.md new file mode 100644 index 000000000..ad82329a8 --- /dev/null +++ b/src/_about/accessibility/focus-management.md @@ -0,0 +1,51 @@ +--- +layout: documentation +title: Focus management +permalink: /about/accessibility/focus-management +has-parent: /about/accessibility/ +intro-text: Focus is the element on a page that is ready for you to interact with. It's important for making websites accessible, especially for people who use keyboards or other assistive technology to use the site. +anchors: + - anchor: Focus indicator + - anchor: Focus order + - anchor: Focus management + +--- + +Testing is crucial to ensure that focus on your page functions as expected across different scenarios. Below are some things to look out for. + +## Focus indicator + +Sighted keyboard users must always be able to see where the keyboard focus is. If they tab through a website without knowing which element is focused, navigating can be unpredictable. + +Browsers handle displaying the keyboard focus automatically, but each displays it in a different way and may be just enough to pass accessibility guidelines. VA.gov has enhanced this outline to make it more visible. + +![visual focus indicator screenshot]({{ site.baseurl }}/images/about/accessibility/focus-management/focus-indicator.png) + +We advise against disabling the focus outline using `outline: 0` or `outline: none` in CSS. This practice can impair navigation for users who rely on keyboard navigation, especially those with visual impairments. Without a visible focus outline, sighted users may struggle to identify the currently focused element, making navigation difficult. + +## Focus order + +The programmatic focus order should match the visual focus order. Focus typically follows the order in which objects appear in the page source, but may not match the order which users expect to interact with elements on the page. + +This can occur when the order of elements in the source is wrong. If an element's position is moved via CSS, it can move that element from where it would normally be positioned. Elements could also be hidden on a page, typically through moving it off-screen or changing it's opacity, but not taken out of the tab order. This makes them focusable even if the focus indicator cannot be seen. Because of that, be sure to test that focus is not placed on an element that is not visible. + +## Focus management + +Manually managing focus is necessary in some scenarios to provide a seamless and accessible user experience, especially for keyboard and screen reader users. Below are key things to know when setting focus manually. + +### The focus should be intentionally set to the appropriate element when a user action requires a change of context or location + +- When content is added to the screen in response to a user-triggered event, the focus should be moved to the new content. +- When content is removed from the screen in response to a user-triggered event, focus should be set to the next logical place in the interaction. +- Example: When opening a dialog, focus should be sent to that dialog. When the dialog is closed, focus is sent back to the original element that triggered it. + +### Focus should not be lost or reset to the top of the page, except when the page is reloaded + +- If focus is reset, keyboard users will have to start again from the beginning of the page. Screen reader users could also become disoriented and unsure if they are on a different page or if the current page reloaded. +- Example: If focus gets lost after closing a dialog. The focus should be set to the original element that triggered it. + +### When setting focus, the target element must contain text that can be programmatically determined + +- If you must set focus to a non-interactive element, it should have text to allow screen readers to read the text inside the container. + - When setting focus to a non-interactive element, the element should _not_ be added to the tab order of the page through `tabindex="0"`, the focus only needs to be set via JavaScript. +- If focus is set to an empty container, screen readers will have nothing to read, so this should be avoided. diff --git a/src/_about/accessibility/index.md b/src/_about/accessibility/index.md index 3bd586124..03e86d406 100644 --- a/src/_about/accessibility/index.md +++ b/src/_about/accessibility/index.md @@ -4,12 +4,14 @@ title: Accessibility permalink: /about/accessibility/ intro-text: How to follow accessibility standards when using or contributing to the VA Design System (VADS) sub-pages: + - sub-page: Accessibility testing for design system components - sub-page: Accessibility annotations + - sub-page: Focus management --- {% include _site-in-this-section.html %} -VA is here to serve Veterans of the United States military, and [approximately 40% have an identified disability](https://www.statista.com/statistics/250316/us-veterans-by-disability-status/). +VA is here to serve Veterans of the United States military, and [approximately 40% have an identified disability](https://www.statista.com/statistics/250316/us-veterans-by-disability-status/). Therefore, [accessibility is core to all design decisions]({{ site.baseurl }}/about/principles#usable-by-everyone) made in our Design System. All components must be tested before admission into the Design System, and all VA products must be tested before launch. @@ -17,24 +19,21 @@ Therefore, [accessibility is core to all design decisions]({{ site.baseurl }}/ab The VA Design System provides accessible components, the guidance to implement these components, and the tools to customize and extend the design system accessibly. It was built on top of a fork of the U.S. Web Design System (USWDS), which prioritizes accessibility throughout. [Learn more about how USWDS practices accessibility.](https://designsystem.digital.gov/documentation/accessibility/) -Components don’t live in a vacuum. As standalone elements, they can only be tested atomically. For a product to launch, you need to test holistically; you should review the product as a whole before launch. +Components don’t live in a vacuum. As standalone elements, they can only be tested atomically. [Learn more about how VA Design System components are tested.](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/8b49df2eddc3956daf9cff03728430311c597631/about/accessibility/accessibility-testing) For a product to launch, you need to test holistically; you should review the product as a whole before launch. The surest way to make an accessible product is to “shift left,” or prioritize accessibility during an entire project’s lifecycle. - ## Create accessible products using the Design System -Whenever you make a new component, feature, or product, follow these steps to ensure that, in the end, your creation is accessible. +Whenever you make a new component, feature, or product, follow these steps to ensure that, in the end, your creation is accessible. We recommend a mix of automated, semi-automated, and manual testing. You should also research with real people who use assistive technology to access services online. - ### Design - Review your mockups for accessibility issues before development ([learn how to design with with accessibility in mind](https://www.w3.org/WAI/tips/designing/)) - Add [accessibility annotations](https://www.figma.com/file/CZcnWfQOwtLqPm4WA5paYG/VADS-Annotation-Kit?type=design&node-id=415-1135&mode=design&t=Ld7dhuyaPcerrnPF-0) to your mockups to communicate important semantic information (heading levels, aria-labels, etc.) to designers, developers, and accessibility specialists - ### Development Manually test your product: @@ -44,51 +43,51 @@ Manually test your product: - Keyboard navigation - Heading levels ([HeadingsMap](https://chromewebstore.google.com/detail/headingsmap/flbjommegcjonpdmenkdiocclhjacmbi) is a useful Chrome extension) - With screen readers - - Based on recommendations from the [Blinded Veterans Association](https://bva.org/), we recommend testing with the following as a minimum: - - iOS with Safari using VoiceOver (Mobile) - - Windows 11 with Chrome using JAWS (Desktop) + - Based on recommendations from the [Blinded Veterans Association](https://bva.org/), we recommend testing with the following as a minimum: + - iOS with Safari using VoiceOver (Mobile) + - Windows 11 with Chrome using JAWS (Desktop) - Conduct automated testing with [axe DevTools by Deque](https://www.deque.com/axe/) +- [Evaluate how Design System components](accessibility-testing-for-design-system-components.md) are used to ensure they aren’t appearing in an unanticipated combination or context within a page. ### Research - [Test with people who use assistive technology](https://depo-platform-documentation.scrollhelp.site/research-design/research-assistive-technology-sessions) (at least 20% of your participants) - ## Contribute accessible components to the Design System ### Foundational accessibility tests As part of staging reviews, new components must complete [foundational accessibility testing using this GitHub ticket](https://github.com/department-of-veterans-affairs/va.gov-team/issues/new?assignees=briandeconinck&labels=a11y-testing&projects=&template=a11y-testing.yaml&title=Accessibility+Testing+for+%5BTeam+Name%2C+Product+Name%2C+Feature+Name%5D). Foundational testing requires evaluating: -1. Color and color contrast -2. Automated testing with [axe by Deque](https://www.deque.com/axe/) -3. Content zoom and reflow -4. Keyboard navigation +1. Color and color contrast +2. Automated testing with [aXe DevTools by Deque](https://www.deque.com/axe/) +3. Content zoom and reflow +4. Keyboard navigation ### Advanced testing with mobile and desktop screen readers -As part of staging reviews, new components must also complete [advanced testing with an accessibility specialist](https://depo-platform-documentation.scrollhelp.site/collaboration-cycle/prepare-for-an-accessibility-staging-review#Prepareforanaccessibilitystagingreview-Advancedaccessibilitytests(recommended)advanced-testing) using a screen reader on both mobile and desktop. As a default, based on recommendations from the [Blinded Veterans Association](https://bva.org/), we recommend testing with the following at a minimum: +As part of staging reviews, new components must also complete [advanced testing with an accessibility specialist]() using a screen reader on both mobile and desktop. As a default, based on recommendations from the [Blinded Veterans Association](https://bva.org/), we recommend testing with the following at a minimum: -* iOS with Safari using VoiceOver (Mobile) -* Windows 11 with Chrome using JAWs (Desktop) +- iOS with Safari using VoiceOver (Mobile) +- Windows 11 with Chrome using JAWs (Desktop) If time and resources allow, do a more comprehensive review by testing with: -* Android with Chrome using TalkBack (Mobile) -* Windows 11 with Chrome using NVDA (Desktop) -It is the intention of this team to improve our testing standards to more accurately reflect the full experience of users with disabilities. Today our compliance testing sets a minimal standard (WCAG 2.1 AA) that we are striving to raise. +- Android with Chrome using TalkBack (Mobile) +- Windows 11 with Chrome using NVDA (Desktop) + +It is the intention of this team to improve our testing standards to more accurately reflect the full experience of users with disabilities. Today our compliance testing sets a minimal standard (WCAG 2.2 AA) that we are striving to raise. ## Resources for Veteran-facing service teams ### Get accessibility guidance early from the CAIA team -The Sitewide Content, Accessibility, and Information Architecture (CAIA) team can help you meet VA.gov’s accessibility standards. Whether you’re starting a new product or refining an existing one, contact the CAIA team as early as possible to create accurate, consistent, accessible, and equitable digital services for Veterans. +The Sitewide Content, Accessibility, and Information Architecture (CAIA) team can help you meet [VA.gov](http://VA.gov)’s accessibility standards. Whether you’re starting a new product or refining an existing one, contact the CAIA team as early as possible to create accurate, consistent, accessible, and equitable digital services for Veterans. - Submit a [Sitewide Content, Accessibility, and IA intake form ticket](https://github.com/department-of-veterans-affairs/va.gov-team/issues/new?assignees=RLHecht%2C+coforma-terry%2C+kristinoletmuskat%2C+laurwill%2C+sara-amanda&labels=sitewide+CAIA%2C+sitewide+content-product+support%2C+Sitewide+IA%2C+sitewide+content%2C+sitewide+accessibility&projects=&template=sitewide-content-intake-form.md&title=%3CType+of+Request%3E+from+%3CTeam%3E) in GitHub -- [Contact CAIA on Slack -](https://depo-platform-documentation.scrollhelp.site/collaboration-cycle/sitewide-content-and-ia-intake-request#Content,Accessibility,andInformationArchitecturesupport-SitewideCAIA-Contactus) +- [Contact CAIA on Slack](https://depo-platform-documentation.scrollhelp.site/collaboration-cycle/sitewide-content-and-ia-intake-request#Content,Accessibility,andInformationArchitecturesupport-SitewideCAIA-Contactus) -### Learn how to make accessible products on the modernized VA.gov platform +### Learn how to make accessible products on the modernized [VA.gov](http://VA.gov) platform - [Resources for researchers](https://depo-platform-documentation.scrollhelp.site/developer-docs/accessibility-on-va-gov#AccessibilityonVA.gov-ResourcesforResearchers) - [Resources for designers](https://depo-platform-documentation.scrollhelp.site/developer-docs/accessibility-on-va-gov#AccessibilityonVA.gov-ResourcesforDesigners) diff --git a/src/_about/contributing/experimental-design.png b/src/_about/contributing/experimental-design.png new file mode 100644 index 000000000..1a10169ca Binary files /dev/null and b/src/_about/contributing/experimental-design.png differ diff --git a/src/_about/contributing/index.md b/src/_about/contributing/index.md index 5a09a95cf..099d33e9e 100644 --- a/src/_about/contributing/index.md +++ b/src/_about/contributing/index.md @@ -24,4 +24,15 @@ When considering if a component or pattern should be added to the design system 2. The component or pattern is different in more than one major way than existing components in the design system, if the component is only different in color or format, for instance, then it would be better as a variant of the existing component. Note that variants of existing components should also go through this experimental process. 3. Our existing components and patterns will not solve the user problems sufficiently. -{% include _site-in-this-section.html %} \ No newline at end of file +### Experimental design decision tree and process + +{% include component-example.html alt="A thumbnail image of experimental design decision tree and process Mural" file="/images/about/experimental-design.png" caption="A thumbnail image of experimental design decision tree and process Mural" %} + + + +View the experimental design decision tree and process Mural. + +{% include _site-in-this-section.html %} diff --git a/src/_about/designers/creating-components.md b/src/_about/designers/creating-components.md index 25265fc5f..9ed94d58d 100644 --- a/src/_about/designers/creating-components.md +++ b/src/_about/designers/creating-components.md @@ -128,7 +128,7 @@ All text styles should be pulled from the VADS Figma file.  ### Iconography -* **Only use icons from the VA Design System.** Currently, these are [Font Awesome version 5.15.4 icons]({{ site.baseurl }}/foundation/icons) however, we are moving to the [USWDS icon set](https://designsystem.digital.gov/components/icon/). Some USWDS v3-based components are already using USWDS icons. +* **Only use icons from the VA Design System.** [Our icons](https://design.va.gov/foundation/icons) are a subset of [USWDS icons](https://designsystem.digital.gov/components/icon/). We aim to maintain consistency in semantic use by avoiding duplicating similar icons. If you have a need for an icon that doesn't exist in our set, you may [request a new icon](https://design.va.gov/foundation/icons#requesting-a-new-icon) to be added. ## Quality assurance diff --git a/src/_about/developers/using-web-components.md b/src/_about/developers/using-web-components.md index 431d03f0c..2e1819d4e 100644 --- a/src/_about/developers/using-web-components.md +++ b/src/_about/developers/using-web-components.md @@ -11,8 +11,6 @@ anchors: - anchor: React applications - anchor: Custom events - anchor: Native events - - anchor: How to migrate to Web Components - - anchor: How to migrate from Font Awesome to va-icon --- ## How to use a web component @@ -205,64 +203,3 @@ Another example using the `blur` event in vanilla JavaScript:
For more information about native events in a specific component, refer to the [Storybook documentation](https://design.va.gov/storybook/?path=/docs/about-introduction--page). - -## How to migrate to Web Components - -The Design System Team provides three ways to migrate specific React Components over to Web Components: -* **Manual** - There is an ESLint rule that informs you that the React component is deprecated but there are too many changes to automate a replacement and a guide will need to be followed ([Storybook](https://design.va.gov/storybook/?path=/story/about-introduction--page) example, Confluence documentation, or other guidance within the ESLint popup). -* **ESLint Rule** - There is an ESLint rule that informs you of the ability to convert from a React Component to a Web Component with a migration click. -* [**Migration Script**](https://github.com/department-of-veterans-affairs/vets-website/blob/main/script/component-migration/README.md) - There is a script available to be used in the CLI when in the `vets-website` repo to convert the React Component to a Web Component. - -Auto-migrations may not be able to perfectly migrate every component. Before you merge your PR be sure to inspect the diff and test thoroughly. Migrations also do not update test files so you will need to update those manually. - -### Web component migrations - -Here is a list of each Web Component and the migration available: - -* `va-modal`: [ESLint Rule](https://github.com/department-of-veterans-affairs/veteran-facing-services-tools/blob/e37233f7ed059c91bf43e92f825390bbf5991298/packages/eslint-plugin/lib/rules/prefer-web-component-library.js) - -## How to migrate from Font Awesome to va-icon - -Font Awesome icons will be deprecated in late-May 2024 in favor of the `va-icon` web component which uses USWDS icons. USWDS icons are a combination of Material Icons and [custom icons](https://github.com/department-of-veterans-affairs/dst-uswds-compile/tree/main/assets/icons). A searchable set can be viewed on the [USWDS Icon page](https://designsystem.digital.gov/components/icon/). - -### Quick References -- [Icon Name Mapping](https://design.va.gov/foundation/icons) -- [va-icon on Storybook](https://design.va.gov/storybook/?path=/docs/uswds-va-icon--default) -- Slack channel: `#platform-design-system` - - - -### The va-icon Web Component API - -Examples and details for the va-icon web component can be found on [Storybook](https://design.va.gov/storybook/?path=/docs/uswds-va-icon--default). The web component has the following customization properties available: - -- icon: The name of the icon to use -- size: The size of the icon as a value between 3 and 9. Sizing can be previewed in Storybook by adjusting the size control - - 3: 24px - - 4: 32px - - 5: 40px - - 6: 48px - - 7: 56px - - 8: 64px - - 9: 72px -- srtext: Screen-reader text if the icon has semantic meaning and is not purely decorative - -### Mapping Icon Names - -Icon name mapping from Font Awesome to USWDS can be found on the [Icons Foundation page](https://design.va.gov/foundation/icons). Icon names can also be referenced on [Storybook](https://design.va.gov/storybook/?path=/docs/uswds-va-icon--default) or the [USWDS Icon page](https://designsystem.digital.gov/components/icon/). \ No newline at end of file diff --git a/src/_about/experience-standards.md b/src/_about/experience-standards.md index ee4c65385..fc0d304e2 100644 --- a/src/_about/experience-standards.md +++ b/src/_about/experience-standards.md @@ -20,7 +20,7 @@ Governance team references these standards when we review products during the Co ## List of Experience Standards -There are 22 experience standards grouped into 7 user experience categories. +There are 23 experience standards grouped into 7 user experience categories. ### Category: Comprehension @@ -118,6 +118,12 @@ GitHub label: [exp-std-voice-tone](https://github.com/department-of-veterans-aff GitHub label: [exp-std-form-integrity](https://github.com/department-of-veterans-affairs/va.gov-team/labels/exp-std-form-integrity) +#### User receives appropriate notification from the VA or VA.gov about the status of their request + +**There's an issue when:** User does not receive appropriate notification from the VA or VA.gov about the status of their request. + +GitHub label: [exp-std-submission-status](https://github.com/department-of-veterans-affairs/va.gov-team/labels/exp-std-submission-status) + ### Category: Efficiency User can accomplish their goals as quickly and efficiently as possible, with minimal cognitive load. diff --git a/src/_about/whats-new.md b/src/_about/whats-new.md index 7fb0f5cff..2a7cec573 100644 --- a/src/_about/whats-new.md +++ b/src/_about/whats-new.md @@ -9,21 +9,46 @@ title: What’s new? The latest news and updates on the Design System, Forms library and the Content style guide. - -

- v1 components have now been deprecated -

-
-

- If your team is still using a v1 component, instances will be flagged in the Collab Cycle and may be considered launch blocking. Learn how to migrate a component. -

-
- +## Fall 2024 + +### New and updated components +* va-process-list-item: Add text to describe status by @powellkerry in #1362 +* Add custom message to va-file-input and update message in va-file-input-multiple by @ataker in #1367 +* va-table: add sorting variation by @it-harrison in #1358 +* va-file-input: add support for read-only mode by @pennja in #1300 +* va-date: add prop to make month optional by @it-harrison in #1377 + +### Bug fixes +* va-modal: set box-sizing to border-box to prevent text overflow by @powellkerry in #1357 +* va-accordion: open accordion when media is print by @ataker in #1363 +* va-process-list: update status eyebrow text to uppercase by @powellkerry in #1365 +* va-process-list: change color variable from usa to vads by @powellkerry in #1368 +* va-table: show table header for non-stacked & stacked small screen by @harshil1793 in #1364 +* va-table: update va-table-inner to properly scope table header row to columns by @1Copenut in #1370 +* va-select: add import for focusable mixin by @powellkerry in #1376 +* va-modal: set overflow-wrap:anywhere on modal content by @powellkerry in #1372 +* focusable: add tabindex selector by @powellkerry in #1380 + +### Other changes +* CSS Library: replace FA icons for action link and alert classes by @jamigibbs in #1371 +* CSS Library: style and image path updates for alert and action link modules by @jamigibbs in #1378 +* CSS Library: remove the /alerts image path by @jamigibbs in #1381 + +### Design updates +* [Design] Table variations #3137 +* [Design]Update Alert spacing in Figma #3231 +* Update breadcrumb spacing in Page templates - Design #3049 + +### Documentation updates +* Update guidance for Keep a record of submitted information pattern #3054 +* Add List guidance to VADS #3206 +* Alerts - Sign in - Documentation +* Issue with downloading logos (PNG format) +* Update va-link External link variation guidance #3224 +* Multiple responses pattern and flow chart #3219 +* Update guidance for select component - Documentation #3251 +* Guidance for international phone numbers #3316 +* Update gender pattern #3289 ## Summer 2024 @@ -36,7 +61,7 @@ The team synced up typography with USWDS v3 and continues to focus on syncing up * [Text input - Suffix text]({{ site.baseurl }}/components/form/text-input#suffix-text) * [Text input - Prefix and Suffix]({{ site.baseurl }}/components/form/text-input#prefix-and-suffix) -Component Library releases +Component Library releases ### New and updated guidance @@ -48,7 +73,7 @@ The team synced up typography with USWDS v3 and continues to focus on syncing up ### Bug fixes -[Issues closed this summer](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues?q=is%3Aissue+is%3Aclosed+closed%3A2024-06-01..2024-08-30+) +[Issues closed this Summer](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues?q=is%3Aissue+is%3Aclosed+closed%3A2024-06-01..2024-08-30+) (206) ## Spring 2024 @@ -235,4 +260,4 @@ Modal (#1634, #2449, #2450) * Developer contribution page updates in #2446 * va-alert and va-expandable-alert: Updated accessibility documentation for announcing alerts (role="alert") in #2145 -* Design Libraries has been updated with Figma information in #2410 \ No newline at end of file +* Design Libraries has been updated with Figma information in #2410 diff --git a/src/_components/alert-expandable.md b/src/_components/alert/alert-expandable.md similarity index 90% rename from src/_components/alert-expandable.md rename to src/_components/alert/alert-expandable.md index 58531ed9e..3d9458f1d 100644 --- a/src/_components/alert-expandable.md +++ b/src/_components/alert/alert-expandable.md @@ -1,6 +1,8 @@ --- layout: component title: Alert - Expandable +permalink: /components/alert/alert-expandable/ +has-parent: /components/alert/ github-title: va-alert-expandable intro-text: A minimized alert style that can be used to alert a user to relevant information on the page that is not prompted by their own action. This component combines the Additional Info component with the Background-Color only Alert variation color schemes. figma-link: https://www.figma.com/file/JDFpGLIojfuQwANXScQjqe/VADS-Component-Example-Library?type=design&node-id=35%3A146&mode=design&t=J32RmU6Fjbjuh9bD-1 @@ -31,24 +33,6 @@ anchors: {% include storybook-preview.html story="components-va-alert-expandable--success" link_text="va-alert-expandable" %} -{% comment %} - - ### Error alert - -Used when there is a problem or something destructive is about to occur. - -{% include storybook-preview.html story="components-va-alert-expandable--error" link_text="va-alert-expandable" %} - -### Continue alert - -{% include storybook-preview.html story="components-va-alert-expandable--continue" link_text="va-alert-expandable" %} - -### No icon alerts - -{% include storybook-preview.html story="components-va-alert-expandable--no-icon" link_text="va-alert-expandable" %} - -{% endcomment %} - ## Usage ### When to use Alert - Expandable @@ -105,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 %} \ No newline at end of file diff --git a/src/_components/alert/alert-sign-in.md b/src/_components/alert/alert-sign-in.md new file mode 100644 index 000000000..059b98dd3 --- /dev/null +++ b/src/_components/alert/alert-sign-in.md @@ -0,0 +1,97 @@ +--- +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 +{% include content/sign-in-alert-examples.md %} + +## 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. 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. + **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." [Refer to the form into page template for that guidance](https://design.va.gov/templates/forms/introduction).) + +## Behavior +[Refer to the related sign-in pattern page for full guidance](https://design.va.gov/patterns/help-users-to/sign-in) + +### All products that only allow verified accounts must implement 1 of these 2 alert variations + +#### Required sign-in (verified) + +When these are true: +* Person is not signed in, **and** +* Your product requires people to sign in, **and** +* Your product only accepts verified (LOA3 or IAL2) accounts + +#### Optional sign-in (verified) + +When these are true: +* Person is not signed in, **and** +* Your product is a form, **and** +* Your product doesn't require sign-in, but if people choose to sign in they must use verified (LOA3 or IAL2) accounts, **and** +* Your form supports both prefill and save-in-progress + +### All products that only allow verified accounts must implement all 3 of these alerts + +#### Verify with ID.me + +When these are true: +* Person is signed in with an unverified (LOA1 or IAL1) ID.me account, **and** +* Your product only accepts verified (LOA3 or IAL2) accounts + +#### Verify with Login.gov + +When these are true: +* Person is signed in with an unverified (LOA1 or IAL1) Login.gov account, **and** +* Your product only accepts verified (LOA3 or IAL2) accounts + +#### Sign in with another account + +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 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 %} diff --git a/src/_components/alert.md b/src/_components/alert/index.md similarity index 97% rename from src/_components/alert.md rename to src/_components/alert/index.md index e8f6bb555..2ebd6f0d8 100644 --- a/src/_components/alert.md +++ b/src/_components/alert/index.md @@ -1,12 +1,16 @@ --- layout: component title: Alert +permalink: /components/alert/ status: use-best-practice intro-text: "Alerts keep users informed of important and sometimes time-sensitive changes." research-title: "Alert boxes" figma-link: https://www.figma.com/file/JDFpGLIojfuQwANXScQjqe/VADS-Example-Library?type=design&node-id=35%3A145&mode=design&t=ep6tlGT5gNsbWqGP-1 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 @@ -100,7 +104,7 @@ Any style of alert box can be modified to be a Slim alert. The iconography for S #### Additional reasons to consider something else * **Destructive actions.** If an action will result in destroying a user’s work (for example, deleting an application) use a more intrusive pattern, such as a confirmation [modal]({{ site.baseurl }}/components/modal) dialogue, to allow the user to confirm that this is what they want. -* **Unprompted and in-page alerts.** Consider the [Alert - Expandable]({{ site.baseurl }}/components/alert-expandable) component to draw attention to important information on the page that is not a response to user feedback. +* **Unprompted and in-page alerts.** Consider the [Alert - Expandable]({{ site.baseurl }}/components/alert/alert-expandable) component to draw attention to important information on the page that is not a response to user feedback. * **Clarifying background information.** Use the [Additional info]({{ site.baseurl }}/components/additional-info) component when clarifying outcomes for an input or a form question as well as providing background information. Keep in mind that Alert - Expandable should warrant an alert and be used sparingly. The value of any type of alert is diminished if the page is littered with alerts of equal weight. * **System maintenance.** Most [system messages]({{ site.baseurl }}/content-style-guide/error-messages/system) related to maintenance are handled by the [Banner - Maintenance]({{ site.baseurl }}/components/banner/maintenance) component. diff --git a/src/_components/breadcrumbs.md b/src/_components/breadcrumbs.md index 547ea09fc..86f8c58d3 100644 --- a/src/_components/breadcrumbs.md +++ b/src/_components/breadcrumbs.md @@ -63,6 +63,11 @@ Start with "VA.gov home". Clearly indicate that the home page is the VA.gov home * The breadcrumb should be placed below the header and above the main content. * The placement of the breadcrumb must be consistent from page to page. +* Spacing for the breadcrumb is built in to the component and should be consistent throughout all layouts. The correct spacing is specified in the images below: + +{% include component-example.html alt="Breadcrumbs have 20px / 2.5 spacing units above and 32px / 4 spacing units below at a mobile breakpoint." file="/images/components/breadcrumbs/breadcrumbs-spacing-mobile.png" caption="Breadcrumbs have 20px or 2.5 spacing units above and 32px or 4 spacing units below at a mobile breakpoint." %} + +{% include component-example.html alt="Breadcrumbs have 20px / 2.5 spacing units above and 48px / 6 spacing units below at a desktop breakpoint." file="/images/components/breadcrumbs/breadcrumbs-spacing-desktop.png" caption="Breadcrumbs have 20px or 2.5 spacing units above and 48px or 6 spacing units below at a desktop breakpoint." %} ### Behavior @@ -90,4 +95,4 @@ To use React Router with this component [follow these instructions](https://desi ### Additional accessibility guidance for VA -* **Make current page a link.** Use a link for the current page for robustness. While it may sound counterintuitive to link to the current page in this component, it makes sense to include this as a link so screen readers voice the current page link whether the user navigates by element or by tabbing. Making the current page a link rather than text makes it a focusable and clickable element. It also follows [WAI-ARIA Authoring Practices Guide (APG) guidances](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/examples/breadcrumb/) which states that an `a` element with `aria-current="page"` should represent the current page. \ No newline at end of file +* **Make current page a link.** Use a link for the current page for robustness. While it may sound counterintuitive to link to the current page in this component, it makes sense to include this as a link so screen readers voice the current page link whether the user navigates by element or by tabbing. Making the current page a link rather than text makes it a focusable and clickable element. It also follows [WAI-ARIA Authoring Practices Guide (APG) guidances](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/examples/breadcrumb/) which states that an `a` element with `aria-current="page"` should represent the current page. diff --git a/src/_components/form/autosave.md b/src/_components/form/autosave.md index 0d2a41b28..8df4091ed 100644 --- a/src/_components/form/autosave.md +++ b/src/_components/form/autosave.md @@ -26,6 +26,10 @@ anchors: ## Usage + +

Testing has revealed issues with this component. See this Usability Report for more details.

+ + ### When to use * **When saving form flow progress as a user completes an application.** This message provides confirmation to the user that their form progress is being saved as they progress through a form flow for an application. diff --git a/src/_components/form/checkbox.md b/src/_components/form/checkbox.md index 4a28276d0..25dce4ea8 100644 --- a/src/_components/form/checkbox.md +++ b/src/_components/form/checkbox.md @@ -14,6 +14,7 @@ anchors: - anchor: Examples - Group - anchor: Usage - anchor: Code usage + - anchor: Content considerations - anchor: Accessibility considerations --- @@ -142,6 +143,11 @@ anchors: The native onBlur event is available on this component. It can be used by adding the event handler to your component and it will then listen to the event and respond accordingly when the event fires. +## Content considerations + +Refer to our bulleted list guidance for punctuation and general considerations + ## Accessibility considerations -Refer to the U.S. Web Design System for accessibility guidance \ No newline at end of file +Refer to the U.S. Web Design System for accessibility guidance diff --git a/src/_components/form/date-input.md b/src/_components/form/date-input.md index c6d47d85f..a218e1af4 100644 --- a/src/_components/form/date-input.md +++ b/src/_components/form/date-input.md @@ -43,14 +43,15 @@ web-component: va-date ### When to use date input -- Use a month, day, year date input component for a date a user knows, like a date of birth or marriage. (Example: July 21, 1992). +- Use a month, day, year date input component for a date a user knows, like a date of birth or marriage. (Example: July 21, 1992). Or a date they can easily look up (for example, the expiration date of a credit card). - Use the [month year](#monthyear) variant for a date a user can approximate, like a date they graduated from high school or a GED equivalent. (Example: May 2010) ### When to consider something else -If users are trying to schedule something, consider using a calendar picker. +Do not use the date input component if users are unlikely to know the exact date of the event you’re asking about. You may consider using a date picker for scheduling, with the following caveats -**Note:** We do not currently have a calendar picker as part of the design system. For reference, visit the VA online scheduling tool (VAOS) to see an experimental version of a calendar picker. +- We do not currently have a calendar picker as part of the design system. For reference, visit the VA online scheduling tool (VAOS) to see an experimental version of a calendar picker. +- Date pickers have not been tested for accessibility, and may lead to launch blocking issues for your product unless carefully designed with an accessibility specialist. We strongly recommend reaching out to #accessibility-help on slack for support before considering this pattern. ### How to use date inputs diff --git a/src/_components/form/prefill.md b/src/_components/form/prefill.md index b54d0f7cd..f7d840fe9 100644 --- a/src/_components/form/prefill.md +++ b/src/_components/form/prefill.md @@ -15,6 +15,17 @@ anchors: - anchor: Content considerations --- + +
+

+ We may be replacing this page soon. +

+
+ + ## Examples ### Intro @@ -23,7 +34,7 @@ anchors: {% include_relative html/prefill-intro.html %} -### Step +### Step
{% include_relative html/prefill-step.html %} @@ -42,7 +53,7 @@ anchors: ### How this component works * **Intro variation uses Alert - Informational.** The Intro variation of this component is an instance of the [Alert - Informational]({{ site.baseurl }}/components/alert#informational-alert) component, but without a header. -* **Step variation uses Alert - Background-only Informational.** The Step variations of this component is an instance of the [Alert - Background-only with icon - Informational]({{ site.baseurl }}/components/alert#background-color-only-alert-with-icon) component. +* **Step variation uses Alert - Background-only Informational.** The Step variations of this component is an instance of the [Alert - Background-only with icon - Informational]({{ site.baseurl }}/components/alert#background-color-only-alert-with-icon) component. ### Placement diff --git a/src/_components/form/radio-button.md b/src/_components/form/radio-button.md index 14b189edc..296076c13 100644 --- a/src/_components/form/radio-button.md +++ b/src/_components/form/radio-button.md @@ -13,6 +13,7 @@ anchors: - anchor: Examples - anchor: Usage - anchor: Code usage + - anchor: Content considerations - anchor: Accessibility considerations --- @@ -89,6 +90,11 @@ anchors: {% include component-docs.html component_name=page.web-component %} +## Content considerations + +Refer to our bulleted list guidance for punctuation and general considerations + ## Accessibility considerations -Refer to the U.S. Web Design System for accessibility guidance \ No newline at end of file +Refer to the U.S. Web Design System for accessibility guidance diff --git a/src/_components/form/select.md b/src/_components/form/select.md index 9ebe952b8..863f377b7 100644 --- a/src/_components/form/select.md +++ b/src/_components/form/select.md @@ -47,6 +47,10 @@ anchors: {% include storybook-preview.html story="uswds-va-select--internationalization" link_text="va-select internationalization" %} +### Widths + +{% include storybook-preview.html story="uswds-va-select--widths" link_text="va-select widths" height="800px" %} + ## Usage Refer to the U.S. Web Design System for usage guidance diff --git a/src/_components/html/card-benefit-application-drafts.html b/src/_components/html/card-benefit-application-drafts.html index c044110de..5f1621a38 100644 --- a/src/_components/html/card-benefit-application-drafts.html +++ b/src/_components/html/card-benefit-application-drafts.html @@ -4,15 +4,15 @@

FORM 20-0996

Application for Higher-level review

-
Alert: +
+ + Alert:

Application expires on: June 26, 2023

Last opened on: April 27, 2023

-
\ No newline at end of file diff --git a/src/_components/html/card-benefit-payments.html b/src/_components/html/card-benefit-payments.html index 5cc5ed368..3d43d0272 100644 --- a/src/_components/html/card-benefit-payments.html +++ b/src/_components/html/card-benefit-payments.html @@ -9,9 +9,6 @@

Check mailed on March 31, 2023

- - Review your payment history - + \ No newline at end of file diff --git a/src/_components/icon.md b/src/_components/icon.md index b69de2158..5efc1f51f 100644 --- a/src/_components/icon.md +++ b/src/_components/icon.md @@ -44,10 +44,6 @@ By default, the web component icon will display as `--vads-color-base` which is ``` -### How to migrate from Font Awesome to va-icon - -Follow our detailed instructions on [how to migrate to va-icon]({{ site.baseurl }}/about/developers/using-web-components#how-to-migrate-from-font-awesome-to-va-icon). - ### Icon Sizing Reference diff --git a/src/_components/language-toggle.md b/src/_components/language-toggle.md index 70c9b220f..d9d3cf19d 100644 --- a/src/_components/language-toggle.md +++ b/src/_components/language-toggle.md @@ -4,6 +4,7 @@ title: Language toggle intro-text: "The language toggle is our way of providing translated versions of select pages on va.gov." github-title: va-language-toggle research-title: va-language-toggle +figma-link: https://www.figma.com/design/afurtw4iqQe6y4gXfNfkkk/VADS-Component-Library?node-id=10077-912&t=hljp6A4V60A0rDms-1 status: use-with-caution-available anchors: - anchor: Examples diff --git a/src/_components/link/action.md b/src/_components/link/action.md index c725cdaea..da816957c 100644 --- a/src/_components/link/action.md +++ b/src/_components/link/action.md @@ -18,15 +18,15 @@ anchors: ### Primary -{% include storybook-preview.html height="50px" story="components-va-link-action--default" link_text="va-action-link primary" %} +{% include storybook-preview.html height="50px" story="components-va-link-action--default" link_text="va-link-action primary" %} ### Secondary -{% include storybook-preview.html height="50px" story="components-va-link-action--secondary" link_text="va-action-link secondary" %} +{% include storybook-preview.html height="50px" story="components-va-link-action--secondary" link_text="va-link-action secondary" %} ### Reverse -{% include storybook-preview.html height="67px" story="components-va-link-action--reverse" link_text="va-action-link reverse" %} +{% include storybook-preview.html height="67px" story="components-va-link-action--reverse" link_text="va-link-action reverse" %} ## Usage diff --git a/src/_components/link/html/link-deep-content.html b/src/_components/link/html/link-deep-content.html index 60bfdd035..52ed3fc0d 100644 --- a/src/_components/link/html/link-deep-content.html +++ b/src/_components/link/html/link-deep-content.html @@ -1,6 +1,6 @@

Link copied

diff --git a/src/_components/link/index.md b/src/_components/link/index.md index 4039d0e91..f072e167c 100644 --- a/src/_components/link/index.md +++ b/src/_components/link/index.md @@ -25,27 +25,31 @@ anchors: ### Default -{% include storybook-preview.html story="components-va-link--docs" link_text="va-link" height="75px" %} +{% include storybook-preview.html story="components-va-link--default" link_text="va-link" height="75px" %} + +### Back + +{% include storybook-preview.html story="components-va-link--back" link_text="back va-link" height="50px" %} ### Active -{% include storybook-preview.html story="components-va-link--active" link_text="active va-link" height="25px" %} +{% include storybook-preview.html story="components-va-link--active" link_text="active va-link" height="50px" %} ### Calendar -{% include storybook-preview.html story="components-va-link--calendar" link_text="calendar va-link" height="25px" %} +{% include storybook-preview.html story="components-va-link--calendar" link_text="calendar va-link" height="50px" %} ### Channel -{% include storybook-preview.html story="components-va-link--channel" link_text="channel va-link" height="25px" %} +{% include storybook-preview.html story="components-va-link--channel" link_text="channel va-link" height="50px" %} ### Download -{% include storybook-preview.html story="components-va-link--download" link_text="download va-link" height="25px" %} +{% include storybook-preview.html story="components-va-link--download" link_text="download va-link" height="50px" %} ### Video -{% include storybook-preview.html story="components-va-link--video" link_text="video va-link" height="25px" %} +{% include storybook-preview.html story="components-va-link--video" link_text="video va-link" height="50px" %} ## Usage @@ -60,6 +64,16 @@ anchors: * **Collections, such as Hub pages.** Active links can be seen on [Hub pages]({{ site.baseurl }}/templates/hub#example) * **Less prominent links.** For links that need less prominence than an [Action link]({{ site.baseurl }}/components/link/action) and may appear in a [collection]({{ site.baseurl }}/components/link/collection), we recommend using an Active Link. Active Links have a hover behavior that includes a background color change and an animated right-facing chevron icon for more emphasis. +### When to use a Back link +* **As a replacement for breadcrumb** on: + * Conventional Multi-step Forms that also: + * Have a [minimal header]({{ site.baseurl }}/components/header/header-minimal) and [minimal footer]({{ site.baseurl }}/components/footer/footer-minimal) + * Follow the [one thing per page pattern]({{ site.baseurl }}/patterns/ask-users-for/a-single-response) pattern + * Use the `H1` element to represent the headline for the current form page, rather than the step title in the step indicator + * Include only a `Continue` button and do not have a `Back` button after the form + * Short Forms that has a small amount of short, concise steps. For example, the [Pact Act Wizard](https://staging.va.gov/pact-act-eligibility/introduction). + * Non-Form Pages where the current page was accessed from a related page and does not have additional navigation. For example, an appointment details page. + ### When to use a Calendar link * **Adding an event to a calendar.** Use when the link adds an event to a digital calendar. diff --git a/src/_components/modal/index.md b/src/_components/modal/index.md index 665b40030..4a05d9cab 100644 --- a/src/_components/modal/index.md +++ b/src/_components/modal/index.md @@ -14,7 +14,6 @@ anchors: - anchor: Usage - anchor: Code usage - anchor: Accessibility considerations - - anchor: Component checklist --- {% include _site-in-this-section.html %} diff --git a/src/_components/summary-box.md b/src/_components/summary-box.md index 0dab8d1ae..21de8523e 100644 --- a/src/_components/summary-box.md +++ b/src/_components/summary-box.md @@ -51,7 +51,7 @@ Summary box is found towards the top of the page after the h1 title of the page ### How to use the Summary box component -* Features must use a `h3` or `h4` heading depending on what the appropriate heading level is for your page based on the content of your page. +* Features must use a `h2`, `h3` or `h4` heading depending on what the appropriate heading level is for your page based on the content of your page. * Also supports open text, such as `

`, `

- - - - + + @@ -51,10 +49,6 @@

{{ section[0] }}

 - -
Icon v3Icon v3 nameIcon v1FontAwesome classIconValue Usage
{{ icon.icon-name }} - - {{ icon.fa-class }} {% if icon.additional-usage %} {% assign usage = icon.name | append: ', ' | append: icon.additional-usage %} @@ -86,7 +80,7 @@

Requesting a new icon

Search USWDS Icon to see if another existing icon suits your needs. Preferably, choose generic icons that could be reused in various applications. - +

If VADS and USWDS do not contain a suitable icon, you may search Material Icons or browse the official - The float grid is the grid provided by the U.S. Web Design System v1. For a grid that offers more flexibility, see the [flexbox grid](flexbox-grid). - - -{% include _site-on-this-page.html %} - -## Grid examples - -

-{% include_relative html/grid.html %} -
- -{% include snippet.html content='html/grid.html' %} - -## Implementation - -To use the grid, wrap each grid row in a block-level element (e.g.
,
, etc...) with the usa-grid class. To use a grid without padding on the right and left, use the usa-grid-full class instead. - -Each grid item is written semantically by its width. For example: usa-width-one-half = 1/2 grid item, usa-width-two-thirds = 2/3 grid item. - -Medium breakpoints are used for 1/6 and 1/12 grid items, which both transform into a 1/3 grid item at medium screen sizes. - -All grid items are full-width at small screen sizes. - -### Accessibility - -- Low-vision users should be able to increase the size of the text by up to 200 percent without breaking the layout. - -### Usability - -#### When to use - -- Almost always use a grid layout — visitors can read more quickly on pages that use grids. Choose a single grid system for your entire site. - -#### When to consider something else - -- Avoid mixing this grid and other grid systems. - -#### Guidance - -- Choose a 12-column grid with flexible column widths and fixed gutters. The width of the padding on the left and right edge of the grid depends on device size. -- Avoid text lines longer than 75 characters. Place text in narrower grid boxes to keep text lines from becoming too wide. - diff --git a/src/_foundation/layout/index.md b/src/_foundation/layout/index.md index 2dcfc3114..ff245b229 100644 --- a/src/_foundation/layout/index.md +++ b/src/_foundation/layout/index.md @@ -4,7 +4,6 @@ permalink: /foundation/layout/ title: Layout sub-pages: - sub-page: Flexbox grid - - sub-page: Float grid - sub-page: Page layouts --- @@ -16,9 +15,9 @@ sub-pages: {% include _site-in-this-section.html %} -## Grids +## Flexbox grid -We have two types of grids. One is the float grid (whereas "float" refers to the `float` CSS property) provide by the U.S. Web Design System. The other grid is a flexbox grid (which refers to the `flexbox` CSS spec) that provides more design flexibility and options to use with responsive design. A similar flexbox grid will be offered in the U.S. Web Design System version 2.0. +The flexbox grid (which refers to the `flexbox` CSS spec) provides more design flexibility and options to use with responsive design. ## Page layouts diff --git a/src/_foundation/typography.md b/src/_foundation/typography.md index 63fe92fd7..0a32e9ae3 100644 --- a/src/_foundation/typography.md +++ b/src/_foundation/typography.md @@ -6,8 +6,8 @@ anchors: - anchor: Fonts - anchor: Headings - anchor: Paragraphs - - anchor: Lists - anchor: Typography tokens + - anchor: Related --- # Typography @@ -172,4 +172,8 @@ Don’t change heading level in order to use a different font size. ### Semantic typography tokens {% assign font_semantic = site.data.tokens.vads-font-semantic %} -{% include tokens.html tokens=font_semantic %} \ No newline at end of file +{% include tokens.html tokens=font_semantic %} + +## Related + +* [List]({{ site.baseurl }}/components/list) \ No newline at end of file diff --git a/src/_foundation/utilities/html/position.html b/src/_foundation/utilities/html/position.html new file mode 100644 index 000000000..7b822a772 --- /dev/null +++ b/src/_foundation/utilities/html/position.html @@ -0,0 +1,14 @@ +
+
+

Elements positioned

+
+ Positioning on mobile breakpoint and larger +
+
+ Positioning on medium-screen breakpoint and larger +
+
+ Positioning on desktop breakpoint and larger +
+
+
\ No newline at end of file diff --git a/src/_foundation/utilities/index.md b/src/_foundation/utilities/index.md index 2d867a659..c603d5907 100644 --- a/src/_foundation/utilities/index.md +++ b/src/_foundation/utilities/index.md @@ -8,7 +8,7 @@ sub-pages: - sub-page: Display - sub-page: Flexbox - sub-page: Font family - - sub-page: Font size + - sub-page: Font size - sub-page: Font style - sub-page: Font weight - sub-page: Height and width @@ -16,6 +16,7 @@ sub-pages: - sub-page: Margins - sub-page: Measure - sub-page: Padding + - sub-page: Position - sub-page: Text align - sub-page: Text color - sub-page: Text decoration @@ -59,9 +60,11 @@ Be descriptive, use the global & utility prefixes, and avoid creating ambiguity Use descriptive class names that clearly indicate the associated CSS property. #### Example + ```css .vads-u-margin-bottom--5 ``` +
@@ -70,9 +73,11 @@ Use descriptive class names that clearly indicate the associated CSS property. Don’t use acroynms or shorthand, ambiguous class names that do not clearly indicate the associated CSS property. #### Example + ```css .vads-u-mb5 ``` +
diff --git a/src/_foundation/utilities/position.md b/src/_foundation/utilities/position.md new file mode 100644 index 000000000..c96a83fa9 --- /dev/null +++ b/src/_foundation/utilities/position.md @@ -0,0 +1,48 @@ +--- +layout: default +permalink: /foundation/utilities/position +has-parent: /foundation/utilities/ +title: Position +--- + +# Position + +
+Change the positioning of text or elements. Position classes include [responsive prefixes](#responsive-prefixes). +
+ +
+ {% + include _showcase-header.html + heading_level=2 + header="Position" + responsive=true + css_property="position" + %} +
+ {% for item in site.data.position.position %} +
+
+ .vads-u-position--{{ item.name }} +
+
+

{{ item.description }}

+
+
+ {% endfor %} +
+
+ +## Responsive prefixes + +Add a responsive breakpoint prefix separated with a : to target a utility at a responsive breakpoint and higher, following a mobile-first methodology. + +{% include snippet.html content='html/position.html' %} + +### Example + +```html +
+``` + +{% include _breakpoint-names.html %} diff --git a/src/_includes/_banner-whats-new.html b/src/_includes/_banner-whats-new.html index d2aa1de17..121ed5579 100644 --- a/src/_includes/_banner-whats-new.html +++ b/src/_includes/_banner-whats-new.html @@ -1,9 +1,9 @@ -
+
-

- Summer updates - - USWDS v3 upgrade nearing completion! +

+ Fall updates + + Formation deprecation nearing completion!

\ No newline at end of file diff --git a/src/_includes/_breakpoint-names.html b/src/_includes/_breakpoint-names.html index 862052cac..ab385baef 100644 --- a/src/_includes/_breakpoint-names.html +++ b/src/_includes/_breakpoint-names.html @@ -1,29 +1,40 @@ - + + + + + + + + + + - + + + diff --git a/src/_includes/_component-checklist.html b/src/_includes/_component-checklist.html index b927c5faa..4b41bbf0b 100644 --- a/src/_includes/_component-checklist.html +++ b/src/_includes/_component-checklist.html @@ -3,6 +3,7 @@ {% assign component = components | map: name %} {% assign definitions = components | map: "definitions" %} +

Component checklist

{% for definition in definitions %} @@ -18,33 +19,38 @@

Component checklist

{{ title | replace: "-", " " | capitalize }}

-
- {% for item in items %} - {% assign name = item.name %} - {% assign values = component.first[title] %} - {% assign slug_name = name | slugify %} - {% assign value = values | where: "name", slug_name %} - {% assign score = value.first.score %} - {% assign notes = value.first.notes %} -
- {% if score == true %} - {% assign completed_items = completed_items | plus: 1 %} - {% assign total_items = total_items | plus: 1 %} - - {% elsif score == "n/a" %} - - {% elsif score == false %} - {% assign total_items = total_items | plus: 1 %} - - {% endif %} - {{ name }} -
-
{{ item.desc }}
- {% if notes %} -
Note: {{ notes }}
- {% endif %} - {% endfor %} -
+ + {% if section[0] == "accessibility" %} + {% include a11y/a11y-checklist.html name=include.component_name %} + {% else %} +
+ {% for item in items %} + {% assign name = item.name %} + {% assign values = component.first[title] %} + {% assign slug_name = name | slugify %} + {% assign value = values | where: "name", slug_name %} + {% assign score = value.first.score %} + {% assign notes = value.first.notes %} +
+ {% if score == true %} + {% assign completed_items = completed_items | plus: 1 %} + {% assign total_items = total_items | plus: 1 %} + + {% elsif score == "n/a" %} + + {% elsif score == false %} + {% assign total_items = total_items | plus: 1 %} + + {% endif %} + {{ name }} +
+
{{ item.desc }}
+ {% if notes %} +
Note: {{ notes }}
+ {% endif %} + {% endfor %} +
+ {% endif %} {% endfor %} diff --git a/src/_includes/_side-nav.html b/src/_includes/_side-nav.html index c0d53b55a..1df29969c 100644 --- a/src/_includes/_side-nav.html +++ b/src/_includes/_side-nav.html @@ -44,7 +44,7 @@ {% assign is-current = false %} {% endif %}
  • - + {{ item.sub-page }} {%- if include.name == 'components' -%} {%- include _site-side-nav-status.html components=sortedPages component=item.sub-page parent=p.title -%} diff --git a/src/_includes/_site-in-this-section.html b/src/_includes/_site-in-this-section.html index ffd48cf50..0d5bc6cc8 100644 --- a/src/_includes/_site-in-this-section.html +++ b/src/_includes/_site-in-this-section.html @@ -8,7 +8,7 @@
    {{ item.sub-page }} diff --git a/src/_includes/a11y/a11y-checklist.html b/src/_includes/a11y/a11y-checklist.html new file mode 100644 index 000000000..f0232c7c4 --- /dev/null +++ b/src/_includes/a11y/a11y-checklist.html @@ -0,0 +1,61 @@ +{% assign component-found = false %} + +{% for component in site.data.component-checklist.a11y.a11y-audit %} + {% if component["Name"] == include.name %} + {% assign component-found = true %} + {% assign row = site.data.component-checklist.a11y.a11y-audit[forloop.index0] %} + +

    + For more information on each category, see Accessibility testing for design system components. +

    + + {% for name_value_pair in row %} + {% if name_value_pair[0] != "Name" %} +
    +
    + {%if name_value_pair[0] != "Last audit date" %} + {% if name_value_pair[1] contains "Pass with exceptions" %} + {% assign completed_items = completed_items | plus: 1 %} + {% assign total_items = total_items | plus: 1 %} + + {% elsif name_value_pair[1] contains "Pass" %} + {% assign completed_items = completed_items | plus: 1 %} + {% assign total_items = total_items | plus: 1 %} + + {% elsif name_value_pair[1] contains "Conditional" %} + {% assign completed_items = completed_items | plus: 1 %} + {% assign total_items = total_items | plus: 1 %} + + {% elsif name_value_pair[1] contains "Fail" %} + {% assign total_items = total_items | plus: 1 %} + + {% else %} + {% assign total_items = total_items | plus: 1 %} + + {% endif %} + {% endif %} + + {{ name_value_pair[0] }} +
    + + {% if name_value_pair[1] %} +
    {{ name_value_pair[1] }}
    + {% else %} +
    This category has not been tested.
    + {% endif %} + + {% if name_value_pair[1] contains "Conditional" %} +

    + Note: This category is dependent on how you use this component. Test this for accessibility in your project. +

    + {% endif %} +
    + {%endif%} + {% endfor %} + {% endif %} +{% endfor %} + + +{% if component-found == false %} +

    While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

    +{% endif %} diff --git a/src/_includes/component-resource-links.html b/src/_includes/component-resource-links.html index bed06e5f1..111c03393 100644 --- a/src/_includes/component-resource-links.html +++ b/src/_includes/component-resource-links.html @@ -31,9 +31,15 @@ {% endif %} {% if research_component_name %}
    + {% if page.layout == 'pattern' %} + + Research + + {% else %} Research + {% endif %}
    {% endif %} {% if page.figma-link %} diff --git a/src/_includes/content/phone-numbers.md b/src/_includes/content/phone-numbers.md index 6502405bc..fc49eb23f 100644 --- a/src/_includes/content/phone-numbers.md +++ b/src/_includes/content/phone-numbers.md @@ -11,10 +11,12 @@ Using the [Telephone component]({{ site.baseurl }}/components/telephone) will ap * Use a verb ahead of the number. Use "call" or "call us at..." for phone numbers and "text" or "text us at" for text numbers. * When a phone number has (TTY: 711) included, it should be formatted in parenthesis directly following the phone number. Example: 866-440-1238 (TTY: 711) or 866-440-1238, ext. 4 (TTY: 711) -### Links -* Hyperlink all phone numbers, including TTY numbers. It’s not a requirement to link the "call" or "text" verb that precedes the number. We do however include "TTY" in the link and aria label to make it clear that it's specifically for TTY so that users who need the service see it and so those who do not do not unintentionally call a TTY number. +### Links and aria +* Hyperlink all phone numbers, including (TTY: 711). Include "TTY:" in the link. Don't link the "call" or "text" verb that precedes the number. +Example: ` 202-123-1234 (TTY: 711)` +* **New guidance as of August 2024:** You no longer need to use aria labels on phone numbers or TTY. This shift came out of evolving accessibility guidance for people who use assistive technology. Teams should stop adding aria labels to phone numbers and TTY in new content, but the shift will take time to implement on existing content. If you have questions, contact the Sitewide Content, Accessibility, and Information Architecture (CAIA) team. -If for some reason you cannot use the Telephone component, you are responsible for meeting the same formatting and accessibility guidance when creating links to phone numbers. +**Note:** If for some reason you cannot use the Telephone component, you are responsible for meeting the same formatting and accessibility guidance when creating links to phone numbers. ### Don't use vanity phone numbers in body copy We don’t use vanity phone numbers in body copy, as it adds visual noise and is not helpful to screen readers. We use and hyperlink only the numeric phone number in body copy. diff --git a/src/_includes/content/sign-in-alert-examples.md b/src/_includes/content/sign-in-alert-examples.md new file mode 100644 index 000000000..18b434a5b --- /dev/null +++ b/src/_includes/content/sign-in-alert-examples.md @@ -0,0 +1,14 @@ +### 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 %} + +### 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 a different account +{% include component-example.html alt="An example of a sign-in alert for unverified My HealtheVet accounts." file="/images/components/alert-sign-in/sign-in-with-a-different-account.png" caption="An example of a sign-in alert for unverified My HealtheVet accounts." reverse=true %} diff --git a/src/_includes/header.html b/src/_includes/header.html index a750fe159..a4b9312ba 100644 --- a/src/_includes/header.html +++ b/src/_includes/header.html @@ -50,7 +50,7 @@
    -
    +
      @@ -64,7 +64,7 @@
      -
      +
        diff --git a/src/_layouts/component.html b/src/_layouts/component.html index 80d28d205..fb27c8e16 100644 --- a/src/_layouts/component.html +++ b/src/_layouts/component.html @@ -1,6 +1,5 @@ - {% include head.html %} @@ -49,6 +48,8 @@

        {{ page.title }}

        {% endif %} {% endunless %} {{ content }} + + {% include edit-on-github.html %} {% include timestamps.html %} diff --git a/src/_patterns/ask-users-for/email-address.md b/src/_patterns/ask-users-for/email-address.md index 86fbdc5e4..8882d1e04 100644 --- a/src/_patterns/ask-users-for/email-address.md +++ b/src/_patterns/ask-users-for/email-address.md @@ -22,13 +22,13 @@ anchors: ### When to use this pattern -* **When you need to collect an email address.** For example, for contact information. +* **For collecting an email address, which is required for online forms.** As of October 2024, collecting an email address is required for online forms. Digital submissions require following up with the user digitally which requires an email address. ## Examples ### Default -{% include component-example.html alt="An email address text-input field." file="/images/patterns/ask-users-for/email-address/email-address.png" caption="An example of asking users for an email address." width="50%" %} +{% include component-example.html alt="An email address text-input field." file="/images/patterns/ask-users-for/email-address/email-address.png" caption="An example of asking users for an email address" width="50%" %} View an example @@ -38,12 +38,12 @@ anchors: ### How this pattern works -* **Prepopulate email address from profile whenever possible.** This makes it easier for users as they have one less field to complete. -* **Adding an email confirmation field.** The email confirmation field is unnecessary if we're using the email from a profile. Also, it's not useful for catching errors as most users copy and paste and don't review their initial entry. +* **Collect an email address for the Veteran and, if not the same person, the person completing the form.** It is a requirement to capture the email address of the person completing the form. If this is not the Veteran it is also necessary to collect the email address of the Veteran. Both should be [notified at the appropriate touch points for a form submission]({{ site.baseurl }}/patterns/help-users-to/stay-informed-of-their-application-status). +* **Pre-populate email address from VA.gov Profile whenever possible.** This makes it easier for users as they have one less field to complete. * **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: *We may use 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. -* **Inform users when prefilling information from VA.gov profile.** Notify users that information from their profile has been prefilled into the form. An example message is: *We've prefilled some of your information from your account.* -* **Indicate to users whether an update in this form will update their VA.gov profile.** Notify users that a change will not update their VA.gov profile. An example message is: *Any updates you make here will only apply to this application.* +* **Do not use an email confirmation field.** The email confirmation field is unnecessary if we're using the email from a profile. Also, it's not useful for catching errors as most users copy and paste and don't review their initial entry. +* **Validate email addresses upon entry.** You should validate email addresses for formatting so you can let users know if they have entered an email incorrectly. +* **Inform users when prefilling information from VA.gov profile.** Notify users that information from their profile has been prefilled into the form using the [prefill component]({{ site.baseurl }}/components/form/prefill). * **Pair with phone numbers.** Collection of email address is paired with [phone numbers]({{ site.baseurl }}/patterns/ask-users-for/phone-numbers). The two patterns typically appear on the same step/page. ### Components used in this pattern diff --git a/src/_patterns/ask-users-for/gender.md b/src/_patterns/ask-users-for/gender.md index 10bae41cd..e7af96152 100644 --- a/src/_patterns/ask-users-for/gender.md +++ b/src/_patterns/ask-users-for/gender.md @@ -17,7 +17,9 @@ anchors: ### 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. +* **Don’t ask a user to provide information that VA already has.** You should only ask users for race or ethnicity, sexual orientation, or gender identity when VA does not already have the user’s information or when VA’s last validation date pre-dates the most recent approved pattern. +* **Only ask a user to provide information if it benefits the user experience.** You should only ask a user for their race or ethnicity, sexual orientation, or gender identity if you can clearly explain how providing this information will benefit the user (not the VA) and the question is related to the larger action they are trying to perform. +* **Only collect data when you can reinforce trust, transparency, and user choice.** You must clarify their information will not be used for their medical treatment or benefits determinations and demonstrate how a user can change their race or ethnicity, sexual orientation, or gender identity and related privacy preferences in the VA.gov profile. If a user does not have and is not eligible to create a VA.gov profile, such as an unauthenticated users, then the data is not collected. **Note:** Many forms are based off of paper forms with limited fields for gender. Work with your stakeholder to expand the fields. @@ -31,7 +33,6 @@ anchors: ### How this pattern works - -* **Provide a way to opt-out of answering.** A checkbox labeled "Prefer not to answer" should be provided. -* **Provide a way to give a 'None of the above' answer.** A checkbox labeled "A gender not listed here." should be provided. -* **Explain what happens to the information collected.** Always explain to Veterans how the information they provide is used, shared, and protected. \ No newline at end of file +* **Provide a way to opt-out of answering.** An option labeled “Prefer not to answer” should be provided. +* **These questions are optional.** Clearly communicate that the information being collected is not required. +* **Do not remove the user from the task at hand to communicate details about this data collection.** Specific use descriptions, definitions, or other descriptive content must be brief and VA policy compliant with no need for a user to leave what they are doing. \ No newline at end of file diff --git a/src/_patterns/ask-users-for/multiple-responses.md b/src/_patterns/ask-users-for/multiple-responses.md index 675281706..14e270215 100644 --- a/src/_patterns/ask-users-for/multiple-responses.md +++ b/src/_patterns/ask-users-for/multiple-responses.md @@ -17,11 +17,8 @@ status: use-deployed anchors: - anchor: Usage - anchor: How to design and build - Multi-page - - anchor: How to design and build - Single page - anchor: How to design and build - Add item - - anchor: How to design and build - Contact information - - anchor: Code considerations - - anchor: Accessibility considerations + - anchor: About single page usage --- ## Usage @@ -40,46 +37,112 @@ anchors: Use this pattern when users need to add similar information multiple times, such as information about dependents. This method allows more table-like data to be collected following the [One thing per page principle]({{ site.baseurl }}/patterns/ask-users-for/a-single-response). -This method is also recommended as the user first identifies the items in a list and then returns to each item in the list on a distinct page, adding details to that item. - -{% include component-example.html alt="A multi-page multiple response flow diagram." file="/images/patterns/ask-users-for/multiple-responses/multiple-response-flow.png" caption="A diagram explaining the parts of the multi-page pattern." %} - -1. A user enters either a required or optional multiple response flow. - * **A required item for the list and loop.** The required version has an intro page explaining that we're about to ask a series of questions about a thing, and if there's a limit, they can enter up to that limit. Teams can customize how they want this page to work. - * **Completely optional list and loop.** For an optional list and loop, the question is asked "Do you have [a thing] to add? yes/no" Yes enters the loop. -2. The first page of the list and loop asks them to identify the thing they are adding. In this case, treatment records from a facility. Designers can choose how they want to construct the pages of the list and loop. We recommend following the one thing per page pattern as we do throughout our forms. -3. At any time in the multiple responses list and loop a user can exit the loop by clicking the "cancel adding this [thing]" button. A modal appears asking them to confirm their choice. If they answer that they want to stop adding this thing, any data they have entered is removed, and the user is returned to the first page of the list and loop pattern. -4. Summary list page allows users to review what they've entered, edit, delete items, or add another. -5. If the user chooses to add another item they return to the first question page to add the new item. - -The loop can be repeated as many times as your form allows. - - - View an example of a multi-page required loop - - - View an example of a multi-page optional loop - - -{% include component-example.html alt="A summary page for the multiple response multi-page pattern variation." file="/images/patterns/ask-users-for/multiple-responses/multiple-response-summary.png" caption="An example of the summary page for a multi-page multiple response pattern. This summary page reflects the data collected thus far and allows the user to act on that data or add more." class="x2" %} - -After adding each item, the user is shown a summary of what they have added so far and they can: - -* **Edit items.** Clicking the edit link returns the user to the first question of the loop and the user has now entered an "edit flow". After editing items, the user is returned to the summary page and alert is shown confirming their item has been updated. When entering an edit flow, the H3s of the pages are updated to include "Edit [previous h3 title]". -* **Delete items.** Clicking the delete button allows a user to confirm that they want to delete the entire loop and all of the answers they have given through the entire loop. A modal pops up asking the user to confirm their choice. After they remove a card, they are returned to the summary page where they can choose to add another. If the user has removed all items, and yet one item is required, the user is returned to the first page of the loop where a warning alert is displayed reminding the user at least one item is required. -* **Add another item.** If the user chooses to add another item they return to the first question page to add the new item. -* **Continue to the next question in the form** - -These summary cards work the same on the review page of the form. - ### When to use the multi-page variation -* **This is the default and preferred variation for multiple responses.** This method is the most flexible of the variations of obtaining multiple responses because it can collect just one or multiple pieces of information across multiple pages. Thus it can collect a very limited set of data or complex details. This variation can be used to collect a key identifier for each item in the set, for example a name or condition, and then collect details for each of those items. +* **This is the default and preferred variation for multiple responses.** This method is the most flexible of the variations of obtaining multiple responses because it can collect just one or multiple pieces of information across multiple pages. Thus it can collect a very limited set of data or complex details. ### When to not use multi-page * **Most of the information being requested is already available.** If we have most of the information being requested already then the "Add item" variation is preferred. If the information we have on file is contact information coming from VA.gov Profile then the "Contact information" variation is preferred. +### Required vs Optional multi-page patterns + +There are two types of multiple page patterns with slightly different user flows: +* **[Required Multi-page Pattern](#required-multi-page-pattern-user-flow)**
        + Use when **at least one item** for this step must be added. +* **[Optional Multi-page Pattern](#optional-multi-page-pattern-user-flow)**
        + Use when the step is **completely optional** and users may or may not add items. + +{% assign intro_required = "The introduction page provides users with information about the next few screens. If there's a limit to the maximum number of items, see the [code & content considerations](#code--content-considerations) to customize the language. " %} + +{% assign intro_optional = "The introduction page provides users with information about the next few screens and provides a **Yes/No** choice to provide additional information. If the user selects **Yes** they will proceed into the questions flow. If the user selects **No**, they proceed to the next step."%} + +{% assign questions_flow = "The user proceeds into the questions flow. We recommend following the [One thing per page](/patterns/ask-users-for/a-single-response#what-is-one-thing-per-page) pattern." %} + +{% assign cancel_flow = "At any time in the questions flow a user can exit by clicking the **Cancel adding this [thing]** button. A modal appears to confirm their choice. If they confirm, any data they have entered is removed, and the user is returned to the Introduction page."%} + +{% assign summary = "A summary page allows users to review what they've entered formatted as summary cards. If the user chooses to add another item, they return to the first question page to add the new item."%} + +{% assign edit_flow = "Clicking **Edit** puts the user into the “edit flow” and returns the user to the first question page. When entering the edit flow, the `H3` of the pages are updated to include “Edit [previous h3 title]”. The fields should pre-populated with their previously supplied information. (Note: There is no **Cancel** button on this page during the editing process.) After editing items, the user returns to the summary page and an [informational alert](/components/alert/#informational-alert-aka-default) is shown confirming their item has been updated."%} + +{% assign delete_flow_required = "A user may choose to delete any of the summary cards. When clicking **Delete**, a modal appears asking them to confirm their choice. If they confirm, that card is removed from the page. If all cards are removed from the summary page, the user will then redirect to the Introduction page with a [warning alert](/components/alert/#warning-alert) reminding the user at least one item is required."%} + +{% assign delete_flow_optional = "A user may choose to delete any of the summary cards. When clicking **Delete**, a modal appears asking them to confirm their choice. If they confirm, that card is removed from the page. If all cards are removed from the summary page, the user is redirected to the Introduction page."%} + +### Required multi-page pattern user flow + +
        +
        +
        + The user flow for the required multi-page multiple responses pattern. +
        +
        + + + {{ intro_required | markdownify }} + + + {{ questions_flow | markdownify }} + + + {{ cancel_flow | markdownify }} + + + {{ summary | markdownify }} + + + {{ edit_flow | markdownify }} + + + {{ delete_flow_required | markdownify }} + + +
        + + View a mock form example of a required multi-page pattern + +
        +
        +
        +
        + +### Optional multi-page pattern user flow + +
        +
        +
        + The user flow for the optional multi-page multiple responses pattern. +
        +
        + + + {{ intro_optional | markdownify }} + + + {{ questions_flow | markdownify }} + + + {{ cancel_flow | markdownify }} + + + {{ summary | markdownify }} + + + {{ edit_flow | markdownify }} + + + {{ delete_flow_optional | markdownify }} + + +
        + + View a mock form example of an optional multi-page pattern + +
        +
        +
        +
        + ### Code & content considerations * **Use the built in error and validation messages**. @@ -96,41 +159,21 @@ These summary cards work the same on the review page of the form. * **If at least one item is required, use hint text to let users know.** The pattern must indicate to users that at least one item is required. If all items are removed, return users to the first page of the loop to gather information. * **If there are a maximum number of items, make this clear to the user.** You can use hint text to do this. Also, after the user has entered the maximum number allowed the pattern removes the "add another" question, and displays a warning instructing the user that they have entered the maximum allowed and they can either edit, or remove a card if they need to add more information. +

        + For more details + +

        + ### Accessibility considerations On the summary page, ensure that the edit links and delete buttons have accessible text so that screen reader users understand what is being edited or deleted. -## How to design and build - Single page - -The Single page implementation variation of this pattern exposes an initial set of fields to collect a set of information with an option to add additional sets of information, one at a time. - - -

        This single-page variation is currently used on VA.gov, but is no longer the preferred variation for this pattern. The multi-page pattern is recommended for new designs.

        - -### Collection - -{% include component-example.html alt="Form example requesting service history from a Veteran." file="/images/patterns/ask-users-for/multiple-responses/editing-service-period.png" caption="Form collecting service history information from a Veteran using the single page implementation of this pattern." class="x2" %} - -* The fields are presented with an option to "Save" the initial entry and to "Add another". Selecting "Add another" before filling in the required fields and clicking "Save" [results in errors associated with each missing field]({{ site.baseurl }}/images/patterns/ask-users-for/multiple-responses/editing-service-period-errors.png). - -### Review for edit and remove - -{% include component-example.html alt="Form showing service history collected from a Veteran." file="/images/patterns/ask-users-for/multiple-responses/adding-service-period.png" caption="Form displaying service history collected from a Veteran and allowing the user to edit or remove the information collected." class="x2" %} - -* Once an initial item is saved it collapses down into a [Card]({{ site.baseurl }}/components/card) with, at minimum, an "Edit" button, and often, a "Remove" button. -* The "Add another" button stays visible so that additional entries can be made. - -### When to use the single page variation - -* **Short data sets.** When the set of information being collected is very short and simple to explain to the user. If the set of information being collected is longer than one or two fields then it can create a long and potentially daunting page of information for the user to fill out and therefore the [Multi-page variation](#how-to-design-and-build---multi-page) should be used instead. - -#### What to watch out for - -* **The "Add another..." secondary button is always visible.** This allows the user to add additional sets of fields before filling out and saving the first set which can get the user into an error condition that may be confusing. Therefore consider whether one of the alternative variations would be better suited to the collection of multiple responses. - -### Code considerations - -[Single page](https://depo-platform-documentation.scrollhelp.site/developer-docs/va-forms-library-using-form-widgets-and-fields#VAFormsLibrary-UsingFormWidgetsandFields-Arrayfield) is available in the VA Forms Library as an Array field. +### Examples in Production +{% include component-example.html alt="A summary page for the multiple response multi-page pattern variation." file="/images/patterns/ask-users-for/multiple-responses/multiple-response-summary.png" caption="An example of the summary page for a multi-page multiple response pattern. This summary page reflects the data collected thus far and allows the user to act on that data or add more." class="x2" %} ## How to design and build - Add item @@ -152,16 +195,5 @@ This method shows all items on one page in a list with an "Add a new [item]" [Li * **Most of the information being requested is already available.** If most of the information being requested is already on file then this variation works well because it presents to the user what we have on file and allows them to add items that are missing. * **Information on file is not contact information coming from VA.gov Profile.** If the information on file is not coming from VA.gov Profile then this variation presents the data clearly and is preferred. If the information on file IS coming from VA.gov Profile then the "Contact information" variation is preferred. -## How to design and build - Contact information - -The Contact information variation of this pattern is captured in the [Help users to know how their information is updated]({{ site.baseurl }}/patterns/help-users-to/know-how-their-information-is-updated) pattern. - -{% include component-example.html alt="Veteran details from the Request a Board Appeal application." file="/images/patterns/ask-users-for/multiple-responses/board-appeal-contact-information.png" caption="The user is shown contact information that is on file and will be used as part of the application process with the option to edit." class="x2" %} - -### When to use the contact information variation - -* **Information on file is contact information coming from VA.gov Profile.** This variation allows the user to see the details of the information we have on file, edit it if necessary, returning them to this screen to confirm the changes have been made and allowing them to continue with their intended goal of completing the application. - -### Code considerations - -[How to create the contact info Array Data](https://depo-platform-documentation.scrollhelp.site/developer-docs/va-forms-library-how-to-create-the-contact-info-ar) details how to add a contact info page via the VA Forms Library that shows the Veteran's contact info and allows updating the changes to their profile directly. \ No newline at end of file +## About single page usage +While the single-page variation is currently used on VA.gov, it is no longer the preferred variation for this pattern. The multi-page pattern is recommended for new designs. diff --git a/src/_patterns/ask-users-for/phone-numbers.md b/src/_patterns/ask-users-for/phone-numbers.md index e3eb9817c..8a3d4daac 100644 --- a/src/_patterns/ask-users-for/phone-numbers.md +++ b/src/_patterns/ask-users-for/phone-numbers.md @@ -4,7 +4,7 @@ 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. -code-link: https://github.com/department-of-veterans-affairs/vets-website/blob/main/src/platform/forms-system/src/js/web-component-patterns/phonePattern.jsx +code-link: https://github.com/department-of-veterans-affairs/vets-website/blob/main/src/platform/forms-system/src/js/web-component-patterns/phonePatterns.jsx example-link: https://staging.va.gov/mock-form-patterns/phone-and-email-address figma-link: https://www.figma.com/file/4A3O3mVx4xDAKfHE7fPF1U/VADS-Templates-(Patterns-%26-Forms)?type=design&node-id=2988%3A9602&mode=design&t=Y0LWxs33fRITMh6x-1 github-title: pattern-phone-numbers @@ -26,11 +26,16 @@ anchors: ## Examples +### U.S. phone numbers + {% include component-example.html alt="Shows the form fields used to obtain home phone number and mobile phone number." file="/images/patterns/ask-users-for/phone-numbers/phone-numbers.png" caption="Example of asking for a home phone number or mobile phone number." class="x2" %} View an example + +### International phone numbers +{% include component-example.html alt="Shows the form fields used to obtain a international phone number." file="/images/patterns/ask-users-for/phone-numbers/international-phone-number.png" caption="Example of asking for an international phone number." class="x2" %} ## How to design and build @@ -39,9 +44,16 @@ anchors: ### 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: +* **Validate phone numbers.** Users must provide at least a 10 digit phone number with or without dashes for U.S. phone numbers and up to a 15-digit phone number for international phone numbers. + + Example of acceptable formats for U.S. phone numbers: * 703-123-4567 * 7031234567 + + Example of acceptable formats for international phone numbers: + * +52 123 456-7890 + * 637031234567 + * **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) * **Pair with email address.** Collection of phone numbers is paired with [email address]({{ site.baseurl }}/patterns/ask-users-for/email-address). The two patterns typically appear on the same step/page. @@ -65,4 +77,4 @@ Use the [VADS templates (Patterns & Forms) for Names in Figma]({{ page.figma-lin ### Labels, error messages, and hint text -{% include _field-labels.html labels=site.data.content.patterns.ask-users-for.phone-numbers %} \ No newline at end of file +{% include _field-labels.html labels=site.data.content.patterns.ask-users-for.phone-numbers %} diff --git a/src/_patterns/ask-users-for/race-ethnicity-or-origin.md b/src/_patterns/ask-users-for/race-and-ethnicity.md similarity index 75% rename from src/_patterns/ask-users-for/race-ethnicity-or-origin.md rename to src/_patterns/ask-users-for/race-and-ethnicity.md index 6e3a9f3a7..2b5d1c8c9 100644 --- a/src/_patterns/ask-users-for/race-ethnicity-or-origin.md +++ b/src/_patterns/ask-users-for/race-and-ethnicity.md @@ -1,11 +1,13 @@ --- layout: pattern -permalink: /patterns/ask-users-for/race-ethnicity-or-origin +permalink: /patterns/ask-users-for/race-and-ethnicity +redirect_from: + - /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. -github-title: pattern-race-ethnicity-origin -research-title: Ask users for race ethnicity or origin +title: Race and ethnicity +intro-text: Follow this pattern whenever you need to ask Veterans for their race and ethnicity. +github-title: pattern-race-ethnicity +research-title: Ask users for race and ethnicity status: use-deployed anchors: - anchor: Usage @@ -38,14 +40,15 @@ anchors: ## Examples -![applicant information race template]({{site.baseurl}}/images/patterns/ask-users-for/race-ethnicity-or-origin/race-ethnicity-or-origin.png) +![applicant information race template]({{site.baseurl}}/images/patterns/ask-users-for/race-and-ethnicity/race-and-ethnicity.png) ## How to design and build ### How this pattern works * **Ethnicity is currently a distinct question that precedes race and is limited to one response.** Ethnicity is currently separate (this may change in future) and must only accept one response. -* **Give users the option of picking more than one race or origin.** Always use checkboxes so that users can identify with multiple races. +* **Give users the option of picking more than one race.** Always use checkboxes so that users can identify with multiple races. * **Provide a way to opt-out of answering.** An option labeled "Prefer not to answer" should be provided to both questions. * **These questions are optional.** Clearly communicate that the information being collected is not required. * **When "Prefer not to answer" is selected, other options are negated.** If a user indicates that they prefer not to answer then all other checkboxes should be unchecked and/or ignored upon submission. +* **Do not remove the user from the task at hand to communicate details about this data collection.** Specific use descriptions, definitions, or other descriptive content must be brief and VA policy compliant with no need for a user to leave what they are doing. diff --git a/src/_patterns/help-users-to/keep-a-record-of-submitted-information.md b/src/_patterns/help-users-to/keep-a-record-of-submitted-information.md index 2044fcc1f..e7a3ad53c 100644 --- a/src/_patterns/help-users-to/keep-a-record-of-submitted-information.md +++ b/src/_patterns/help-users-to/keep-a-record-of-submitted-information.md @@ -6,6 +6,8 @@ title: Keep a record of submitted information intro-text: "This pattern provides the user with a printable record of their submission." status: use-deployed research-title: Help users to keep a record of submitted info +figma-link: https://www.figma.com/design/4A3O3mVx4xDAKfHE7fPF1U/VADS-Templates%2C-Patterns%2C-and-Forms?node-id=2988-66786&t=4uWczdHlyBNGV123-1 +code-link: https://github.com/department-of-veterans-affairs/vets-website/blob/main/src/platform/forms-system/src/js/components/ConfirmationView/README.md anchors: - anchor: Usage - anchor: Examples @@ -17,38 +19,56 @@ anchors: ### When to use this pattern -**When you are collecting information from users on a long form.** The pattern provides the user with a printable record of their submission. A printed record provides a reference for future use and helps to confirm a successful form submission. +**When you are collecting information from users on a long form.** The pattern provides the user with a printable record of their submission data. A printed record provides a reference for future use and helps to confirm a completed form was submitted to VA. + +The pattern must display the name of the form, the date of the submission, a confirmation number, a copy of the data used in the form submission, and a task list outlining the next steps in the form submission process. + ## Examples ### Confirmation page summary -{% include component-example.html alt="An example confirmation page containing a component that allows users to print the confirmation page." file="/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page.png" caption="The 'Your application information' component provides a clear call-to-action for the user to 'Print this page'." width="75%" %} +{% include component-example.html alt="An example confirmation page showing a printable copy of their form status, a downloadable PDF, and s task list" file="/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page-status.png" caption="The confirmation page provides a way for the user to 'Print this page', see their submission status and download a copy of their submission PDF. There is also a task list displaying known next steps." width="75%" %} ### Print preview of confirmation page summary -![print preview of confirmation page summary]({{ site.baseurl }}/images/patterns/help-users-to/keep-a-record-of-submitted-information/print-view-page1.png) -![print preview of confirmation page summary]({{ site.baseurl }}/images/patterns/help-users-to/keep-a-record-of-submitted-information/print-view-page2.png) +![print preview of confirmation page summary]({{ site.baseurl }}/images/patterns/help-users-to/keep-a-record-of-submitted-information/print-confirmation-status.png) ## How to design and build ### How this pattern works -* **Create a summary of submitted information.** Include a title for the summary page. An example message is: *Your application information* -* **Include a recap of submitted information.** Include the applicant's name and date of application. -* **Inform users to print the confirmation for their records.** Notify users that they can print or download their application information. An example message is: *You can print this confirmation page for your records. You can also download your completed application as a PDF.* +* **Create a summary of the action completed.** Include a success alert that accurately describes the action just completed. For example, for forms that have to travel through several systems before it gets to the system of record you can say, _Form submission started on Date_ + * The alert should give a time frame for when the user should expect the next communication from VA about their form submision. + * The alert should also include a confirmation number. + * The alert should also include a link where they can go to check the status of the application. This may be a link to Claim Status Tool or My VA. +* **Include a copy of the submitted information.** Include a copy of the information submitted on the form. Be sure to mask out SSN, VA File number, and Alien Registration numbers on this copy. +* **Inform users to print the confirmation for their records.** Notify users that they can print this confirmation page. * **Include a "Print this page" primary button.** A printed record provides a reference for future use. The "Print this page" button appears at the bottom of the summary page. -* **Include a link to download the completed application in PDF format.** The download link appears below the "Print this page" button. +* **Include a "What to expect next" task list.** (add more text here) -### Placement -The component that contains the prompt to print the confirmation page should appear under the Alert - Success component. +### Placement +The pattern should load at the top of the page beneath the h1 in this order +1. Form submission started alert +2. Coming soon: Download a PDF copy of the form +3. Information you submitted on this form accordion +4. Print this confirmation page +5. What to expect process list ### Components used in this pattern -* [Summary box]({{ site.baseurl }}/components/summary-box) -* [Button - Primary]({{ site.baseurl }}/components/button) -* [Link - Download]({{ site.baseurl }}/components/link/#download) +* [Alert]({{ site.baseurl}}/components/alert) +* [Link]({{ site.baseurl}}/components/link) (download?) +* [Accordion]({{ site.baseurl}}/components/accordion) +* [Button-Primary]({{ site.baseurl }}/components/button) +* [ProcessList-Status]({{ site.baseurl }}/components/process-list) + +## When to consider something else +Forms that are submitted by unauthenticated users should not display links to claim status tool or My VA on the confirmation page as those submissions will not be immediately tracked or connected to a profile account. + +If a user fills out a claim or benefit form unauthenticated or on paper, once VA associates the form with their record, it will show up in the Claim Status Tool. +This could take 7-10 days. ## Content considerations @@ -56,4 +76,11 @@ Review the USWDS [Keep a record pattern](https://designsystem.digital.gov/patter ## Accessibility considerations +This pattern provides a copy of the submission in a collaspible and accessible accordion. When the page is printed, the information is also displayed even if the accordion is still closed. This helps make the page more accessible by providing a copy of the form submission outside of a PDF. A user may still save this page as a PDF, but we can't guarantee the individual accessibility methods of individual browsers and printer settings. + + Review the USWDS [Keep a record pattern](https://designsystem.digital.gov/patterns/complete-a-complex-form/keep-a-record/#section_9) for accessibility considerations. + +## Research findings +In [2024, VFF/MY VA Form Status Research](https://github.com/department-of-veterans-affairs/VA.gov-team-forms/blob/main/Product/2024-05%20VFF%20and%20My%20VA%20Form%20Submission%20Research/Research/Research%20Findings%20for%202024-05%20VFF%20and%20My%20VA%20Form%20Submission%20Research%20Study.md) found that a majority of Veterans indicated they would download a copy of their form submission. But, they were equally confused about the expiration date next to the PDF in My VA. Some findings are relevant to this pattern despite not yet being fully implemented. + - The majority of participants expressed a desire to download a copy of their form submission (10 of 12), and 5 of 12 participants also indicated they would want to print a copy of their form submission. With the option to download a PDF copy of the form they submitted, there was uncertainty about the significance of the date in the associated link. In My VA, the download link will only be available for 60 days due to data security concerns. \ No newline at end of file diff --git a/src/_patterns/help-users-to/know-how-their-information-is-updated.md b/src/_patterns/help-users-to/know-how-their-information-is-updated.md index 64c31d47d..c04a70983 100644 --- a/src/_patterns/help-users-to/know-how-their-information-is-updated.md +++ b/src/_patterns/help-users-to/know-how-their-information-is-updated.md @@ -12,6 +12,17 @@ anchors: - anchor: Research findings --- + +
        +

        + We are updating this pattern. Please note that some guidance may be out of date. +

        +
        +         + ## Usage ### When to use this pattern @@ -25,7 +36,7 @@ anchors: ### When not to use this pattern -* **When an update in this form will not update their VA.gov profile.** If a contact information addition or change will **not** update the user's VA.gov profile then use the text "*Any updates you make here to your [type of contact information] will only apply to this application.*" +* **When an update in this form will not update their VA.gov profile.** If a contact information addition or change will **not** update the user's VA.gov profile then use the text "*Any updates you make here to your [type of contact information] will only apply to this application.*" ### When to use caution @@ -47,7 +58,7 @@ However, some forms show a set of data taken from VA.gov profile and display the * In this example, at the start of the Request a Board Appeal process, the user is shown information that we have on file but that cannot be changed in this application. A note below the information calls out how to get the information updated. -#### Communicate information that can be edited +#### Communicate information that can be edited {% include component-example.html alt="Contact information from the Request a Board Appeal application." file="/images/patterns/help-users-to/know-how-their-information-is-updated/board-appeal-contact-information.png" caption="The user is shown contact information stored in their profile that can be edited before continuing with the process." width="50%" %} diff --git a/src/_patterns/help-users-to/know-when-their-information-is-prefilled.md b/src/_patterns/help-users-to/know-when-their-information-is-prefilled.md new file mode 100644 index 000000000..afc2d3c67 --- /dev/null +++ b/src/_patterns/help-users-to/know-when-their-information-is-prefilled.md @@ -0,0 +1,202 @@ +--- +layout: pattern +title: Know when their information is prefilled +permalink: /patterns/help-users-to/know-when-their-information-is-prefilled +sub-section: help-users-to +intro-text: Follow this pattern to help users know when their information will be prefilled for them in an application. +research-title: Help users know when their info is prefilled +status: use-with-caution-candidate +anchors: + - anchor: Usage + - anchor: How to design and build + - anchor: Examples + - anchor: Code usage + - anchor: Content considerations + - anchor: Research findings +--- + +## Usage + +### When to use this pattern + +- **When you prefill the user's data into an application, like a form.** When using this pattern, clearly inform the user of where their data is being pulled from to prefill for them. +- **When users can update prefilled information.** Review [Help users to... Know how their information is updated](https://design.va.gov/patterns/help-users-to/know-how-their-information-is-updated) for guidance on helping users update this prefilled information. + +#### Design principles +* **Visibility of system status.** This pattern demonstrates the [usability principle of communicating the current state](https://www.nngroup.com/articles/visibility-system-status/) in order to allow users to feel in control and to be able to take appropriate action. +* **User control and freedom.** This pattern also gives users control over their own information thereby providing [control and freedom](https://www.nngroup.com/articles/user-control-and-freedom/). + +### When not to use this pattern +- **For unauthenticated users**. Users who aren't signed in shouldn't see their information prefilled when they interact with an application. But, when forms don't require users to be signed in, they should see an information alert describing benefits to signing in. [View the unauthenticated intro page alert](#unauthenticated-intro-page-alert) later described on this page. + +### When to use caution +- **When prefilling data from a source other than VA Profile.** It is crucial to explain to the user exactly where the data is coming from so that if there are any errors in the data, it is clear how to correct them. + +## How to design and build +### Anatomy or layout details +This pattern involves these types of pages found in VA.gov forms: +- **Introduction page**: The first page of a form. Introduces the process the Veteran or other beneficiary will follow to apply for a benefit or to complete a supporting form. Changes slightly after a user signs in. +- **Personal information page**: Usually the first page of a form after the user signs in. Has personal details that cannot be edited online, like name, date of birth, Social Security number, etc. +- **Prefill check page**: Any page of a form that displays prefilled information users can edit within the form. + +#### Introduction page +There are two states of an introduction page: Authenticated and Unauthenticated. + +{% include component-example.html alt="A form introduction page viewed by an authenticated user with an alert that the form will fill parts of their application based on the their account details. Annotations state that alerts should be placed at the top of the page and the word 'note' in the alert should be bolded." file="/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-authenticated-alert.png" caption="Authenticated introduction page alert on the introduction page." %} + +{% include component-example.html alt="An alert encouraging users to sign in to save time and save work in progress. A note at the bottom shares that applicants can sign in after they start their application, but will lose any information already filled in." file="/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-unauthenticated-alert.png" caption="Unauthenticated introduction page alert on the introduction page." class="x2" %} + +#### Personal information page +{% include component-example.html alt="A Veteran information page in a form flow with an uneditable card containing the Veteran's name, privacy masked Social Security number, date of birth, and gender. Below the card is a note explaining why the content can't be edited in the form and how to update this information. An annotation states that the gray card might be replaced in future iterations of the pattern." file="/images/patterns/help-users-to/know-when-their-information-is-prefilled/uneditable-prefill-information.png" caption="Uneditable prefilled information on the personal information page." %} + +#### Prefill check page +{% include component-example.html alt="A Veteran information page in a form flow with an alert followed by a white editable card containing the Veteran's mailing address. The alert states that the form has prefilled some of the Veteran's information. Annotations state that alerts should be placed at the top of the page, and that the white card might be replaced in future iterations of the pattern." file="/images/patterns/help-users-to/know-when-their-information-is-prefilled/editable-prefill-information.png" caption="Editable prefilled information displayed on the Prefill check page. This is the proposed style to display data that is editable." %} + +### How this pattern works + +#### Communicate when and why information will be prefilled +This pattern communicates when and why information will be prefilled with: +- **Unauthenticated intro page alert.** This tells users they should expect prefilled information in a form after they sign in. The alert also encourages users to sign in to benefit from this time-saving feature. +- **Authenticated intro page alert.** This alert tells users that some of their information may be prefilled for them because they are signed in. + +#### Communicate information that cannot be edited +This pattern communicates information that cannot be edited with: +- **Uneditable prefilled information displayed in a card.** Prefilled information (such as legal name, date of birth, and Social Security number) is displayed in a card component. +- **Directions for updating uneditable information.** Helper text is added under the card that has the bolded word "note" and directions to update this information offline. For additional guidance on helping users update prefilled information, see the ["Help users to... Know how their information is updated"](https://design.va.gov/patterns/help-users-to/know-how-their-information-is-updated) pattern which will be updated soon. + +#### Communicate information that can be edited +This pattern communicates information that can be edited with: +- **Editable prefilled information displayed in a card with an edit link.** Prefilled information that is editable is displayed in a card component with a link to edit the information. For additional guidance on helping users update prefilled information, see the ["Help users to... Know how their information is updated"](https://design.va.gov/patterns/help-users-to/know-how-their-information-is-updated) pattern which will be updated soon. + +### Components used in this pattern + +- [Alert](https://design.va.gov/components/alert/) +- [Card](https://design.va.gov/components/card) + + +## Examples + +### Uneditable Prefill Card +{% include storybook-preview.html story="patterns-components-card--uneditable" height="200px" link_text="uneditable prefill alert" %} + +### Editable Prefill Card +{% include storybook-preview.html story="patterns-components-card--editable" height="250px" link_text="editable prefill alert" %} + + +### Signed In Prefill Alert +{% include storybook-preview.html story="patterns-components-prefill-alert--signed-in-prefill-alert" link_text="signed in prefill alert" %} + +### Unauthenticated Prefill Alert +{% include storybook-preview.html story="patterns-components-prefill-alert--unauthenticated-prefill-alert" height="350px" link_text="unauthenticated prefill alert" %} + +### Prefilled Info Alert +{% include storybook-preview.html story="patterns-components-prefill-alert--prefilled-info-alert" link_text="prefilled info alert" %} + + +### Examples in production +Coming soon! + +## Code usage + +When using the `va-card` element to display prefilled information, ensure that the correct structure of the html is present. The description list `
        ` and unordered list `
          ` elements can be useful for displaying several pieces of uneditable data. + +### Uneditable information +Here is some example markup for a card of uneditable content that utilizes a description list. + +```html + +
          +
          +
          Name
          +
          Godzilla
          +
          Born
          +
          1952
          +
          Birthplace
          +
          Japan
          +
          Color
          +
          Green
          +
          +
          +           +``` + +### Editable information + +If a user can update their information, than pieces of information can be shown with a heading followed by the information itself, along with an edit link. + +```html + + +

          + Email address +

          + +

          testemail1234@unattended.com

          + + + +           +``` + +[View more prefill card examples on storybook](https://design.va.gov/storybook/?path=/docs/patterns-components-card--docs) + +### Prefilled info alert + +A prefill info alert tells users that some information on a form has been prefilled. + +```html + +

          + Note: We've prefilled some of your information from your account. + If you need to correct anything, you can select edit below. + All updates will be made only to this form. +

          +           +``` + +[View mort prefill alert examples on storybook](https://design.va.gov/storybook/?path=/docs/patterns-components-prefill-alert--docs) + + +## Content considerations +### Directions for updating uneditable information +Directions for updating information that can't be updated online vary. So directions should be updated based on the context of the form or application used. CAIA is currently working on finalizing some base language to be included, but general guidelines are: +- If it's benefits-related, include the content that has the VA benefits hotline +- If it's health-related, include the content that has the VA benefits hotline AND the content to contact your local medical center + +#### Unauthenticated intro page alert + +> [heading] Sign in with a verified account +> +> [content] Here’s how signing in with an identity-verified account helps you: +> - We can fill in some of your information for you to save you time. +> - You can save your work in progress. You’ll have {time limit} from when you start or make changes to submit your form. +> +> After you sign in, we’ll tell you if you need to verify your identity for your account. +> +> **Note:** You can sign in after you start filling out your form. But you'll lose any information you already filled in. +> +> [button] Sign in or create an account +> +> [text link] Start your form without signing in + + +Unauthenticated introduction page alert + + +#### Authenticated intro page alert +> [content] **Note:** Since you’re signed in to your account, we can prefill part of your form based on your account details. You can also save your form in progress and come back later to finish filling it out. + +Authenticated alert for introduction page + +#### Authenticated contextual alert +> [content] **Note:** We've prefilled some of your information from your account. If you need to correct anything, you can select edit below. All updates will be made only to this form. + +Authenticated alert for a form application page + +## Research findings +The Authenticated Experience Design Patterns team conducted [user research](https://github.com/department-of-veterans-affairs/va.gov-team/tree/master/products/authenticated-patterns/Design%20and%20Research/2024-07-Research%20Initiative-One-Prefill) to gather validation about this pattern. diff --git a/src/_patterns/help-users-to/navigate-a-long-list.md b/src/_patterns/help-users-to/navigate-a-long-list.md index 1d0d2693a..81d0f0029 100644 --- a/src/_patterns/help-users-to/navigate-a-long-list.md +++ b/src/_patterns/help-users-to/navigate-a-long-list.md @@ -32,7 +32,7 @@ anchors: ## Examples -{% 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-long-list.png" caption="The VA Claim Status tools uses this pattern for navigating a long list of older updates to a claim." class="x2" %} +{% include component-example.html alt="Help users to navigate a long list when scheduling a medical appointment with a provider." file="/images/patterns/help-users-to/navigate-a-long-list/choose-a-provider.png" caption="The Appointments tool uses this pattern to help users navigate a long list when scheduling a medical appointment with a provider.
          Disclaimer: These are not actual providers or health care facilities." class="x2" %} ## How to design and build @@ -76,4 +76,4 @@ For example, "Show past updates (3)" ## Accessibility considerations * Use aria-controls and aria-expanded attributes to convey the expand functionality to assistive technologies. -* The link element that acts as the trigger to reveal more options has a role of heading so it can be found in the page. Setting an aria-level is recommended. \ No newline at end of file +* The link element that acts as the trigger to reveal more options has a role of heading so it can be found in the page. Setting an aria-level is recommended. diff --git a/src/_patterns/help-users-to/recover-from-errors.md b/src/_patterns/help-users-to/recover-from-errors.md index b879b21aa..73be953ec 100644 --- a/src/_patterns/help-users-to/recover-from-errors.md +++ b/src/_patterns/help-users-to/recover-from-errors.md @@ -6,297 +6,62 @@ 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." +intro-text: "Details the structure for error messages." status: use-deployed anchors: - - anchor: Structure - - anchor: Content within the message - General - - anchor: Content within the message - Task completion - - anchor: Messages dictionary - - anchor: Style and tone - - anchor: Additional guidance + - anchor: How to structure an error message + - anchor: Contact options for VA error messages --- -*Note: The guidelines below don't apply to inline error messages in form fields (for example, "Please enter a valid Social Security number."). Inline form field error messages will be handled in a separate error guide.* +**Note:** These guidelines don’t apply to inline error messages in form fields (for example, “Enter a valid Social Security number”). -## Structure +## How to structure an error message -Every error message will have **up to** 3 parts: +### Step 1. Explain what went wrong +- In a standard alert style, explain the problem in the header. (In a slim alert style without a header, this will be in the main text). [Go to alert styles](https://design.va.gov/components/alert) +- If we caused the error, say “We’re sorry.” For example, “We’re sorry. There’s a problem with our system. We can’t access your records right now.” +- If the person doing the action caused the error, don’t say “we’re sorry.” But don’t blame the person. Use a neutral tone to describe the problem. For example, “We can’t upload this file type. Try uploading a .pdf or .doc file instead.” -{% 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%" %} +### Step 2. Explain how to fix it (recovery step) +- After you explain the error, tell the person how to fix it. Include as many recovery steps as you need to make sure the person won’t get stuck in a dead end. +- If the error is likely to resolve on its own, use “Try again” or “Check back later” as the first step. +- If the first recovery step is something the person needs to do, provide a contact option as the second recovery step. For example, “If it still doesn’t work, call us at [number].” +- Make sure the recovery steps are clear, specific, and actionable. + - **Like this:** “We can’t upload this file type. Upload a .pdf or .doc file instead.” + - **Not this:** “Invalid file type.” +- You can include a link or button in the error message, if needed to complete the recovery step. -### 1.Title +## Contact options for VA error messages +These are some of the most common contact options we provide in error messages. Some errors may need a more specific contact option. -* Bold title giving the user a quick idea of what’s wrong (or, for informational alerts, the key message the user needs to know). +You can add conditional statements before these recovery steps as needed. For example: +- If you need more help, … +- If it still doesn’t work, … +- If you have questions about your VA benefits, … -### 2. Description +**Note:** When you create a new error message with a contact option, you’ll need to coordinate with the Veteran Support team. Tell that team what triggers the error, what the recovery steps are, and how contact center staff can help people troubleshoot or resolve the problem. If you’re launching a new product, you can include this information in the product guide. Otherwise, you can contact the Veteran Support team via this Slack channel: vsp-contact-center-support. -- Apology (if the error is coming from a problem on our end). -- Succinct description of the issue, cause, and any relevant details. -- Call to action telling the user what to do next (if applicable). -- Next-step call to action telling the user what to do if the first call to action fails to resolve the issue (if applicable). +**Problem:** The person needs technical help navigating VA.gov or using an online tool or form +- **Recovery step:** Call MyVA411 +- **Text to use:** Call us at 800-698-2411 (TTY: 711). We’re here 24/7. -### 3. Button or Link +**Problem:** The person needs help filling out a benefit application or has questions about VA benefits +- **Recovery step:** Call benefits hotline +- **Text to use:** Call us at 800-827-1000 (TTY: 711). We’re here Monday through Friday, 8:00 a.m. to 9:00 p.m. ET. -* Actionable next-step for user (if applicable). +**Problem:** The person needs help filling out an education benefits application or has questions about VA education benefits +- **Recovery step:** Call the GI Bill hotline +- **Text to use:** Call us at 888-442-4551 (TTY: 711). We’re here Monday through Friday, 8:00 a.m. to 7:00 p.m. ET. -## Content within the message - General +**Problem:** The person needs help filling out a health benefits application or has questions about VA health care benefits +- **Recovery step:** Call health benefits hotline +- **Text to use:** Call us at 877-222-8387 (TTY: 711). We’re here Monday through Friday, 8:00 a.m. to 8:00 p.m. ET. -To create an effective error message, ask yourself these 4 questions: +**Problem:** The person needs to contact their health care provider or talk to someone at a VA medical center +- **Recovery step:** Call VA health facility +- **Text to use:** Contact your VA health facility. + [Find your VA health facility](https://www.va.gov/find-locations/?page=1&facilityType=health) -### 1. What’s the error/issue? - -The answer will inform the details of the issue and cause. - -### 2. What’s the source of the error/issue? - -The answer will determine how the error/issue needs to be framed, and whether an apology is needed. - -Consider if the issue is caused by: - -**A. The user's action** - -**B. An authorization issue.** If so, consider whether the issue is due to: -- VA.gov's inability to find user's records in our system -- The user's records showing user can't use benefit/service (ie, user isn't a VA patient, user isn't enrolled in benefit/service, user isn't eligible for benefit/service) -- Something else - -**C. A system or network access issue.** If so, consider whether the issue: - -- Affects the entire site or just one page/application/component/user task -- Is scheduled/expected or unexpected -- Is the result of an issue of VA.gov, a separate site/app (such as DS Logon), or Internet network connection - -### 3. What does the user need to know to resolve the error/issue? - -The answer will inform the call to action telling the user what to do next, as well as any relevant details. - -For an error caused by or due to: - -- **User action.** Offer the user clear guidance on how to resolve the error (ie, "Please make sure your file is a .pdf format"). -- **Authorization issue.** If the issue is due to VA.gov inability to find user's records in our system, direct the user to try again or call the VA.gov help desk if they think their records should be available. -- **User's records showing the user can't use benefit/service.** Offer a path forward: - - **User not eligible for benefit:** Direct to relevant eligibility information - - **User not enrolled in benefit:** Direct to relevant eligibility information and application page. - - **User not a VA patient:** Direct to facility locator to find contact information to call their VA facility. -- **System or network access issue.** The error message should include timing for when the user should try again. This can be specific timing (eg, in an hour, tomorrow, etc.) if an estimate is available or more general timing (eg, soon, later) if an estimate isn't available. - -### 4. If the resolution fails, what’s the next step? - -The answer will inform whether or not to include a “next-step call to action” to help guide the user further should the first call to action fail to resolve the issue. This may be language directing the user to call the VA.gov help desk or other VA resources, and will be determined on an issue-by-issue basis. See [Next-step calls to action](#next-step) below for more information and guidance. - -## Content within the message - Task completion - -Below are examples of each type of [Alert]({{ site.baseurl }}/components/alert) style for task completion. - -### Success alerts - -Create a brief title documenting the task that was successfully completed, followed by a brief description of the success. - -#### Saved - -{% 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 - -Include exactly what failed in the title, followed by a brief apology, reiteration of the failure reframed in the VA.gov perspective, and prompt to try again. - -#### Your form didn't save - -{% 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/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 - -To create an effective informational message or warning, ask yourself these 2 questions: - -### 1. What's the key information the user needs to know? - -This information should be presented as succinctly as possible in the title and then reiterated in the description with any additional relevant details. - -#### Informational example - -{% 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/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? - -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/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/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 - -The messages dictionary holds the title, content, component, and state for each scenario of message on the site. - -View the messages dictionary - -## Style and tone - -### Clear and direct - -Tell the user what’s happened/happening, how it will impact them, and how they can resolve it. - -### Humble, helpful, and non-alarming - -
          -
          -

          Use language that...

          -
          - -- Accepts ownership (or shared ownership) of the error *(ie, “We’re sorry. We can’t find your records in our system.”)* -- Instills confidence in the user *(ie, “We’re working to fix the problem.”)* -- Offers steady, helpful guidance toward resolution *(ie, “Please make sure the file you’re uploading is a .pdf or .doc file and try again.”)* - -
          -
          -
          -

          Avoid language that...

          -
          - -- Blames the user for the error (even if error is user-generated) *(ie, “You're not in our system.”)* -- Instills alarm *(ie, “Warning!”)* -- Feels overly casual or dismissive *(ie, “Oops! Incorrect file type”)* - -
          -
          -
          - -### Framed to highlight VA.gov ownership/shared ownership of the error - -Did the user’s action cause the error? - -**If yes:** Avoid language that feels alarming or blame-oriented and re-frame error as being a shared one, while guiding user to correct the error. - -| Situation | Sample error message | -| ----- | ----- | -| File upload fails because user tried to upload an unacceptable file type. | **We couldn't upload your file** We weren’t able to upload your file. Please make sure the file you’re uploading is a .pdf or .doc file and try again. [button] Upload file again | - -**If no:** Accept responsibility for the error and offer user brief, but clear, details and guidance to resolution. - -| Situation | Sample error message | -| ----- | ----- | -| Application fails to go through due to server issues. | **Please save this application and try again** 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. [button] Save your application | - -### Conversational and plain language - -First person/second person with a personal/helpful tone. Example: - -
          -
          -

          This...

          -
          - -- These records are unavailable. The help desk may be able to help locate them... - -
          -
          -
          -

          Becomes something like this

          -
          - -- We can’t find your records. You can call the VA.gov help desk...We're here Monday through Friday... - -
          -
          -
          - -Plain, simple words (ie, avoid jargon and multisyllabic words wherever possible). Examples: - -
          -
          -

          This...

          -
          - -- If you need immediate assistance... -- The system is currently unavailable... - -
          -
          -
          -

          Becomes something like this

          -
          - -- If you need help right now... -- VA.gov isn't working right now...or VA.gov is down at the moment - -
          -
          -
          - -When the instructions are conditional, lead with the conditional phrase to make it clear who the instructions are for. Examples: - -
          -
          -

          This...

          -
          - -- Please call us if it still doesn’t work. -- You can’t use this tool if you’re not a VA patient. - -
          -
          -
          -

          Becomes something like this

          -
          - -- If it still doesn’t work, please call us. -- If you’re not a VA patient, you can’t use this tool. - -
          -
          -
          - -## Additional guidance - -### Error state and message intent -Focusing in on the intent of the error message can help to further flesh out the nuances of tone and description content. - -| Error state | When to use | Tone | Goals | Example | -| ----- | ----- | ----- | ----- | ----- | -| **Informational** | To surface system-related feedback not initiated by the user (e.g. status updates). or, To provide information that helps set the user's expectations for their experience (e.g. SiP available). | Clear and direct, Humble, Empathetic, Helpful | Succinctly convey information Explain how (and for how long) user may be impacted Offer guidance toward resolution (if needed) | **VA.gov will be down for maintenance soon**
          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. | -| **Success** | As a confirmation that a user-initiated action was completed successfully. | Positive, direct, and definitive | Quickly and clearly convey user's success | **File uploaded**
          We've uploaded your file. Thank you. | -| **Warning** | An action was unsuccessful, but the user can still proceed. or, some parts of the user’s experience may be limited that normally wouldn’t be (e.g. system is down and records are accessible but outdated). | Clear that there may be a problem, while being un-alarming and focused on reason and resolution | Help user understand the issue and resolve it as needed | **Some information may not be current**
          We're sorry. We're having issues with our server. We're working to fix it, but it may take us a while. You can still use [APPLICATION/PAGE NAME], but you may not see all of your updated information. If you're having trouble, please try again later. | -| **Error** | A user action was not completed and must be resolved to proceed. | Clear that's something's wrong that will block the user from moving forward, while being un-alarming and focused on reason and resolution | Help user understand the issue and resolve it | **We've run into a problem**
          We're sorry. It looks like your latest action didn't go through on the site because there's a problem with the Internet connection. We can't take you to the next step until this is complete. Please check to make sure you're connected to the Internet and try again. | -| **Actions (single button)** | The user must take an action to proceed with the task indicated by the message | Enticing to help prompt user to take action, while being clear about the action needed | Get user to take a specific action | **Still want to apply for VA health care benefits?**
          You started an application for health care benefits on [DATE], but you didn't submit it. You can open the application and finish applying at any time. [button] Open your application | -| **Actions (binary button)** | The user must choose between two actions to proceed with a task, or to confirm an important action. | Clear and direct about how each of the choices will impact the user | Help user make an informed choice of action to take | **Are you sure you want to start this application over?**
          If you start over, you'll lose all the information you've filled in so far. [button 1] Start over [button 2] Continue your application | - -### Messaging categories - -The [Messaging Dictionary]({{site.baseurl}}/content-style-guide/error-messages) can help offer specific messages to use and/or examples to inform new message creation. We’ll continue to expand the dictionary, so check back often for new messages. - -| Error state | When to use | Link to dictionary of messages | -| ----- | ----- | ----- | -| **System messaging** | Alerts the user of important system-related issues or status. It’s initiated by the system and it’s not a result of the user’s actions. | [See system message examples]({{site.baseurl}}/content-style-guide/error-messages/system) | -| **Engagement messaging** | Alerts the user of important system-related issues or status. It’s initiated by the system and it’s not a result of the user’s actions. | [See engagement message examples]({{site.baseurl}}/content-style-guide/error-messages/engagement) | -| **Access messaging** | Appears when the user tries to access an item that’s not available to them. It may be because the record has been deleted, the user doesn’t have access, etc. etc. | [See access message examples]({{site.baseurl}}/content-style-guide/error-messages/access) | -| **Feedback messaging** | 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. | [See feedback message examples]({{site.baseurl}}/content-style-guide/error-messages/feedback) | - -### Next-step calls to action - -Some errors may not be resolved based on initial instructions to user (ie, "Try again later"). In these cases, a next-step call to action (ie, "Call the VA.gov help desk") may be necessary. This will be decided on a case-by-case basis, but below are some initial guidelines for determining the appropriate next-step call to action. - -| Next-step call to action | When to use | Standard language to use | Potential condition variations | -| ----- | ----- | ----- | ----- | -| **Call the VA.gov help desk** | User can’t resolve an error that is directly related to the website (specifics TBD) | Please call the VA.gov help desk at 800-698-2411 (TTY: 711). We’re here 24/7. | If you need more help, please call... If it still doesn't work, please call... | -| **Get more information about/help with your VA benefits** | User may not be able to resolve error, but next step would involve talking to someone at VA about benefits | If you need more help, call us at 800-827-1000. Or, contact a VA regional benefit office near you. (button) [Find a VA regional benefit office](https://www.vets.gov/facilities/) | If you have questions about your benefits... | -| **Get help filing a disability claim** | User needs more help filing a disability claim | If you need more help with your claim, you may want to work with a trained professional. (button) [Get help with your claim](https://www.vets.gov/disability-benefits/apply/help/index.html) | | -| **Contact the Veterans Health Administration toll-free hotline** | User needs help filling out a health care benefits application | If you need more help filling out your application, call our toll-free hotline at 877-222-VETS (877-222-8387). We’re here Monday–Friday, 8:00 a.m. to 8:00 p.m. ET. You can also get help from a trained professional called an accredited representative. Or, find your state’s Veterans agency. | (button 1) [Request a representative](https://www.ebenefits.va.gov/ebenefits/about/feature?feature=request-vso-representative)
          (button 2) [Find a Veterans agency](https://www.va.gov/statedva.htm)
          If you have questions about your application,... | -| **Contact your local VA medical center** | User needs to contact their doctor or speak to someone at a VA medical center for more information | If you need more help with this, call your healthcare provider or your local VA medical center or clinic. button) [Find a VA health facility](https://www.vets.gov/facilities/) | If you have questions, call your doctor or a VA medical center or clinic near you... | -| **Get answers to questions about education benefits** | User needs more help/answers to questions about their education benefits | If you need more help, call us at 888-GI-Bill-1 (888-442-4551). We’re here Monday–Friday, 8:00 a.m. to 7:00 p.m. ET. | If you'd like to request a paper application... | +**Problem:** The person needs help using My HealtheVet health tools +- **Recovery step:** Call the My HealtheVet help desk +- **Text to use:** Call us at 877-327-0022 (TTY: 711). We’re here Monday through Friday, 8:00 a.m. to 8:00 p.m. ET. diff --git a/src/_patterns/help-users-to/sign-in.md b/src/_patterns/help-users-to/sign-in.md new file mode 100644 index 000000000..d07068e8d --- /dev/null +++ b/src/_patterns/help-users-to/sign-in.md @@ -0,0 +1,62 @@ +--- +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 to implement, depending on whether your product requires everyone to sign in. These will only show to people who are not yet signed in. + +2. Implement all 3 of the yellow verification alerts. These will only show to people who signed in with an unverified account, depending on which account type they're using (Login.gov, ID.me, or My HealtheVet). + +**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. + +{% include content/sign-in-alert-examples.md %} + +**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) diff --git a/src/_patterns/help-users-to/stay-informed-of-their-application-status.md b/src/_patterns/help-users-to/stay-informed-of-their-application-status.md index 085aeea96..d47eeae85 100644 --- a/src/_patterns/help-users-to/stay-informed-of-their-application-status.md +++ b/src/_patterns/help-users-to/stay-informed-of-their-application-status.md @@ -1,49 +1,120 @@ --- layout: pattern -title: Stay informed of their application status +title: Stay informed of their form submission status permalink: /patterns/help-users-to/stay-informed-of-their-application-status sub-section: help-users-to -intro-text: "When we need to keep the user informed of their application status, there is currently no \"one size fits all\" solution. To provide clarity, this page shows examples of patterns that exist on VA.gov today." +intro-text: "Follow this pattern to notify people when their online form submission is in progress, when we receive their submitted form, and when a system error has caused the submission to fail. These are required notification touch points." status: use-with-caution-candidate research-title: Help users to stay informed of app status anchors: - anchor: Usage - anchor: Examples - anchor: How to design and build + - anchor: Examples in production --- -Review examples of patterns that exist today that help users to stay informed of their application status. - ## Usage ### When to use this pattern -**When users need to stay informed of their application status.** After users have submitted an application, keep them informed of their application status. +* **Any online form that takes data from someone and submits that data to a back-end system.** This pattern is widely applicable to any online form that accepts someone's data and submits that data, synchronously or asynchronously, to the system of record. We're required to notify that person at critical touch points in the submission process. ## Examples -### MyVA +### Email notifications + +{% include component-example.html alt="Screen shots of 5 email templates." file="/images/patterns/help-users-to/stay-informed-of-their-application-status/email-templates.png" caption="Five template examples for email notification touch points sent via VA Notify." class="x2" %} + +### Form submission status in My VA + +{% include component-example.html alt="Screen shots of 3 My VA status cards." file="/images/patterns/help-users-to/stay-informed-of-their-application-status/myva-status-cards.png" caption="Three Card component variations used to show the status of someone's submission in My VA for Benefits applications." reverse="true" %} + +## How to design and build + +### Sending email notifications + +#### For synchronous submissions + +If there’s no lag time between when someone submits a form and when we receive it—the form was received in the system of record in time for us to show a success message on the confirmation page—then we consider it a synchronous form. In this case, you need to implement only one email notification: + +1. **Received**: The notification when we've received a submitted form in the system of record. This means the form is ready for processing. **Only send this status notification when we have confirmation that the request has reached the system of record.** + +**Note:** The reason you don't need "Action needed" notifications for synchronous submissions is that you show the person the error message in the form itself. If form submission can fail after the person gets a success message on the form confirmation page, your form has asynchronous submissions and you need to implement 3 email notifications. + +Submit a [VA Notify intake ticket](https://github.com/department-of-Veterans-affairs/va.gov-team/issues/new?assignees=christy-tongty%2C+mjones-oddball%2C+GitSamJennings&labels=vanotify-intake&template=VANotify-Business-Intake.md&title=Business+intake+form+for+%5BBusiness+or+team%5D) to start the process of activating email notifications for your application. + +#### For asynchronous submissions + +If there's a lag time between when someone submits the form and when VA receives it in the system of record, you must implement these 3 email notifications: + +1. **Submission in progress**: The notification we send immediately after someone selects the **Submit** button on an online form. This means that the form submission has successfully started, but it has not yet reached the system of record. During this time, data submitted by the person may travel through several systems. +2. **Received**: The notification we send when we've received a submitted form in the system of record. This means the form is ready for processing. **Only send this status notification when we have confirmation that the request has reached the system of record.** +3. **Action needed:** The error notification we send if a form submission fails to reach the system of record. This means we need the person to resubmit or take another action before we can process their form. This notification must include instructions for the person to recover from the error. There are different templates available based on the remediation steps specific to the form. + +Submit a [VA Notify intake ticket](https://github.com/department-of-Veterans-affairs/va.gov-team/issues/new?assignees=christy-tongty%2C+mjones-oddball%2C+GitSamJennings&labels=vanotify-intake&template=VANotify-Business-Intake.md&title=Business+intake+form+for+%5BBusiness+or+team%5D) to start the process of activating email notifications for your application. + +#### Protecting PII & PHI in notifications -{% include component-example.html alt="An example of a claims and appeals status card in My VA." file="/images/patterns/help-users-to/stay-informed-of-their-application-status/status-in-myva.png" caption="A status Card component used in MyVA to show the status of a claim with a call-to-action to retrieve details on that claim." reverse="true" class="x2" %} +* **Do not send personally identifiable information (PII) or protected health information (PHI) in notifications.** It's imperative that notifications do not include any PII or PHI. +* **Hide filenames.** File names for evidence and other uploads of documents to the VA can often include personal information. So we hide all filenames in notifications. To do this: + * Replace all but the first 3 and last 2 characters (numbers or letters) of the filename with the "X" character. + * Show the MIME type of the file (like ".png", ".pdf", etc.) -### 10-10ez application status on health care intro page +### Showing form submission status on the form confirmation page -{% include component-example.html alt="An example of the 10-10ez health care application status on intro page." file="/images/patterns/help-users-to/stay-informed-of-their-application-status/10-10ez-status-on-intro-page.png" caption="The 10-10ez Health Care application provides status to users if and when they return to the introduction page." class="x2" %} +#### For synchronous submissions -### Claim status +If there's no lag time between when someone submits the form and when VA receives it in the system of record, do these 2 things on your form confirmation page: +- Show a success message confirming that the submission was successful and we've received the form, like "You've submitted your form" +- In the **What to expect** section, tell the person about the next notification we'll send (in this case, that should be an email confirming we've received their form) -{% include component-example.html alt="An example of the track your claims page." file="/images/patterns/help-users-to/stay-informed-of-their-application-status/track-your-claims.png" caption="The Claim status page uses Cards that provide details on the current step of the process." class="x2" %} +#### For asynchronous submissions -### Decision letter +If there's a lag time between when someone submits the form and when VA receives it in the system of record, do these 2 things on the form confirmation page: +- Show a success message confirming only that the submission is in progress, like "Your form submission is in progress" — and explain that we'll send an email to confirm when we've received the form and an estimate for how long that will take +- In the **What to expect** section, tell the person about the next notifications we'll send (in this case, an email confirming the submission is in progress and then a second email confirming when we've received their form) -{% include component-example.html alt="An example of a claim status card that shows the ability to download a decision letter" file="/images/patterns/help-users-to/stay-informed-of-their-application-status/decision-letter-status-card.png" caption="This claim Card component provides a status of the claim and indicates that a decision letter is available for download." class="x2" %} +### Showing form submission status in My VA -### Certificate of eligibility +Form submissions on VA.gov or in the mobile app must show the submission status in My VA for people who are authenticated. These statuses appear in the **Benefit applications and forms** section of My VA. This section currently gets statuses from the [Lighthouse Benefits Intake API](https://developer.va.gov/explore/api/benefits-intake) polling mechanism for submissions processed asynchronously. -{% include component-example.html alt="An example of the Certificate of eligibility status page." file="/images/patterns/help-users-to/stay-informed-of-their-application-status/COE-automatic-download-page.png" caption="The Certificate of eligibility uses an Alert component to show status." class="x2" %} +Some forms also show a "received" status in the **Claims and appeals** section of My VA. If your form appears as a claim, decision review, or appeal in the claim status tool, work with the team that manages that tool to determine how and where you should show form submission status in My VA. + +#### How to handle forms submitted within the process of another form (sub-forms) + +For sub-forms such as the Authorization to Disclose Information to the Department of Veterans Affairs (21-4142), submitted within the process of completing an Application for Disability Compensation and Related Compensation Benefits (21-526EZ) or Decision Review Request: Supplemental Claim (20-0995), the status of the sub-forms should be communicated independently from the status of the main form. In other words, each sub-form would send a separate email notification and would have a separate status card shown in My VA, independent from the notifications and cards of the main form. + +#### How to show status for uploaded documents + +Indicate to the user on the status card shown in My VA the count of uploaded documents. For example, "You uploaded 22 documents. We'll email you if we can't successfully deliver any of them." + +> NOTE: The exact language and how to convey this to users is currently being designed and is subject to change. + +In addition, documents uploaded in the claims status tool do not need to be reflected in My VA. + +### Showing form processing status after we receive it in the system of record + +Some forms show processing status after point of receipt in the claim status tool. In the future, all forms should work toward allowing people to track the processing status through to the point of a VA decision or other ultimate end point. + +### How this pattern works + +Communicating form submission status has 3 critical phases that all teams must account for in their online forms: + +1. **Status notification via email or text** +2. **Status notification in the user interface of VA.gov and the flagship mobile app** +3. **A clear next step in the event of an error** + +#### How to provide a clear next step in the event of an error + +Every time a form submission error happens, you must notify the person about that error and provide a recovery step. At the very least, tell people to contact the Call Center. ### Components used in this pattern -* [Alert]({site.baseurl}/components/alert) -* [Card]({site.baseurl}/components/card) -* [Process list]({site.baseurl}/components/process-list) \ No newline at end of file +* [Alert]({{site.baseurl}}/components/alert) +* [Card]({{site.baseurl}}/components/card) + +### Page templates available for this pattern + +* [Email templates are available in VA Notify](https://staging.notifications.va.gov/). You'll need a VA Notify account to access the sample templates. Select a service. If you're not assigned to a service contact #va-notify-public. Select **Add template**. Then select **Sample templates**. +* The sample email templates include customizable content you'll need to fill in for your form. Try to use as much of the template content as possible and only adjust where needed. If you have questions or need help adjusting the templates for your form, you can contact #sitewide-content-accessibility-ia +* Email templates must be reviewed by a VA Privacy Officer in the appropriate portfolio (VBA or VHA). diff --git a/src/_templates/forms/intro.md b/src/_templates/forms/intro.md index d81d7d779..b8f6b9aba 100644 --- a/src/_templates/forms/intro.md +++ b/src/_templates/forms/intro.md @@ -22,25 +22,25 @@ anchors: The form intro page does 3 things: -- Sets clear expectations about the process of using this form +- Sets clear expectations about the process of using the form - Helps the person prepare to fill out the form by gathering required information and documents before they start - Provides ways to get help and to find more information about the related benefit -Since people can navigate directly to this page from outside VA.gov, this intro page should include basic information they need to understand if this is the correct form. +Since people can navigate directly to this page from outside VA.gov, the intro page should include basic information the person needs to understand if this is the correct form. ## Variations -There are 2 versions of the Introduction page: +There are 2 versions of the intro page: - **Application**: Use this variation if the form is an application for a benefit or service. - **Non-application**: In most cases, use this variation if the form is **not** an application for a benefit or service. For example, use this for [supporting forms](https://www.va.gov/supporting-forms-for-claims/) that people need to submit along with their application and for claims for reimbursement under VA health care programs. -Both variations mostly follow the same structure. The only difference is the section after the intro: +Both variations mostly follow the same structure. The only difference is the section after the intro paragraph: - Applications use a process list - Non-applications use a "What to know before you fill out this form" section -**Note:** Some straightforward applications may not require a process list. It's OK to use the same structure as non-application forms for those. +**Note:** Some straightforward applications may not require a process list. It's OK to use the same structure as non-application forms for those. ## Structure @@ -48,9 +48,9 @@ Both variations mostly follow the same structure. The only difference is the sec **Plain language title** -For the H1, use a plain language CTA that starts with an action verb, like "Apply for VA health care" or "File for disability compensation" +For the H1, use a plain language call to action that starts with an action verb, like "Apply for VA health care" or "File for disability compensation." -Aim for 52 characters or less, but exceptions to character length are OK if a slightly longer description adds clarity (like "Authorize the release of non-VA medical information to VA") +Aim for 52 characters or fewer. Exceptions to character length are OK if a slightly longer description adds clarity (like "Authorize the release of non-VA medical information to VA") **Subtitle** @@ -59,27 +59,27 @@ In general, use the full, official name of the form in title case, followed by t Example: [Title] Request personal records -[Subtitle] Freedom of Information Act (FOIA) or Privacy Act (PA) Request (VA Form 20-10206) +[Subtitle] Freedom of Information Act (FOIA) or Privacy Act (PA) Request (VA Form 20-10206) -Alternate example: +Alternate example: -[Title] Request a Higher-Level Review +[Title] Request a Higher-Level Review [Subtitle] (VA Form 20-0996) **Intro paragraph** -- Add a brief intro describing when to use this form (1 to 3 sentences, no more than 25 words per sentence). +- Add a brief intro describing when to use this form. This could be 1 to 3 sentences, with no more than 25 words per sentence. - Try reusing the "When to use" blurb from the form detail page in Find a Form. For example, using the Veterans Pension blurb from the form detail page, this intro could be "Use this form if you’re a wartime Veteran and want to file a pension claim." **Note:** Guidance on this part of the template is evolving. Check back for updates. ## Process list (for applications) -- Use a [process list]({{ site.baseurl }}/components/process-list) to describe the steps to apply. +- Use a [process list]({{ site.baseurl }}/components/process-list) to describe the steps to apply - Use this H2 above the list: "Follow these steps to get started" - Use the numbered process steps listed here as H3s - Add tailored need-to-know information about the specific form under each step, but aim to keep this section as brief as possible -- Consider how the information in this process list aligns with information on the related VA.gov pages for this benefit — if you need to add or update information on those pages, talk with the **Sitewide content, accessibility, information architecture (CAIA)** team that manages all benefit pages in the Drupal CMS +- Consider how the information in this process list aligns with information on the related VA.gov pages for this benefit—if you need to add or update information on those pages, talk with the Sitewide content, accessibility, information architecture (CAIA) team that manages all benefit pages in the Drupal CMS **1. Check your eligibility** @@ -126,11 +126,12 @@ Example: ## Sign-in widget, prefill alert, or "continue saved form" alert Dynamically display one of these options. Sign-in widgets and prefill alerts should appear directly under the process list or "what to know" section. The "continue saved form" alert should appear above the process list or "what to know" section, because the person has already gotten that information when they started the form in a past session. + **Note:** The sign-in and prefill variations assume that the form prefills information for people who are signed in to VA.gov. ### If the person is already signed in -**If the person has no saved forms,** use the standard [prefill alert](https://design.va.gov/components/form/prefill) component. +**If the person has no saved forms,** use the standard [prefill alert](/patterns/help-users-to/know-when-their-information-is-prefilled#signed-in-prefill-alert) component. **If the person has saved forms,** use the "Continue your form" alert. @@ -145,7 +146,7 @@ Dynamically display one of these options. Sign-in widgets and prefill alerts sho Choose the correct sign-in widget for your form. -**Note:** The [alert component page]({{ site.baseurl }}/components/alert) has examples of sign-in widget alerts, but we're currently updating our guidance for sign-in and verification widgets in online forms. Check back here for updates, and in the meantime reach out to the Sitewide CAIA team in our sitewide-content-accessibility-ia slack channel for support. +**Note:** The [alert component page]({{ site.baseurl }}/components/alert) has examples of sign-in widget alerts, but we're currently updating our guidance for sign-in and verification widgets in online forms. Check back here for updates, and in the meantime reach out to the Sitewide CAIA team in our sitewide-content-accessibility-ia Slack channel for support. ## OMB and Need help sections @@ -155,7 +156,7 @@ Choose the correct sign-in widget for your form. ### Need help -The [Need help component]({{ site.baseurl }}/components/form/need-help) is a footer that appears on the bottom of every page of the form. This content lets people know how to get additional help with the form or the benefits. +The [Need help component]({{ site.baseurl }}/components/form/need-help) is a footer that appears on the bottom of every page of the form. This content lets people know how to get additional help with the form or the benefits. {% include component-example.html alt="An example of a need help footer for forms pages." file="/images/templates/forms/introduction/need-help.png" caption="An example of a Need help component used on all forms pages." class="x2" %} @@ -192,11 +193,11 @@ The introduction form page for authenticated users consists of: ### Instances of this template in production -* [https://www.va.gov/disability/file-disability-claim-form-21-526ez/introduction](https://www.va.gov/disability/file-disability-claim-form-21-526ez/introduction) -* [https://www.va.gov/education/apply-for-education-benefits/application/1990/introduction](https://www.va.gov/education/apply-for-education-benefits/application/1990/introduction) -* [https://www.va.gov/burials-and-memorials/pre-need/form-10007-apply-for-eligibility/introduction](https://www.va.gov/burials-and-memorials/pre-need/form-10007-apply-for-eligibility/introduction) -* [https://www.va.gov/pension/application/527EZ/introduction](https://www.va.gov/pension/application/527EZ/introduction) -* [https://www.va.gov/health-care/apply/application/introduction](https://www.va.gov/health-care/apply/application/introduction) +* [File for disability compensation](https://www.va.gov/disability/file-disability-claim-form-21-526ez/) +* [Apply for VA Education Benefits](https://www.va.gov/education/apply-for-education-benefits/application/1990/) +* [Apply for pre-need eligibility determination](https://www.va.gov/burials-and-memorials/pre-need/form-10007-apply-for-eligibility/) +* [Apply for Veterans Pension benefits](https://www.va.gov/pension/application/527EZ/) +* [Apply for VA health care](https://www.va.gov/health-care/apply/application/) ## Examples (non-application) diff --git a/src/downloads/VALogos.zip b/src/downloads/VALogos.zip index 1c939b9e8..b43cd0df7 100644 Binary files a/src/downloads/VALogos.zip and b/src/downloads/VALogos.zip differ diff --git a/src/images/about/accessibility/focus-management/focus-indicator.png b/src/images/about/accessibility/focus-management/focus-indicator.png new file mode 100644 index 000000000..a8901d1f3 Binary files /dev/null and b/src/images/about/accessibility/focus-management/focus-indicator.png differ diff --git a/src/images/about/experimental-design.png b/src/images/about/experimental-design.png new file mode 100644 index 000000000..1a10169ca Binary files /dev/null and b/src/images/about/experimental-design.png differ diff --git a/src/images/components/alert-sign-in/optional-sign-in-verified.png b/src/images/components/alert-sign-in/optional-sign-in-verified.png new file mode 100644 index 000000000..f651e503d Binary files /dev/null and b/src/images/components/alert-sign-in/optional-sign-in-verified.png differ diff --git a/src/images/components/alert-sign-in/required-sign-in-verified.png b/src/images/components/alert-sign-in/required-sign-in-verified.png new file mode 100644 index 000000000..aa2215879 Binary files /dev/null and b/src/images/components/alert-sign-in/required-sign-in-verified.png differ diff --git a/src/images/components/alert-sign-in/sign-in-with-a-different-account.png b/src/images/components/alert-sign-in/sign-in-with-a-different-account.png new file mode 100644 index 000000000..3f04cd470 Binary files /dev/null and b/src/images/components/alert-sign-in/sign-in-with-a-different-account.png differ diff --git a/src/images/components/alert-sign-in/verify-with-idme.png b/src/images/components/alert-sign-in/verify-with-idme.png new file mode 100644 index 000000000..fd22daac6 Binary files /dev/null and b/src/images/components/alert-sign-in/verify-with-idme.png differ diff --git a/src/images/components/alert-sign-in/verify-with-logingov.png b/src/images/components/alert-sign-in/verify-with-logingov.png new file mode 100644 index 000000000..f5ba9d189 Binary files /dev/null and b/src/images/components/alert-sign-in/verify-with-logingov.png differ diff --git a/src/images/components/breadcrumbs/breadcrumbs-spacing-desktop.png b/src/images/components/breadcrumbs/breadcrumbs-spacing-desktop.png new file mode 100644 index 000000000..f104d42ef Binary files /dev/null and b/src/images/components/breadcrumbs/breadcrumbs-spacing-desktop.png differ diff --git a/src/images/components/breadcrumbs/breadcrumbs-spacing-mobile.png b/src/images/components/breadcrumbs/breadcrumbs-spacing-mobile.png new file mode 100644 index 000000000..919b9d60f Binary files /dev/null and b/src/images/components/breadcrumbs/breadcrumbs-spacing-mobile.png differ diff --git a/src/images/patterns/ask-users-for/addresses/military-base-address.png b/src/images/patterns/ask-users-for/addresses/military-base-address.png index c0bc2d162..77c2151da 100644 Binary files a/src/images/patterns/ask-users-for/addresses/military-base-address.png and b/src/images/patterns/ask-users-for/addresses/military-base-address.png differ diff --git a/src/images/patterns/ask-users-for/email-address/email-address.png b/src/images/patterns/ask-users-for/email-address/email-address.png index 51710a05c..06d5f9920 100644 Binary files a/src/images/patterns/ask-users-for/email-address/email-address.png and b/src/images/patterns/ask-users-for/email-address/email-address.png differ diff --git a/src/images/patterns/ask-users-for/gender/gender-identity-profile-what-to-know.png b/src/images/patterns/ask-users-for/gender/gender-identity-profile-what-to-know.png index 2dbd5a43e..8222602e1 100644 Binary files a/src/images/patterns/ask-users-for/gender/gender-identity-profile-what-to-know.png and b/src/images/patterns/ask-users-for/gender/gender-identity-profile-what-to-know.png differ diff --git a/src/images/patterns/ask-users-for/gender/gender-identity-profile.png b/src/images/patterns/ask-users-for/gender/gender-identity-profile.png index 924cede57..e72e9dc88 100644 Binary files a/src/images/patterns/ask-users-for/gender/gender-identity-profile.png and b/src/images/patterns/ask-users-for/gender/gender-identity-profile.png differ diff --git a/src/images/patterns/ask-users-for/multiple-responses/adding-service-period.png b/src/images/patterns/ask-users-for/multiple-responses/adding-service-period.png deleted file mode 100644 index 5058f83de..000000000 Binary files a/src/images/patterns/ask-users-for/multiple-responses/adding-service-period.png and /dev/null differ diff --git a/src/images/patterns/ask-users-for/multiple-responses/board-appeal-contact-information.png b/src/images/patterns/ask-users-for/multiple-responses/board-appeal-contact-information.png deleted file mode 100644 index 8a4ec57ea..000000000 Binary files a/src/images/patterns/ask-users-for/multiple-responses/board-appeal-contact-information.png and /dev/null differ diff --git a/src/images/patterns/ask-users-for/multiple-responses/editing-service-period.png b/src/images/patterns/ask-users-for/multiple-responses/editing-service-period.png deleted file mode 100644 index 2b1147072..000000000 Binary files a/src/images/patterns/ask-users-for/multiple-responses/editing-service-period.png and /dev/null differ diff --git a/src/images/patterns/ask-users-for/multiple-responses/optional-multipage-flow.png b/src/images/patterns/ask-users-for/multiple-responses/optional-multipage-flow.png new file mode 100644 index 000000000..ac00a670d Binary files /dev/null and b/src/images/patterns/ask-users-for/multiple-responses/optional-multipage-flow.png differ diff --git a/src/images/patterns/ask-users-for/multiple-responses/required-multipage-flow.png b/src/images/patterns/ask-users-for/multiple-responses/required-multipage-flow.png new file mode 100644 index 000000000..bc35cb208 Binary files /dev/null and b/src/images/patterns/ask-users-for/multiple-responses/required-multipage-flow.png differ diff --git a/src/images/patterns/ask-users-for/names/form-names.png b/src/images/patterns/ask-users-for/names/form-names.png index b542ba291..636db26bc 100644 Binary files a/src/images/patterns/ask-users-for/names/form-names.png and b/src/images/patterns/ask-users-for/names/form-names.png differ diff --git a/src/images/patterns/ask-users-for/phone-numbers/international-phone-number.png b/src/images/patterns/ask-users-for/phone-numbers/international-phone-number.png new file mode 100644 index 000000000..cd9f41afa Binary files /dev/null and b/src/images/patterns/ask-users-for/phone-numbers/international-phone-number.png differ diff --git a/src/images/patterns/ask-users-for/race-ethnicity-or-origin/race-ethnicity-or-origin.png b/src/images/patterns/ask-users-for/race-and-ethnicity/race-and-ethnicity.png similarity index 100% rename from src/images/patterns/ask-users-for/race-ethnicity-or-origin/race-ethnicity-or-origin.png rename to src/images/patterns/ask-users-for/race-and-ethnicity/race-and-ethnicity.png diff --git a/src/images/patterns/ask-users-for/relationship/relationship-to-veteran-other.png b/src/images/patterns/ask-users-for/relationship/relationship-to-veteran-other.png index ce90f0b32..66ae08834 100644 Binary files a/src/images/patterns/ask-users-for/relationship/relationship-to-veteran-other.png and b/src/images/patterns/ask-users-for/relationship/relationship-to-veteran-other.png differ diff --git a/src/images/patterns/ask-users-for/relationship/relationship-to-veteran.png b/src/images/patterns/ask-users-for/relationship/relationship-to-veteran.png index d3f1241c0..0b6b592ea 100644 Binary files a/src/images/patterns/ask-users-for/relationship/relationship-to-veteran.png and b/src/images/patterns/ask-users-for/relationship/relationship-to-veteran.png differ diff --git a/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page-status.png b/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page-status.png new file mode 100644 index 000000000..c8076ec72 Binary files /dev/null and b/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page-status.png differ diff --git a/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page.png b/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page.png index 3d83d0988..d3e124eba 100644 Binary files a/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page.png and b/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/confirmation-page.png differ diff --git a/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/print-confirmation-status.png b/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/print-confirmation-status.png new file mode 100644 index 000000000..119b69f1a Binary files /dev/null and b/src/images/patterns/help-users-to/keep-a-record-of-submitted-information/print-confirmation-status.png differ diff --git a/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-authenticated-alert-for-intro.png b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-authenticated-alert-for-intro.png new file mode 100644 index 000000000..2aad36788 Binary files /dev/null and b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-authenticated-alert-for-intro.png differ diff --git a/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-authenticated-alert-for-page.png b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-authenticated-alert-for-page.png new file mode 100644 index 000000000..b601ed221 Binary files /dev/null and b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-authenticated-alert-for-page.png differ diff --git a/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-unauthenticated-alert.png b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-unauthenticated-alert.png new file mode 100644 index 000000000..5f65cb951 Binary files /dev/null and b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/content-unauthenticated-alert.png differ diff --git a/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/editable-prefill-information.png b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/editable-prefill-information.png new file mode 100644 index 000000000..f529d40bc Binary files /dev/null and b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/editable-prefill-information.png differ diff --git a/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-authenticated-alert.png b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-authenticated-alert.png new file mode 100644 index 000000000..b315a6c0b Binary files /dev/null and b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-authenticated-alert.png differ diff --git a/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-unauthenticated-alert.png b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-unauthenticated-alert.png new file mode 100644 index 000000000..5f65cb951 Binary files /dev/null and b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/intro-page-unauthenticated-alert.png differ diff --git a/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/uneditable-prefill-information.png b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/uneditable-prefill-information.png new file mode 100644 index 000000000..ce886899f Binary files /dev/null and b/src/images/patterns/help-users-to/know-when-their-information-is-prefilled/uneditable-prefill-information.png differ diff --git a/src/images/patterns/help-users-to/navigate-a-long-list/choose-a-provider.png b/src/images/patterns/help-users-to/navigate-a-long-list/choose-a-provider.png new file mode 100644 index 000000000..1fa4910c3 Binary files /dev/null and b/src/images/patterns/help-users-to/navigate-a-long-list/choose-a-provider.png differ diff --git a/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-action-needed.png b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-action-needed.png new file mode 100644 index 000000000..2d082ef2c Binary files /dev/null and b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-action-needed.png differ diff --git a/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-received.png b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-received.png new file mode 100644 index 000000000..39883e40e Binary files /dev/null and b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-received.png differ diff --git a/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-resubmit-alt.png b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-resubmit-alt.png new file mode 100644 index 000000000..b7769c6b5 Binary files /dev/null and b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-resubmit-alt.png differ diff --git a/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-resubmit.png b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-resubmit.png new file mode 100644 index 000000000..4db9dec00 Binary files /dev/null and b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-resubmit.png differ diff --git a/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-submission-in-progress.png b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-submission-in-progress.png new file mode 100644 index 000000000..325fb7734 Binary files /dev/null and b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-submission-in-progress.png differ diff --git a/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-templates.png b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-templates.png new file mode 100644 index 000000000..2e5d33bae Binary files /dev/null and b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/email-templates.png differ diff --git a/src/images/patterns/help-users-to/stay-informed-of-their-application-status/myva-status-cards.png b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/myva-status-cards.png new file mode 100644 index 000000000..57d61bf25 Binary files /dev/null and b/src/images/patterns/help-users-to/stay-informed-of-their-application-status/myva-status-cards.png differ diff --git a/src/images/readme/pr-branch-from-fork.png b/src/images/readme/pr-branch-from-fork.png new file mode 100644 index 000000000..f40467a4f Binary files /dev/null and b/src/images/readme/pr-branch-from-fork.png differ diff --git a/src/images/readme/pr-checks-preview-details.png b/src/images/readme/pr-checks-preview-details.png new file mode 100644 index 000000000..fc807fa9e Binary files /dev/null and b/src/images/readme/pr-checks-preview-details.png differ diff --git a/src/images/readme/pr-view-deployment-button.png b/src/images/readme/pr-view-deployment-button.png new file mode 100644 index 000000000..c213672d3 Binary files /dev/null and b/src/images/readme/pr-view-deployment-button.png differ diff --git a/src/images/readme/re-run-workflow-button.png b/src/images/readme/re-run-workflow-button.png new file mode 100644 index 000000000..fdece0852 Binary files /dev/null and b/src/images/readme/re-run-workflow-button.png differ diff --git a/src/images/templates/email/email-template.png b/src/images/templates/email/email-template.png index 718f5c71f..ee724588f 100644 Binary files a/src/images/templates/email/email-template.png and b/src/images/templates/email/email-template.png differ diff --git a/src/img/sprite.svg b/src/img/sprite.svg index d01077f5f..7973e696d 100644 --- a/src/img/sprite.svg +++ b/src/img/sprite.svg @@ -1,3 +1,5 @@ - + + + \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index b7cf5169b..117f96e00 100644 --- a/yarn.lock +++ b/yarn.lock @@ -9,34 +9,25 @@ dependencies: regenerator-runtime "^0.14.0" -"@department-of-veterans-affairs/component-library@^44.0.0": - version "44.0.0" - resolved "https://registry.yarnpkg.com/@department-of-veterans-affairs/component-library/-/component-library-44.0.0.tgz#298610380a275034c8d47eae2c0ef0d2b8525c07" - integrity sha512-KHcHgWK8aWIjkMe09eeBwN54R00aZZiqYJ+xR2j9PTGkPkjR5rTqUn3PrnUoI3UdExE5tgMyYZWewJITgHcAQw== +"@department-of-veterans-affairs/component-library@^47.1.0": + version "47.1.0" + resolved "https://registry.yarnpkg.com/@department-of-veterans-affairs/component-library/-/component-library-47.1.0.tgz#2162d343b38614057632af42e444c658bf68d908" + integrity sha512-ZKTDY8kiQ3F3i3hL3OLQ+fyv9B4Xi1qQkUnBegu8TC6KjXDNed3PxAuVO+5iJXYi604cgBW72gXYZYbi63ITFQ== dependencies: "@department-of-veterans-affairs/react-components" "28.1.0" - "@department-of-veterans-affairs/web-components" "12.0.0" + "@department-of-veterans-affairs/web-components" "15.1.0" i18next "^21.6.14" i18next-browser-languagedetector "^6.1.4" react-focus-on "^3.5.1" react-transition-group "^1.0.0" -"@department-of-veterans-affairs/css-library@^0.8.1": - version "0.8.3" - resolved "https://registry.yarnpkg.com/@department-of-veterans-affairs/css-library/-/css-library-0.8.3.tgz#b5bf4fe1cb0ac5193ae8182b0e14ef2da8b4645a" - integrity sha512-nQRTmjZKbFFHsBiW9kK6QlWKi9KJcPnDPvWLt2i6fJu8icNoET19n4TE5JPJPdR63zzMtgJUfYaAXd81HMB/uA== - dependencies: - "@divriots/style-dictionary-to-figma" "^0.4.0" - "@uswds/uswds" "^3.7.1" - rimraf "^5.0.5" - -"@department-of-veterans-affairs/css-library@^0.8.5": - version "0.8.5" - resolved "https://registry.npmjs.org/@department-of-veterans-affairs/css-library/-/css-library-0.8.5.tgz#610f1f4304e0636a190ad9fd79e8ba3fff80207c" - integrity sha512-kld40XYUlEPk2qcwiBFSSmBLdfdG1vKOs4rPpq9EgF8iDLlkXN2iSp8cgsmryc7hgKCZe800jRGqEnXOcFno4A== +"@department-of-veterans-affairs/css-library@^0.12.2": + version "0.12.2" + resolved "https://registry.yarnpkg.com/@department-of-veterans-affairs/css-library/-/css-library-0.12.2.tgz#da2554d1d71c1927b7462fa70d9cc8b482f8206e" + integrity sha512-nkrgeEGPWLEuoAfCdfFFPNIWIc9BDnxXZZ3HxZrKjL3yIAgNZYB+gm02JbYUHNXZZfXdfHxseaBY4M5C+Z3Iqg== dependencies: "@divriots/style-dictionary-to-figma" "^0.4.0" - "@uswds/uswds" "^3.7.1" + "@uswds/uswds" "^3.8.1" rimraf "^5.0.5" "@department-of-veterans-affairs/formation@^11.0.12": @@ -60,13 +51,13 @@ react-transition-group "1" recast "^0.14.4" -"@department-of-veterans-affairs/web-components@12.0.0": - version "12.0.0" - resolved "https://registry.yarnpkg.com/@department-of-veterans-affairs/web-components/-/web-components-12.0.0.tgz#46595e952fa0a997e835f913c0bceefb02d7d2db" - integrity sha512-rbOTVeOuu1jQ0qrpeMfNzKvWERH8oNzK8NSzkGs6hgxuLMjLU89OQhSU/TvRJKq34fnn7xGgkaEMiTn3ekoxDg== +"@department-of-veterans-affairs/web-components@15.1.0": + version "15.1.0" + resolved "https://registry.yarnpkg.com/@department-of-veterans-affairs/web-components/-/web-components-15.1.0.tgz#ec0a6952a591f9ed0a7d3ddea2211047a3471d71" + integrity sha512-/kUPjVJb+Ira1rekD3suBNDJqYFzW1rsF5xT6d2NLe58kY6JnbMV+/w9KH1fG1uCIaXV5RaKVK0bDjSjMhRxAw== dependencies: - "@department-of-veterans-affairs/css-library" "^0.8.1" - "@stencil/core" "^2.19.2" + "@department-of-veterans-affairs/css-library" "^0.12.2" + "@stencil/core" "4.20.0" aria-hidden "^1.1.3" body-scroll-lock "^4.0.0-beta.0" chromatic "^11.0.4" @@ -100,17 +91,16 @@ resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33" integrity sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg== -"@stencil/core@^2.19.2": - version "2.22.3" - resolved "https://registry.yarnpkg.com/@stencil/core/-/core-2.22.3.tgz#83987e20bba855c450f6d6780e3a20192603f13f" - integrity sha512-kmVA0M/HojwsfkeHsifvHVIYe4l5tin7J5+DLgtl8h6WWfiMClND5K3ifCXXI2ETDNKiEk21p6jql3Fx9o2rng== +"@stencil/core@4.20.0": + version "4.20.0" + resolved "https://registry.yarnpkg.com/@stencil/core/-/core-4.20.0.tgz#221f2b36ab999891560449b02d6915862c435f49" + integrity sha512-WPrTHFngvN081RY+dJPneKQLwnOFD60OMCOQGmmSHfCW0f4ujPMzzhwWU1gcSwXPWXz5O+8cBiiCaxAbJU7kAg== -"@uswds/uswds@^3.7.1": - version "3.8.1" - resolved "https://registry.yarnpkg.com/@uswds/uswds/-/uswds-3.8.1.tgz#3d834559498ae1bb7d3a618f3f85a5f4e9818497" - integrity sha512-bKG/B9mJF1v0yoqth48wQDzST5Xyu3OxxpePIPDyhKWS84oDrCehnu3Z88JhSjdIAJMl8dtjtH8YvdO9kZUpAg== +"@uswds/uswds@^3.8.1": + version "3.8.2" + resolved "https://registry.npmjs.org/@uswds/uswds/-/uswds-3.8.2.tgz#230668293c33f6866995ba9d03d6f42aba251336" + integrity sha512-8sTx/GqlbTwSIK+0AFOGrYdaW1rKVB7Bp0+v9AMVt3I5vPK7CL0+I6vlclSf3U7ysJZeTTdkNS8q89sIAeL+AA== dependencies: - classlist-polyfill "1.2.0" object-assign "4.1.1" receptor "1.0.0" resolve-id-refs "0.1.0" @@ -505,11 +495,6 @@ class-utils@^0.3.5: isobject "^3.0.0" static-extend "^0.1.1" -classlist-polyfill@1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/classlist-polyfill/-/classlist-polyfill-1.2.0.tgz#935bc2dfd9458a876b279617514638bcaa964a2e" - integrity sha512-GzIjNdcEtH4ieA2S8NmrSxv7DfEV5fmixQeyTmqmRmRJPGpRBaSnA2a0VrCjyT8iW8JjEdMbKzDotAJf+ajgaQ== - classnames@^2.2.6, classnames@^2.3.1: version "2.5.1" resolved "https://registry.yarnpkg.com/classnames/-/classnames-2.5.1.tgz#ba774c614be0f016da105c858e7159eae8e7687b"
        • Breakpoint sass variableVADS Breakpoint Sass VariableUSWDS Breakpoint Custom Property Width
        $xsmall-screen--mobile 320px
        $small-screen--mobile-lg 481px
        ----tablet640px
        $medium-screen--medium-screen 768px
        $small-desktop-screen1008px--desktop1024px
        $large-screen--desktop-lg 1201px