Figma Variables для AI-кодогенерації — навіщо вони потрібні і що робити без них

Figma Variables з'явилися у 2023 році як довгоочікувана відповідь платформи на дизайн-токени. Функція потужна: іменовані колекції примітивних значень — кольори, числа, рядки, булеві значення — які можна прив'язати до будь-якої властивості в будь-якому компоненті. Змініть змінну — кожен екземпляр оновиться. Додайте колекцію темного режиму — кожна прив'язка змінної автоматично перемикається.

Для AI-кодогенерації Variables не просто корисні. Вони є механізмом, що перетворює файл Figma з піксельно точного макету на специфікацію, яку ваш агент може реалізувати правильно. Коли колір має ім'я — color/brand/primary, а не #7F5CFE — агент може відобразити його на токен коду, правильно реалізувати темний режим і виробити вивід, що бере участь у вашій реальній дизайн-системі.

Ось проблема: більшість файлів Figma в активному використанні сьогодні не мають налаштованих Variables. figmascope обробляє обидва випадки. Ця стаття пояснює як.

Що насправді являють собою Variables

Figma Variable — це іменований скаляр, прив'язаний до колекції. Колекції організовують змінні за режимом — "Light" і "Dark" є канонічним прикладом. Кожна змінна в колекції може мати різні значення для кожного режиму: color/surface/background — це #FFFFFF у Light та #0D0D0D у Dark. Прив'язка поширюється: кожна заливка, що посилається на color/surface/background, оновлюється під час перемикання режимів.

Variables можуть бути кольорами, числами, рядками або булевими значеннями. На практиці найбільш впливові — кольори та числа, що охоплює більшу частину поверхні токенів у типовій дизайн-системі: колірна палітра, шкала відступів, радіуси границь, розміри шрифтів, значення піднесення.

Figma надає Variables через REST API як колекцію localVariables. Кожна змінна має ID, ім'я, тип і значення для кожного режиму. Властивості компонентів, що посилаються на змінні, несуть поле boundVariables з ID змінної. Це структуровані дані, що чисто проходять через пайплайн вилучення.

Щасливий шлях: Variables присутні

Коли файл Figma має Variables, figmascope зчитує їх з API та будує tokens.json за структурою, сумісною з W3C Design Tokens Community Group. Кожен токен має $value та $type. Токени кольорів отримують hex-значення з опціональним альфа. Токени відступів отримують числові значення з підказкою одиниці px. Ім'я токена відповідає шляху колекції та імені змінної:

{
  "color": {
    "brand": {
      "primary": { "$value": "#7F5CFE", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#FFFFFF", "$type": "color" }
    }
  },
  "spacing": {
    "4": { "$value": 4, "$type": "number" },
    "8": { "$value": 8, "$type": "number" },
    "16": { "$value": 16, "$type": "number" }
  }
}

Коли будується покроковий IR, кожна заливка, що мала посилання boundVariables, отримує ім'я токена замість розв'язаного hex. Вузол несе:

"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]

Не #7F5CFE. Ім'я токена. Агент читає це і генерує background-color: var(--color-brand-primary) або Color.brandPrimary, або що завгодно, що є патерном споживання токенів цільового фреймворку. Це вивід, який ви хочете: код, з'єднаний з вашою дизайн-системою, а не код, що зламається, щойно дизайнер оновить колір.

Семантичне іменування — це різниця між кодом, що добре старіє, і кодом, що дрейфує. Hex-значення у вихідному коді — це зобов'язання; посилання на токен — це контракт. Variables — це те, що робить файли Figma здатними виражати контракти, а не просто пікселі.

Реальність: у більшості файлів немає Variables

Variables вимагають тарифного плану Figma Professional або вище. Вони вимагають дизайнера, який їх налаштував — що означає створення колекцій, іменування змінних і ручне прив'язування їх до кожної властивості компонента. У зрілому, добре підтримуваному файлі дизайн-системи це зроблено. У продуктовому Figma стартапу, файлі клієнта фрілансера або будь-якому файлі, що передує функції Variables, зазвичай ні.

figmascope був розроблений корисним і для таких файлів. Він деградує витончено: коли Variables відсутні, він повертається до виведення токенів за частотністю.

Резервний варіант: inferred-from-frequency

Алгоритм виведення працює так:

Обходить кожен листовий вузол у кожному експортованому фреймі.
Збирає всі кольори заливок, значення відступів та радіуси границь.
Підраховує входження кожного унікального значення.
Значення, що з'являються вище порогу частотності, просуваються до виведених токенів.
Кожен токен отримує ім'я, похідне від значення: color.7f5cfe, spacing.16, radius.8.

Вивід tokens.json структурно схожий на шлях Variables, але імена є похідними від значень, а не семантичними:

{
  "color": {
    "7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
    "f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
  },
  "spacing": {
    "16": { "$value": 16, "$type": "number" },
    "8": { "$value": 8, "$type": "number" }
  }
}

В IR вузли, що використовують ці значення, отримують посилання на токени: "tokenRef": "color.7f5cfe". Не захардкоджені літерали. Посилання — просто на виведені токени, а не іменовані.

Агент все одно генерує код з посиланнями на токени. var(--color-7f5cfe) не такий читабельний, як var(--color-brand-primary), але це все одно токен — ви можете знайти і замінити його, перейменувати, перевірити його використання. Це іменований дескриптор значення, а не магічне число.

Поле tokensSource

Кожен бандл figmascope включає _meta.json, що документує вміст бандлу і спосіб його виробництва. Поле tokensSource має три можливих значення:

figma-variables — Variables були присутні та використані. Імена токенів семантичні.
inferred-from-frequency — Variables не знайдено. Токени виведені з частотності значень. Імена похідні від значень.
none — Токени не могли бути вилучені або виведені. IR використовує розв'язані значення безпосередньо.

Це важливо, бо повідомляє споживаючому агенту (і розробнику, що читає бандл) точно, наскільки довіряти іменам токенів. Бандл figma-variables є джерелом правди для вашої дизайн-системи. Бандл inferred-from-frequency — корисний структурний каркас, що потребує рев'ю іменування дизайнером до того, як стати канонічним. Бандл none — відправна точка із захардкодованими значеннями, що потребують токенізації пізніше.

Чесні метадані недооцінені. Інструменти, що мовчки виводять без позначення виводу, створюють хибну впевненість. figmascope явно відображає ланцюжок виводу, щоб ви знали, з чим працюєте.

Чому виведення за частотністю краще ніж нічого

Альтернативою виведенню за частотністю є виведення розв'язаних літеральних значень скрізь — #7F5CFE у кожному вузлі заливки, що використовує цей колір. Це виробляє код, який важче рефакторити, важче перевіряти та важче підключити до дизайн-системи, коли вона врешті додається.

Виведення за частотністю щонайменше вилучає набір значень, що дизайн насправді використовує. Якщо #7F5CFE з'являється 47 разів по всьому дизайну, це сигнал: це основний колір, а не акцентний. Ім'я токена цього не знає — це просто color.7f5cfe — але дані частотності розповідають історію.

Практичніше: виведення за частотністю дає вам tokens.json, що дифується між версіями. Якщо ви двічі експортуєте один файл після того, як дизайнер змінив повторюваний колір, диф показує зміну значення токена. Без виведення ви б переслідували кожну окрему літеральну зміну, розкидану по кількох IR-файлах.

Що дизайнери все одно мають робити

Виведення за частотністю — це шар сумісності, а не замінник Variables. Правильний шлях — щоб дизайнери прийняли Variables для всіх значень, що беруть участь у дизайн-системі: фірмові кольори, нейтральна шкала, шкала відступів, радіуси границь, піднесення, типографіка. Як тільки вони налаштовані, бандл figmascope переходить від токенів якості каркасу до токенів виробничої якості.

Variables також розблоковують тематизацію в бандлі: кілька значень режиму на токен. Файл зі режимами Light/Dark виробляє tokens.json зі значеннями для кожного режиму, що безпосередньо вмикається у CSS custom properties з перевизначеннями медіа-запитів, або специфічні для платформи об'єкти теми. Це неможливо вивести з одного знімка дизайну — це вимагає явного наміру дизайнера, вираженого через Variables.

Шлях оновлення є поступовим. Команда може починати з токенів якості виведення сьогодні, поступово приймати Variables по мірі зрілості дизайн-системи і автоматично отримувати кращі бандли в процесі. Поле tokensSource відстежує, де ви знаходитесь у цьому прогресі.

Повний пайплайн токенів

Щоб зробити це конкретним, ось повний порядок розв'язання, який figmascope використовує для кожної заливки в IR:

Чи має вузол посилання boundVariables.fills? Якщо так, розв'яжіть до імені змінної та значення режиму-нуль. Джерело токена: figma-variables.
Чи присутнє розв'язане значення у виведених частотних токенах (вище порогу)? Якщо так, відобразіть на виведене ім'я токена. Джерело токена: inferred-from-frequency.
В іншому випадку: використовуйте розв'язане hex-значення безпосередньо. Без посилання на токен. Джерело токена: none.

Кроки випробовуються по порядку. Виграє найвищоякісне джерело. Поле tokensSource в _meta.json відображає домінуючий шлях для бандлу в цілому.

Це означає, що частково Variables-зований файл — де деякі компоненти мають прив'язки, а інші ні — виробляє змішаний бандл. Іменовані токени там, де вони існують, виведені токени там, де їх немає. Це правильна поведінка: використовуйте кожен фрагмент структурованої інформації, що доступна, витончено деградуйте там, де її немає, і чесно вказуйте, який шлях пройшло кожне значення.

Експортуйте ваш бандл з застосунку figmascope, щоб побачити, який tokensSource виробляє ваш файл. Потім використовуйте бандл з Claude Code або Cursor для точної генерації коду з посиланнями на токени.