@atezer/figma-mcp-bridge 1.7.30 → 1.9.1

package/skills/figma-canvas-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figma-canvas-ops
-description: F-MCP Bridge ile Figma tuvalinde güvenli yazma/düzenleme için zorunlu önkoşul kılavuzu. figma_execute çağrısı öncesi bu skill yüklenmelidir. Renk aralığı, font yükleme, array klonlama, atomik hata yönetimi, node ID return kuralları ve sayfa konteksti sıfırlanmasını kapsar. "figma'da düzenle", "tuvale yaz", "node oluştur", "figma execute kılavuz", "canvas ops", "tuval işlemi" ifadeleriyle tetiklenir.
+description: F-MCP Bridge ile Figma tuvalinde güvenli yazma/düzenleme için zorunlu önkoşul kılavuzu. figma_execute çağrısı öncesi bu skill yüklenmelidir.
 metadata:
   mcp-server: user-figma-mcp-bridge
   personas:
@@ -10,175 +10,142 @@ metadata:
 
 # Figma Canvas Ops — figma_execute Güvenli Kullanım Kılavuzu
 
-## Overview
+## Araç Eşleme (topluluk → F-MCP)
 
-Bu skill, `figma_execute` aracıyla Figma tuvalinde yazma/düzenleme yapılmadan önce **zorunlu** olarak yüklenmesi gereken önkoşul kılavuzudur. Topluluk `figma-use` skill'inden uyarlanmış, F-MCP Bridge araçlarına göre yeniden yazılmıştır.
-
-**Tuval yazan her skill** (apply-figma-design-system, fix-figma-design-system-finding, generate-figma-screen, generate-figma-library, figjam-diagram-builder) bu kılavuzdaki kuralları uygulamalıdır.
-
-## Araç eşleme (topluluk → F-MCP)
-
-| Topluluk (resmi MCP) | F-MCP Bridge | Not |
+| Topluluk | F-MCP Bridge | Not |
 |---|---|---|
-| `use_figma` | `figma_execute` | JS çalıştırma; `code` parametresi |
-| `get_metadata` | `figma_get_file_data` | Yapı/metadata; `depth` parametresi |
-| `get_screenshot` | `figma_capture_screenshot` | Node bazlı görsel doğrulama |
+| `use_figma` | `figma_execute` | JS çalıştırma |
+| `get_metadata` | `figma_get_file_data` | Yapı/metadata |
+| `get_screenshot` | `figma_capture_screenshot` | Görsel doğrulama |
 | `search_design_system` | `figma_search_components` + `figma_get_design_system_summary` | İki araç birlikte |
 
-Detaylı eşleme: [TOOL_MAPPING.md](../TOOL_MAPPING.md)
-
 ## Prerequisites
 
-- F-MCP Bridge plugin Figma'da çalışıyor ve bağlı olmalı
-- `figma_get_status()` ile bağlantı doğrulanmalı
-
-## 1. Kritik Kurallar
-
-1. **`return` ile veri dön.** Return değeri otomatik JSON serialize edilir (object, array, string, number). `figma.closePlugin()` çağırma — bu bridge tarafından yönetilir.
+- F-MCP Bridge plugin bağlı olmalı (`figma_get_status()`)
+- Aktif DS context: `.claude/design-systems/active-ds.md` → `Status: ✅`
 
-2. **Düz JavaScript yaz, top-level `await` kullan.** Kod otomatik async bağlama sarılır. `(async () => { ... })()` ile sarma.
+## 0. Design System Context (ZORUNLU)
 
-3. **`figma.notify()` çalışmaz** — kullanma.
+### 0a — Active DS check
+```
+1. Read .claude/design-systems/active-ds.md
+2. ✅ Aktif → Library Name not al, 0b'ye geç
+   ❌ Seçilmedi → 0c'ye geç
+   "DS bypass mode" → DS'siz devam
+```
 
