CI: auto-publish Figma Code Connect on merge to develop

[frankensteinke]

Summary

Now that we're connecting Cauldron components to Figma via Code Connect (#2373), we need a way to keep the published mappings in sync with develop automatically. Today this would require someone to run yarn figma:publish locally with a token — easy to forget, and the published state can silently drift from develop.

Two complementary jobs would solve this:

1. PR validation — run figma:publish:dry-run on PRs that touch .figma.tsx files so validation errors fail the check before merge (this is the higher-leverage half — it would have caught the Show Copy#938:498 / Label Description#131:7 regression in feat: connect components to Figma (batch 1/5) #2375 before it landed).
2. Auto-publish on merge to develop — run figma:publish after merge so the Figma Dev Mode panel always reflects the current state of develop.

Implementation sketch

Add a single workflow at .github/workflows/figma-code-connect.yml with two jobs, both using the existing .github/actions/dependencies composite. Path-filter to only run when .figma.tsx files (or the figma config) change.

name: Figma Code Connect

on:
  pull_request:
    branches: [develop]
    paths:
      - 'packages/react/src/**/*.figma.tsx'
      - 'packages/react/figma.config.json'
  push:
    branches: [develop]
    paths:
      - 'packages/react/src/**/*.figma.tsx'
      - 'packages/react/figma.config.json'

jobs:
  validate:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ./.github/actions/dependencies
        with:
          root: true
          packages-react: true
      - run: yarn --cwd packages/react figma:parse

  publish:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ./.github/actions/dependencies
        with:
          root: true
          packages-react: true
      - run: yarn --cwd packages/react figma:publish
        env:
          FIGMA_ACCESS_TOKEN: \${{ secrets.FIGMA_ACCESS_TOKEN }}

Notes:

• figma:parse is used for PR validation rather than figma:publish:dry-run because the dry-run still requires a token. Parse validates the React side; the publish step on merge is where Figma-side validation lands. (If we want Figma-side validation on PRs too, we'd need to gate the token on pull_request_target or wire it via a workflow_dispatch — has security tradeoffs worth a separate conversation.)
• All scripts already exist in packages/react/package.json (figma:parse, figma:publish, figma:publish:dry-run).

Secrets / Figma-side setup

The publish job needs a FIGMA_ACCESS_TOKEN secret added to the repo at Settings → Secrets and variables → Actions.

Generating the token (Figma → Settings → Security → Personal access tokens):

• Scopes required: `code_connect:write`, `file_content:read` (Code Connect docs).
• Owner: the token is bound to a single Figma user. Strongly recommend a service account (e.g. `design-system-bot@deque.com`) rather than an individual's account, so the integration doesn't break when someone leaves the team or rotates their token. The service account needs at least Viewer access to the Cauldron library file.
• Rotation: Figma personal access tokens don't expire by default but should be rotated periodically. Worth adding a calendar reminder or documenting an expiry date when the secret is created.

Acceptance criteria

• `.github/workflows/figma-code-connect.yml` exists with PR validation + push-to-develop publish jobs
• `FIGMA_ACCESS_TOKEN` repo secret is set using a service-account token
• Opening a PR that breaks a `.figma.tsx` file (e.g. wrong property name) fails the `validate` check
• Merging a valid `.figma.tsx` change to `develop` publishes it; the Figma Dev Mode panel reflects the change without manual intervention
• `CONTRIBUTING.md` → Figma Code Connect section is updated to mention that publish is automated and contributors don't need to run `figma:publish` locally

Related

• Connect Cauldron components to Figma #2373 — the umbrella issue for connecting Cauldron components to Figma
• The recently merged Batch 1 PR was a real-world example of why we want the PR-validation half: validation errors only surfaced when running `yarn figma:publish:dry-run` locally, which is easy to skip.