dequelabs / dequelabs/cauldron
CI: auto-publish Figma Code Connect on merge to develop
- 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
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