-4. **`console.log()` dönmez** — çıktı için `return` kullan.
+### 0b — DS asset cache hazırlığı
+```
+1. .claude/design-systems/<library-id>/components.md var mı?
+2. .claude/design-systems/<library-id>/tokens.md var mı?
+3. Yoksa: figma_get_library_variables + figma_search_assets ile keşfet, cache'e yaz
+```
 
-5. **Küçük adımlarla çalış.** Büyük işlemleri birden fazla `figma_execute` çağrısına böl. Her adımdan sonra doğrula. Bug'lardan kaçınmanın en önemli pratiği budur.
+### 0c — Kullanıcıya DS seçimi sor
+active-ds.md `❌` ise: "Hangi DS? (SUI / Material / HIG / Kendi / Hiçbiri)". Yanıt sonrası active-ds.md güncelle, 0b'ye geç. Sonraki turlarda TEKRAR SORMA.
 
-   **Timeout yapılandırması:** `figma_execute` varsayılan timeout 5000ms'dir. Çok node oluşturma veya karmaşık işlemlerde `timeout` parametresini artır (maksimum 30000ms):
-   ```
-   figma_execute({ code: "...", timeout: 15000 })
-   ```
-   Kılavuz: 1-5 node → 5000ms | 6-12 node → 10000ms | 13+ node → işlemi böl veya 15000-30000ms
+## 1. Kritik Kurallar
 
-6. **Renkler 0–1 aralığında** (0–255 değil): `{r: 1, g: 0, b: 0}` = kırmızı. Renk değerlerini hardcoded yazma — tasarım sisteminden (`figma_get_variables` / `figma_get_styles`) oku.
+1. **`return` ile veri dön.** `figma.closePlugin()` çağırma.
 
-7. **Fills/strokes read-only array** — klonla, değiştir, geri ata:
-```js
-// Renk değerini DS'den oku, aşağıdaki sadece API FORMAT örneğidir
-const fills = [...node.fills];
-fills[0] = { ...fills[0], color: DS_COLOR }; // DS'den okunan değer
-node.fills = fills;
-```
+2. **Düz JS, top-level `await`.** Kod otomatik async sarılır. `(async()=>{})()` sarma. **Async API zorunlu** — dynamic-page mode'da sync API'ler throws:
 
-8. **Font yükleme zorunlu** — metin işleminden önce font yükle. Hangi fontu kullanacağını belirlemek için şu sırayı takip et:
+   | ❌ YASAK (sync) | ✅ ZORUNLU (async) |
+   |---|---|
+   | `instance.mainComponent` | `await instance.getMainComponentAsync()` |
+   | `figma.getNodeById(id)` | `await figma.getNodeByIdAsync(id)` |
+   | `figma.variables.importVariableByKey(key)` | `await figma.variables.importVariableByKeyAsync(key)` |
+   | `figma.importComponentByKey(key)` | `await figma.importComponentByKeyAsync(key)` |
+   | `figma.importStyleByKey(key)` | `await figma.importStyleByKeyAsync(key)` |
+   | `node.effectStyleId = x` | `await node.setEffectStyleIdAsync(x)` |
+   | `node.textStyleId = x` | `await node.setTextStyleIdAsync(x)` |
+   | `figma.listAvailableFonts()` | `await figma.listAvailableFontsAsync()` |
+   | `figma.loadFont(...)` | `await figma.loadFontAsync(...)` |
+   | `figma.variables.getVariableCollectionById(id)` | `await figma.variables.getVariableCollectionByIdAsync(id)` |
 
-   **a)** Kayıtlı kütüphane varsa (`.claude/libraries/`) text style'lardan veya variable'lardan font ailesini oku. Örnek: kütüphanedeki text style `global/surface/body` → font family ve style bilgisini al.
+3. **`figma.notify()` çalışmaz** — kullanma.
 
-   **b)** Kütüphane yoksa veya font bilgisi bulunamazsa kullanıcıya sor: "Hangi fontu kullanmamı istersiniz?"
+4. **`console.log()` dönmez** — `return` kullan.
 
