Add more docs to Percy workflows; add Percy testing section to pull r…

…equests guide

.github/workflows/percy-prepare.yml

@@ -1,3 +1,5 @@
+# This workflow is triggered by the `pr-percy-prepare` workflows.
+# It checks out the SCSS/example markup changes and uploads them to Github as an artifact.
 name: "Prepare Percy build"
 
 on:

.github/workflows/pr-percy-prepare-label.yml

@@ -8,7 +8,6 @@ on:
     types:
         # workflow runs after a label is added to the PR, or when a commit is added to a PR with the Percy label
       - labeled
-      - ready_for_review
       - synchronize
 
 jobs:
@@ -19,4 +18,6 @@ jobs:
     with:
       pr_number: ${{ github.event.number }}
       repository: ${{ github.repository }}
-      commitsh: ${{ github.event.pull_request.head.sha }}
+      commitsh: ${{ github.event.pull_request.head.sha }}
+
+# Completion should trigger `pr-percy-snapshots` workflow.

.github/workflows/pr-percy-prepare-push.yml

@@ -10,7 +10,6 @@ on:
       - "scss/**"
     types:
       - opened
-      - ready_for_review
       - synchronize
 
 jobs:
@@ -23,4 +22,6 @@ jobs:
     with:
       pr_number: ${{ github.event.number }}
       repository: ${{ github.repository }}
-      commitsh: ${{ github.event.pull_request.head.sha }}
+      commitsh: ${{ github.event.pull_request.head.sha }}
+
+# Completion should trigger `pr-percy-snapshots` workflow.

.github/workflows/pr-percy-snapshots.yml

@@ -1,3 +1,4 @@
+# This workflow listens for completion of the `pr-percy-prepare` workflows, picks up their outputs, and performs Percy testing.
 name: "Percy screenshots"
 
 on:

guides/pull-requests.md

@@ -78,6 +78,34 @@ apply the relevant `-1` Labels.
 
 ### Submitting & merging a PR
 
+#### Percy visual testing
+
+We use [Percy](https://percy.io) for visual testing. Percy tests are run against pull requests to
+ensure that PRs to not introduce visual regressions. Your PR will be tested by Percy if it meets the following conditions:
+
+- PR is against the `main` branch
+- One of the following is true:
+  - PR passes Percy selectivity filters
+    - PR changes files in the `scss/` or `templates/docs/examples/` directories
+    - PR is not a draft
+  - PR is labeled with "Review: Percy needed"
+
+To ensure optimal Percy usage, we suggest the following PR flow:
+
+1. Open the PR (against `main`) in such a way that it causes an initial Percy test to run.
+   - If your PR makes changes to files in the `scss/` or `templates/docs/examples/` directories, it will be automatically
+     tested as long as it is not marked as a draft.
+   - Applying the "Review: Percy needed" label to the PR ensures that it is always tested.
+2. Review the initial [Percy build](https://percy.io/bb49709b/vanilla-framework).
+3. If there are additional changes needed to the PR through the review process, you can remove the "Review: Percy needed"
+   label and mark the PR as a draft to prevent additional Percy tests from running.
+4. Once the PR is ready for final review, remove the draft status and reapply the "Review: Percy needed" label to trigger
+   a final Percy test.
+5. If the Percy test passes, apply "Review: Percy +1" to indicate that the PR has passed Percy testing.
+6. If all other reviews have been completed, the PR is ready to be merged.
+
+#### Merging a PR
+
 After the necessary review steps have been completed and the PR is ready to be
 merged, the creator of the PR should merge it themself. The type of merge to use
 should be decided using the following logic: