Figma do Claude Code — Strukturalny kontekst projektowy dla CLI Anthropic

Instrukcja „nie reimplementuj komponentów, które już istnieją" ma znaczenie, gdy inwentarz komponentów jest współdzielony. Claude Code może odczytać design/components/inventory.json, aby zidentyfikować, które komponenty są już zaimplementowane i importować je zamiast regenerować.

Podłączanie tokenów projektowania

tokens.json eksportowany przez figmascope używa zagnieżdżonej struktury W3C z polami $value i $type:

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

Poproś Claude Code o wygenerowanie bloku rozszerzenia motywu tailwind.config.ts z tego pliku jako pierwszego kroku, przed implementacją jakichkolwiek ekranów. Dzięki temu wszystkie kolejne implementacje ekranów mogą spójnie używać aliasów tokenów Tailwind:

claude --print "Przeczytaj design/tokens.json i wygeneruj blok
theme.extend dla tailwind.config.ts. Zmapuj tokeny kolorów do theme.extend.colors,
tokeny odstępów do theme.extend.spacing i typografię do
theme.extend.fontFamily / fontSize. Wypisz tylko obiekt konfiguracji."

Zobacz Eksport tokenów projektowania dla agentów AI po głęboką analizę formatu tokenów i fallback wnioskowania z częstotliwości, którego figmascope używa, gdy zmienne Figmy nie są skonfigurowane.

Obsługa warstwy ciągów znaków

Każdy węzeł tekstowy w pliku Figmy dostaje slot w strings.json. Klucze używają notacji kropkowej wywodzącej się z hierarchii ramek:

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

Poinstruuj Claude Code, aby używał tych kluczy jako identyfikatorów i18n. Zamiast hardcodować ciąg "Everything you need" w JSX, generowany komponent wywołuje t('home.hero.title') (lub odpowiednik twojej biblioteki i18n). Plik zasobów jest już w strings.json — musisz tylko zaimportować go lub podłączyć do konfiguracji i18n.

Jeśli figmascope wykryje kolizję — dwa węzły hashujące do tego samego klucza — emituje ostrzeżenie strings-collision w _meta.json i dodaje sufiks numeryczny do disambiguacji. Sprawdź _meta.json przed rozpoczęciem sesji, abyś wiedział, czego się spodziewać.

Integracja CLAUDE.md

Jeśli używasz pliku kontekstu projektu CLAUDE.md, dodaj krótką sekcję wskazującą agenta na katalog projektowy. Dobrze łączy się z podejściem opisanym w Przekazaniu projektu AI i uzupełnia dlaczego figmascope różni się od wtyczek Figma inspector.

Dodaj sekcję projektową tak:

## Kontekst projektowy

Tokeny projektowania, IR układu, referencyjne rendery i ciągi znaków żyją w `design/`.
Zawsze czytaj `design/CONTEXT.md` przed implementacją dowolnego ekranu.
Wartości tokenów są w `design/tokens.json` — nigdy nie koduj na stałe kolorów ani odstępów.
Kanoniczne nazwy komponentów są w `design/components/inventory.json`.

Oznacza to, że każda sesja Claude Code w projekcie będzie automatycznie miała kontekst projektowy jako część swojej wiedzy roboczej, bez konieczności powtarzania go w każdym prompcie.

Co agent faktycznie robi dobrze

Ze strukturalnym kontekstem, Claude Code niezawodnie uzyskuje:

• Wartości odstępów — ponieważ są w tokens.json jako spacing.4 → 16px, nie szacowane ze zrzutu ekranu
• Kolor — dokładne wartości hex, nie „wygląda jak ciepła pomarańcza"
• Typografię — rodzina czcionek, rozmiar, grubość, wysokość wiersza, wszystko typowane
• Kierunek układu — węzły stack mają explicite pole direction i gap
• Nazewnictwo komponentów — inventory.json jest kanonicznym źródłem, więc bez wymyślonych nazw
• Teksty — strings.json zapobiega parafrazowaniu lub wymyślaniu tekstu zastępczego przez agenta