-   **c)** Kullanıcı "sen seç" derse `Inter` kullan.
+5. **Küçük adımlarla çalış.** Timeout: varsayılan 15000ms, max 30000ms.
 
-```js
-// Fontu belirledikten sonra yükle:
-await figma.loadFontAsync({ family: "FONT_ADI", style: "Regular" });
-// Gerekli diğer ağırlıklar:
-await figma.loadFontAsync({ family: "FONT_ADI", style: "Bold" });
-```
-   **Asla** hardcoded font varsayma — her zaman bu sırayı takip et. Bu kural font, renk, boyut, spacing dahil TÜM design token'lar için geçerlidir. Detay: `project-context.md` → "Design Token Kuralı".
+   ### 5a. CHUNKING MANDATE (v2.0)
 
-   **FigJam özel durumu:** `createShapeWithText()` varsayılan fontu **"Inter Medium"**'dir ("Inter Regular" DEĞİL). FigJam shape text'i düzenlemek için:
-   ```js
-   await figma.loadFontAsync({ family: "Inter", style: "Medium" });
-   const shape = figma.createShapeWithText();
-   shape.text.characters = "Metin"; // Medium yüklenmeden hata verir
-   ```
-   Genel kural: metin düzenlemeden önce **mevcut fontu kontrol et** ve o fontu yükle:
-   ```js
-   await figma.loadFontAsync(shape.text.fontName); // dinamik font algılama
-   ```
+   Her `figma_execute` **max 15 atomic operation**. Atomic op'lar: node/instance oluşturma, variable/style/component import, font load, bind operasyonu, getNodeByIdAsync, getMainComponentAsync.
 
-9. **Sayfa konteksti her çağrıda sıfırlanır** — `figma.currentPage` her `figma_execute` çağrısında ilk sayfaya döner. Farklı sayfada çalışacaksan:
-```js
-const page = figma.root.children.find(p => p.name === "Hedef Sayfa");
-await figma.setCurrentPageAsync(page);
-```
+   - 1 execute = 1 mega-goal (discovery, frame+structure, 3-4 component placement)
+   - 25+ op → 2-3 execute'a böl
+   - Execute arası state: nodeId'leri `return` et, sonraki execute `getNodeByIdAsync` ile al
+   - Her execute sonrası 1 satır Türkçe micro-report
 
-10. **Tüm tasarım değerleri DS variable'larına BAĞLANMALI (ZORUNLU).** Renk, spacing, padding, radius gibi hiçbir değer hardcoded yazılmaz. Akış:
+6. **Renkler 0–1 aralığında** (0–255 değil). Hardcoded renk YASAK — DS'den oku.
 
-   **a) Kütüphaneden variable key'lerini oku:** `.claude/libraries/` dosyasını kontrol et. Key yoksa **HEDEF dosyada** `figma_get_library_variables` veya `figma_execute` ile `figma.teamLibrary` API'sini kullan. **DS dosyasına F-MCP plugin bağlamak GEREKMEZ.**
+7. **Fills/strokes read-only array** — klonla, değiştir, ata:
    ```js
-   // HEDEF dosyada çalıştır — DS dosyası değil!
-   var cols = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
-   var semCol = cols.find(function(c) { return c.libraryName === "❖ SUI" && c.name.indexOf("Semantic Colors") !== -1; });
-   var vars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(semCol.key);
-   return vars.map(function(v) { return { name: v.name, key: v.key, resolvedType: v.resolvedType }; });
+   const fills = [...node.fills];
+   fills[0] = { ...fills[0], color: DS_COLOR };
+   node.fills = fills;
    ```
-   Veya doğrudan: `figma_get_library_variables({ libraryName: "❖ SUI" })`
 
-   **b) Hedef dosyada variable'ı import et:**
-   ```js
-   const variable = await figma.variables.importVariableByKeyAsync("VARIABLE_KEY");
-   ```
+8. **Font yükleme zorunlu.** Sıra: (a) DS cache'ten font oku → (b) Yoksa kullanıcıya sor → (c) "Sen seç" → Inter.
 
