Każdy eksport figmascope zaczyna się od .zip zawierającego siedem artefaktów. CONTEXT.md jest tym, który jest czytany jako pierwszy — z założenia. To nie jest README. To nie są wygenerowane dokumenty. To kontrakt w stylu kompilatora między projektem a agentem, który przekształci go w kod.

Ten wpis opisuje, co się w nim znajduje, dlaczego jest ustrukturyzowany w ten sposób i co się psuje, gdy go pomijasz.

Jak wygląda kontrakt vs jak wyglądają dokumenty

Dokumentacja opisuje to, co istnieje. Kontrakt określa, co musi być prawdą. To rozróżnienie ma znaczenie, gdy Twoim czytelnikiem jest LLM, który ochoczo wymyśli wartości odstępów, spłaszczy hierarchie układu lub zakoduje na stałe kolory hex, gdy tylko nie ma lepszej opcji.

CONTEXT.md otwiera się deklaracją celu:

# CONTEXT.md — cel Jetpack Compose

Ten plik jest autorytatywną specyfikacją dla generowania kodu UI z tego pakietu.
Przeczytaj go przed przeczytaniem jakiegokolwiek innego pliku.

"Cel Jetpack Compose" to nie ozdoba. Agent używa go do wyboru prymitywów composable, obsługi jednostek dp vs sp, wiedzy, że Modifier.padding() jest właściwą abstrakcją dla odstępów i rozumienia, że Box z Alignment to sposób na obsługę układów nakładkowych. React/Tailwind jako cel generuje inny CONTEXT.md z innymi prymitywami w ograniczeniach.

Instrukcja "przeczytaj to najpierw" jest również celowa. Agenty przetwarzają kontekst sekwencyjnie. Jeśli reguła tokenu pojawia się po tym, jak agent już zaczął rozumować o komponencie, ograniczenie przybywa za późno. Wstępne ładowanie kontraktu oznacza, że reguły są aktywne od pierwszego tokenu generowania.

Sekcja surowych ograniczeń

Najbardziej krytyczna część CONTEXT.md to blok ograniczeń:

## Surowe ograniczenia (musisz przestrzegać)

- Nigdy nie hardkoduj wartości dp, jeśli token istnieje w zakresie ±2dp
- Nigdy nie spłaszczaj hierarchii układu — zachowaj każdy węzeł stack/overlay/absolute
- Używaj wartości stringRef z strings.json, nigdy wbudowanego tekstu literalnego
- Traktuj brakujące pola jako nieobecne, nie zero
- Nie wymyślaj nazw komponentów nieobecnych w components/inventory.json

Każde ograniczenie istnieje, ponieważ widzieliśmy, jak agenty je naruszają. Reguła ±2dp tokenów jest najwyraźniejszym przykładem. Bez niej agent napotykający gap: 14 na węźle stosu napisze Arrangement.spacedBy(14.dp). Z regułą wie, by sprawdzić, czy spacing.16 lub spacing.12 mieści się w 2dp i użyje tokenu zamiast. To inny wynik — taki, który pozostaje spójny, gdy wartość tokenu się zmienia.

Reguła hierarchii istnieje, ponieważ Compose jest drzewem układu. Gdy agent spłaszcza zagnieżdżony stos w płaską listę pozycjonowanych elementów, niszczy responsywne zachowanie implikowane przez oryginalną strukturę. IR zachowuje każdy poziom zagnieżdżenia z określonego powodu — zobacz IR Per-Ekran — Stack, Overlay, Absolute, Leaf, by zobaczyć, jak to zagnieżdżenie koduje intencję układu.

Ograniczenie nie brzmi "używaj tokenów, jeśli masz ochotę". Brzmi "nigdy nie hardkoduj, jeśli token istnieje". To zakaz, nie sugestia. LLM-y reagują inaczej na zakazy niż na sugestie.

Reguła stringRef ma znaczenie dla i18n. Jeśli agent wbuduje "Speed Test" zamiast odwołania do klucza zasobu, stworzyłeś dziurę w lokalizacji. Ograniczenie wskazuje agentowi jawnie na strings.json.

Jak agent czyta CONTEXT.md sekwencyjnie

Okna kontekstu LLM przetwarzają tokeny od lewej do prawej. Struktura CONTEXT.md to wykorzystuje. Kolejność to:

  1. Deklaracja celu (ustawia całą ramkę generowania)
  2. Surowe ograniczenia (zakazy obowiązujące przy każdej decyzji)
  3. Mapa pakietu (jakie pliki istnieją i co każdy zawiera)
  4. Reguły użycia tokenów (jak rozwiązywać odstępy, kolor, promień, typografię)
  5. Uwagi dotyczące zakresu (szczere luki — co ten pakiet obejmuje, a czego nie)

Sekcja mapy pakietu mówi agentowi, które pliki czytać i w jakiej kolejności:

## Zawartość pakietu

