Merge branch 'main' into external-link-docs

Author: humancompanion-usds

.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

.github/ISSUE_TEMPLATE/DST-component_design.md

@@ -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.
 

.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

.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/*"

.github/workflows/deploy.yml

@@ -8,7 +8,7 @@ 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
@@ -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 }}

.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 }}

.github/workflows/pull-request.yml

@@ -7,7 +7,7 @@ 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

.gitignore

@@ -2,6 +2,7 @@
 .jekyll-metadata
 .sass-cache
 .vscode
+*.code-workspace
 _site
 fonts
 node_modules

Gemfile.lock

@@ -64,20 +64,18 @@ GEM
     rb-fsevent (0.11.1)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.3.6)
-      strscan
+    rexml (3.3.9)
     rouge (3.29.0)
     safe_yaml (1.0.5)
     sass-embedded (1.0.21)
       google-protobuf (~> 3.19.0)
       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

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
 

_config.yml

@@ -9,7 +9,7 @@ example_library_name: "VADS Example Library"
 resource_library_name: "VADS Templates, Patterns, and Forms"
 
 # Common links
-figma_example_library: https://www.figma.com/file/JDFpGLIojfuQwANXScQjqe/VADS-Component-Examples?type=design&node-id=0%3A1&mode=design&t=c29j3xBxzMAyLWxu-1 
+figma_example_library: https://www.figma.com/file/JDFpGLIojfuQwANXScQjqe/VADS-Component-Examples?type=design&node-id=0%3A1&mode=design&t=c29j3xBxzMAyLWxu-1
 figma_component_library: https://www.figma.com/file/afurtw4iqQe6y4gXfNfkkk/VADS-Component-Library?type=design&node-id=121%3A1484&mode=design&t=ygQCLqlAL5VdSPil-1
 figma_templates_library: https://www.figma.com/file/4A3O3mVx4xDAKfHE7fPF1U/VADS-Templates%2C-Patterns%2C-and-Forms?type=design&node-id=2988%3A29744&mode=design&t=A89mK0w9KGp2uWIR-1
 figma_annotations_library: https://www.figma.com/file/CZcnWfQOwtLqPm4WA5paYG/VADS-Web-Annotation-Kit?type=design&node-id=415%3A1135&mode=design&t=V0V5YZrcbM7VnWa6-1
@@ -34,16 +34,16 @@ new_pattern_template_raw_link: https://raw.githubusercontent.com/department-of-v
 update_documentation_link: https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues/new?assignees=&labels=vsp-design-system-team&template=2_documentation_request_form.yml
 uswds_link: https://designsystem.digital.gov/
 
-
 # People
-sketch_for_teams_admin: "Kevin Hoffman" 
+sketch_for_teams_admin: "Kevin Hoffman"
 sketch_library_owner: "Lillian Boot, Barb Denney"
 experimental_reviewer_1: "Matthew Dingee"
 
-
 # Build settings
 markdown: kramdown
-highlighter: none
+highlighter: rouge
+kramdown:
+  syntax_highlighter: rouge
 plugins:
   - jekyll-last-modified-at
   - jekyll-redirect-from
@@ -91,7 +91,7 @@ exclude:
   - _foundation/layout/html
   - _foundation/utilities/html
 
-# Default for building locally. 
+# Default for building locally.
 # See configuration files in jekyll-configs/ for environment overrides.
 storybook_path: "http://127.0.0.1:6006"
 storybook_prod_uswds_path: "https://design.va.gov/storybook/?path=/docs/uswds"

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"

src/_about/contributing/experimental-design.png

@@ -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 %}
+### 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" %}
+
+<va-link-action
+  href="https://app.mural.co/t/departmentofveteransaffairs9999/m/departmentofveteransaffairs9999/1715279885465/a8a7701ed5948be8cd98f972ee930a16b9e7444b"
+  text="Open experimental design Mural file"
+/>
+
+<a href="https://app.mural.co/t/departmentofveteransaffairs9999/m/departmentofveteransaffairs9999/1715279885465/a8a7701ed5948be8cd98f972ee930a16b9e7444b">View the experimental design decision tree and process Mural.</a>
+
+{% include _site-in-this-section.html %}

src/_about/contributing/index.md

@@ -148,7 +148,7 @@ If the Web Component has a custom event that you need to use and you're **not**
   const element = document.querySelector('va-example-component');
   const exampleCallback = event => { console.log(event.detail) }
   element.addEventListener('vaChange', exampleCallback)
-<script>
+</script>
 
 <va-example-component>
 ```

src/_about/developers/using-web-components.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.