-   **c) Renk bağlama (fill/stroke):** `setBoundVariableForPaint` kullan — DİKKAT: yeni paint döner, yakala ve geri ata:
+   **8a-1) Font weight check (ZORUNLU):** `loadFontAsync` öncesi `listAvailableFontsAsync` ile kontrol et. Fallback helper:
    ```js
-   const fills = [...node.fills];
-   const boundPaint = figma.variables.setBoundVariableForPaint(fills[0], "color", variable);
-   node.fills = [boundPaint];
+   const allFonts = await figma.listAvailableFontsAsync();
+   const styles = allFonts.filter(f => f.fontName.family === "SHBGrotesk").map(f => f.fontName.style);
+   function pickStyle(desired, available) {
+     if (available.indexOf(desired) >= 0) return desired;
+     var fb = { "Medium":["Semi Bold","Regular"], "ExtraBold":["Bold"], "Black":["Bold"], "Thin":["Light","Regular"] };
+     var alts = fb[desired] || [];
+     for (var i = 0; i < alts.length; i++) { if (available.indexOf(alts[i]) >= 0) return alts[i]; }
+     return available.find(s => s.indexOf("Italic") < 0) || available[0];
+   }
+   await figma.loadFontAsync({ family: "SHBGrotesk", style: pickStyle("Medium", styles) });
    ```
+   **FigJam:** `createShapeWithText()` varsayılan "Inter Medium". Metin düzenlemeden önce `await figma.loadFontAsync(shape.text.fontName)`.
 
-   **d) Spacing/padding/radius bağlama:** `setBoundVariable` kullan:
-   ```js
-   node.setBoundVariable("paddingLeft", variable);
-   node.setBoundVariable("paddingRight", variable);
-   node.setBoundVariable("itemSpacing", variable);
-   node.setBoundVariable("topLeftRadius", variable);
-   ```
+9. **Sayfa konteksti her çağrıda sıfırlanır.** Farklı sayfa: `await figma.setCurrentPageAsync(page)`.
 
-   **e) Text style bağlama:** Doğrudan text style ID'si ile uygula:
-   ```js
-   const textStyles = await figma.getLocalTextStylesAsync();
-   const bodyStyle = textStyles.find(s => s.name === "global/surface/body");
-   await textNode.setTextStyleIdAsync(bodyStyle.id);
-   ```
+10. **Tüm tasarım değerleri DS variable'a BAĞLANMALI (ZORUNLU).**
 
-   **f) Text rengi bağlama (text node fill):**
-   ```js
-   const textFills = [...textNode.fills];
-   const boundTextPaint = figma.variables.setBoundVariableForPaint(textFills[0], "color", textColorVar);
-   textNode.fills = [boundTextPaint];
-   ```
+    Renk, spacing, padding, radius — HİÇBİR değer hardcoded yazılmaz. Token yoksa DURDUR, kullanıcıya sor.
 
-   **Asla** `node.fills = [{ type: "SOLID", color: { r: X, g: Y, b: Z } }]` gibi hardcoded renk yazma. Her zaman variable import et ve bağla.
+    **Akış:**
+    - **Variable import:** `const v = await figma.variables.importVariableByKeyAsync("KEY")`
+    - **Renk bind:** `node.fills = [figma.variables.setBoundVariableForPaint(fills[0], "color", v)]`
+    - **Spacing bind:** `node.setBoundVariable("paddingLeft", v)`
+    - **Text style:** `await textNode.setTextStyleIdAsync(style.id)`
+    - **Text renk:** `textNode.fills = [figma.variables.setBoundVariableForPaint(textFills[0], "color", textColorVar)]`
 
-11. **`layoutSizingHorizontal/Vertical = 'FILL'` appendChild'DAN SONRA** ayarlanmalı — öncesinde hata verir.
+    Hardcoded `node.fills = [{ type: "SOLID", color: {...} }]` YASAK.
 
