dequelabs / dequelabs/cauldron

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

Open
#2,376 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
127
Forks
31
Avg merge
2d 12h
Merged PRs (30d)
8

Description

## 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 #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.

```yaml
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](https://www.figma.com/code-connect-docs/quickstart-guide/#getting-started)).
- **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

- #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.

Contributor guide

Open the contributing guide

Research direction

Start with the existing .github/actions/dependencies composite and packages/react/package.json, then inspect related workflows before creating .github/workflows/figma-code-connect.yml. Verify the PR validation and push-to-develop jobs against the listed paths and scripts, then update the Figma Code Connect section in CONTRIBUTING.md. Done means validation runs for relevant pull requests, publishing runs after eligible merges, and the FIGMA_ACCESS_TOKEN setup is documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, typescript
Domain
ci-cd, devops, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.