Figma Variables dla AI Codegen — Dlaczego mają znaczenie i co robić bez nich

Figma Variables pojawiły się w 2023 roku jako długo oczekiwana odpowiedź platformy na design tokens. Funkcja jest potężna: nazwane kolekcje prymitywnych wartości — kolory, liczby, ciągi, wartości logiczne — które można powiązać z dowolną właściwością dowolnego komponentu. Zmień zmienną, a każda instancja się zaktualizuje. Dodaj kolekcję trybu ciemnego, a każde powiązanie zmiennej automatycznie się zmieni.

Dla AI codegen Variables nie są tylko przydatne. Są mechanizmem, który przekształca plik Figma z pikselowo precyzyjnego makietu w specyfikację, którą agent może poprawnie zaimplementować. Gdy kolor ma nazwę — color/brand/primary, a nie #7F5CFE — agent może go zmapować na token kodu, poprawnie zaimplementować tryb ciemny i wygenerować wynik, który uczestniczy w Twoim faktycznym systemie projektowania.

Problem polega na tym, że większość aktywnie używanych plików Figma nie ma skonfigurowanych Variables. figmascope obsługuje oba przypadki. Ten artykuł wyjaśnia, jak.

Czym są Variables

Figma Variable to nazwany skalar powiązany z kolekcją. Kolekcje organizują zmienne według trybów — "Light" i "Dark" to kanoniczny przykład. Każda zmienna w kolekcji może mieć różne wartości na tryb: color/surface/background to #FFFFFF w Light i #0D0D0D w Dark. Powiązanie propaguje się: każde wypełnienie odwołujące się do color/surface/background aktualizuje się przy przełączeniu trybu.

Variables mogą być kolorami, liczbami, ciągami lub wartościami logicznymi. W praktyce najbardziej wpływowe są kolory i liczby — co pokrywa większość powierzchni tokenów w typowym systemie projektowania: paleta kolorów, skala odstępów, promienie zaokrąglenia, rozmiary czcionek, wartości elewacji.

Figma udostępnia Variables poprzez REST API jako kolekcję localVariables. Każda zmienna ma ID, nazwę, typ i wartości na tryb. Właściwości komponentów odwołujące się do zmiennych niosą pole boundVariables z ID zmiennej. To dane strukturalne, które przepływają czysto przez pipeline ekstrakcji.

Ścieżka szczęśliwa: Variables są obecne

Gdy plik Figma ma Variables, figmascope czyta je z API i buduje tokens.json zgodny ze strukturą W3C Design Tokens Community Group. Każdy token ma $value i $type. Tokeny kolorów mają wartości hex z opcjonalną alfą. Tokeny odstępów mają wartości liczbowe z wskazówką jednostki px. Nazwa tokenu podąża za ścieżką kolekcji i nazwy zmiennej:

{
  "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" }
  }
}

Gdy budowane jest per-screenowe IR, każde wypełnienie mające referencję boundVariables otrzymuje nazwę tokenu zamiast rozwiązanego hex. Węzeł niesie:

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

Nie #7F5CFE. Nazwę tokenu. Agent czyta to i generuje background-color: var(--color-brand-primary) lub Color.brandPrimary czy cokolwiek innego pasuje do wzorca konsumpcji tokenów docelowego frameworka. To właśnie chcesz: kod podłączony do systemu projektowania, a nie kod, który zepsuje się, gdy projektant zaktualizuje kolor.

Semantyczne nazewnictwo to różnica między kodem, który dobrze się starzeje, a kodem, który dryfuje. Wartość hex w źródle to zobowiązanie; referencja do tokenu to kontrakt. Variables to to, co sprawia, że pliki Figma mogą wyrażać kontrakty, a nie tylko piksele.

Rzeczywistość: większość plików nie ma Variables

Variables wymagają planu Figma Professional lub wyższego. Wymagają projektanta, który je skonfigurował — co oznacza tworzenie kolekcji, nazewnictwo zmiennych i ręczne powiązywanie ich z każdą właściwością komponentu. W dojrzałym, dobrze utrzymanym pliku systemu projektowania jest to zrobione. W Figmie produktowej startupu, pliku klienta freelancera lub każdym pliku sprzed funkcji Variables — zazwyczaj nie.

figmascope był zaprojektowany by być użytecznym również dla tych plików. Degraduje się łagodnie: gdy Variables są nieobecne, cofa się do inferencji tokenów opartej na częstotliwości.

Fallback: wnioskowane z częstotliwości

Algorytm inferencji działa tak:

Przejdź przez każdy węzeł liścia w każdej wyeksportowanej ramce.
Zbierz wszystkie kolory wypełnień, wartości odstępów i promienie zaokrąglenia.
Policz wystąpienia każdej unikalnej wartości.
Wartości pojawiające się powyżej progu częstotliwości są promowane do wnioskowanych tokenów.
Każdy token dostaje nazwę wyprowadzoną z wartości: color.7f5cfe, spacing.16, radius.8.

Wynikowy tokens.json wygląda strukturalnie podobnie do ścieżki Variables, ale nazwy są wyprowadzone z wartości, nie semantyczne:

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

W IR węzły używające tych wartości dostają referencje tokenów: "tokenRef": "color.7f5cfe". Nie zahardkodowane literały. Referencje — tyle że do wnioskowanych tokenów, nie nazwanych.

Agent nadal generuje kod z referencjami do tokenów. var(--color-7f5cfe) nie jest tak czytelne jak var(--color-brand-primary), ale to nadal token — możesz go find-and-replace, zmienić jego nazwę, sprawdzać jego użycie. To nazwany uchwyt na wartość, nie magiczna liczba.