-12. **Yeni üst-düzey node'ları (0,0)'dan uzağa konumlandır.** `figma.currentPage.children` tarayarak boş alan bul.
+11. **appendChild sıralaması kritik.** ÖNCE `parent.appendChild(child)`, SONRA `child.layoutSizingHorizontal = "FILL"` / `layoutPositioning = "ABSOLUTE"`:
+    ```js
+    parent.appendChild(child);              // ÖNCE
+    child.layoutSizingHorizontal = "FILL";  // SONRA
+    ```
+    Hata: "Can only set layoutPositioning = ABSOLUTE if parent has layoutMode !== NONE" → child append edilmemiş.
 
-13. **Hata durumunda DUR.** Hemen tekrar deneme. Hata mesajını oku, scripti düzelt, sonra tekrar çalıştır. Başarısız scriptler atomiktir — hata olursa hiçbir değişiklik uygulanmaz.
+12. **Yeni node'ları (0,0)'dan uzağa konumlandır.** Boş alan bul.
 
-14. **Tüm oluşturulan/değiştirilen node ID'lerini RETURN ET:**
-```js
-return { createdNodeIds: [...], mutatedNodeIds: [...] };
-```
+13. **Hata durumunda DUR.** Hata oku, düzelt, tekrar çalıştır. Atomik — hata olursa değişiklik uygulanmaz.
 
-15. **Variable scope'larını açıkça ayarla.** Varsayılan `ALL_SCOPES` her property picker'ı kirletir. Spesifik scope kullan:
-   - Arka plan: `["FRAME_FILL", "SHAPE_FILL"]`
-   - Metin rengi: `["TEXT_FILL"]`
-   - Boşluk: `["GAP"]`
+14. **Tüm node ID'lerini RETURN ET:** `return { createdNodeIds: [...] }`
 
-16. **Her Promise'i `await` et.** `await` olmadan async çağrılar sessizce başarısız olur.
+15. **Variable scope'ları:** Arka plan: `["FRAME_FILL"]`, Metin: `["TEXT_FILL"]`, Boşluk: `["GAP"]`
 
-## 2. Sayfa Kuralları
+16. **Her Promise'i `await` et.**
 
-### Sayfalar arası geçiş
+## 2. Sayfa Kuralları
 
 ```js
-const targetPage = figma.root.children.find(p => p.name === "Sayfa Adı");
-await figma.setCurrentPageAsync(targetPage);
-// targetPage.children artık yüklü
+const page = figma.root.children.find(p => p.name === "Sayfa");
+await figma.setCurrentPageAsync(page);
 ```
-
-**Sync setter `figma.currentPage = page` hata verir** — her zaman `await figma.setCurrentPageAsync(page)` kullan.
-
-### Çağrılar arası
-
-Her `figma_execute` çağrısında `figma.currentPage` ilk sayfaya sıfırlanır. Çoklu çağrı gerektiren iş akışlarında her çağrının başında `setCurrentPageAsync` çağır.
+Sync `figma.currentPage = page` HATA verir. Her `figma_execute`'ta `currentPage` sıfırlanır.
 
 ## 3. Auto-Layout Kalıpları
 
-### Frame oluşturma
-
 ```js
 const frame = figma.createFrame();
 frame.layoutMode = "VERTICAL";
@@ -189,140 +156,130 @@ frame.paddingTop = frame.paddingBottom = 24;
 frame.paddingLeft = frame.paddingRight = 24;
 ```
 
-### FILL boyutlandırma (sıralama kritik)
-
-```js
-const parent = figma.createFrame();
-parent.layoutMode = "VERTICAL";
-const child = figma.createFrame();
-parent.appendChild(child); // ÖNCE ekle
-child.layoutSizingHorizontal = "FILL"; // SONRA FILL ayarla
-```
+FILL boyutlandırma: ÖNCE appendChild, SONRA `layoutSizingHorizontal = "FILL"` (Rule 11).
 
 ## 4. Bileşen ve Instance Kalıpları
 
