feat: add Code Connect template mappings and publish workflow (#832)

* feat: add code-connect support

* feat: add code connect workflow

* chore: add worflow dispatch

* chore: add mask for figma files

* fix: improve code connect files

* fix: remove code connect defaults

* fix: update emptystate code connect

Author: rohanchkrabrty

.github/workflows/code-connect.yaml

@@ -0,0 +1,82 @@
+name: Publish Figma Code Connect
+
+# Code Connect mappings are version-independent — they only change when the
+# template files do. Publish to Figma whenever those files land on main,
+# or trigger manually from the Actions tab.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - "packages/raystack/figma/**"
+      - "packages/raystack/figma.config.json"
+      - "packages/raystack/scripts/generate-icons-code-connect.js"
+      - ".github/workflows/code-connect.yaml"
+
+# Avoid overlapping publishes racing against the same Figma file.
+concurrency:
+  group: code-connect
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    name: Publish Figma Code Connect
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm 9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.3.0
+
+      - name: Setup Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "pnpm"
+
+      - name: Install Dependencies 🔧
+        run: pnpm install --frozen-lockfile
+
+      # Redact the Figma file keys from all subsequent step logs. The publish
+      # command prints every mapped node URL; masking turns the file key into
+      # *** so links read https://figma.com/file/***/?node-id=... in CI logs.
+      - name: Mask Figma file keys 🔒
+        env:
+          FIGMA_FILE_URL: ${{ vars.FIGMA_FILE_URL }}
+          FIGMA_ICONS_FILE_URL: ${{ vars.FIGMA_ICONS_FILE_URL }}
+        run: |
+          for url in "$FIGMA_FILE_URL" "$FIGMA_ICONS_FILE_URL"; do
+            key=$(printf '%s' "$url" | sed -E 's#.*/(design|file)/([^/?]+).*#\2#')
+            if [ -n "$key" ] && [ "$key" != "$url" ]; then
+              echo "::add-mask::$key"
+            fi
+          done
+
+      # Generate the per-icon batch JSON from the Figma icons file.
+      - name: Generate icon mappings 🎨
+        working-directory: ./packages/raystack
+        env:
+          FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}
+          FIGMA_ICONS_FILE_URL: ${{ vars.FIGMA_ICONS_FILE_URL }}
+        run: pnpm figma:generate-icons
+
+      # Substitute the real Figma file URL into figma.config.json.
+      - name: Update Figma config 🔧
+        working-directory: ./packages/raystack
+        env:
+          FIGMA_FILE_URL: ${{ vars.FIGMA_FILE_URL }}
+        run: pnpm figma:update-config
+
+      # Redact the file key from publish output at the source (belt-and-suspenders
+      # with the add-mask step). pipefail preserves figma:publish's exit code.
+      - name: Publish to Figma 🚀
+        working-directory: ./packages/raystack
+        env:
+          FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}
+        run: |
+          set -o pipefail
+          pnpm figma:publish 2>&1 | sed -E 's#(/(design|file)/)[^/?]+#\1***#g'

.gitignore

@@ -43,3 +43,6 @@ yarn-error.log*
 
 # npm pack artifacts
 *.tgz
+
+# generated Code Connect batch file (created by figma:generate-icons at publish time)
+packages/raystack/figma/icons.figma.batch.json

packages/raystack/figma.config.json