Co nadal wymaga przeglądu ludzkiego: stany interakcji (hover, focus, active) niewidoczne w statycznych ramkach Figmy, czas animacji i responsywne punkty przerwania, które nie były explicite projektowane w pliku. IR przechwytuje statyczny układ; dynamiczne zachowanie jest poza zakresem.

Używanie --dangerously-skip-permissions w kontrolowanych środowiskach

Dla automatycznych potoków, gdzie chcesz, żeby Claude Code działał bez interaktywnych monitów zatwierdzenia — na przykład w kroku CI generującym stuby komponentów po aktualizacji projektu — możesz użyć --dangerously-skip-permissions. Odpowiednie tylko w środowiskach sandbox bez poświadczeń produkcyjnych.

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Przeczytaj design/CONTEXT.md. Wygeneruj pliki stub komponentów dla wszelkich komponentów
w design/components/inventory.json, które nie istnieją jeszcze w src/components/.
Używaj formatu funkcjonalnego komponentu TypeScript + React. Dodaj komentarz TODO
dla każdego komponentu odwołujący się do odpowiedniego JSON ekranu.
EOF
)"

W produkcyjnych przepływach pracy programistów, pozostaw uprawnienia interaktywne. Monity istnieją z dobrego powodu — Claude Code może i będzie zapisywać pliki, i chcesz wiedzieć, które, zanim to zrobi.

Sprawdzanie ostrzeżeń eksportu przed promptowaniem

figmascope emituje ostrzeżenia do _meta.json dla warunków, które mogą wpłynąć na jakość wynikową. Sprawdź je przed rozpoczęciem sesji Claude Code:

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Wyeksportowane ramki: {meta['frameCount']}\")
print(f\"Źródło tokenów: {meta.get('tokensSource', 'variables')}\")
"

Dwa ostrzeżenia, na które zwrócić uwagę:

• layout-mode-none-inferred — ramka nie miała ustawionego auto-layout. figmascope wywnioskował układ z bezwzględnych pozycji dzieci, co jest mniej niezawodne. Oznacz odpowiedni ekran w prompcie: „Ten ekran używa pozycjonowania bezwzględnego; generuj odpowiednio."
• strings-collision — dwa węzły tekstowe wyprodukowały ten sam klucz zasobu. figmascope disambiguuje sufiksem numerycznym, ale powinieneś zweryfikować ciągi w strings.json przed generowaniem wywołań i18n przez agenta.

Przepływy pracy Android i iOS

Claude Code nie jest ograniczony do frameworków webowych. Pakiet kontekstu jest niezależny od frameworku — IR układu i tokeny to dane, nie CSS. Dla Jetpack Compose:

claude --print "$(cat <<'EOF'
Przeczytaj design/CONTEXT.md i design/tokens.json.

Zaimplementuj design/screens/Home.json jako ekran Jetpack Compose.
- Zmapuj tokeny kolorów do MaterialTheme ColorScheme
- Zmapuj tokeny odstępów do wartości Dp (usuń sufiks 'px', użyj .dp)
- Zmapuj tokeny typografii do MaterialTheme.typography
- Używaj nazw komponentów z design/components/inventory.json jako nazw Composable
- Odwołaj się do design/screens/Home.png dla dokładności wizualnej
EOF
)"

Węzły stack IR naturalnie mapują do Column (direction: vertical) i Row (direction: horizontal) w Compose. Węzły leaf z type: "text" stają się composable Text; type: "image" staje się Image lub placeholderem. Zobacz Jetpack Compose z Figmy po pełny wzorzec.

Wersjonowanie pakietu projektowego

Traktuj katalog design/ jak każdą inną zależność projektu. Gdy projekt zmienia się znacząco, ponownie wyeksportuj z figmascope.dev, zatwierdź i odnotuj zmianę w PR:

# Sprawdź, kiedy pakiet był ostatnio eksportowany vs kiedy plik Figmy był ostatnio modyfikowany
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'OSTRZEŻENIE: Plik Figmy był modyfikowany {delta} po ostatnim eksporcie')
else:
    print('Pakiet jest aktualny')
"

Nieaktualny pakiet oznacza, że agent pracuje z przestarzałym projektem. Sprawdzenie znacznika czasu wychwytuje to przed spędzeniem czasu na sesji codegen opartej na przestarzałych specyfikacjach.