-### Mevcut bileşen ile instance oluşturma
-
-Tercihen `figma_instantiate_component` aracını kullan. `figma_execute` içinde:
-
 ```js
-const component = figma.root.findOne(
-  n => n.type === "COMPONENT" && n.name === "Button"
-);
-if (!component) return { error: "Bileşen bulunamadı" };
-const instance = component.createInstance();
-return { instanceId: instance.id, componentName: component.name };
+// Local component
+const comp = figma.root.findOne(n => n.type === "COMPONENT" && n.name === "Button");
+const instance = comp.createInstance();
+
+// Variant seçimi
+const set = figma.root.findOne(n => n.type === "COMPONENT_SET" && n.name === "Button");
+const variant = set.children.find(c => c.name === "Size=Large, Type=Primary");
+const inst = variant.createInstance();
 ```
 
-### Variant seçimi
+## 5. Variable Bağlama
 
 ```js
-const componentSet = figma.root.findOne(
-  n => n.type === "COMPONENT_SET" && n.name === "Button"
-);
-const variant = componentSet.children.find(
-  c => c.name === "Size=Large, Type=Primary"
-);
-const instance = variant.createInstance();
-```
-
-## 5. Variable Bağlama Kalıpları
-
-```js
-const collections = await figma.variables.getLocalVariableCollectionsAsync();
-const colorCollection = collections.find(c => c.name === "Colors");
-const variables = await Promise.all(
-  colorCollection.variableIds.map(id =>
-    figma.variables.getVariableByIdAsync(id)
-  )
-);
-const primaryColor = variables.find(v => v.name === "primary/500");
-
-// Fill'e bağla
+const variable = await figma.variables.importVariableByKeyAsync("KEY");
+// Fill bind
 const fills = [...node.fills];
-const boundPaint = figma.variables.setBoundVariableForPaint(
-  fills[0], "color", primaryColor
-);
-node.fills = [boundPaint]; // YENİ paint'i geri ata
+node.fills = [figma.variables.setBoundVariableForPaint(fills[0], "color", variable)];
+// Spacing bind
+node.setBoundVariable("paddingLeft", variable);
 ```
 
