Skip to main content

Design Tokens Workflow Tutorial

Learn the complete workflow for managing design tokens between Figma and GitHub.

Time: 20 minutes Difficulty: Beginner

What You'll Learn​

  • Set up a tokens repository structure
  • Create and organize tokens in JSON
  • Pull tokens to create Figma Variables
  • Modify tokens in Figma
  • Push changes back to GitHub
  • Review changes via Pull Requests

Prerequisites​

  • GitFig installed and authenticated
  • A GitHub repository (we'll create one)
  • Basic familiarity with Figma Variables

Step 1: Create Repository Structure​

Create a new repository with this structure:

design-tokens/
├── tokens/
│   ├── colors.json
│   ├── spacing.json
│   └── typography.json
└── README.md

Step 2: Define Your Tokens​

colors.json​

{
  "brand": {
    "primary": {
      "$value": "#0066FF",
      "$type": "color",
      "$description": "Primary brand color for CTAs"
    },
    "secondary": {
      "$value": "#6B7280",
      "$type": "color",
      "$description": "Secondary text and borders"
    }
  },
  "background": {
    "default": {
      "$value": "#FFFFFF",
      "$type": "color"
    },
    "surface": {
      "$value": "#F9FAFB",
      "$type": "color"
    }
  },
  "text": {
    "primary": {
      "$value": "#111827",
      "$type": "color"
    },
    "secondary": {
      "$value": "#6B7280",
      "$type": "color"
    }
  }
}

spacing.json​

{
  "spacing": {
    "xs": { "$value": 4, "$type": "number" },
    "sm": { "$value": 8, "$type": "number" },
    "md": { "$value": 16, "$type": "number" },
    "lg": { "$value": 24, "$type": "number" },
    "xl": { "$value": 32, "$type": "number" }
  }
}

Step 3: Connect and Configure​

  1. Open GitFig in Figma
  2. Connect to your repository
  3. Configure mappings:
    • tokens/colors.json → Variables
    • tokens/spacing.json → Variables

Step 4: Pull Tokens​

Click Pull to create Variables from your JSON files.

Check the Variables panel - you should see:

  • brand/primary, brand/secondary
  • background/default, background/surface
  • text/primary, text/secondary
  • spacing/xs through spacing/xl

Step 5: Use Tokens in Your Designs​

Apply variables to your design elements:

  1. Select a shape
  2. Click the variable icon in the Fill property
  3. Choose a color variable

Step 6: Modify Tokens​

Change the primary brand color:

  1. Open Variables panel
  2. Edit brand/primary
  3. Change to #FF6600

Step 7: Push Changes​

  1. Click Push in GitFig
  2. Enter message: "Update primary brand color to orange"
  3. Push to GitHub

Step 8: Verify on GitHub​

Open your repository and check tokens/colors.json. The primary color should be updated.

Next Steps​