- tokens.json — tokeny projektu (odstępy, promień, kolor, typografia)
- screens/*.json — IR per-ekran w formacie stack/overlay/absolute/leaf
- components/inventory.json — lista tożsamości komponentów
- strings.json — klucze zasobów i18n
- _meta.json — metadane generowania i ostrzeżenia

Bez tej mapy agent może nie wiedzieć, że components/inventory.json istnieje, lub może traktować _meta.json jako główną specyfikację. Jawne wyliczenie prowadzi kolejność czytania.

Uwagi dotyczące zakresu — czego v0.4 szczerze nie obejmuje

Sekcja uwag dotyczących zakresu to miejsce, gdzie figmascope dokumentuje własne ograniczenia. Jest to celowe i nienegocjowalne. Agent, który nie wie, że specyfikacja jest niekompletna, pewnie wypełni luki własnymi pomysłami. To gorzej niż wiedza o istnieniu luki.

## Uwagi dotyczące zakresu (v0.4)

- Wypełnienia gradientowe nie są obsługiwane. Węzły z wypełnieniami gradientowymi emitują ostrzeżenie
  w _meta.json pod warnings. Traktuj jako przybliżenie solidnego wypełnienia lub TODO.
- Tokeny typografii wymagają wypełnienia zmiennych Figma. Jeśli tokensSource
  to "inferred-from-frequency" lub "none", pokrycie typografii może być częściowe.
- Ten pakiet obejmuje tylko strukturę UI. Nawigacja, zarządzanie stanem
  i wywołania sieciowe są poza zakresem.
- Instancje komponentów są identyfikowane przez componentId. Pełne propsy źródłowe komponentu
  nie są uwzględnione — inwentarz daje tożsamość, nie implementację.

Ostrzeżenie dotyczące gradientów jest szczególnie ważne. Figma obsługuje złożone wypełnienia gradientowe, które nie mają bezpośredniego odpowiednika w Compose bez niestandardowego rysowania. Zamiast cicho pomijać gradienty lub generować zepsuty kod, figmascope emituje ostrzeżenie background-gradient-not-supported:<name> w _meta.json i zaznacza to tutaj, aby agent wiedział, że ma traktować dotknięte węzły jako znane luki, a nie błędy w swoim własnym wynikcie.

Przykłady WRONG / RIGHT

Uczyńmy to konkretnym. Dany węzeł stosu z gap: 16 i plik tokenów zawierający spacing.16: 16:

Bez ograniczeń CONTEXT.md (WRONG):

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

Z ograniczeniami CONTEXT.md (RIGHT):

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

Wynik RIGHT odwołuje się do tokenu. Gdy system projektowania zmienia spacing.16 z 16dp na 14dp, kod pozostaje poprawny bez przeszukiwania i zamiany w bazie kodu.

Inny przykład — obsługa ciągów. Dany węzeł leaf z text: "Speed Test" i stringRef: "speed.test":

WRONG:

Text(text = "Speed Test")

RIGHT:

Text(text = stringResource(R.string.speed_test))

Ograniczenie wskazuje na strings.json, klucz to speed.test i agent wie, jak mapować notację kropkową do identyfikatorów zasobów Android. Jest to możliwe tylko wtedy, gdy agent przeczytał ograniczenie przed wygenerowaniem komponentu.

Dlaczego nie po prostu samemu promptować agenta?

Możesz pisać te instrukcje ręcznie w prompcie. figmascope externalizuje je do pliku, ponieważ:

Celem nie jest prompt-engineering wokół domyślnych ustawień agenta. Chodzi o dostarczenie specyfikacji, która sprawia, że domyślne ustawienia stają się nieistotne.

Struktura w porównaniu z alternatywami

Dev Mode Figmy wyświetla pomiary, zmienne i fragmenty kodu. Nie produkuje specyfikacji. Agent używający wyniku Dev Mode musi wywnioskować reguły z przykładów — co oznacza, że wnioskuje błędne reguły dla przypadków brzegowych.

Locofy i podobne narzędzia generują kod bezpośrednio. Nie mają odpowiednika CONTEXT.md, ponieważ nie oczekują, że agent będzie czytał specyfikację — oczekują bycia agentem. To działa, gdy generowanie kodu przez narzędzie dokładnie pasuje do Twojego stosu. Nie działa, gdy masz konwencje nazewnictwa specyficzne dla projektu, niestandardową bibliotekę komponentów lub system projektowania z tokenami, o których narzędzie nie wie.

CONTEXT.md to maszynowo czytelny brief projektowy. To rzecz, która istniała jako strona Confluence lub dokument Notion w każdym pre-LLM przekazaniu projektu, tylko ustrukturyzowana dla odbiorcy, który faktycznie przestrzega reguł.

Co z tym zrobić

Gdy otwierasz eksport figmascope w Cursor lub Claude Code:

  1. Dodaj @CONTEXT.md do kontekstu przed jakimkolwiek promptem dotyczącym projektu.
  2. Odwołaj się do JSON ekranu, nad którym pracujesz: @screens/home.json.
  3. Jeśli dotykasz tokenów, dodaj @tokens.json.
  4. Jeśli pracujesz z ciągami, dodaj @strings.json.

Ograniczenia CONTEXT.md obowiązują przez całą sesję po załadowaniu. Nie dodajesz go ponownie per prompt — dodajesz go raz na początku i pozwalasz mu oprawić każde kolejne generowanie.

Pozostałe artefakty w pakiecie są omówione w pozostałej części tej serii. Zacznij od Wyjaśnienia tokens.json, by zobaczyć, jak system tokenów obsługuje pliki z i bez zmiennych Figma, lub od IR Per-Ekran, by zobaczyć, jak układy Figma mapują się do węzłów stack/overlay/absolute/leaf. Gotowy, by to wypróbować? Wklej URL Figma na figmascope.dev i wyeksportuj swój pierwszy pakiet.