-## 6. Ek API Gotcha'lar (Canlı Testte Keşfedilen)
-
-17. **`import` keyword yasağı.** Plugin sandbox'ta `eval()` ile kod çalıştırılır. `import` JavaScript reserved word olduğundan function/variable adında kullanılamaz:
-```js
-// YANLIŞ — syntax error verir
-const iv = async (k) => await figma.variables.importVariableByKeyAsync(k);
-
-// DOĞRU
-async function getVar(k) { return await figma.variables.importVariableByKeyAsync(k); }
-```
-
-18. **`setEffectStyleIdAsync` zorunlu.** Sync setter `node.effectStyleId = style.id` dynamic-page mode'da hata verir:
-```js
-// YANLIŞ
-card.effectStyleId = esCard.id;
-
-// DOĞRU
-await card.setEffectStyleIdAsync(esCard.id);
-```
-
-19. **`setTextStyleIdAsync` kullan, fontSize variable binding YASAK.** Text style atamak font, size, line-height, letter-spacing'i tek seferde bağlar:
-```js
-// YANLIŞ — sadece font size bağlar, style bağlamaz
-textNode.setBoundVariable("fontSize", fontSizeVar);
-
-// DOĞRU — tüm tipografi token'larını tek seferde uygular
-const style = await figma.importStyleByKeyAsync("TEXT_STYLE_KEY");
-await textNode.setTextStyleIdAsync(style.id);
-```
-
-20. **`setExplicitVariableModeForCollection` — string ID çalışmaz.** Library API chain ile collection OBJECT alınmalı:
-```js
-// YANLIŞ — hata verir
-frame.setExplicitVariableModeForCollection("VariableCollectionId:3015:5729", "3019:3");
-
-// DOĞRU — library API chain
-var colls = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
-var sem = colls.find(function(c){ return c.name.indexOf("Semantic Colors") !== -1; });
-var vars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(sem.key);
-var first = await figma.variables.importVariableByKeyAsync(vars[0].key);
-var coll = await figma.variables.getVariableCollectionByIdAsync(first.variableCollectionId);
-var darkMode = coll.modes.find(function(m){ return m.name === "Dark"; });
-frame.setExplicitVariableModeForCollection(coll, darkMode.modeId);
-```
-
-21. **Escaped quote dikkat.** `figma_execute` code parametresinde `\"` yerine düz `"` kullan. Template literal içinde kaçış karakteri syntax error verir.
+## 6. Ek API Gotcha'lar
+
+17. **`import` keyword yasağı.** Plugin sandbox'ta reserved word. `async function getVar(k)` kullan.
+
+18. **`setEffectStyleIdAsync` zorunlu.** Sync `node.effectStyleId = id` hata verir.
+
+19. **`setTextStyleIdAsync` kullan, fontSize binding YASAK:**
+    ```js
+    const style = await figma.importStyleByKeyAsync("KEY");
+    await textNode.setTextStyleIdAsync(style.id);
+    ```
+
+20. **`setExplicitVariableModeForCollection` — string ID çalışmaz.** Library API chain ile collection OBJECT al:
+    ```js
+    var colls = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+    var sem = colls.find(c => c.name.indexOf("Semantic Colors") !== -1);
+    var vars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(sem.key);
+    var first = await figma.variables.importVariableByKeyAsync(vars[0].key);
+    var coll = await figma.variables.getVariableCollectionByIdAsync(first.variableCollectionId);
+    var darkMode = coll.modes.find(m => m.name === "Dark");
+    frame.setExplicitVariableModeForCollection(coll, darkMode.modeId);
+    ```
+
+21. **Escaped quote dikkat.** `figma_execute` code'da `\"` yerine düz `"` kullan.
+
+23. **Style Import Sessiz Fail.** `importStyleByKeyAsync` null/throws olabilir. Her zaman try-catch:
+    ```js
+    let style = null;
+    try { style = await figma.importStyleByKeyAsync("KEY"); } catch(e) {}
+    if (style) {
+      await textNode.setTextStyleIdAsync(style.id);
+      await figma.loadFontAsync(textNode.fontName);
+      textNode.characters = "Metin";
+    } else {
+      await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+      textNode.fontName = { family: "Inter", style: "Regular" };
+      textNode.characters = "Metin (fallback)";
+    }
+    ```
+    **Fast Path:** roleMap hazırsa `setTextStyleIdAsync(roleMap[role].id)` direkt kullan, import atla (bkz. fmcp-screen-recipes Adım 1.6).
+
+24. **Component Discovery Fallback.** `figma_search_assets` boş dönerse manuel instance scan:
+    ```js
+    const instances = figma.currentPage.findAll(n => n.type === "INSTANCE");
+    const map = new Map();
+    for (const inst of instances) {
+      const main = await inst.getMainComponentAsync();
+      if (main && main.remote && main.key && !map.has(main.name))
+        map.set(main.name, { name: main.name, key: main.key });
+    }
+    return Array.from(map.values());
+    ```
+    Sıra: (1) Cache → (2) `figma_search_assets` → (3) Manuel scan → (4) Key biliniyor → `importComponentByKeyAsync(key)` direkt.
+
+25. **`figma_validate_screen` Timeout Fallback.** 3 seviyeli:
+    - **Seviye 1:** `figma_validate_screen(nodeId, minScore=80)` — timeout olursa:
+    - **Seviye 2:** Content Body wrapper'ı validate et (daha küçük tree), minScore=70
+    - **Seviye 3:** Manuel QA Checklist üret:
+      - [ ] Instance coverage ≥60%
+      - [ ] Rastgele 5 fill'de variable icon 🎨 var mı
+      - [ ] Rastgele 3 spacing variable-bound mu
+      - [ ] Auto-layout tüm frame'lerde aktif mi
+      - [ ] Dark mode renkleri doğru mu
+
+26. **Component Property Discovery — Tek Execute.**
+    ```js
+    const comp = await figma.importComponentByKeyAsync(key);
+    let set = comp.parent?.type === "COMPONENT_SET" ? comp.parent : comp;
+    const propDefs = set.componentPropertyDefinitions || {};
+    return {
+      componentName: comp.name,
+      propertyDefinitions: Object.entries(propDefs).map(([n, d]) => ({
+        name: n, type: d.type, defaultValue: d.defaultValue, variantOptions: d.variantOptions || []
+      }))
+    };
+    ```
+    `figma_instantiate_component` timeout olursa: `figma_execute` içinde `importComponentByKeyAsync(key)` + `comp.createInstance()`.
+
+    **Text Style Discovery:** (1) Instance scan: `findAll(TEXT)` → `textStyleId` → `getStyleByIdAsync` (2) Boşsa `figma_search_assets` (3) Boşsa team library API (4) Fallback Inter + hardcoded size.
 
 ## 7. Hata Kurtarma
 