@@ -1,8 +1,14 @@
 {
   "codeConnect": {
-    "include": ["components/**/*", "figma/**/*"],
+    "include": [
+      "figma/**/*.figma.ts",
+      "figma/**/*.figma.batch.ts",
+      "figma/**/*.figma.batch.json"
+    ],
     "exclude": [],
     "parser": "react",
+    "label": "React",
+    "language": "jsx",
     "documentUrlSubstitutions": {
       "<FIGMA_LINK>": "FIGMA_FILE_URL"
     }

packages/raystack/figma/accordion.figma.ts

@@ -0,0 +1,20 @@
+// url=<FIGMA_LINK>?node-id=8089-1150
+// source=https://github.com/raystack/apsara/blob/main/packages/raystack/components/accordion/accordion.tsx
+// component=Accordion
+
+import figma from 'figma';
+
+// State (Collapsed/Hover/Expanded) is visual-only — the Accordion root exposes no
+// matching prop, so it is not mapped. A composed example uses the public sub-component API.
+
+export default {
+  id: 'Accordion',
+  imports: ["import { Accordion } from '@raystack/apsara'"],
+  example: figma.code`<Accordion>
+      <Accordion.Item value='item-1'>
+        <Accordion.Trigger>Trigger</Accordion.Trigger>
+        <Accordion.Content>Content</Accordion.Content>
+      </Accordion.Item>
+    </Accordion>`,
+  metadata: { nestable: true }
+};

packages/raystack/figma/accordion.figma.tsx

@@ -0,0 +1,38 @@
+// url=<FIGMA_LINK>?node-id=6633-2337
+// source=https://github.com/raystack/apsara/blob/main/packages/raystack/components/alert-dialog/alert-dialog.tsx
+// component=AlertDialog
+
+import figma from 'figma';
+
+const instance = figma.selectedInstance;
+
+// Title/Description booleans toggle whether those sub-components are rendered.
+const title = instance.getBoolean('Title', {
+  true: `
+      <AlertDialog.Title>Are you sure?</AlertDialog.Title>`,
+  false: ''
+});
+const description = instance.getBoolean('Description', {
+  true: `
+      <AlertDialog.Description>
+        This action cannot be undone.
+      </AlertDialog.Description>`,
+  false: ''
+});
+
+export default {
+  id: 'AlertDialog',
+  imports: ["import { AlertDialog } from '@raystack/apsara'"],
+  example: figma.code`<AlertDialog>
+  <AlertDialog.Trigger>Open</AlertDialog.Trigger>
+  <AlertDialog.Content>
+    <AlertDialog.Header>${title}${description}
+    </AlertDialog.Header>
+    <AlertDialog.Footer>
+      <AlertDialog.Close>Cancel</AlertDialog.Close>
+      <AlertDialog.Close>Continue</AlertDialog.Close>
+    </AlertDialog.Footer>
+  </AlertDialog.Content>
+</AlertDialog>`,
+  metadata: { nestable: false }
+};

packages/raystack/figma/alert-dialog.figma.ts

@@ -0,0 +1,29 @@
+// url=<FIGMA_LINK>?node-id=613-990
+// source=https://github.com/raystack/apsara/blob/main/packages/raystack/components/announcement-bar/announcement-bar.tsx
+// component=AnnouncementBar
+
+import figma from 'figma';
+
+const variant = figma.selectedInstance.getEnum('Variant', {
+  Error: 'error',
+  Gradient: 'gradient'
+});
+const text = figma.selectedInstance.getString('Message');
+const leadingIcon = figma.selectedInstance.getBoolean('Leading icon', {
+  true: figma.selectedInstance.getInstanceSwap('Icon')?.executeTemplate()
+    .example,
+  false: undefined
+});
+
+export default {
+  id: 'AnnouncementBar',
+  imports: ["import { AnnouncementBar } from '@raystack/apsara'"],
+  example: figma.code`<AnnouncementBar${figma.helpers.react.renderProp(
+    'variant',
+    variant
+  )}${figma.helpers.react.renderProp(
+    'text',
+    text
+  )}${figma.helpers.react.renderProp('leadingIcon', leadingIcon)}/>`,
+  metadata: { nestable: true }
+};

packages/raystack/figma/announcement-bar.figma.ts

@@ -0,0 +1,44 @@
+// url=<FIGMA_LINK>?node-id=1-24
+// source=https://github.com/raystack/apsara/blob/main/packages/raystack/components/avatar/avatar.tsx
+// component=Avatar
+
+import figma from 'figma';
+
+const radius = figma.selectedInstance.getEnum('Radius', {
+  Full: 'full'
+});
+const size = figma.selectedInstance.getEnum('Size', {
+  '1': 1,
+  '2': 2,
+  '4': 4,
+  '5': 5,
+  '6': 6,
+  '7': 7,
+  '8': 8,
+  '9': 9,
+  '10': 10,
+  '11': 11,
+  '12': 12,
+  '13': 13
+}); // '3' removed (default)
+const fallback = figma.selectedInstance.getString('Initials');
+const src = figma.selectedInstance.getBoolean('Image', {
+  true: 'https://example.com/avatar.png',
+  false: undefined
+});
+
+export default {
+  id: 'Avatar',
+  imports: ["import { Avatar } from '@raystack/apsara'"],
+  example: figma.code`<Avatar${figma.helpers.react.renderProp(
+    'radius',
+    radius
+  )}${figma.helpers.react.renderProp(
+    'size',
+    size
+  )}${figma.helpers.react.renderProp(
+    'src',
+    src
+  )}${figma.helpers.react.renderProp('fallback', fallback)}/>`,
+  metadata: { nestable: true }
+};