Promptowanie zrzutami ekranu ma sufit. Wklejasz projekt, model robi wiarygodne przybliżenie, poprawiasz je, w następnej turze znów dryfuje. Nic nie jest zakotwiczone. Model nie ma źródła prawdy, względem którego mógłby się sprawdzić między turami.

Pakiet kontekstu figmascope zmienia kontrakt. Zamiast referencji pikselowej, którą model musi za każdym razem interpretować, otrzymujesz ustrukturyzowany, referencjowalny zestaw plików — tokeny projektu, układ IR, inwentarz komponentów, ciągi UI — które pozostają w sesji i pozostają spójne. Claude Code może je czytać, implementować z nich i sprawdzać swoje własne wyjście względem nich na żądanie.

Ten opis obejmuje pełny potok od eksportu pakietu do przejrzanej, zweryfikowanej pod kątem tokenów implementacji.

Co sprawia, że to jest deterministyczne

Trzy rzeczy sprawiają, że pakiet jest referencjowalny, a nie interpretowalny:

  1. Tokeny są typowane i kluczowane. tokens.json mapuje nazwy semantyczne (spacing.16, color.7f5cfe) do dokładnych wartości. Model może sprawdzić swoje wyjście względem pliku bez ponownego przetwarzania projektu.
  2. IR to drzewo, nie piksele. screens/home.json opisuje układ w kategoriach węzłów stack/overlay/absolute/leaf — tę samą abstrakcję, której używa cel implementacji (Compose, React itp.). Nie ma kroku interpretacji wizualnej.
  3. Pakiet jest stabilny między turami. Po umieszczeniu w repozytorium każdy prompt w sesji może odwoływać się do tych samych plików. Dryf tokenów jest wykrywalny: poproś model o porównanie jego wyjścia z tokens.json i może to zrobić mechanicznie.

Krok 1: Wygeneruj pakiet

Otwórz figmascope.dev w przeglądarce. Wklej URL pliku Figma. Eksporter działa po stronie klienta używając Figma REST API — Twój personal access token Figma jest przechowywany w localStorage i nigdy nie jest wysyłany na serwery figmascope.

Kliknij Eksportuj kontekst agenta. Strona eksportuje ramki najwyższego poziomu, rozwiązuje tokeny projektu, buduje IR i pobiera context-bundle.zip.

Krok 2: Rozpakuj do projektu

# z katalogu głównego projektu
unzip ~/Downloads/context-bundle.zip -d ./design/

# potwierdź, co masz
find design/ -type f | sort
# design/CONTEXT.md
# design/_meta.json
# design/components/inventory.json
# design/screens/home.json
# design/screens/home.png
# design/screens/settings.json
# design/screens/settings.png
# design/strings.json
# design/tokens.json

Nazwa katalogu nie ma znaczenia — design/ to tylko konwencja. Ważne jest, aby Claude Code mógł czytać pliki z katalogu roboczego.

Krok 3: Uruchom Claude Code w repozytorium

cd moja-aplikacja
claude

Claude Code uruchamia się w katalogu głównym repozytorium z pełnym dostępem do plików. Może czytać, pisać i odwoływać się do dowolnego pliku w drzewie przez całą sesję — to kluczowa zdolność, która sprawia, że wzorzec pakietu działa.

Krok 4: Zorientuj agenta

Zacznij od promptu czytającego przed jakąkolwiek implementacją. To ładuje specyfikację do kontekstu sesji i pozwala zweryfikować, że eksport wygląda dobrze przed pisaniem jakiegokolwiek kodu.

Przeczytaj ./design/CONTEXT.md i powiedz mi:
1. Na jaki framework docelowy jest ten pakiet?
2. Do jakich plików tokenów się odwołuje?
3. Czy są jakieś ostrzeżenia, o których powinienem wiedzieć przed implementacją?

Claude zgłosi cel (domyślnie Jetpack Compose), źródło tokenów i wszelkie ostrzeżenia z nagłówka CONTEXT.md — wypełnienia gradientowe, brakujące mapowania tokenów, nieobsługiwane efekty. Wyłapujesz to teraz, nie po wygenerowaniu 200 linii kodu.

Następnie szybkie sprawdzenie tokenów:

Wymień 10 najważniejszych tokenów kolorów z ./design/tokens.json.
Następnie wymień tokeny odstępów.

Potwierdza to, że plik tokenów został prawidłowo sparsowany i daje Ci mentalny model palety przed implementacją.

Krok 5: Zaimplementuj ekran

Teraz prompt implementacji. Bądź jawny w kwestii tego, które pliki są autorytatywne dla jakich decyzji:

Zaimplementuj ./design/screens/home.json jako ekran Jetpack Compose.

