Автоматична синхронізація Figma: дизайн-токени та ассети

Чому ручний експорт дизайн-ассетів гальмує розробку?

Кожного разу, коли дизайнер оновлює іконку або змінює колірну палітру, розробка зупиняється. Потрібно вручну вивантажити новий SVG, перевірити hex-коди, оновити CSS-змінні. На одну правку йде 15–30 хвилин. У масштабі дизайн-системи з сотнями токенів це години щотижневої роботи. Кейс: команда з 5 дизайнерів витрачала 10 годин на тиждень на експорт іконок. Після інтеграції — 20 хвилин. Помилки неминучі: скопіювали не той колір, забули експортувати іконку. Результат — інтерфейс відрізняється від макета.

Ми автоматизуємо цей процес через Figma API. Дизайнер працює у Figma, а код оновлюється автоматично. Більше жодних ручних вивантажень та розсинхрону. Автоматична синхронізація займає 5 хвилин замість 2–3 годин, що у 24 рази швидше ручного експорту. За даними Figma, такий підхід скорочує час синхронізації на 95%.

Які проблеми вирішує інтеграція Figma API?

Розсинхрон дизайн-системи

Дизайн-команда змінює стилі, але розробники не встигають оновлювати код. Через тиждень інтерфейс вже не відповідає макетам. Наша інтеграція вирішує це: після кожної зміни у Figma (або за розкладом) токени автоматично потрапляють до репозиторію.

Ручний експорт ассетів

Іконки, ілюстрації, логотипи — все це потрібно вивантажувати вручну. Неправильний nodeId, не той формат, втрачені файли. Figma API робить експорт надійним: виклик одного ендпоінта — і всі ассети завантажені у потрібному форматі.

Версіонування токенів

Токени зберігаються лише у Figma. Розробники дізнаються про зміни постфактум. Ми створюємо єдине джерело істини: токени у Figma → токени у CSS/SCSS → Git. Історія змін зберігається.

Як автоматизація усуває помилки?

На прикладі типового проекту: налаштовуємо скрипт, який парсить стилі Figma та генерує CSS-змінні. Помилки зводяться до нуля, тому що машина не помиляється у копіюванні. Людський фактор виключений. Статистика: 95% токенів синхронізуються без помилок після впровадження.

Кейс з практики. Дизайн-система на 120+ компонентів. Раніше оновлення токенів займало 4–6 годин щотижнево. Після інтеграції — 5 хвилин роботи GitHub Actions. Помилки при копіюванні кольорів зникли.

Як влаштована інтеграція Figma API?

Використовуємо офіційний Figma API для вилучення даних. Нижче — ключові етапи та приклади коду.

Аутентифікація

const FIGMA_TOKEN = process.env.FIGMA_ACCESS_TOKEN;
async function figmaRequest(path: string): Promise<any> {
  const resp = await fetch(`https://api.figma.com/v1${path}`, {
    headers: {
      'X-Figma-Token': FIGMA_TOKEN!,
    },
  });
  return resp.json();
}

Експорт ассетів з Figma

async function exportAssets(fileKey: string, nodeIds: string[]): Promise<Record<string, string>> {
  // Отримуємо URL для експорту
  const resp = await figmaRequest(
    `/images/${fileKey}?ids=${nodeIds.join(',')}&format=svg&svg_simplify_stroke=true`
  );
  const urls: Record<string, string> = resp.images;

  // Завантажуємо та зберігаємо
  for (const [nodeId, url] of Object.entries(urls)) {
    const svgContent = await fetch(url).then(r => r.text());
    const filename = nodeId.replace(':', '-');
    fs.writeFileSync(`./assets/icons/${filename}.svg`, svgContent);
  }

  return urls;
}

Вилучення дизайн-токенів

async function extractDesignTokens(fileKey: string): Promise<DesignTokens> {
  const file = await figmaRequest(`/files/${fileKey}`);
  const tokens: DesignTokens = { colors: {}, typography: {}, spacing: {} };
  // Кольори зі стилів
  const styles = await figmaRequest(`/files/${fileKey}/styles`);
  for (const style of styles.meta.styles) {
    if (style.style_type === 'FILL') {
      const node = await figmaRequest(`/files/${fileKey}/nodes?ids=${style.node_id}`);
      const fill = node.nodes[style.node_id].document.fills[0];
      if (fill.type === 'SOLID') {
        tokens.colors[style.name] = rgbToHex(fill.color);
      }
    }
  }
  return tokens;
}

function rgbToHex({ r, g, b }: {r: number, g: number, b: number}): string {
  const toHex = (v: number) => Math.round(v * 255).toString(16).padStart(2, 0);
  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
}

Генерація CSS-змінних з токенів

function tokensToCSS(tokens: DesignTokens): string {
  const vars = Object.entries(tokens.colors)
    .map(([name, value]) => ` --color-${name.toLowerCase().replace(/\s+/g, '-')}: ${value};`)
    .join('\n');
  return `:root {\n${vars}\n}`;
}

Автоматизація через GitHub Actions

---
# .github/workflows/sync-tokens.yml
name: Sync Figma Tokens
on:
  schedule:
    - cron: '0 9 * * 1' # кожен понеділок о 9:00
  workflow_dispatch:
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: node scripts/sync-figma-tokens.js
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
      - name: Commit updated tokens
        run: |
          git add src/styles/tokens.css
          git commit -m "chore: sync design tokens from Figma" || exit 0
          git push

Процес роботи

Терміни: від 7 до 10 робочих днів під ключ. Вартість розраховується індивідуально, залежить від кількості токенів та файлів. Отримайте консультацію щодо вашого проекту — оцінимо обсяг робіт за 2 дні.

Чек-лист типових помилок

• Неправильний file_key — перевіряйте URL файлу Figma.
• Токен доступу з минулим терміном дії — використовуйте Personal Access Token без терміну дії або OAuth refresh.
• Відсутність прав на читання файлу — файл має бути в команді.
• Неправильні nodeId — nodeId змінюються при копіюванні шарів. Використовуйте плагін для отримання стабільних id.

Що входить у роботу

• Документація щодо API-методів та конфігурації інтеграції.
• Вихідний код скриптів з коментарями.
• Налаштування CI/CD пайплайну (GitHub Actions).
• Навчання команди (1 година онлайн).
• Гарантія коректної роботи протягом 30 днів.

Наш досвід — понад 20 проектів з інтеграції дизайн-систем з Figma. Економія бюджету на рутинній синхронізації досягає 90%. Хочете забути про ручний експорт? Зв'яжіться з нами — оцінимо ваш проект за 2 дні. Замовте інтеграцію та отримайте стабільну синхронізацію без помилок.