chore: ci rework

Author: castastrophe

.github/CONTRIBUTING.md

@@ -65,13 +65,21 @@ To generate a new component, run the generator:
 yarn new component
 ```
 
-Build the project, open a live-reloading browser window, and watch for changes:
+To kick-off the project's storybook locally, run:
+
+```shell
+yarn start
+```
+
+This is our development environment, where you can see all the components in action, and develop new components. All components must have a storybook entry.
+
+Working on the documentation site? Run:
 
 ```shell
 yarn dev
 ```
 
-Commit changes with a [conventional commit message](https://www.conventionalcommits.org), making sure to correctly use `feat:`, `fix:`, and `BREAKING CHANGE` accordingly, and referencing the relevant issue number (if any):
+Commit all changes with a [conventional commit message](https://www.conventionalcommits.org), making sure to correctly use `feat:`, `fix:`, and `BREAKING CHANGE` accordingly, and referencing the relevant issue number (if any):
 
 ```shell
 git commit -m "fix(calendar): rendering issue in Safari, fixes #252"
@@ -84,6 +92,12 @@ git fetch upstream
 git merge upstream/main
 ```
 
+Run your updates through the formatter which will automatically fix any linting issues. Note that this is also handled on commit via lint-staged so running this manually is only necessary if you used a `--no-verify` flag on any of your commits.
+
+```shell
+nx affected --target format
+```
+
 Review your changes and any possible conflicts and push to your fork:
 
 ```shell
@@ -96,7 +110,7 @@ At this point you're waiting on us. We do our best to keep on top of all the pul
 
 Some things that will increase the chance that your pull request is accepted:
 
-- Write a thorough pull request description, include screenshots, and test your changes across all evergreen browsers.
-- Write out your test cases for any new features or bug fixes in as much detail as possible and include them in the pull request description.
-- Make sure the PR merges cleanly with the latest main.
-- Describe your feature/bugfix and why it's needed/important in the pull request description.
+-   Write a thorough pull request description, include screenshots, and test your changes across all evergreen browsers.
+-   Write out your test cases for any new features or bug fixes in as much detail as possible and include them in the pull request description.
+-   Make sure the PR merges cleanly with the latest main.
+-   Describe your feature/bugfix and why it's needed/important in the pull request description.

.github/ISSUE_TEMPLATE/--bug-report.md

@@ -26,8 +26,8 @@ assignees: pfulton, castastrophe
 
 ## Environment
 
-- **Version of the impacted component(s):** <!-- 2.13.0 -->
-- **Browser(s) and OS(s):** <!-- Chrome 75.0.3770.142 on Win 10 -->
+-   **Version of the impacted component(s):** <!-- 2.13.0 -->
+-   **Browser(s) and OS(s):** <!-- Chrome 75.0.3770.142 on Win 10 -->
 
 ## Additional context
 

.github/ISSUE_TEMPLATE/--support-request.md

@@ -16,8 +16,8 @@ assignees: pfulton, castastrophe
 
 ## Environment
 
-- **Spectrum CSS version:** <!-- 2.13.0 -->
-- **Browser(s) and OS(s):** <!-- Chrome 75.0.3770.142 on Win 10 -->
+-   **Spectrum CSS version:** <!-- 2.13.0 -->
+-   **Browser(s) and OS(s):** <!-- Chrome 75.0.3770.142 on Win 10 -->
 
 ## Additional context
 

.github/README.md