Reguły:
- Obowiązują ograniczenia CONTEXT.md. Przeczytaj go, jeśli jeszcze nie.
- Wszystkie wartości odstępów, kolorów i promieni muszą pochodzić z ./design/tokens.json.
  Mapuj klucze tokenów do odpowiednich prymitywów Compose (np. spacing.16 → 16.dp).
- Ciągi UI muszą używać kluczy z ./design/strings.json przez stringResource().
  Użyj wartości pola "fallback" jako wartości literalnej, jeśli żaden ID zasobu nie jest jeszcze dostępny.
- Rodzaje węzłów IR mapują się następująco:
    stack (axis:vertical)   → Column
    stack (axis:horizontal) → Row
    overlay                 → Box
    absolute                → Box z Modifier.offset
    leaf (text)             → Text z TextStyle
    leaf (rectangle)        → Box z Modifier.background
- Nie wymyślaj żadnej wartości nieobecnej w plikach tokenów lub IR.
  Jeśli czegoś brakuje, zostaw komentarz TODO z kluczem tokenu, którego oczekiwałeś.

Claude Code przeczyta IR, przejdzie przez drzewo węzłów, zmapuje każdy węzeł do jego prymitywu Compose i pobierze wartości tokenów według klucza. Wynik jest śledzony — każda wartość .dp powinna odpowiadać tokenowi odstępu, każde Color(0xFF...) powinno pasować do tokenu koloru.

Krok 6: Wykryj i napraw dryf tokenów

Po pierwszym przebiegu implementacji uruchom sprawdzenie dryfu przed wizualnym przeglądem. To jest kluczowa zaleta pakietu nad promptowaniem zrzutami ekranu — możesz poprosić model o mechaniczne zweryfikowanie własnego wyjścia.

Porównaj każdą wartość koloru w wygenerowanym HomeScreen.kt z ./design/tokens.json.
Wymień wszelkie wartości hex w wyjściu, które nie odpowiadają kluczowi tokenu koloru.
Dla każdej z nich zidentyfikuj właściwy token i zastąp hardkodowaną wartość.

To samo dla odstępów:

Porównaj każdą wartość .dp w HomeScreen.kt z tokenami odstępów w ./design/tokens.json.
Oznacz wszelkie wartości, które nie pasują do tokenu odstępu. Zastąp właściwą referencją tokenu.

Ta pętla — implementuj, sprawdzaj dryf, napraw — szybko się zbiega. Po drugim lub trzecim przebiegu wynik jest w pełni odwołujący się do tokenów.

Wskazówka: dołącz ostrzeżenia _meta.json do pierwszego promptu

design/_meta.json zawiera tablicę warnings. To są rzeczy, których eksporter nie mógł w pełni rozwiązać: wypełnienia gradientowe, osadzone obrazy, efekty bez odpowiednika tokenu. Przeczytaj je przed implementacją:

cat design/_meta.json

Jeśli wyjście zawiera coś takiego:

{
  "warnings": [
    "node 'hero-background': gradientFill not fully supported — background fill omitted",
    "node 'avatar': imageFill — reference only, no pixel data"
  ]
}

Dodaj je jawnie do promptu implementacji: "Pomiń wypełnienie tła hero i zostaw // TODO: gradient. Dla węzła avatar użyj zastępczego AsyncImage z szarym tłem."

Zapobiega to cichemu przybliżaniu przez Claude — zrobi to, co mu powiedziałeś, zamiast zgadywać.

Dlaczego to bije promptowanie zrzutami ekranu

Bezpieczne dla wielu tur. Plik tokenów i IR nie zmieniają się między turami. Możesz zapytać "czy użyłeś właściwego odstępu dla paddingu karty?" w turze 12 i uzyskać dokładną odpowiedź, ponieważ źródło prawdy wciąż jest na dysku.

Przyjazne dla diffów. Gdy ponownie eksportujesz po zmianie projektu, nowy pakiet produkuje diff względem starego. Możesz poprosić Claude o przejrzenie diffu i aktualizację tylko dotkniętych komponentów — bez pełnej reimplementacji.

Bez ponownego przesyłania. Pakiet żyje w repozytorium. Nie wklejasz ponownie zrzutów ekranu dla każdego nowego ekranu. Każdy nowy ekran to po prostu design/screens/<name>.json — jeszcze jeden plik do odwołania w następnym prompcie.

Szczery wobec luk. CONTEXT.md i _meta.json jawnie wymieniają to, czego pakiet nie obejmuje. Promptowanie zrzutami ekranu nie ma odpowiednika — model po prostu zgaduje przez luki.

Główna aplikacja figmascope obsługuje eksport w przeglądarce — wklej URL Figma, wyeksportuj pakiet i jesteś gotowy do uruchomienia Claude Code względem deterministycznej specyfikacji.