ci: add Chromatic workflow and clarify release cadence

.github/workflows/chromatic.yml

@@ -0,0 +1,82 @@
+name: Chromatic
+
+on:
+  push:
+    branches: [main, next]
+  pull_request:
+    branches: [main, next]
+
+concurrency:
+  group: chromatic-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Fork PRs cannot use repository secrets.
+    if: >-
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Check Chromatic token is configured
+        id: chromatic-token
+        env:
+          CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+        run: |
+          if [ -n "$CHROMATIC_PROJECT_TOKEN" ]; then
+            echo "configured=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+            echo "CHROMATIC_PROJECT_TOKEN is not configured; skipping Chromatic publish."
+          fi
+
+      - name: Check out latest
+        if: steps.chromatic-token.outputs.configured == 'true'
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set up Node.js (pinned npm)
+        if: steps.chromatic-token.outputs.configured == 'true'
+        uses: ./.github/workflows/actions/setup-node-with-pinned-npm
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        if: steps.chromatic-token.outputs.configured == 'true'
+        run: npm ci
+
+      - name: Build doc components
+        if: steps.chromatic-token.outputs.configured == 'true'
+        run: npx nx run @pine-ds/doc-components:build
+
+      - name: Build Stencil (Storybook consumes dist)
+        if: steps.chromatic-token.outputs.configured == 'true'
+        run: npx nx run @pine-ds/core:build
+
+      - name: Build Storybook static
+        if: steps.chromatic-token.outputs.configured == 'true'
+        run: npx nx run @pine-ds/core:build.storybook
+
+      - name: Publish to Chromatic
+        if: steps.chromatic-token.outputs.configured == 'true'
+        # Pin to full SHA (v16.9.1) for supply-chain security
+        uses: chromaui/action@c231f99a49d72bfcf68eca3f1ef3187f471e352b
+        with:
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          workingDir: libs/core
+          storybookBuildDir: storybook-static
+          token: ${{ secrets.GITHUB_TOKEN }}
+          # PRs: do not fail the workflow on visual changes — Chromatic
+          # posts its own PR status check that blocks merge when changes
+          # are unapproved. This keeps the workflow itself green so other
+          # required checks can render their state independently.
+          exitZeroOnChanges: true
+          # Main and next: accept visual diffs into the baseline automatically.
+          # By the time something is on main or next it has been reviewed, so
+          # re-approving in Chromatic adds friction without catching anything new.
+          autoAcceptChanges: '@(main|next)'

.github/workflows/schedule-release.yml

@@ -6,9 +6,15 @@ permissions:
   contents: read
 
 on:
-  ## We will uncomment this when we settle on a deployment schedule
+  # Release cadence today is **manual / on-demand** via `workflow_dispatch` (and `workflow_call`
+  # from other automation). There is no weekly cron publish yet.
+  #
+  # When the team wants a fixed cadence (for example weekly npm publishes), uncomment and adjust:
   # schedule:
-  #  - cron: '00 04 * * 1' # 4 am UTC (9 am CST) Monday
+  #   - cron: '00 04 * * 1' # example: 4 am UTC Mondays
+  #
+  # Until then, maintainers cut versions from the default branch using the dispatch form in GitHub
+  # Actions for this workflow ("Pine Continuous Deployment").
 
   workflow_call:
     inputs:

CONTRIBUTING.md

@@ -78,6 +78,16 @@ npm run size
 
 When a budget fails, the CLI prints each tracked file with its gzipped size and limit.
 
+### Visual regression (Chromatic)
+
+Pull requests and pushes to `main` / `next` run [Chromatic](https://www.chromatic.com/) via [`.github/workflows/chromatic.yml`](.github/workflows/chromatic.yml). The workflow publishes the static Storybook build from `libs/core/storybook-static`.
+
+Repository maintainers must add a **`CHROMATIC_PROJECT_TOKEN`** secret (from the Chromatic project for this Storybook) so the job can authenticate. Forked pull requests skip Chromatic because secrets are not available to them.
+
+### Releases
+
+`Pine Continuous Deployment` ([`.github/workflows/schedule-release.yml`](.github/workflows/schedule-release.yml)) is triggered **manually** with `workflow_dispatch` (or by another workflow via `workflow_call`). There is no scheduled npm publish cron enabled in-repo yet; see the comment block at the top of that workflow when enabling a cadence.
+
 ### Submitting a Pull Request
 
 Once the desired changes have been made, add and commit the necessary files. We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), so please be sure that your commit messages adhere to these standards.