@atezer/figma-mcp-bridge 1.7.23 → 1.7.25

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

@@ -0,0 +1,325 @@
+---
+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.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - designer
+    - designops
+---
+
+# Figma Canvas Ops — figma_execute Güvenli Kullanım Kılavuzu
+
+## Overview
+
+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 |
+|---|---|---|
+| `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 |
+| `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.
+
+2. **Düz JavaScript yaz, top-level `await` kullan.** Kod otomatik async bağlama sarılır. `(async () => { ... })()` ile sarma.
+
+3. **`figma.notify()` çalışmaz** — kullanma.
+
+4. **`console.log()` dönmez** — çıktı için `return` kullan.
+
+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.
+
+   **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
+
+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.
+
+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;
+```
+
+8. **Font yükleme zorunlu** — metin işleminden önce font yükle. Hangi fontu kullanacağını belirlemek için şu sırayı takip et:
+
+   **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.
+
+   **b)** Kütüphane yoksa veya font bilgisi bulunamazsa kullanıcıya sor: "Hangi fontu kullanmamı istersiniz?"
+
+   **c)** Kullanıcı "sen seç" derse `Inter` kullan.
+
+```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ı".
+
+   **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
+   ```
+
+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);
+```
+
+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ış:
+
+   **a) Kütüphaneden variable key'lerini oku:** `.claude/libraries/` dosyasını kontrol et. Key yoksa SUI/DS dosyasında `figma_execute` ile çek:
+   ```js
+   // DS dosyasında çalıştır (fileKey = DS dosyasının key'i)
+   const v = await figma.variables.getVariableByIdAsync("VariableID:...");
+   return { name: v.name, key: v.key };
+   ```
+
+   **b) Hedef dosyada variable'ı import et:**
+   ```js
+   const variable = await figma.variables.importVariableByKeyAsync("VARIABLE_KEY");
+   ```
+
+   **c) Renk bağlama (fill/stroke):** `setBoundVariableForPaint` kullan — DİKKAT: yeni paint döner, yakala ve geri ata:
+   ```js
+   const fills = [...node.fills];
+   const boundPaint = figma.variables.setBoundVariableForPaint(fills[0], "color", variable);
+   node.fills = [boundPaint];
+   ```
+
+   **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);
+   ```
+
+   **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);
+   ```
+
+   **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];
+   ```
+
+   **Asla** `node.fills = [{ type: "SOLID", color: { r: X, g: Y, b: Z } }]` gibi hardcoded renk yazma. Her zaman variable import et ve bağla.
+
+11. **`layoutSizingHorizontal/Vertical = 'FILL'` appendChild'DAN SONRA** ayarlanmalı — öncesinde hata verir.
+
+12. **Yeni üst-düzey node'ları (0,0)'dan uzağa konumlandır.** `figma.currentPage.children` tarayarak boş alan bul.
+
+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.
+
+14. **Tüm oluşturulan/değiştirilen node ID'lerini RETURN ET:**
+```js
+return { createdNodeIds: [...], mutatedNodeIds: [...] };
+```
+
+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"]`
+
+16. **Her Promise'i `await` et.** `await` olmadan async çağrılar sessizce başarısız olur.
+
+## 2. Sayfa Kuralları
+
+### Sayfalar arası geçiş
+
+```js
+const targetPage = figma.root.children.find(p => p.name === "Sayfa Adı");
+await figma.setCurrentPageAsync(targetPage);
+// targetPage.children artık yüklü
+```
+
+**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.
+
+## 3. Auto-Layout Kalıpları
+
+### Frame oluşturma
+
+```js
+const frame = figma.createFrame();
+frame.layoutMode = "VERTICAL";
+frame.primaryAxisSizingMode = "AUTO";
+frame.counterAxisSizingMode = "AUTO";
+frame.itemSpacing = 16;
+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
+```
+
+## 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 };
+```
+
+### Variant seçimi
+
+```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 fills = [...node.fills];
+const boundPaint = figma.variables.setBoundVariableForPaint(
+  fills[0], "color", primaryColor
+);
+node.fills = [boundPaint]; // YENİ paint'i geri ata
+```
+
+## 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.
+
+## 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
+
+## F-MCP skill koordinasyonu
+
+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
+
+## Evolution Triggers
+
+- 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

package/skills/figma-screen-analyzer/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: figma-screen-analyzer
+description: Figma ekranını teknik olmayan dilde analiz eder. Bileşen envanteri, DS uyum oranı, görsel hiyerarşi, kullanıcı akışı özeti ve design token kapsamı raporlar. PO, PM ve SEM'lerin tasarım durumunu anlamaları için tasarlanmıştır. "ekranı analiz et", "tasarım raporu", "screen analysis", "UI raporu çıkar", "ne var bu ekranda", "bileşen sayısı", "DS uyum oranı" ifadeleriyle tetiklenir. F-MCP Bridge plugin bağlantısı gerektirir.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - po
+    - designer
+---
+
+# Figma Screen Analyzer — UI Analiz Raporu
+
+## Overview
+
+Bu skill, Figma ekranını **teknik olmayan** dilde analiz ederek PO, PM ve SEM'ler için anlaşılır bir rapor üretir. DS uyum oranı, bileşen envanteri, görsel hiyerarşi değerlendirmesi ve aksiyon önerileri içerir.
+
+**Salt okunur** — Figma tuvalinde değişiklik yapmaz.
+
+## Prerequisites
+
+- F-MCP Bridge plugin bağlı olmalı
+- Hedef ekranın node ID'si veya URL'i bilinmeli
+
+## F-MCP skill koordinasyonu
+
+- **İlişkili:** `audit-figma-design-system` (teknik DS denetimi — bu skill'in PO/PM versiyonu)
+- **Sonra:** Bulgulara göre `apply-figma-design-system` veya `ai-handoff-export` önerilir
+- **Karşılaştırma:** İki ekran karşılaştırması için her ikisine de ayrı analiz yapılır
+
+## Required Workflow
+
+### Step 1: Plugin Bağlantısını Doğrula
+
+```
+figma_get_status()
+```
+
+### Step 2: Ekran Verisi Topla
+
+> **DERİN ANALİZ KURALI:** Sadece frame/node isimlerine bakarak sonuç çıkarma. Her node'un içindeki text content (`characters`), instance prop'ları ve child yapılarını detaylı oku. Bir şeyin "eksik" veya "yok" olduğunu iddia etmeden önce tüm child node'ların içeriğini kontrol et.
+
+> **GÖRSEL DOĞRULAMA KURALI:** Analiz sonucunu raporlamadan önce `figma_capture_screenshot` ile ekran görüntüsü al ve görsel olarak kontrol et. Text content ile screenshot'ın tutarlı olduğunu teyit et. Çelişki varsa screenshot'ı esas al.
+
+```
+figma_get_design_context(
+  nodeId="<NODE_ID>",
+  depth=3,
+  verbosity="full",
+  includeLayout=true,
+  includeVisual=true,
+  includeTypography=true
+)
+```
+
+```
+figma_capture_screenshot(nodeId="<NODE_ID>")
+```
+
+### Step 3: İlk İzlenim Analizi (2 Saniye Testi)
+
+Screenshot'a bakarak hızlı sezgisel değerlendirme yap (DS metriklerinden ÖNCE):
+
+1. **Göz çekimi:** İlk bakışta göz nereye gidiyor? Bu doğru öğe mi? (CTA, başlık, hero görsel?)
+2. **Duygusal tepki:** Ekran güven mi, kafa karışıklığı mı, heyecan mı uyandırıyor?
+3. **Amaç netliği:** Ekranın ne için olduğu 2 saniyede anlaşılıyor mu?
+4. **Görsel yoğunluk:** Sıkışık mı, dengeli mi, çok boş mu?
+
+> Bu bölüm **sezgisel** — metrik değil, izlenim. Raporda "İlk İzlenim" başlığı altında 2-3 cümle.
+
+### Step 4: DS Uyum Analizi
+
+```
+figma_get_design_system_summary()
+```
+
+`figma_execute` ile instance ve token sayımı:
+
+```js
+const page = figma.currentPage;
+const target = page.findOne(n => n.id === "<NODE_ID>");
+if (!target) return { error: "Node bulunamadı" };
+
+const allNodes = target.findAll(() => true);
+const instances = target.findAll(n => n.type === "INSTANCE");
+const textNodes = target.findAll(n => n.type === "TEXT");
+const frames = target.findAll(n => n.type === "FRAME");
+
+let boundVariableCount = 0;
+let unboundCount = 0;
+allNodes.forEach(n => {
+  if (n.boundVariables && Object.keys(n.boundVariables).length > 0) {
+    boundVariableCount++;
+  }
+  if (n.fills && n.fills.length > 0 && n.type !== "INSTANCE") {
+    const hasBound = n.boundVariables && n.boundVariables.fills;
+    if (!hasBound) unboundCount++;
+  }
+});
+
+const uniqueComponents = new Map();
+instances.forEach(inst => {
+  const mc = inst.mainComponent;
+  const key = mc?.key || mc?.id;
+  const name = mc?.name || "Bilinmeyen";
+  if (key) {
+    if (!uniqueComponents.has(key)) uniqueComponents.set(key, { name, count: 0 });
+    uniqueComponents.get(key).count++;
+  }
+});
+
+return {
+  totalNodes: allNodes.length,
+  instanceCount: instances.length,
+  textNodeCount: textNodes.length,
+  frameCount: frames.length,
+  boundVariableCount,
+  unboundFillCount: unboundCount,
+  uniqueComponents: [...uniqueComponents.values()],
+  dsComplianceRate: Math.round(((instances.length + boundVariableCount) / Math.max(allNodes.length, 1)) * 100)
+};
+```
+
+### Step 5: Görsel Hiyerarşi Değerlendirmesi
+
+AI analizi ile:
+
+1. **Ana bölümler:** Ekranın kaç ana bölümü var (header, content, footer, sidebar vb.)
+2. **Görsel akış:** Kullanıcı gözünün doğal akışı (F-pattern, Z-pattern, üstten alta)
+3. **Öne çıkan öğeler:** CTA butonları, başlıklar, görsel odak noktaları
+4. **Boşluk dengesi:** Sıkışık mı, dengeli mi, çok boş mu
+5. **Okuma sırası doğru mu?** Başlık → alt başlık → içerik → CTA sırası mantıklı mı?
+6. **Vurgu doğru elemanda mı?** CTA görsel olarak en dikkat çekici mi, yoksa dekoratif bir öğe mi öne çıkıyor?
+7. **Tipografi hiyerarşisi net mi?** Kaç farklı boyut var? 3-4 kademe yeterli, 7+ sorun işareti
+8. **Beyaz alan etkili mi?** Kasıtlı dramatik boşluk mu, dengesiz dağılım mı, sıkışıklık mı?
+
+### Step 6: Geri Bildirim Prensipleri
+
+Rapor üretilirken aşağıdaki prensiplere uyulmalı:
+
+1. **Spesifik ol** — "CTA navigasyonla yarışıyor" yaz, "layout kafa karıştırıcı" yazma
+2. **Neden'i açıkla** — Geri bildirimi tasarım prensibine veya kullanıcı ihtiyacına bağla
+3. **Alternatif öner** — Sadece sorun tespit etme, çözüm de sun
+4. **İyi olanı kabul et** — Yalnızca eleştiri değil, iyi yapılan şeyleri de raporla
+5. **Aşamaya göre ayarla** — Erken keşif farklı feedback alır, son düzeltme farklı
+
+### Step 7: Rapor Üret
+
+> **Marka Profili Entegrasyonu:** `.fmcp-brand-profile.json` varsa `aestheticDirection` ve `typography` bilgisiyle değerlendir — ekranın marka estetiğiyle uyumu raporla.
+
+## Çıktı Formatı
+
+### Executive Summary (Varsayılan)
+
+```markdown
+# Ekran Analiz Raporu — [Ekran Adı]
+
+## Özet Tablo
+
+| Metrik | Değer | Durum |
+|---|---|---|
+| Toplam öğe | 127 | — |
+| DS bileşeni (instance) | 23 | ✓ İyi |
+| Benzersiz bileşen türü | 8 | — |
+| Token'a bağlı öğe | 45 | ✓ İyi |
+| Bağsız renk (hardcode) | 5 | ⚠ Düzeltilmeli |
+| DS Uyum Oranı | %85 | ✓ Kabul edilebilir |
+
+## Bileşen Envanteri
+
+| Bileşen | Kullanım Sayısı |
+|---|---|
+| Button | 5 |
+| Input | 3 |
+| Card | 4 |
+| NavBar | 1 |
+| Avatar | 2 |
+| Badge | 3 |
+| Icon | 5 |
+
+## Görsel Hiyerarşi
+
+- **Ana akış:** Üstten alta, F-pattern
+- **Bölümler:** Header → Arama → Filtreler → Kart Listesi → Footer
+- **CTA:** "Yeni Ekle" butonu sağ üstte — dikkat çekici konumda ✓
+- **Boşluk:** Dengeli — bölümler arası tutarlı spacing
+
+## Öneriler
+
+1. 5 hardcode renk token'a bağlanmalı (tema değişikliğinde kırılır)
+2. Alt bölümdeki 2 custom card DS Card bileşenine çevrilebilir
+3. Genel DS uyumu iyi — üretime hazır
+
+## Sonraki Adımlar
+→ `audit-figma-design-system` ile detaylı teknik denetim
+→ `ai-handoff-export` ile implementasyon paketi
+```
+
+### Karşılaştırmalı Rapor (İki Ekran)
+
+İki ekran ID'si verildiğinde yan yana karşılaştırma:
+
+```markdown
+## Karşılaştırma — Ekran A vs Ekran B
+
+| Metrik | Ekran A | Ekran B | Fark |
+|---|---|---|---|
+| DS Uyum | %85 | %72 | Ekran B %13 düşük |
+| Instance sayısı | 23 | 15 | Ekran B'de daha az DS kullanımı |
+| Hardcode renk | 5 | 12 | Ekran B'de 2.4x daha fazla |
+```
+
+### JSON Çıktı (`--json`)
+
+Yapılandırılmış JSON — dashboard veya CI entegrasyonu için.
+
+## Türkçe Karakter Kuralı (ZORUNLU)
+
+Tüm Türkçe metin içeriklerinde (Figma text node, kod string, dokümantasyon) doğru Unicode karakterler kullanılmalıdır. ASCII karşılıkları YASAKTIR:
+
+| Doğru | Yanlış | Doğru | Yanlış |
+|-------|--------|-------|--------|
+| ş | s | Ş | S |
+| ı | i | İ | I |
+| ö | o | Ö | O |
+| ü | u | Ü | U |
+| ç | c | Ç | C |
+| ğ | g | Ğ | G |
+
+Son adım: Üretilen tüm Türkçe metinleri karakter kontrolünden geçir.
+
+## Evolution Triggers
+
+- PO/PM geri bildirimine göre rapor metrikleri genişletilmeli
+- Yeni DS analiz araçları bridge'e eklenirse daha detaylı metrikler çıkarılmalı
+- Sprint/milestone bazlı trend izleme desteği eklenebilir

package/skills/fix-figma-design-system-finding/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: fix-figma-design-system-finding
+description: audit-figma-design-system ile tespit edilen tek bir design system bulgusunu Figma tuvalinde dar kapsamda düzeltir (swap, token bağlama, variant hizalama). F-MCP Bridge ve figma_execute gerektirir. "tek bulguyu düzelt", "ds finding fix", "şu node'u kütüphaneye bağla", "bileşeni değiştir", "token bağla" ifadeleriyle tetiklenir.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - designer
+    - designops
+---
+
+# Fix Figma Design System Finding (dar yazma)
+
+## Overview
+
+**Tek bulgu**, **tek sorunlu node veya minimal küme**, **minimal okuma/yazma**. `audit-figma-design-system` çıktısı veya eşdeğer net görev tanımı olmadan kapsamı sessizce genişletme.
+
+Ekran geneli veya çoklu bölüm için **apply-figma-design-system** kullan.
+
+## F-MCP araç eşlemesi
+
+| Niyet | F-MCP Bridge |
+|--------|----------------|
+| Okuma | `figma_get_design_context`, `figma_capture_screenshot`, `figma_get_file_data` (gerekirse düşük `depth`), `figma_get_component`, `figma_get_variables`, `figma_get_styles` |
+| Kütüphane adayı | `figma_search_components`, `figma_get_component` |
+| Tuval yazma / Plugin API | `figma_execute` (Figma plugin JS; swap, import, yedek kopya) |
+| Bağlantı | `figma_get_status()` |
+
+`figma_execute` içinde büyük JSON döndürme; **figjam-diagram-builder** skill’indeki kısa dönüş disiplinine benzer şekilde özet sonuç tercih et.
+
+## F-MCP skill koordinasyonu
+
+| Durum | Sonraki skill |
+|--------|----------------|
+| Audit’ten önce tek düzeltme istendi | İsteğe bağlı kısa `audit-figma-design-system` ile doğrula; sonra bu skill |
+| Birden fazla bulgu, koordineli reconcile | **apply-figma-design-system** |
+| Sadece kod token dosyası güncellemesi | **design-token-pipeline** (tuval + kod ayrı) |
+| Düzeltme sonrası kod parity | **design-drift-detector** |
+| Mapping güncellemesi | **code-design-mapper** |
+| İsteğe bağlı regresyon (tuval) | **audit-figma-design-system** ile aynı node’u yeniden denetle |
+
+## Beklenen girdi
+
+Bu skill üç farklı girdi formatını otomatik algılar:
+
+1. **Tek finding JSON** — `audit-figma-design-system` çıktısından tek `finding` objesi. `code_location` alanı varsa bu format algılanır.
+2. **Tam audit JSON + indeks** — Tüm audit çıktısı + hangi bulgunun düzeltileceği (indeks veya `ruleId`). `findings` dizisi varsa bu format algılanır.
+3. **Serbest metin + URL** — Sorun özeti + Figma URL / `fileKey` + `nodeId`. Yapılandırılmış JSON yoksa bu format algılanır.
+
+**Format algılama sırası:** `code_location` → `findings[]` → serbest metin fallback.
+
+Audit JSON kullanılıyorsa `code_location.absolute_file_path` içinden `fileKey` ve `nodeId` çıkar: `/figma/<fileKey>/nodes/<nodeId>`.
+
+## Kapsam kuralı
+
+Seçilen bulgu çözülene, **blocked** veya **needs-follow-up** raporlanana kadar başka cleanup yapma. Birden fazla bulgu kullanıcıda varsa birini seç veya en yüksek öncelikli tekini uygula; geri kalanı için audit/apply yönlendir.
+
+## Required Workflow
+
+1. **Plugin bağlantısını doğrula:** `figma_get_status()` — bağlantı yoksa devam etme.
+3. **Normalize:** `fileKey`, `nodeId`, bulgu başlığı ve gerekçe.
+3. **Uyumluluk (belirsiz replacement’ta):** Yazmadan önce hangi component/variant, override’lar, layout sözleşmesi — sonuç `safe-to-apply` \| `blocked` \| `needs-human-choice`. `blocked` / `needs-human-choice` ise yazma; durumu bildir.
+4. **Minimal kanıt:** `figma_capture_screenshot`; yapı için `figma_get_design_context` veya `figma_get_file_data` (dar kapsam); token bulgusuysa `figma_get_variables` / `figma_get_styles`; gerekirse `figma_search_components`.
+5. **Remediasyon modu (tek seç):** `swap-instance` \| `compose-from-primitives` \| `bind-tokens` \| `align-variant` \| `blocked`. En küçük yeterli değişiklik.
+6. **Yedek:** Yıkıcı düzenlemeden önce yalnızca etkilenen alt ağacı veya minimal üst section’ı çoğalt; net isimlendir (`Backup - Fix finding …`). Mümkünse ayrı `figma_execute` çağrısı; dönen node id’yi not et.
+7. **Uygula:** `figma_execute` ile adım adım. Remediasyon modu örnekleri:
+
+   **swap-instance** (mevcut node'u kütüphane bileşeniyle değiştir):
+   ```js
+   const node = await figma.getNodeByIdAsync("<NODE_ID>");
+   const comp = await figma.importComponentByKeyAsync("<COMPONENT_KEY>");
+   // veya local: figma.root.findOne(n => n.type === "COMPONENT" && n.name === "<NAME>");
+   const instance = comp.createInstance();
+   instance.x = node.x; instance.y = node.y;
+   instance.resize(node.width, node.height);
+   if (node.parent) node.parent.insertChild(node.parent.children.indexOf(node), instance);
+   node.remove();
+   return { swapped: instance.id, replacedName: node.name };
+   ```
+
+   **bind-tokens** (hard-coded değeri variable'a bağla):
+   ```js
+   const node = await figma.getNodeByIdAsync("<NODE_ID>");
+   const variable = await figma.variables.getVariableByIdAsync("<VAR_ID>");
+   const fills = [...node.fills];
+   const boundPaint = figma.variables.setBoundVariableForPaint(fills[0], "color", variable);
+   node.fills = [boundPaint];
+   return { bound: node.name, variable: variable.name };
+   ```
+
+   **align-variant** (yanlış variant'ı doğrusuyla değiştir):
+   ```js
+   const instance = await figma.getNodeByIdAsync("<INSTANCE_ID>");
+   instance.setProperties({ "Variant": "Primary" });
+   return { aligned: instance.id, newVariant: "Primary" };
+   ```
+
+8. **Doğrula:** Bulgunun özellikle çözüldüğünü screenshot ve yapı ile kanıtla; global pattern dokunduysa genişlet.
+9. **İsteğe bağlı:** Regresyon için **audit-figma-design-system** ile aynı kapsamı yeniden çalıştır (özellikle çok adımlı fix sonrası).
+
+## Yazma kuralları
+
+- Belirsiz replacement’ta `safe-to-apply` yoksa yazma.
+- Tek bulgu düzeltildi diye tüm ekranı “sistemde” ilan etme.
+- Component key ve variable id’leri isimden önce tercih et.
+- Import timeout / erişilemeyen kütüphane → `blocked`, zorla devam etme.
+
+## Kapanış raporu
+
+- **Finding fixed:** Ne değişti, hangi node.
+- **Validation:** Orijinal şikayetin giderildiği kanıtı.
+- **Blocked / Follow-up:** Varsa kısa.
+
+## Evolution Triggers
+
+- Bridge'e yeni `figma_execute` kalıpları eklendiğinde remediasyon modları güncellenmeli
+- Audit bulgu formatı değişirse girdi normalize adımı uyarlanmalı
+- Batch düzeltme desteği eklenirse tek/toplu mod ayrımı yapılmalı