-1. `figma_execute` hata dönerse **hemen tekrar deneme**
-2. Hata mesajını oku ve analiz et
-3. Yaygın hatalar:
-   - `Cannot read property of undefined` → Node ID geçersiz veya sayfa yüklenmemiş
-   - `Font not loaded` → `loadFontAsync` eksik
-   - `Cannot set FILL before appendChild` → Sıralama hatası
-   - `Maximum call stack` → Sonsuz döngü; daha küçük parçalara böl
-4. Scripti düzelt ve yeni çağrı yap
-
-## 7. Doğrulama Adımları
-
-Her yazma işleminden sonra:
-
-1. `figma_capture_screenshot` ile görsel doğrulama
-2. Gerekirse `figma_get_file_data` ile yapı kontrolü
-3. Oluşturulan node ID'lerini sonraki çağrılarda referans olarak kullan
+| Hata | Çözüm |
+|---|---|
+| `Cannot read property of undefined` | Node ID geçersiz / sayfa yüklenmemiş |
+| `Font not loaded` | `loadFontAsync` eksik |
+| `Font could not be loaded` | Weight yok → `pickStyle()` fallback (Rule 8a-1) |
+| `Cannot set FILL before appendChild` | Rule 11 sırası |
+| `Maximum call stack` | Küçük parçalara böl |
+| `Resource links not supported` | Yanlış MCP (resmi) → F-MCP kullan |
 
-## F-MCP skill koordinasyonu
+## 8. Doğrulama
 
-Bu skill şu skill'lerle birlikte kullanılır:
-- **generate-figma-screen** — Ekran oluşturma iş akışı
-- **generate-figma-library** — DS kütüphanesi inşa
-- **apply-figma-design-system** — DS hizalama
-- **fix-figma-design-system-finding** — Tek bulgu düzeltme
-- **figjam-diagram-builder** — FigJam diyagram oluşturma
+Her yazma sonrası: `figma_capture_screenshot` + gerekirse `figma_get_file_data`.
 
-## Evolution Triggers
+## Skill Koordinasyonu
 
-- Bridge'e yeni `figma_*` yazma aracı eklendiğinde ilgili kalıp bölümü güncellenmeli
-- `figma_execute` parametrelerinde değişiklik olursa Kural 1–2 güncellenmeli
-- Yeni Plugin API yetenekleri bridge'e eklendiğinde ilgili örnekler eklenmeli
+- **fmcp-screen-orchestrator** — DS GATE, Fast Path routing
+- **fmcp-screen-recipes** — Fast Path (Rule 25 validate, Rule 26 discovery referans alınır)
+- **generate-figma-screen** — Tam workflow
+- **generate-figma-library** / **apply-figma-design-system** / **fix-figma-design-system-finding** / **figjam-diagram-builder**