@atezer/figma-mcp-bridge 1.7.23 → 1.7.25

package/skills/audit-figma-design-system/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: audit-figma-design-system
+description: Figma ekran veya bileşenini design system entegrasyonu açısından okuma-only denetler; eksik kütüphane instance'ları, yerel override'lar ve bağlanmamış token'ları raporlar. "figma ds audit", "design system audit", "kütüphane kullanımı kontrol", "token bağlı mı", "DS sağlık kontrolü", "ne kadar DS uyumlu", "tasarım durumu raporu", "ekran kalitesi" ifadeleriyle tetiklenir. F-MCP Bridge plugin bağlantısı gerektirir.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - designer
+    - designops
+    - po
+---
+
+# Audit Figma Design System (tuval içi)
+
+## Overview
+
+Bu skill **yalnızca okur**; Figma node'unun yayınlanmış design system ile ne kadar entegre olduğunu yapısal kanıta dayanarak denetler. Görsel tatmin değil, **instance / tekrar / ham değer / token bağlama** odaklıdır.
+
+Yazma gerekiyorsa aşağıdaki skill’lerden birine yönlendir.
+
+## F-MCP araç eşlemesi (resmi Figma MCP isimleri yerine)
+
+| Niyet | F-MCP Bridge |
+|--------|----------------|
+| Design context | `figma_get_design_context` |
+| Görsel doğrulama | `figma_capture_screenshot` |
+| Variable / bağlılık | `figma_get_variables` (verbosity=`full`), gerekiyorsa `figma_get_styles` |
+| Yapı / iç içe instance haritası | `figma_get_file_data` (düşük `depth`), hedef node için `figma_get_component` veya `figma_get_design_context`; büyük tahta için `figma_get_file_data` (timeout riski — dikkat). **Not:** Bridge’te ayrı bir “yalnızca metadata” MCP aracı yok; yapı bu üç araçla alınır. |
+| Kod/dev spec ipucu | `figma_get_design_context` (`includeCodeReady=true`); uygunsa `figma_get_component_for_development` |
+| Kütüphanede aday bileşen | `figma_search_components`, özet için `figma_get_design_system_summary` |
+
+## F-MCP skill koordinasyonu
+
+| Bulgu sonrası | Ne zaman |
+|---------------|----------|
+| **fix-figma-design-system-finding** | Tek net bulgu, tek node veya dar küme |
+| **apply-figma-design-system** | Çoklu bulgu, ekran geneli veya bölüm bölüm reconcile |
+| **design-token-pipeline** | Rapor “token export / kod tarafı senkron” gerektiriyorsa |
+| **design-drift-detector** | Aynı ekranın **kod** ile parity’si de soruluyorsa (Figma audit’ten sonra) |
+| **code-design-mapper** | Eşleştirilecek bileşen aileleri netleştikten sonra mapping güncellemesi |
+| **figma-screen-analyzer** | PO/PM/SEM'e yönelik teknik olmayan ekran analizi ve DS uyum raporu |
+| **ds-impact-analysis** | Bir token/bileşen değişikliğinin etki yarıçapını ölçmek istiyorsan |
+| **ai-handoff-export** / **implement-design** | Audit “Pass” veya düzeltme sonrası koda geçiş |
+
+### Önerilen uçtan uca akış (özet)
+
+1. **audit-figma-design-system** (tuval DS uyumu)  
+2. **fix-figma-design-system-finding** (tek bulgu) *veya* **apply-figma-design-system** (çok bölüm)  
+3. **design-token-pipeline** (kod token dosyaları)  
+4. İsteğe bağlı **code-design-mapper**  
+5. **ai-handoff-export** → **implement-design**  
+6. **design-drift-detector** (kod–Figma parity)  
+7. Gerekirse **design-system-rules** ile repo kurallarını güncelle
+
+**FigJam** ve bu zincir zorunlu sıralı değildir.
+
+### Zincir performansı (tek oturum)
+
+- Aynı zincirde **tekrarlı** `figma_get_variables(verbosity="full")` ve `figma_get_design_context` çağrılarını azalt: önceki adımın çıktısı hâlâ geçerliyse yeniden çağırma; mümkünse `verbosity="summary"` ile başla, orta detay için `"standard"`, tam detay için `"full"` kullan.
+- `figma_search_components`: varsayılan **`currentPageOnly=true`**; `false` yalnızca gerektiğinde (büyük dosyada timeout riski).
+
+## Çıktı Formatı
+
+- Kullanıcı `--json` veya JSON isterse: şema altındaki JSON’u **markdown fence’siz**, ek metin yok.
+- Sohbet ortamı veya `--markdown`: insan okunur markdown rapor.
+- **Ortam bazlı otomatik tespit:** CI ortamı algılandığında (`CI=true`, `GITHUB_ACTIONS`, `GITLAB_CI` vb. ortam değişkenleri) varsayılan format **JSON** olarak ayarlanır. Etkileşimli sohbet ortamında varsayılan **markdown**’dır. Kullanıcı her iki durumda da `--json` veya `--markdown` flag’i ile tercihi geçersiz kılabilir.
+- Belirsizse: markdown varsayılan.
+
+## Required Workflow
+
+1. **Girdi:** Figma URL veya `fileKey` + `nodeId`. `node-id=72-293` → `72:293` normalize et.
+2. **Bağlantı:** `figma_get_status()`.
+3. **Kanıt:** Hedef node için `figma_get_design_context`; `figma_capture_screenshot`; `figma_get_variables`. Büyük/hacimli yapıda `figma_get_file_data` (düşük `depth`) veya aynı node üzerinden `figma_get_component` / `figma_get_design_context`. Özel primitive için `figma_search_components`.
+
+> **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.
+4. **İnceleme:** Yerel frame ile yeniden icat edilmiş primitive, tekrarlayan kardeş yapılar, tokenize eşlerin yanında ham hex/spacing/typography, navigasyon gibi yüksek etkili custom yapılar, variant sapması.
+5. **Öneri:** Yalnızca `figma_search_components` ile **inandırıcı** aday bulunduğunda değiştirme öner; zayıf eşleşmede aday yazma.
+6. **Çıktı:** Seçilen formatta rapor; ardından yukarıdaki koordinasyon tablosuna göre sonraki skill’i öner.
+
+## Nielsen 10 Sezgisel Değerlendirme (İsteğe Bağlı)
+
+`--heuristic` flag'i ile aktif edilir. DS denetiminin yanı sıra Jakob Nielsen'in 10 kullanılabilirlik sezgisel ilkesini DS bağlamında değerlendirir:
+
+| # | İlke | DS Bağlamında Değerlendirme |
+|---|------|-----------------------------|
+| 1 | Sistem durumu görünürlüğü | Loading/progress state bileşenleri mevcut mu? |
+| 2 | Sistem-gerçek dünya uyumu | Token isimlendirme kullanıcı diline uygun mu? (ör. `danger` vs `color-red-500`) |
+| 3 | Kullanıcı kontrolü ve özgürlüğü | Undo/geri alma/iptal bileşenleri var mı? (dismiss, close, cancel) |
+| 4 | Tutarlılık ve standartlar | DS bileşenleri platform konvansiyonlarına uyuyor mu? |
+| 5 | Hata önleme | Validation, disabled state, form kısıtlama bileşenleri mevcut mu? |
+| 6 | Tanıma > hatırlama | Bileşen isimleri açıklayıcı mı? Description'lar yeterli mi? |
+| 7 | Kullanım esnekliği | Variant çeşitliliği farklı kullanım senaryolarını kapsıyor mu? |
+| 8 | Estetik ve minimalist tasarım | Token sayısı gereksiz yere şişkin mi? Kullanılmayan variant var mı? |
+| 9 | Hata tanıma ve kurtarma | Error state, empty state, fallback bileşenleri var mı? |
+| 10 | Yardım ve dokümantasyon | Bileşen description'ları, kullanım notları yeterli mi? |
+
+**Çıktı:** Rapora `heuristicEvaluation` bölümü eklenir (JSON veya markdown formatına göre). Her ilke için `pass` / `partial` / `fail` + açıklama.
+
+## DS Eksiksizlik Çerçevesi
+
+Audit sırasında yalnızca instance/token sayısı değil, DS'nin **yapısal eksiksizliği** de değerlendirilir.
+
+### Token Kategorileri Kontrolü
+
+Sağlıklı bir DS'de aşağıdaki token kategorilerinin tamamı bulunmalıdır:
+
+| Kategori | Alt Kategoriler | Min Beklenen |
+|----------|----------------|-------------|
+| **Renkler** | Brand (primary, secondary, accent), Semantic (success, warning, error, info), Neutral (gray scale) | 15+ token |
+| **Tipografi** | Scale (6+ kademe), Weights (regular, medium, semi-bold, bold), Line-heights | 10+ token |
+| **Spacing** | Scale (4/8/12/16/24/32/48/64 vb.) | 6+ token |
+| **Border** | Radius kademeleri (sm, md, lg, full), Genişlik (1, 2) | 4+ token |
+| **Shadow** | Elevation seviyeleri (sm, md, lg, xl) | 3+ token |
+| **Motion** | Duration (fast: 150ms, normal: 250ms, slow: 400ms), Easing (ease-in-out, spring) | 4+ token |
+
+> **Sık eksik:** Motion token'ları — çoğu DS'de duration ve easing tanımlı değil. Audit raporunda bu eksiklik ayrıca belirtilmeli.
+
+### Bileşen Eksiksizlik Kontrolü
+
+Bir bileşenin "eksiksiz" sayılması için:
+
+| Kriter | Açıklama | Kontrol Yöntemi |
+|--------|----------|-----------------|
+| **Variant'lar** | Primary, secondary, ghost/outline, destructive vb. | Component set'te variant prop sayısı |
+| **Durumlar** | Default, hover, active, disabled, loading, error, focus | En az 4 durum olmalı |
+| **Boyutlar** | sm, md, lg (en az 2) | Size prop veya ayrı variant |
+| **Davranış spec'i** | Transition, animasyon, etkileşim notları | Description veya code-only props |
+| **A11y spec'i** | Min touch target, fokus göstergesi, label | Description veya annotation |
+
+> **Mevcut audit'ten farkı:** Mevcut audit instance/token sayar; bu çerçeve bileşenin **iç kalitesini** değerlendirir.
+
+### Pattern Katmanı Kontrolü
+
+Bileşen üstü pattern'ların varlığı (yoksa "DS olgunluk eksikliği" olarak raporla):
+
+| Pattern | Bileşenler | Kontrol |
+|---------|-----------|---------|
+| **Forms** | Input grubu + validation görseli + submit akışı | Form-like frame'lerde input+button+error text birlikte mi? |
+| **Navigation** | Sidebar, tabs, breadcrumb, bottom nav | Nav pattern'ı yayınlanmış bileşen mi yoksa ad-hoc frame mi? |
+| **Data Display** | Tablo, kart listesi, liste | Tekrarlayan veri gösteriminde DS bileşeni mi kullanılıyor? |
+| **Feedback** | Toast, modal, inline mesaj, snackbar | Geri bildirim mekanizmaları DS'de tanımlı mı? |
+
+### DS Prensipleri
+
+Audit raporunun sonuna bu prensipler bağlam olarak eklenir:
+
+1. **Tutarlılık > Yaratıcılık** — DS, ekiplerin tekerleği yeniden icat etmemesi için var
+2. **Kısıtlamalar içinde esneklik** — Bileşenler composable olmalı, rigid değil
+3. **Belgelenmemiş = yok** — Dökümante edilmeyen bileşen/token kullanılmayacaktır → bkz. [component-documentation](../component-documentation/SKILL.md)
+4. **Versiyonla ve migrate et** — Breaking change'lerde migration path sun → bkz. [ds-impact-analysis](../ds-impact-analysis/SKILL.md)
+
+### Audit JSON Şemasına Ek Alan
+
+`--json` çıktısına `dsCompleteness` objesi eklenir:
+
+```json
+{
+  "findings": [...],
+  "dsCompleteness": {
+    "tokenCategories": {
+      "colors": { "count": 24, "status": "complete" },
+      "typography": { "count": 12, "status": "complete" },
+      "spacing": { "count": 8, "status": "complete" },
+      "border": { "count": 5, "status": "complete" },
+      "shadow": { "count": 4, "status": "complete" },
+      "motion": { "count": 0, "status": "missing" }
+    },
+    "componentStates": {
+      "averageStatesPerComponent": 3.2,
+      "componentsWithAllStates": 5,
+      "componentsWithMissingStates": 8,
+      "missingStateDetails": [
+        { "component": "Button", "missing": ["loading", "focus"] },
+        { "component": "Input", "missing": ["error", "loading"] }
+      ]
+    },
+    "patternCoverage": {
+      "forms": true,
+      "navigation": true,
+      "dataDisplay": false,
+      "feedback": false
+    }
+  }
+}
+```
+
+## Ne işaretlenir / ne işaretlenmez
+
+**İşaretle:** Ad-hoc frame ile yapılmış button/card/alert/chip vb.; tekrarlayan kardeş modüller; somut ham değer + tokenize komşular; global pattern’lerin custom olması; nominal component içi variant sapması.
+
+**İşaretleme:** Saf estetik; copy; makul ölçüde ekrana özgü layout; zaten instance + token ile doğru olan tek seferlik kompozisyonlar; belgesiz varsayımlar.
+
+## Kanıt standardı
+
+Her bulgu için: (1) Figma yapısında somut ne gösteriyor? (2) Bakım, tutarlılık, tema veya ölçeklenebilirlik için neden önemli?
+
+## JSON çıktı şeması ( `--json` )
+
+Tek JSON obje; markdown veya ek prose yok:
+
+```json
+{
+  "findings": [
+    {
+      "title": "<= 80 karakter, emir kipi>",
+      "body": "Markdown açıklama",
+      "confidence_score": 0.0,
+      "priority": 0,
+      "code_location": {
+        "absolute_file_path": "/figma/<fileKey>/nodes/<nodeId>",
+        "line_range": { "start": 1, "end": 1 }
+      }
+    }
+  ],
+  "overall_correctness": "ds compliant" | "ds non-compliant",
+  "overall_explanation": "1-3 cümle özet",
+  "overall_confidence_score": 0.0
+}
+```
+
+- En az bir bulgu varsa `overall_correctness`: `"ds non-compliant"`.
+- Bulgu yoksa `"ds compliant"`.
+- `code_location.absolute_file_path`: en spesifik sorunlu node için `/figma/<fileKey>/nodes/<nodeId>`.
+- `line_range` her zaman `1`.
+
+## Öncelik ve güven skorları
+
+- **priority:** 0 nit, 1 orta drift, 2 önemli primitive/token, 3 kütüphane/nav seviyesi kritik.
+- **confidence_score:** 0.9–1.0 doğrudan yapısal kanıt; 0.7–0.89 güçlü çıkarım; 0.5–0.69 zayıf — tercihen bulgu yazma.
+
+## Erişilebilirlik (a11y) Kontrol Noktaları
+
+Audit sırasında aşağıdaki temel a11y kontrolleri de yapılır. Ayrıntılı a11y denetimi için **figma-a11y-audit** skill'ine yönlendir.
+
+- **Renk kontrastı:** Metin/arka plan renk çiftlerinde WCAG AA minimum kontrastı (4.5:1 normal metin, 3:1 büyük metin) sağlanıyor mu?
+- **Minimum boyut:** Etkileşimli öğeler (button, input, link) iOS için 44x44pt, Android için 48x48dp minimumunu karşılıyor mu?
+- **Metin boyutu:** Body metin en az 14px (mobil) / 16px (masaüstü) mü?
+
+Bu kontroller audit raporunda `[a11y]` etiketiyle ayrı bölümde gösterilir. Detaylı denetim (fokus sırası, VoiceOver/TalkBack, ARIA) için:
+
+→ **figma-a11y-audit** skill'ini kullan.
+
+## PO/PM Executive Rapor Modu
+
+`--executive` flag veya PO/PM persona algılandığında teknik detay yerine yönetici özeti çıkar:
+
+**Executive summary formatı:**
+
+```markdown
+## DS Uyum Raporu — [Ekran Adı]
+
+- **DS Uyum Oranı:** %85 (17/20 öğe DS ile uyumlu)
+- **Risk Seviyesi:** Orta
+- **Kritik Bulgular:** 2 adet
+- **Önerilen Aksiyon Süresi:** ~2 saat
+
+### Bulgular (öncelik sırasıyla)
+1. [Yüksek] Navigation bar custom yapılmış — DS NavBar bileşeni mevcut
+2. [Orta] 3 renk token'a bağlı değil — tema değişikliğinde kopacak
+
+### Sonraki Adım
+→ apply-figma-design-system ile otomatik düzeltme önerilir
+```
+
+## Tetik örnekleri
+
+- "Bu ekranı design system entegrasyonu için denetle"
+- "Bu board'da eksik component kullanımı var mı?"
+- "Token'lar doğru bağlı mı — audit --json ile ver"
+- "Tasarım durumu raporu ver" (PO/PM)
+- "Ne kadar DS uyumlu bu ekran?" (PO/PM)
+
+## Evolution Triggers
+
+- Bridge'e yeni DS analiz aracı eklendiğinde kanıt toplama adımları güncellenmeli
+- Yeni a11y standartları (WCAG 3.0) yayınlandığında kontrol noktaları güncellenmeli
+- PO/PM geri bildirimine göre executive summary formatı genişletilmeli