Pole tokensSource

Każdy pakiet figmascope zawiera _meta.json dokumentujący zawartość pakietu i sposób jego wytworzenia. Pole tokensSource ma trzy możliwe wartości:

figma-variables — Variables były obecne i użyte. Nazwy tokenów są semantyczne.
inferred-from-frequency — Nie znaleziono Variables. Tokeny zostały wnioskowane z częstotliwości wartości. Nazwy są wyprowadzone z wartości.
none — Nie można było wyekstrahować ani wywnioskować tokenów. IR używa bezpośrednio rozwiązanych wartości.

Ma to znaczenie, ponieważ mówi agentowi konsumującemu (i deweloperowi czytającemu pakiet) dokładnie, ile można zaufać nazwom tokenów. Pakiet figma-variables jest źródłem prawdy dla systemu projektowania. Pakiet inferred-from-frequency to użyteczna struktura rusztowania, która wymaga przeglądu nazewnictwa przez projektanta przed kanonizacją. Pakiet none to punkt startowy z zahardkodowanymi wartościami, które trzeba tokenizować później.

Szczere metadane są niedoceniane. Narzędzia, które cicho wnioskują bez flagowania tego jako inferencję, tworzą fałszywe zaufanie. figmascope explicite ujawnia łańcuch inferencji, abyś wiedział, z czym pracujesz.

Dlaczego inferencja z częstotliwości jest lepsza niż nic

Alternatywą dla inferencji z częstotliwości jest wszędzie wypisywanie rozwiązanych wartości literalnych — #7F5CFE w każdym węźle wypełnienia używającym tego koloru. To produkuje kod trudniejszy do refaktoryzacji, trudniejszy do audytowania i trudniejszy do połączenia z systemem projektowania, gdy w końcu zostanie dodany.

Inferencja z częstotliwości co najmniej wyodrębnia zestaw wartości, których projekt faktycznie używa. Jeśli #7F5CFE pojawia się 47 razy w projekcie, to sygnał: to kolor główny, nie akcentowy. Nazwa tokenu tego nie wie — to tylko color.7f5cfe — ale dane częstotliwości opowiadają historię. Agent z wnioskowanymi tokenami może rozsądnie zgadywać, które wartości są główne, a które jednorazowe.

Bardziej praktycznie: inferencja z częstotliwości daje tokens.json, który można diffować między wersjami. Jeśli wyeksportujesz ten sam plik dwa razy po tym, jak projektant zmienił powtarzający się kolor, diff pokaże zmienioną wartość tokenu. Bez inferencji, śledzenie każdej indywidualnej zmiany literału rozproszonej po wielu plikach IR byłoby żmudne.

Co projektanci nadal powinni robić

Inferencja z częstotliwości to warstwa kompatybilności, nie substytut dla Variables. Właściwa ścieżka to adopcja Variables przez projektantów dla wszystkich wartości uczestniczących w systemie projektowania: kolory marki, skala neutralna, skala odstępów, promienie zaokrąglenia, elewacja, typografia. Gdy te będą na miejscu, pakiet figmascope przejdzie od tokenów jakości rusztowania do tokenów jakości produkcyjnej.

Variables odblokowują też motywowanie w pakiecie: wiele wartości trybów na token. Plik z trybami Light/Dark produkuje tokens.json z wartościami na tryb, które zasilają bezpośrednio CSS custom properties z nadpisaniami media query lub obiektami motywów specyficznymi dla platformy. Tego nie można wnioskować z pojedynczej migawki projektu — wymaga to explicite wyrażonego zamiaru projektanta, wyrażonego przez Variables.

Ścieżka aktualizacji jest inkrementalna. Zespół może zacząć z tokenami jakości inferencji dziś, stopniowo adoptować Variables w miarę dojrzewania systemu projektowania i automatycznie otrzymywać lepsze pakiety. Pole tokensSource śledzi, gdzie jesteś w tej progresji.

Pełny pipeline tokenów

Żeby było konkretnie, oto pełna kolejność rozwiązywania stosowana przez figmascope dla każdego wypełnienia w IR:

Czy węzeł ma referencję boundVariables.fills? Jeśli tak, rozwiąż do nazwy zmiennej i wartości trybu zerowego. Źródło tokenów: figma-variables.
Czy rozwiązana wartość jest obecna w wnioskowanych tokenach częstotliwości (powyżej progu)? Jeśli tak, zmapuj na wnioskowaną nazwę tokenu. Źródło tokenów: inferred-from-frequency.
W przeciwnym razie: użyj bezpośrednio rozwiązanej wartości hex. Brak referencji do tokenu. Źródło tokenów: none.

Kroki są próbowane po kolei. Wygrywa źródło najwyższej jakości. Pole tokensSource w _meta.json odzwierciedla dominującą ścieżkę dla pakietu jako całości.

Oznacza to, że częściowo skonfigurowany plik Variables — gdzie niektóre komponenty mają powiązania, a inne nie — produkuje mieszany pakiet. Nazwane tokeny tam, gdzie istnieją, wnioskowane tokeny tam, gdzie nie. To właściwe zachowanie: używaj każdego skrawka dostępnych informacji strukturalnych, łagodnie cofaj się tam, gdzie ich brakuje, i bądź szczery co do ścieżki każdej wartości.

Wyeksportuj pakiet z aplikacji figmascope, by zobaczyć, jakie tokensSource produkuje Twój plik. Następnie użyj pakietu z Claude Code lub Cursor do precyzyjnego generowania kodu z referencjami do tokenów.