Automate Design Token Publishing with GitHub Actions

Why This Matters for Your Design System

The average design system team updates tokens 3-4 times per week. Every single update triggers the same ritual: export JSON, ping an engineer, wait for a PR, hope nothing broke. That is 150+ manual handoffs per year for something a 12-line YAML file can do in 40 seconds.

This workflow sets up that file. Once it runs, every token change you push to GitHub gets built and published automatically. No Slack message. No waiting. No drift.

---

Step 1: Understand the Pieces

Before you touch any configuration, it helps to know what GitHub Actions actually does.

GitHub Actions is an automation service built into every GitHub repository. You define a workflow (a YAML file) that tells GitHub: “When X happens, do Y.” In your case, X is “someone pushes token changes” and Y is “rebuild and publish the tokens.”

The workflow file lives in a special folder: .github/workflows/. GitHub watches this folder and runs whatever you define there.

Why this step matters: Understanding the mental model prevents confusion later. You are not installing software. You are writing a recipe that GitHub’s servers follow on your behalf.

---

Step 2: Create the Workflow File

In your repository on GitHub, create a new file at .github/workflows/publish-tokens.yml.

You can do this directly from the GitHub web interface. Click “Add file,” then “Create new file,” and type the full path including the folder names.

Paste this starter configuration:

name: Publish Design Tokens

on:
  push:
    paths:
      - "tokens/**"
    branches:
      - main

jobs:
  build-tokens:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Build tokens
        run: npm run build:tokens

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: design-tokens
          path: build/

Why this step matters: The paths filter is the key line. It tells GitHub to only run this workflow when files inside the tokens/ folder change. If someone updates a README or fixes a typo elsewhere, the pipeline stays quiet. This keeps your builds fast and your usage costs at zero for non-token changes.

---

Step 3: Configure the Token Build Command

The workflow references npm run build:tokens, which needs to exist in your package.json. If you are using Style Dictionary or a similar tool, this script should already be set up.

Add or verify this in your package.json:

{
  "scripts": {
    "build:tokens": "style-dictionary build"
  }
}

If you are not using Style Dictionary yet, set that up first before continuing here.

Why this step matters: The workflow is only as good as the build command it runs. If npm run build:tokens fails locally, it will fail in GitHub Actions too. Always test locally first by running the command in your terminal.

---

Step 4: Add Publishing (Optional but Recommended)

The basic workflow builds your tokens but does not publish them anywhere. To make the built tokens available as an npm package your engineering team can install, add a publishing step:

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

You will need to add your npm token as a repository secret. Go to your repository on GitHub, then Settings, then Secrets and Variables, then Actions. Click “New repository secret” and add NPM_TOKEN with your npm access token.

For teams that prefer a simpler approach, you can skip npm publishing entirely and have engineers pull the built files directly from the repository’s build/ folder.

Why this step matters: Publishing to npm creates a versioned, installable package. This means your engineering team runs npm update @yourcompany/tokens and gets your latest design decisions. No copying files, no manual downloads.

---

Step 5: Verify It Works

Make a small change to one of your token JSON files. Update a single color value, commit it, and push to main.

Then open the “Actions” tab in your GitHub repository. You should see your workflow running. Click into it to watch the logs in real time.

If the build succeeds, you will see green checkmarks next to each step. If something fails, the logs will tell you exactly which step broke and why.

Publish Design Tokens
  ✓ Checkout repository         (2s)
  ✓ Set up Node.js              (8s)
  ✓ Install dependencies        (12s)
  ✓ Build tokens                (3s)
  ✓ Upload build artifacts      (1s)

Why this step matters: The first run is always the most important. It validates your entire pipeline end to end. Once this works, every future token change follows the same path automatically.

---

What You Get

• Automatic builds on every token change. No manual steps, no forgotten exports.
• Consistent output across CSS, iOS, and Android (depending on your build tool).
• A clear audit trail. Every build is logged in the Actions tab with timestamps, commit references, and full output logs.
• Team confidence. Engineers know that the token package is always current because it is rebuilt on every push.

---

Common Pitfalls

• Forgetting to commit the workflow file. The YAML file must be in .github/workflows/ on the main branch for GitHub to detect it.
• Mismatched paths filter. If your tokens live in design-tokens/ instead of tokens/, update the paths value in the YAML accordingly.
• No package-lock.json. The npm ci command requires a lockfile. Run npm install locally first to generate one, then commit it.

---

Exercise

Set up the token publish workflow and watch it run

45 min

1. Create the workflow file and push it

   In your token repository, create .github/workflows/publish-tokens.yml using the YAML from Step 2. Confirm that npm run build:tokens exists in package.json and works locally. Commit the workflow file to main.

   • .github/workflows/publish-tokens.yml is committed to main
   • npm run build:tokens runs clean in your local terminal
   • The Actions tab in GitHub lists the new workflow by name

2. Trigger a real run and read the logs

   Edit one token value in a JSON file under tokens/. Commit and push to main. Open the Actions tab and click into the running workflow. Watch each step turn green or fail with a readable error. If it fails, fix the surfacing issue (usually a missing lockfile or a bad script name) and push again.

   • The workflow triggers automatically on your token change, not on unrelated commits
   • Every step shows a green check, including Build tokens
   • The design-tokens artifact appears on the run page and can be downloaded