Merge branch 'main' into hoc-rich-vertical-list

Author: jmuzina

.github/actions/percy-snapshot/action.yml

@@ -38,7 +38,7 @@ runs:
 
     - name: Install dependencies
       shell: bash
-      run: yarn && pip3 install -r requirements.txt
+      run: yarn install && pip3 install -r requirements.txt
 
     - name: Build
       shell: bash
@@ -80,13 +80,16 @@ runs:
       id: percy_snapshot
       env:
         PERCY_TOKEN: ${{ inputs.percy_token_write }}
-        # This identifies the diff by name in the percy diffs list
+        # This is used to name the build on the Percy dashboard. For PRs, it is `pull/{pr_number}`, and for baseline, it is `main`.
         PERCY_BRANCH: ${{ inputs.branch_name }}
+        # HEAD commit SHA signature that triggered this test
         PERCY_COMMIT: ${{ inputs.commitsh }}
-        PERCY_CLIENT_ERROR_LOGS: false
         # If PR number is set & a Percy-GHA integration is set up, this allows Percy to set status on the PR
         PERCY_PULL_REQUEST: ${{ inputs.pr_number }}
+        # GH runner sometimes runs into issues loading assets (large images especially) in the default 30s timeout.
+        # This increases the timeout to 2 minutes to allow for more time to load assets.
         PERCY_PAGE_LOAD_TIMEOUT: 120000
+        # Debugging vars to show more console output and diagnose issues with Percy
         LOG_LEVEL: debug
         PERCY_DEBUG: "*"
       run: |

.github/workflows/percy-baseline.yml

@@ -1,3 +1,6 @@
+# This workflow updates the Percy baseline on every push to main.
+# This allows pull requests to be compared against baseline test results.
+
 name: Update Percy Baseline
 
 on:

.github/workflows/percy-prepare.yml

@@ -1,5 +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.
+# It checks out the SCSS/example markup changes and uploads them to GitHub as an artifact.
 name: "Prepare Percy build"
 
 on:
@@ -16,9 +16,10 @@ on:
 
 jobs:
   copy_artifact:
-    name: Copy changed files to GHA artifact
+    name: Copy visual testing files to GitHub Actions artifact
     runs-on: ubuntu-latest
     steps:
+      # Checkout only the files that are needed for visual testing and safe for the snapshots workflow to run
       - name: Checkout repo
         uses: actions/checkout@v4
         with:
@@ -31,7 +32,7 @@ jobs:
 
       - name: Populate artifact directory
         run: |
-          # Create needed directories so `cp` doesn't fail
+          # Create needed directories so `cp` doesn't fail. This is for backwards compatibility with PRs that are based on commits that don't have these directories.
           # If a PR is made that doesn't have these directories in the source, the CPs at the end of the step will fail
           mkdir -p artifact
           mkdir -p tokens
@@ -45,9 +46,9 @@ jobs:
           # underscore-prefixed directories are ignored by GH artifacts, so we need to copy to a non-prefixed directory
           cp -R templates/_macros/. templates/macros/
           
+          # Copy all of the needed files to the artifact directory
           cp -R templates/docs/examples/ templates/macros/ scss/ tokens/ sd.config.json artifact/
 
-        
       # Archive the PR number associated with this workflow since it won't be available in the base workflow context
       # https://github.com/orgs/community/discussions/25220
       - name: Archive PR data
@@ -59,6 +60,7 @@ jobs:
           echo "Contents of artifact"
           tree .
 
+      # Upload artifact so the `pr-percy-snapshots` workflow can pick it up
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:

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

@@ -21,22 +21,24 @@ jobs:
       percy_org_id: ${{ steps.percy_snapshot.outputs.org_id }}
       percy_build_id: ${{ steps.percy_snapshot.outputs.build_id }}
     steps:
+      # Checkout `main` branch of Vanilla
       - name: Checkout SCM
         uses: actions/checkout@v4
 
       - name: Remove SCM directories that will be replaced by artifact files
-        run: |
-          set -e
-          rm -rf templates/docs/examples/ templates/_macros/ tokens/ sd.config.json scss/
+        run: rm -rf templates/docs/examples/ templates/_macros/ tokens/ sd.config.json scss/
 
-      - name: Download artifact from workflow run
+      - name: Download artifact from prepare workflow
         uses: actions/download-artifact@v4
         with:
           name: "percy-testing-web-artifact"
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repository: ${{ github.event.workflow_run.repository.full_name }}
           run-id: ${{ github.event.workflow_run.id }}
 
