Cursor Composer potrafi wygenerować sporo kodu UI. Czego nie potrafi — to odczytać pliku Figma. Wklej zrzut ekranu, a zgaduje: błędne odstępy, wymyślone wartości kolorów, nazwy komponentów niespójne z kodem. Problem nie leży w modelu. Brakuje ustrukturyzowanego kontekstu.
figmascope rozwiązuje ten problem. Eksportuje plik Figma jako pakiet zip: design tokens, drzewa układu dla każdego ekranu, podglądy referencyjne 2×, inwentarz komponentów i ciągi UI — wszystko, czego agent Cursor potrzebuje, by generować precyzyjny kod zamiast kodu, który jedynie wygląda poprawnie.
Ten przewodnik obejmuje pełny pipeline: URL Figma → pakiet kontekstowy → prompt do Cursor → przegląd wyniku.
Co zawiera pakiet
Gdy figmascope eksportuje plik, zip zawiera:
CONTEXT.md— specyfikacja, którą agent czyta jako pierwszą. Zawiera docelowy framework, źródła tokenów, ograniczenia i znane luki.tokens.json— typowane design tokens: odstępy, border-radius, kolor, typografia.screens/<name>.json— pośrednia reprezentacja ekranu: węzły stack/overlay/absolute/leaf z wypełnieniami, odstępami i referencjami do ciągów.screens/<name>.png— podglądy referencyjne 2× do weryfikacji wizualnej.components/inventory.json— id, nazwa i typ komponentu.strings.json— ciągi UI z kluczami zasobów w notacji z kropką._meta.json— manifest buildu: nazwa pliku źródłowego, znacznik czasu eksportu, ostrzeżenia.
Pakiet pozostaje na Twoim komputerze. Nigdy nie jest ponownie przesyłany.
Krok 1: Wygeneruj pakiet
Przejdź do figmascope i wklej URL pliku Figma w pole wejściowe. Eksporter działa w przeglądarce przez Figma REST API — za pierwszym razem potrzebny jest personal access token (przechowywany w localStorage, nigdy nie wysyłany na serwery figmascope).
Naciśnij Eksportuj kontekst agenta. Strona przetwarza każdą ramkę, rozwiązuje tokeny, buduje IR, a następnie pobiera context-bundle.zip na Twój komputer.
Jeśli plik ma wiele ramek, uwzględniane są tylko ramki najwyższego poziomu, które nie są komponentami ani miniaturami. _meta.json pokazuje dokładnie, które ramki zostały wyeksportowane i ewentualne ostrzeżenia (wypełnienia gradientowe, nieobsługiwane efekty).
Krok 2: Rozpakuj do projektu
Umieść pakiet tam, gdzie Cursor może go zobaczyć — katalog design/ w katalogu głównym repozytorium to najczystszy wzorzec.
# z katalogu głównego projektu
unzip ~/Downloads/context-bundle.zip -d ./design/
# sprawdź strukturę
ls design/
# CONTEXT.md _meta.json components/ screens/ strings.json tokens.jsonDodaj design/ do .gitignore, jeśli nie chcesz commitować pakietu. Lub go commituj — jest deterministyczny; ten sam plik Figma w tym samym stanie zawsze produkuje ten sam pakiet, więc diffy mają sens.
Krok 3: Dodaj snippet do .cursorrules
Cursor odczytuje .cursorrules z katalogu głównego repozytorium i dołącza go do każdego kontekstu czatu. Tu podłączasz agenta do pakietu.
# .cursorrules
When building UI screens:
1. Read ./design/CONTEXT.md first. It specifies the target framework and constraints.
2. Use tokens from ./design/tokens.json for all spacing, color, radius, and typography values.
3. Reference ./design/screens/<name>.json for layout structure and node hierarchy.
4. Match ./design/screens/<name>.png for visual confirmation — use it as a sanity check, not the source of truth.
5. Use string keys from ./design/strings.json rather than hardcoding UI copy.
6. Do not invent token values. If a value isn't in tokens.json, flag it.Ten jeden blok zapobiega trzem najczęstszym źródłom dryftu: wymyślonym kolorom, zahardkodowanym ciągom i zgadywaniu układu ze zrzutu ekranu.
Krok 4: Otwórz Cursor Composer i zaimplementuj ekran
Otwórz Composer (Cmd+I na macOS). Przypnij pliki przed promptem: kliknij ikonę spinacza i dodaj design/CONTEXT.md, design/tokens.json oraz design/screens/home.json. Następnie wpisz prompt:
Implement the home screen from ./design/screens/home.json.
Constraints:
- Target framework and component conventions are in ./design/CONTEXT.md
- All spacing, color, and radius values must come from ./design/tokens.json
- UI strings must use keys from ./design/strings.json
- The root node is a stack (vertical). Children are declared in order in the JSON.
- Do not invent any values not present in the token or IR files.Cursor odczyta przypięte pliki, zmapuje węzły IR na prymitywy Twojego frameworka i wygeneruje implementację. Wynik odwołuje się do tokenów — jeśli sprawdzisz wygenerowany kod, każda wartość odstępu powinna dawać się prześledzić do klucza w tokens.json.
Krok 5: Przejrzyj i iteruj
Otwórz design/screens/home.png obok wyrenderowanego wyniku. PNG to eksport 2× z Figmy — pokazuje dokładnie, jak powinien wyglądać projekt. Różnice są znaczące: wskazują albo na luki w mapowaniu IR, albo na wartości tokenów, które nie zostały zastosowane.
Typowe problemy i promptowe odpowiedzi:
Dryft tokenów — agent użył zahardkodowanego hex zamiast tokenu:
Compare every color value in the generated component against ./design/tokens.json.
List any colors that don't match a token key. Replace them with the correct token reference.Brakujący komponent — IR odwołuje się do ID komponentu, którego agent nie rozwiązał:
The IR references componentId "btn-primary-01". Check ./design/components/inventory.json
for its name and type, then implement a placeholder with that name and the correct token values.Zły układ — odstępy lub wyrównanie nie zgadzają się z PNG:
The vertical gap between the header and the card list should be spacing.24 from tokens.json (24dp).
Your output uses 16px. Fix it.Co działa, co nie
Działa dobrze: płaskie ekrany z układami stack, odstępy i kolory sterowane tokenami, tekst z referencjami do ciągów, proste wzorce kart i list. Cursor radzi sobie z nimi dobrze, gdy IR jest w kontekście — przestaje zgadywać i zaczyna mapować.
Działa gorzej: złożone nakładki z pozycjonowaniem absolutnym (Cursor czasem błędnie odczytuje współrzędne offsetu), wypełnienia gradientowe (oznaczane jako ostrzeżenia w _meta.json — Cursor przybliży je) i ikony wektorowe (IR przechowuje tylko ID referencyjny, bez danych ścieżki).
Tylko zrzut vs. pakiet: podejście ze zrzutem ekranu jest szybsze na start, ale niedeterministyczne. Każda sesja zaczyna od nowa. Model może trafić z odstępami raz i pudłować w kolejnej turze. Pakiet jest referencjowalny przez całą sesję — Cursor może sprawdzić swój wynik w stosunku do pliku tokenów w dowolnym momencie bez ponownego przesyłania czegokolwiek.
Wskazówka: sprawdź ostrzeżenia w _meta.json przed promptem
Przed pierwszym promptem implementacyjnym przeczytaj design/_meta.json. Tablica warnings zawiera wszystko, czego eksporter nie mógł w pełni rozwiązać: wypełnienia gradientowe, brakujące mapowania tokenów, ramki z osadzonymi obrazami. Dodaj notatkę o tych elementach do promptu, by agent nie próbował ich implementować i cicho nie cofał się do zahardkodowanych wartości.
cat design/_meta.json | python3 -m json.tool | grep -A 20 '"warnings"'Jeśli wynik pokazuje "gradientFill: not fully supported" dla konkretnego węzła, powiedz Cursor, by pominął tło tego węzła i zamiast tego zostawił komentarz // TODO: gradient.
Podsumowanie
Workflow wygląda tak: eksportuj raz, odwołuj się wszędzie. Pakiet to stabilna, maszynowo czytelna specyfikacja, którą Cursor może sprawdzać przez wiele tur bez ponownego przetwarzania projektu. Otrzymujesz kod dokładny co do tokenów, z referencjami do ciągów i poprawnym układem — zamiast przybliżenia ze zrzutu ekranu. A gdy coś odbiega, możesz odesłać agenta do źródła prawdy jedną linią.
Wypróbuj samodzielnie na figmascope.dev — wklej URL Figma, naciśnij Eksportuj kontekst agenta i rozpakuj pakiet w przestrzeni roboczej Cursor w mniej niż dwie minuty.