package/skills/code-design-mapper/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: code-design-mapper
+description: Figma tasarım bileşenlerini iOS, Android ve Web platformlarındaki kod bileşenlerine eşler. Bir Figma component'i birden fazla platform implementasyonuyla eşleşebilir. Enterprise plan gerektirmez, lokal çalışır. "code connect", "connect component", "map component", "bileşen eşle", "component mapping", "hangi kod bu bileşene karşılık geliyor", "bileşen eşleme tablosu" ifadeleriyle tetiklenir. F-MCP Bridge plugin bağlantısı gerektirir.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - uidev
+    - designops
+---
+
+# Code-Design Mapper (Multi-Platform)
+
+## Overview
+
+Bu skill, Figma tasarım bileşenlerini **iOS, Android ve Web** platformlarındaki kod karşılıklarına eşler. Tek bir Figma component'i 3 farklı platform implementasyonuyla eşleşebilir.
+
+Figma resmi Code Connect'ten farkları:
+- Enterprise plan gerektirmez
+- Published component zorunluluğu yok
+- **Multi-platform mapping**: 1 Figma component → N platform implementasyonu
+- Her platformun implementasyon durumu ayrı izlenir
+- Platformlar arası tutarlılık kontrolü
+
+REST API veya Figma access token gerekmez.
+
+## Code Connect Uyarlama Notu
+
+Resmi Figma MCP'de Code Connect akışı `get_code_connect_suggestions` ve `send_code_connect_mappings` araçlarıyla çalışır. **F-MCP Bridge'de bu araçlar kayıtlı değildir** (FUTURE.md'de planlı).
+
+F-MCP ile eşdeğer iş akışı:
+
+| Resmi Code Connect adımı | F-MCP Bridge karşılığı |
+|---|---|
+| Resmi: code connect suggestions | `figma_search_components` + `figma_get_component` + `figma_get_component_for_development` |
+| Bileşen–kod eşleme | AI ile `.figma-mappings.json` üretimi (bu skill'in ana akışı) |
+| Resmi: send code connect mappings | **yok** — eşleme dosyası repoda kalır, Figma'ya gönderilmez |
+
+**Resmi Code Connect `.figma.js` şablonları gerekiyorsa:** Kullanıcıya resmi Figma MCP sunucusunu etkinleştirmesi ve [topluluk figma-code-connect skill'ini](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-code-connect/SKILL.md) kullanması önerilir.
+
+**Bridge'e Code Connect araçları eklendiğinde** bu bölüm ve iş akışı güncellenmeli.
+
+## Prerequisites
+
+- F-MCP Bridge plugin Figma'da çalışıyor ve bağlı olmalı
+- En az bir platformda component implementasyonu mevcut olmalı
+- Platform proje dizinleri biliniyor olmalı
+
+## F-MCP skill koordinasyonu
+
+- **Önce:** Stabil kütüphane instance’ları için isteğe bağlı **apply-figma-design-system** veya **audit-figma-design-system**.
+- **Sonra:** `.figma-mappings.json` ile **design-drift-detector** ve **implement-design**; manifest için **ai-handoff-export**.
+
+## Required Workflow
+
+**Bu adımları sırayla uygula. Adım atlama.**
+
+### Step 1: Plugin Bağlantısını Doğrula
+
+```
+figma_get_status()
+```
+
+### Step 2: Platform Projelerini Belirle
+
+Kullanıcıdan veya codebase'den platform proje köklerini belirle:
+
+```
+Hangi platformlarda çalışıyorsunuz ve proje dizinleri nerede?
+
+- iOS:     ör. ios-app/ veya MyApp.xcodeproj/
+- Android: ör. android-app/ veya app/src/main/
+- Web:     ör. web-app/ veya src/
+```
+
+Her platform için component dizinlerini tespit et:
+
+| Platform | Yaygın Component Dizinleri |
+|----------|---------------------------|
+| **iOS (SwiftUI)** | `Sources/Components/`, `Views/`, `UI/` |
+| **iOS (UIKit)** | `Views/`, `UI/Components/`, `Cells/` |
+| **Android (Compose)** | `ui/components/`, `presentation/components/` |
+| **Android (XML)** | `res/layout/`, `res/values/styles.xml` |
+| **Web (React)** | `src/components/`, `components/ui/` |
+| **Web (Vue)** | `src/components/`, `views/` |
+| **Web (Legacy)** | `templates/`, `partials/`, `public/js/` |
+
+### Step 3: Figma Component'lerini Keşfet
+
+Belirli component:
+
+```
+figma_get_component(nodeId="<NODE_ID>")
+```
+
+Tüm component'ler (aktif sayfa):
+
+```
+figma_search_components(query="", currentPageOnly=true, limit=50)
+```
+
+**Uyarı:** `currentPageOnly=false` büyük dosyalarda timeout'a neden olabilir. Önce `currentPageOnly=true` (varsayılan) ile dene. Component başka sayfadaysa dikkatli şekilde `false` kullan.
+
+### Step 4: Component Detaylarını Çek
+
+```
+figma_get_component_for_development(nodeId="<NODE_ID>", scale=2, format="PNG")
+```
+
+Bu tek çağrıda hem metadata hem base64 screenshot döner. Ancak base64 screenshot context'i şişirir — çok fazla component taranacaksa önce `figma_get_component(nodeId="...")` (sadece metadata) kullan, screenshot'ı sadece eşleşme onayı için al.
+
+Her component için Figma'daki bilgiler:
+- Component adı ve yolu
+- Variant özellikleri (variant props ve değerleri)
+- Child yapısı
+- Görsel referans (base64 screenshot — context ağır)
+
+### Step 5: Her Platformda Eşleşme Ara
+
+Her Figma component'i için, **her platformda ayrı ayrı** eşleşme ara:
+
+**iOS arama:**
+- `.swift` dosyalarında `struct ComponentName: View` (SwiftUI)
+- `.swift` dosyalarında `class ComponentName: UIView` (UIKit)
+- `.xib` / `.storyboard` dosyalarında custom class referansları
+
+**Android arama:**
+- `.kt` dosyalarında `@Composable fun ComponentName` (Compose)
+- `res/layout/` altında `component_name.xml` (XML)
+- Custom View class'ları
+
+**Web arama:**
+- `.tsx`/`.jsx` dosyalarında `export function ComponentName` veya `export const ComponentName`
+- `.vue` dosyalarında `<script>` içinde component tanımı
+- `.html`/`.hbs` dosyalarında template/partial
+
+### Step 6: Eşleşmeleri Kullanıcıya Sun
+
+**Multi-platform sunum formatı:**
+
+```
+Figma Component: Button (42:15)
+Variant'lar: primary | secondary | ghost × sm | md | lg
+
+Platform Eşleşmeleri:
+┌──────────┬────────────────────────────────────┬──────────┐
+│ Platform │ Kod Dosyası                        │ Durum    │
+├──────────┼────────────────────────────────────┼──────────┤
+│ iOS      │ Sources/UI/ButtonComponent.swift   │ Eşleşti  │
+│ Android  │ ui/components/ButtonComponent.kt   │ Eşleşti  │
+│ Web      │ src/components/Button.tsx           │ Eşleşti  │
+└──────────┴────────────────────────────────────┴──────────┘
+
+Figma Component: Avatar (42:30)
+┌──────────┬────────────────────────────────────┬──────────────┐
+│ Platform │ Kod Dosyası                        │ Durum        │
+├──────────┼────────────────────────────────────┼──────────────┤
+│ iOS      │ Sources/UI/AvatarView.swift        │ Eşleşti      │
+│ Android  │ —                                  │ Eksik        │
+│ Web      │ src/components/Avatar.tsx           │ Eşleşti      │
+└──────────┴────────────────────────────────────┴──────────────┘
+
+Bu eşleşmeleri kaydetmek ister misiniz?
+```
+
+### Step 7: Multi-Platform Mapping Dosyasını Oluştur/Güncelle
+
+**Önemli:** `.figma-mappings.json` dosyası AI agent tarafından oluşturulur ve yönetilir. Hiçbir MCP aracı bu dosyayı okumaz veya yazmaz — tamamen agent-tarafı bir artifact'tir.
+
+Proje kökünde `.figma-mappings.json` dosyası:
+
+```json
+{
+  "version": "2.0",
+  "lastUpdated": "2026-03-12T10:30:00Z",
+  "figmaFile": "Design System",
+  "platforms": {
+    "ios": {
+      "rootDir": "ios-app/",
+      "framework": "SwiftUI",
+      "language": "Swift",
+      "componentDirs": ["Sources/UI/", "Sources/Components/"]
+    },
+    "android": {
+      "rootDir": "android-app/",
+      "framework": "Compose",
+      "language": "Kotlin",
+      "componentDirs": ["app/src/main/java/com/app/ui/components/"]
+    },
+    "web": {
+      "rootDir": "web-app/",
+      "framework": "React",
+      "language": "TypeScript",
+      "componentDirs": ["src/components/", "src/ui/"]
+    }
+  },
+  "components": [
+    {
+      "figmaNodeId": "42:15",
+      "figmaName": "Button",
+      "figmaPath": "Components/Button",
+      "variants": {
+        "variant": ["primary", "secondary", "ghost"],
+        "size": ["sm", "md", "lg"]
+      },
+      "implementations": {
+        "ios": {
+          "codePath": "ios-app/Sources/UI/ButtonComponent.swift",
+          "componentName": "ButtonComponent",
+          "propMapping": {
+            "variant": { "codeProp": "style", "codeType": "ButtonStyle" },
+            "size": { "codeProp": "size", "codeType": "ButtonSize" }
+          },
+          "status": "synced",
+          "lastSync": "2026-03-12T10:30:00Z"
+        },
+        "android": {
+          "codePath": "android-app/app/src/main/java/com/app/ui/components/ButtonComponent.kt",
+          "componentName": "ButtonComponent",
+          "propMapping": {
+            "variant": { "codeProp": "variant", "codeType": "ButtonVariant" },
+            "size": { "codeProp": "size", "codeType": "ButtonSize" }
+          },
+          "status": "synced",
+          "lastSync": "2026-03-12T10:30:00Z"
+        },
+        "web": {
+          "codePath": "web-app/src/components/Button.tsx",
+          "componentName": "Button",
+          "propMapping": {
+            "variant": { "codeProp": "variant", "codeType": "string" },
+            "size": { "codeProp": "size", "codeType": "string" }
+          },
+          "status": "synced",
+          "lastSync": "2026-03-12T10:30:00Z"
+        }
+      }
+    },
+    {
+      "figmaNodeId": "42:30",
+      "figmaName": "Avatar",
+      "figmaPath": "Components/Avatar",
+      "variants": {
+        "size": ["xs", "sm", "md", "lg", "xl"]
+      },
+      "implementations": {
+        "ios": {
+          "codePath": "ios-app/Sources/UI/AvatarView.swift",
+          "componentName": "AvatarView",
+          "status": "synced",
+          "lastSync": "2026-03-12T10:30:00Z"
+        },
+        "android": null,
+        "web": {
+          "codePath": "web-app/src/components/Avatar.tsx",
+          "componentName": "Avatar",
+          "status": "outdated",
+          "lastSync": "2026-02-15T14:00:00Z"
+        }
+      }
+    }
+  ],
+  "coverageSummary": {
+    "totalComponents": 25,
+    "ios": { "implemented": 20, "missing": 5, "outdated": 2 },
+    "android": { "implemented": 18, "missing": 7, "outdated": 1 },
+    "web": { "implemented": 22, "missing": 3, "outdated": 3 }
+  }
+}
+```
+
+### Step 8: Platform Coverage Raporu Oluştur
+
+Mapping tamamlandıktan sonra coverage raporu sun:
+
+```
+Design System Platform Coverage Raporu
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Toplam Figma Component: 25
+
+        iOS     Android   Web
+Impl.   20/25   18/25     22/25
+%       80%     72%       88%
+Güncel  18/20   17/18     19/22
+Eksik   5       7         3
+
+Eksik Component'ler:
+  Android: Avatar, Tooltip, Breadcrumb, Stepper, DatePicker
+  iOS:     Breadcrumb, DataTable, Pagination, RichText, CodeBlock
+  Web:     Stepper, DatePicker, BottomSheet
+```
+
+## Mevcut Mapping'leri Güncelleme
+
+"Mapping'leri güncelle" veya "sync" dendiğinde:
+
+1. `.figma-mappings.json` oku
+2. Her component + her platform için güncel durumu kontrol et
+3. Figma'da variant değişikliği varsa → `status: "outdated"`
+4. Kodda component silinmişse → `status: "missing"`
+5. Coverage summary'yi güncelle
+
+## Eksik Platform Implementasyonu Başlatma
+
+Coverage raporunda eksik görünen component'i implement etmek için:
+
+1. Mapping'den eksik platformu ve Figma nodeId'yi belirle
+2. `figma_get_component_for_development(nodeId="...")` ile Figma verisini al
+3. **implement-design** skill'ini hedef platform belirterek kullan
+4. Oluşturulan implementasyonu mapping'e ekle
+
+## Examples
+
+### Örnek 1: Tekli Component — 3 Platform Eşleme
+
+Kullanıcı: "Button component'ini tüm platformlarda eşle, nodeId: 42:15"
+
+**Akış:**
+
+1. `figma_get_status()` → bağlı
+2. `figma_get_component_for_development(nodeId="42:15")` → Button, variants
+3. iOS'ta ara → `ButtonComponent.swift` bulundu
+4. Android'de ara → `ButtonComponent.kt` bulundu
+5. Web'de ara → `Button.tsx` bulundu
+6. 3 platform eşleşmesini sun
+7. Kullanıcı onayladı → `.figma-mappings.json`'a kaydet
+
+### Örnek 2: Platform Eksikleri Tespiti
+
+Kullanıcı: "Tüm component'leri tara, hangi platformlarda eksik göster"
+
+**Akış:**
+
+1. `figma_search_components(query="", currentPageOnly=false)` → 25 component
+2. Her component için 3 platformda ara
+3. Coverage raporu oluştur
+4. Kullanıcıya öncelik öner: "Android'de 7 component eksik, en kritikleri: Avatar, Tooltip"
+
+### Örnek 3: Sadece Bir Platform İçin Eşleme
+
+Kullanıcı: "Android Compose component'lerini Figma ile eşle"
+
+**Akış:**
+
+1. Sadece Android component dizinlerini tara
+2. Figma component'leriyle eşleştir
+3. Sadece Android sütununu güncelle, diğer platformları koru
+
+## Common Issues and Solutions
+
+### Sorun: Platform projesi farklı repo'da
+
+**Çözüm:** `platforms.ios.rootDir` alanını absolute path veya relative path olarak ayarla. Farklı repo'lar için workspace root'a göre path ver.
+
+### Sorun: Aynı Figma component'i platformlarda farklı isimle
+
+**Çözüm:** Her platform implementasyonunun `componentName` alanı bağımsızdır. Figma'da "SegmentedControl" → iOS'ta "Picker", Android'de "TabRow", Web'de "SegmentedControl" olabilir.
+
+### Sorun: Platform-spesifik component (ör. BottomSheet sadece mobile)
+
+**Çözüm:** Web implementasyonu `null` olarak bırak, coverage raporunda "N/A" göster. Platform-specific component'leri mapping'de işaretle.
+
+### Sorun: Legacy ve modern aynı platformda
+
+**Çözüm:** `platforms` altında ayrı entry ekle: `"web-legacy": { "framework": "jQuery", ... }`. Bir Figma component'in hem modern hem legacy web karşılığı olabilir.
+
+## Evolution Triggers
+
+- Bridge'e Code Connect araçları (suggestions / send mappings) eklenirse Code Connect uyarlama bölümü ve iş akışı güncellenmeli
+- Yeni platform desteği (Flutter, .NET MAUI) eklenirse platform profilleri genişletilmeli
+- `.figma-mappings.json` şeması değişirse çıktı formatı uyarlanmalı