@@ -0,0 +1,108 @@
+# GitHub Actions, templates, and bots (oh my!)
+
+The goal of this documentation is to provide an outline for the GitHub goodness that exists in this folder. This is a living document, so please feel free to contribute to it.
+
+## Architecture
+
+```bash
+⎪ actions
+├── file-diff
+├──── action.yml - this defines the inputs and outputs of the action
+├──── index.js - the code that runs the action
+├──── package.json - has dependencies so has package
+├──── README.md - more documentation yay!
+⎪ workflows
+├── development.yml - run on pull requests only
+├── production.yml - runs only on pushes to main
+├── vrt.yml - a reusable workflow that can be called by other workflows (i.e., development.yml or production.yml) or called on it's own via [workflow dispatch](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/).
+├── build.yml - builds a branch and outputs the compiled assets as artifacts
+├── compare-results.yml - compares the compiled assets between the pull request branch and the main branch
+```
+
+**But wait! There's more!**
+
+```bash
+⎪ ISSUE_TEMPLATE
+├── --bug-report.md
+├── --documentation-issue.md
+├── --feature-request.md
+├── --support-request.md
+⎪ PULL_REQUEST_TEMPLATE.md
+⎪ CONTRIBUTING.md
+⎪ dependabot.yml
+```
+
+## Actions
+
+### File Diff
+
+This action is used to determine if a compiled asset has changed between two branches. See the [README](./file-diff/README.md) for more information.
+
+## Workflows
+
+### Development
+
+This workflow runs:
+
+- on pull requests when:
+  - opened against the `main` branch
+  - opened, reopened, synchronized (i.e., when a commit is pushed to the pull request), labeled or unlabeled, or if auto merge is enabled
+  - any files other than markdown have changed (i.e., will not run on a pull request that only changes markdown files)
+
+#### What does this workflow do?
+
+##### 👷‍♀️ Build
+
+Builds the pull request branch against various development environments. Installs dependencies and builds the project looking for basic processing errors.
+
+##### 👷‍♀️ Compare results
+
+Compares the compiled assets between the pull request branch and the base branch. If there are differences, a comment is added to the pull request with a table detailing the files and the size differences.
+
+_to-do_: This needs to diff the actual content of the files as well. Right now we're leveraging a canary approach which would catch any file size changes to the compiled assets. However, **if the content of the file changes but the size doesn't, we won't catch that**.
+
+##### 🧹 Linting
+
+Runs stylelint or eslint if any relevant assets have been updated in this PR.
+
+##### 📝 Publish site
+
+After the build and visual regression tests have passed, this will build the docs site and publish it to Netlify.
+
+##### 📸 Visual regression testing
+
+Run these tests if the `run_vrt` label is added to the pull request.
+
+**OR** the pull request is not in a draft state and is mergeable (meaning no conflicts with the base branch)
+
+**OR** the pull request review request is approved.
+
+The only step in this job is to run the `vrt.yml` workflow.
+
+### Production
+
+This workflow runs:
+
+- on pushes to the `main` branch
+
+#### What does this workflow do?
+
+##### 👷🏾 1. Build
+
+Builds the `main` branch and outputs the compiled assets as artifacts.
+
+##### 📝 2. Publish site
+
+Publish the docs site to Netlify.
+
+##### 📸 3. Visual regression testing
+
+Run the visual regression testing for **ALL** pushes to the `main` branch. Triggers the `vrt.yml` workflow, see below for more information.
+
+<!-- ##### 💾 Auto-updates
+
+If a pull request includes the `auto-update` label and uses `main` as the base branch, this workflow will run. It will attempt to update the pull request with the latest changes from `main` but will fail gracefully if there are conflicts. Conflicts will need to be resolved manually. -->
+
+### Visual regression testing
+
+First, why is this a workflow and not it's own action? We want to be able to trigger the visual regression test manually via the GitHub UI or dynamically via another workflow. It also doesn't need to run in the same container as the rest of the workflow. An action is a definition of tasks and runs in the context it's called within while a workflow runs in it's own container.

.github/actions/file-diff/README.md

@@ -0,0 +1,52 @@
+# File diff
+
+A GitHub Action for comparing compiled assets between branches.
+
+## Inputs
+
+### `path`
+
+**Required** Path to file or directory for file sizes analysis.
+
+### `diff-path`
+
+**Optional** Path to another directory against which to perform file comparisons.
+
+### `token`
+
+**Optional** GitHub token for accessing the GitHub API. Defaults to `${{ github.token }}`.
+
+### `file-glob-pattern`
+
+**Optional** Glob pattern for selecting files to compare. Defaults to `dist/*`.
+
+### `comment`
+
+**Optional** If true, add a comment on the pull request with the results of the comparison. Defaults to `true`.
+
+### `comment-header`
+
+**Optional** Header content for the comment. Markdown is supported. Defaults to `## File metrics`.
+
+## Outputs
+
+### `has-changed`
+
+True if the overall file size has changed, false otherwise.
+
+### `total-size`
+
+Total size of all files for this branch in bytes.
+
+## Example usage
+
+```yaml
+name: Compare compiled output file size
+uses: "spectrum-tools/gh-action-file-diff"
+with:
+    path: ${{ github.workspace }}/pull-request
+    diff-path: ${{ github.workspace }}/base-branch
+    file-glob-pattern: |
+        components/*/dist/*.{css,json}
+        components/*/dist/themes/*.css
+```

.github/actions/file-diff/action.yml

@@ -0,0 +1,35 @@
+name: "File comparisons"
+description: "Compares files between branches."
+author: "spectrum-tools"
+inputs:
+    path:
+        description: "Path to file or directory for file sizes analysis."
+        required: false
+        default: ${{ github.workspace }}
+    diff-path:
+        description: "Optional path to another directory to perform file size diff against the provided path."
+        required: false
+    token:
+        description: "GITHUB_TOKEN for the repository."
+        required: false
+        default: ${{ github.token }}
+    file-glob-pattern:
+        description: "Glob pattern for filtering of the files."
+        required: false
+        default: "**/dist/**"
+    comment:
+        description: "Whether to comment on the PR."
+        required: false
+        default: "true"
+    comment-header:
+        description: "Comment header to be used in the PR comment."
+        required: false
+        default: "## File metrics"
+outputs:
+    has-changed:
+        description: "True if the overall file size has changed."
+    total-size:
+        description: "Total size of the files in bytes."
+runs:
+    using: "node20"
+    main: "index.js"