Merge branch 'main' into megzehn-claims-special-topics

.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

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

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

.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,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:

.gitignore

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

.tool-versions

@@ -0,0 +1 @@
+ruby 3.0.2

Gemfile.lock

@@ -64,20 +64,18 @@ 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)
       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
 

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"

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"