+      # Downloading the artifact in the previous step also extracts its contents into `./`.
+      # However, there are some files in the artifact that are not in the same place as Vanilla expects them to be.
+      # This step moves those files to the correct place.
       - name: Move artifact files into place to replace SCM
         run: |
           # ensure the examples & macros dirs exist for backwards compatibility in case they aren't in the PR artifact
@@ -48,15 +50,19 @@ jobs:
           mv examples/ templates/docs/.
           mv macros/ templates/_macros
 
+      # The `pr_num.txt` and `pr_head_sha.txt` files are used to pass the PR number and head SHA from the PR to this workflow.
+      # This is required as the `workflow_run` context of this workflow has no access to the context of the PR that triggered the `pr-percy-prepare` workflow.
       - name: Get PR data
         if: github.event.workflow_run.event=='pull_request'
         id: get_pr_data
         run: |
           echo "sha=$(cat pr_head_sha.txt)" >> $GITHUB_OUTPUT
           echo "pr_number=$(cat pr_num.txt)" >> $GITHUB_OUTPUT
+          # Debugging step to show the full contents of the filesystem just before the Percy snapshot step
           tree
 
-      - name: Take snapshots & upload to Percy
+      # Composite action uses the filesystem we have prepared for it with this workflow
+      - name: Build, run, and test Vanilla
         id: percy_snapshot
         uses: "./.github/actions/percy-snapshot"
         with:

guides/percy-workflow.md

