همگام‌سازی خودکار توکن‌های فیگما با کدهای Tailwind بدون افت هماهنگی تیم

بدون پایپ‌لاین، توکن‌های طراحی بعد از هر بار «چیدن دستی در کد» از فیگما فاصله می‌گیرند و تیم بین دو نسخه از حقیقت سرگردان می‌شود. در این مقاله، خط لوله‌ای را شرح می‌دهیم که فیگما را منبع واحد حقیقت نگه می‌دارد و هر push، کد را با طراحی هم‌قفل می‌کند.

منبع واحد حقیقت: Variables در فیگما

توکن‌ها را به‌جای Styles، در Variables تعریف می‌کنیم — چون فقط Variables مدل مجموعه (collections) و mode دارند و می‌توان برای فارسی/انگلیسی یا تیره/روشن مقدار مجزا تعریف کرد:

• color/bg/base با modeهای light و dark
• space/md با مقدار عددی یکسان در همه مدها
• font/size/body متصل به تایپ‌استایل سازنده

خروجی‌گیری با REST API و تبدیل به توکن

اسکریپت CI با PAT فیگما، Variables را می‌خواند و به فرمت W3C DTCG تبدیل می‌کند:

import { getLocalVariables, themeToJSON } from "@figma/rest-api-spec";

export async function exportTokens(fileKey: string, pat: string) {
  const vars = await getLocalVariables(fileKey, pat);
  const tokens = themeToJSON(vars); // ساختار سلسله‌مراتبی توکن‌ها
  await writeFile("design/tokens.json", JSON.stringify(tokens, null, 2));
  return Object.keys(tokens).length;
}

سپس یک تبدیل‌کننده سبک، همان JSON را به دو خروجی می‌رساند: پیکربندی Tailwind و تایپ‌های TypeScript.

// design/tailwind-plugin.ts — بخش کلیدی تبدیل توکن به پیکربندی
import tokens from "./tokens.json";

export const colors = {
  bg: { base: tokens.color["bg/base"].value },
  brand: { moon: tokens.color["brand/moon"].value },
};

export const spacing = Object.fromEntries(
  Object.entries(tokens.space).map(([k, v]) => [k, (v as { value: number }).value]),
);

قفل کردن CI: بدون هم‌گام‌سازی، merge نکنید

در GitHub Actions، job مخصوصی توکن‌ها را regenerate و با فایل commit‌شده مقایسه می‌کند؛ اگر تفاوتی باشد، همان job فایل‌ها را به‌روز می‌کند و اگر باز هم کسی دستی تغییر داده باشد، build قرمز می‌شود:

name: design-tokens
on: [push, pull_request]
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm tokens:export        # فیگما ← tokens.json
      - run: pnpm tokens:build         # tokens.json ← tailwind + types
      - run: git diff --exit-code design/ # خروجی commit‌نشده = خطا

نتایج تیم

معیار	قبل از پایپ‌لاین	بعد
تعداد نسخه رنگ در کد	۱۴ مقدار هم‌نام متفاوت	۱ منبع
زمان اعمال یک تغییر برند	~۲ روز کاری (دستی)	زیر ۱۰ دقیقه
دعواهای طراح/توسعه‌دهنده	هفتگی	فقط در review اولیه

نتیجه‌گیری

هماهنگی طراحی و توسعه یک مسئله فرهنگی نیست؛ یک مسئله لوله‌کشی است. وقتی تغییرِ فیگما بدون دخالت دستی در کد می‌نشیند، طراح بدون ترس تغییر می‌دهد و توسعه‌دهنده بدون ترس merge می‌کند.