@@ -0,0 +1,158 @@
+## Percy visual testing
+
+We use [Percy](https://percy.io) for visual testing. Percy tests are run against pull requests to
+ensure that PRs do 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 makes changes to any of the following directories or files:
+      - `scss/`
+      - `templates/docs/examples/`
+      - `templates/_macros/`
+      - `tokens/`
+      - `sd.config.json`
+    - PR is not a draft
+  - PR is labeled with "Review: Percy needed"
+    - Note that a Percy (labeled) workflow will be triggered on each labelling and synchronisation event on PRs to `main`. They will be skipped shortly after starting if the PR does not have the "Review: Percy needed" label.
+
+To ensure optimal Percy usage, we suggest the following PR flow:
+
+1. Open the PR (against `main`) as a draft. Ensure that all non-Percy PR status checks pass.
+2. Apply the "Review: Percy needed" label to the PR to trigger a Percy test.
+3. Review the initial Percy build. After a few minutes, it will be available on our [Percy dashboard](https://percy.io/bb49709b/vanilla-framework). You can also click the Percy status check on the PR to navigate directly to the test results.
+
+<img src="https://assets.ubuntu.com/v1/a4b79af3-percy_status_check.png" alt="Percy status check" width="400">
+
+4. 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. Any commits you add to the PR will not trigger a Percy test, as long as the PR is a draft and does not have the "Review: Percy needed" label.
+5. 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.
+6. If the Percy test passes, apply "Review: Percy +1" to indicate that the PR has passed Percy testing.
+
+### Workflows
+
+#### Baseline Workflow
+
+The [baseline workflow](../.github/workflows/percy-baseline.yml) runs a Percy test on every push to `main`, and sets the results
+as the new Percy baseline that all future PRs will be compared against.
+
+#### Prepare Workflow
+
+The [prepare workflow](../.github/workflows/percy-prepare.yml) checks out a merge commit of a PR and `main`, then
+uploads all files in the PR that have any affects on the visual appearance of the design system as a GitHub artefact.
+
+#### PR Snapshot Workflow
+
+The [snapshot workflow](../.github/workflows/pr-percy-snapshots.yml) downloads the artefacts from the [prepare workflow](#prepare-workflow)
+and calls the [Percy snapshot action](../.github/actions/percy-snapshot/action.yml) to build, run, & visually test Vanilla.
+
+The PR snapshot workflow is always called after the completion of the [prepare workflow](#prepare-workflow).
+
+### Example snapshots
+
+Percy is run by executing `yarn percy` or `npm run percy` in the root of the project. The [Percy CLI](https://github.com/percy/cli)
+runs [snapshots.js](../snapshots.js) which returns a list of all the snapshots that Percy will take.
+
+Percy uses our [examples](https://vanillaframework.io/docs/examples) to take snapshots of all components, patterns, and utilities in Vanilla.
+
+[snapshots.js](../snapshots.js) will take a snapshot of an example template file if the following conditions are met:
+
+- Is an HTML file in `templates/docs/examples/`
+- File is not a partial (does not start with `_`)
+- File is not included in a combined example (is not in the same directory as a combined example or in a directory that descends from a directory with a combined example)
+
+#### Snapshot widths
+
+Each snapshot object returned by [snapshots.js](../snapshots.js) has a `widths` array property that specifies the widths (in pixels) at which the snapshot should be captured.
+The following table shows the widths at which snapshots are captured and which examples they apply to:
+
+| Device  | Width (px) | Captured on                                                                                                                                    |
+| ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Desktop | 1,280      | All examples                                                                                                                                   |
+| Tablet  | 800        | All examples with `responsive` in their names, and [combined examples](#combined-examples) that include a `responsive` file in their directory |
+| Mobile  | 375        | Default theme only (currently `light`)                                                                                                         |
+
+Each width is captured as a separate screenshot, and counts as an additional screenshot in Percy's pricing model.
+
+#### Snapshot browsers
+
+Percy can be configured to take snapshots in multiple browsers. Each additional browser counts as an additional set of screenshots in Percy's pricing model.
+Vanilla is currently only tested on Chrome. To add additional browsers, view the [Percy project settings page](https://percy.io/bb49709b/vanilla-framework/settings).
+
+#### Combined examples
+
+Combined examples are a way to show all the variants of a component or pattern on the same page. This helps us keep our
+Percy usage down by only taking one snapshot of a component or pattern, rather than one for each variant.
+Combined examples follow a naming convention: they must be named `combined.html`.
+If `combined.html` is found in a directory, [snapshots.js](../snapshots.js) will assume that every example in that directory (and its subdirectories) is rendered in the `combined.html` file.
+
+**Combined examples do not currently include the JavaScript or CSS that is included in individual examples by `{% block script %}` and `{% block style %}` tags.**
+
+##### Creating a combined example
+
+1. Create a Jinja template file named `combined.html` in any subdirectory of `templates/docs/examples/`
+2. In your `content` block, create a `with` block that sets the flag `is_combined` to `true`. This will ensure that the [base example template](../templates/_layouts/examples.html) renders the example without the `{% block script %}` and `{% block style %}` tags and adds links to the individual examples.
+3. Include the examples you want to combine in the `combined.html` file using `{% include 'path/to/example.html' %}` inside the `with` block. It is good practice to separate the examples in `<section>` tags.
+
+For example, see the [combined example for the button pattern](../templates/docs/examples/patterns/buttons/combined.html).
+
+##### Spacing below examples
+
+If an example's content is expected to overflow its body (such as a dropdown or tooltip), you can use the `spacing_below` parameter to add space below the example.
+`spacing_below` `rems` will be added beneath the example as `margin-bottom`.
+
+For example:
+
+```html
+<!-- Add `12rem` of space below the example -->
+{% with spacing_below = 12 %}
+<section>{% include 'docs/examples/patterns/contextual-menu/default.html' %}</section>
+{% endwith %}
+```
+
+### Testing
+
+[snapshots.test.js](../tests/snapshots.test.js) is a [Jest](https://jestjs.io/) testing file used to test the output of the [snapshots.js](../snapshots.js) file.
+It tests that the snapshots are correctly generated. It is run as part of our wider testing script (`yarn test`), but you can also execute it directly by running `npx jest tests/snapshots.test.js`.
+
+[snapshots.js](../snapshots.js) considers `combined.html` to require responsive snapshots if a sibling or descendant file contains `responsive` in its name.
+[snapshots.test.js](../tests/snapshots.test.js) does not read the filesystem to decide whether a combined snapshot is responsive.
+If you add a combined example that must be captured responsively, you must add the path of that example to `RESPONSIVE_COMBINED_EXAMPLES` in [snapshots.test.js](../tests/snapshots.test.js).
+
+### PR File Inclusion
+
+Only some of a pull request's files are represented in each pull request snapshot test. Depending on which files need to be changed,
+you may need to make a separate pull request to make changes to `main` before a pull request will use your changes in Percy testing.
+
+#### Files included in Percy tests
+
+- Visual files:
+  - `scss/`
+  - `templates/docs/examples/`
+  - `templates/_macros/`
+  - `tokens/`
+  - `sd.config.json`
+- Workflows that are run on the `pull_request` trigger, including (but not limited to):
+  - [Prepare workflow](../.github/workflows/percy-prepare.yml)
+  - [Prepare (labelled) workflow](../.github/workflows/pr-percy-prepare-label.yml)
+  - [Prepare (pushed) workflow](../.github/workflows/pr-percy-prepare-push.yml)
+
+Changes to other files should be added to a separate PR and merged before testing a PR that requires their changes.
+Otherwise, the changes will not be included in Percy tests.
+This notably includes:
+
+- Dependencies
+  - `Dockerfile`
+  - `package.json`
+  - `requirements.txt`
+- Workflows that are run on the `workflow_run` trigger:
+  - [PR snapshots workflow](../.github/workflows/pr-percy-snapshots.yml)
+  - [Snapshot action](../.github/actions/percy-snapshot/action.yml)
+- `snapshots.js` and `snapshots.test.js`
+
+### Additional resources
+
+- [Percy CLI documentation](https://www.browserstack.com/docs/percy/take-percy-snapshots/snapshots-via-cli#advanced-options)
+- [Percy environment variables](https://www.browserstack.com/docs/percy/get-started/set-env-var#Percy_SDK)
+- [Percy workflow blog post](https://ubuntu.com/blog/visual-testing-github-actions-migration-test-optimisation)

guides/pull-requests.md

@@ -80,29 +80,7 @@ apply the relevant `-1` Labels.
 
 #### 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/`, `templates/docs/examples/`, or `templates/_macros/` 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 above 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.
+Please review the [Percy visual testing](percy-workflow.md) documentation for a detailed overview of how to work with the Percy visual testing system.
 
 #### Merging a PR
 

releases.yml

@@ -8,6 +8,22 @@
       url: /docs/base/forms#fieldset
       status: New
       notes: We've introduced <code>is-required</code> to legend fieldset elements.
+    - component: Rule
+      url: /docs/patterns/rule#default
+      status: Deprecated
+      notes: We've deprecated the <code>.p-rule</code> component. Use the <a href="/docs/base/separators#no-bottom-margin">HR with no bottom margin</a> instead.
+    - component: Separator
+      url: /docs/base/separators
+      status: New
+      notes: We've added <code>.is-highlighted</code> and <code>.is-highlighted.is-accent</code> classes to the base horizontal rule.
+    - component: Image container
+      url: /docs/patterns/images#image-container-with-aspect-ratio
+      status: New
+      notes: We've added new breakpoint-specific aspect ratio classes to the image container component.
+    - component: Tiered list
+      url: /docs/patterns/tiered-list
+      status: Updated
+      notes: We've added new CTA block usage examples for the tiered list pattern.
     - component: Rich list / vertical
       url: /docs/patterns/rich-list#vertical
       status: New

scss/_base_hr.scss

@@ -35,6 +35,14 @@
       background-color: $colors--theme--border-low-contrast;
     }
 
+    &.is-highlighted {
+      @include vf-highlight-bar($colors--theme--text-default);
+
+      &.is-accent {
+        @include vf-highlight-bar($color-accent);
+      }
+    }
+
     &.u-no-margin--bottom {
       // compensate for hr thickness, to make sure it doesn't drift from baseline grid
       @extend %u-no-margin--bottom--hr;

scss/_layouts_fluid-breakout.scss

@@ -149,7 +149,7 @@
       grid-column: 2 / -1;
       grid-template-columns: repeat(2, minmax(0, 1fr));
 
-      @media (max-width: $threshold-4-6-col - 1) {
+      @media (width < $threshold-4-6-col) {
         grid-template-columns: repeat(1, minmax(0, 1fr));
         width: $l-fluid-breakout-main-child-width;
       }
@@ -163,7 +163,7 @@
       &:nth-child(2) {
         justify-content: flex-end;
 
-        @media (max-width: $threshold-4-6-col - 1) {
+        @media (width < $threshold-4-6-col) {
           justify-content: flex-start;
         }
       }

scss/_patterns_article-pagination.scss

@@ -55,7 +55,7 @@
     padding-left: $sp-xx-large;
     text-align: left;
 
-    @media (max-width: $breakpoint-x-small - 1) {
+    @media (width < $breakpoint-x-small) {
       margin-right: 0;
       width: auto;
 
@@ -84,7 +84,7 @@
     padding-right: $sp-xx-large;
     text-align: right;
 
-    @media (max-width: $breakpoint-x-small - 1) {
+    @media (width < $breakpoint-x-small) {
       width: 100%;
     }