@atezer/figma-mcp-bridge 1.7.30 → 1.9.0

package/skills/fmcp-token-sync-orchestrator/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: fmcp-token-sync-orchestrator
+description: Figma design token'larını kod dosyalarıyla (CSS/Tailwind/Swift/Compose) platform-agnostic senkronize eder. Diff preview + onay + write akışı zorunlu. Her platformda çalışır. Condensed-first: Essentials bölümü %80 case'i kapsar, Advanced sadece edge case'lerde.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  version: 1.9.0
+  priority: 95
+  phase: orchestrator
+  personas:
+    - designops
+    - uidev
+  token_budget: condensed-first
+required_inputs:
+  - name: target_platform
+    type: "enum: css | tailwind | swift | compose | sass | auto"
+    description: "Hedef platform. 'auto' → hedef dosya uzantısından tespit, belirsizse sor"
+  - name: target_file
+    type: "string | null"
+    description: "Hedef dosya yolu. null → platform defaultuna göre öner"
+  - name: direction
+    type: "enum: figma-to-code | code-to-figma"
+    description: "Senkronizasyon yönü. Default: figma-to-code (export)"
+---
+
+# FMCP Token Sync Orchestrator
+
+## Essentials (Üst Bölüm — %80 Case İçin Yeterli)
+
+### Ortak Protokol (Condensed — full: `agents/_orchestrator-protocol.md`)
+
+1. **Skill Registry** açık — tahmin yasak
+2. **Intent Routing** — platform belirsiz → kullanıcıya sor (AskUserQuestion / düz metin)
+3. **Cheap-First** — `figma_get_variables(verbosity="summary")` yeterli, full sadece eksik binding keşfinde
+4. **Cache-First** — tokens için cache yok (hızlı değişir), opsiyonel `.claude/token-sync-log.md`
+5. **User Onay** — **diff preview olmadan WRITE YOK** (mutlak kural)
+6. **Self-Audit** — write sonrası binding coverage raporu (hardcoded kalan node sayısı)
+7. **Skill Evolution** — yeni platform için iki aşamalı onay
+8. **Türkçe rapor** — metrik bloğu sonunda
+
+### Skill Registry (Ref Only)
+
+| Skill | Dosya yolu | Trigger | Common case lazım mı? |
+|---|---|---|---|
+| `design-token-pipeline` | `skills/design-token-pipeline/SKILL.md` | Token export/import | **HER ZAMAN** (ana motor) |
+| `code-design-mapper` | `skills/code-design-mapper/SKILL.md` | Component ↔ Figma mapping | Sadece component mapping istenirse |
+| `design-system-rules` | `skills/design-system-rules/SKILL.md` | Platform-specific rule generation | Sadece rule generation istenirse |
+
+### Platform Routing
+
+| Sinyal | Platform | Standard hedef path |
+|---|---|---|
+| `.css`, `:root`, `var(--...)`, `tokens.css` | CSS | `src/styles/tokens.css` |
+| `tailwind.config.*`, `theme.extend` | Tailwind | `tailwind.config.js` → `theme.extend` |
+| `.swift`, `UIKit`, `SwiftUI`, `Color(...)` | Swift | `Sources/DesignTokens/Tokens.swift` |
+| `.kt`, `Compose`, `@Composable`, `MaterialTheme` | Compose | `app/src/main/java/.../DesignTokens.kt` |
+| `.scss`, `$token-...` | Sass | `src/styles/_tokens.scss` |
+| Hiçbiri net değil | — | AskUserQuestion (4 platform seçeneği) |
+
+### Diff Preview Before Write (Zorunlu Akış)
+
+1. **Dry-run:** `Read("skills/design-token-pipeline/SKILL.md")` + workflow'u çalıştır ama dosyaya yazma → çıktıyı buffer'a al
+2. **Mevcut dosya varsa:** mevcut içerikle yeni içerik arası **unified diff** üret
+3. **Diff'i sohbete yaz:**
+   ```diff
+   --- current tokens.css
+   +++ new tokens.css
+   @@ -12,3 +12,5 @@
+      --color-primary: #0066cc;
+   -  --color-secondary: #666;
+   +  --color-secondary: #4a4a4a;
+   +  --color-success: #10b981;
+   ```
+4. **Onay al:** AskUserQuestion / düz metin: "Bu değişiklikleri uygulayayım mı? (Evet / Hayır / Sadece bazıları)"
+5. **Onay sonrası** `Write` veya `Edit` ile dosyaya yaz
+6. **Mevcut dosya yoksa:** sadece yeni içeriği göster, onay al, sonra `Write`
+
+### Self-Audit (Write Sonrası)
+
+Binding coverage raporu:
+- **Toplam token:** `figma_get_variables` ile sayım
+- **Binding oranı:** senkronlanan / toplam (yüzde)
+- **Upgraded:** hardcoded değerden variable binding'e dönüşen sayı
+- **Leftover:** hâlâ hardcoded kalan node sayısı (ds-auditor'a yönlendir)
+
+### Rapor Formatı
+
+```markdown
+## 🔄 Token Sync — <platform>
+
+**Yön:** Figma → Kod | Kod → Figma
+**Hedef dosya:** <path>
+**Mod:** export | import
+
+### Diff Özeti
+- Eklenen: <n>
+- Güncellenen: <m>
+- Kaldırılan: <k>
+
+### Binding Coverage
+- Toplam token: <n>
+- Binding oranı: <%>
+- Hardcoded kalanlar: <k> node (ds-auditor ile detaylandır)
+
+---
+📊 Metrikler
+- Kullanılan skill'ler: <liste>
+- API çağrı sayısı: <n>
+- Dry-run + write: tamamlandı
+```
+
+---
+
+## Advanced — Only Load If Needed
+
+**Bu bölümü Claude aşağıdaki koşullarda tarar:**
+- ⚠️ Multi-platform sync (aynı token'ları hem CSS hem Swift'e)
+- ⚠️ Custom component mapping (code-design-mapper gerektiren)
+- ⚠️ Platform default path kullanıcı için uygun değil (custom path gerekir)
+- ⚠️ Kod → Figma yönünde sync (import mode, daha nadir)
+- ⚠️ Yeni platform desteği (Flutter, Jetpack Multiplatform vb.)
+
+### Detay 1 — Multi-Platform Sync
+
+Kullanıcı "hem CSS hem Tailwind hem Swift'e aynı token'ları export et" derse:
+1. Her platform için ayrı dry-run
+2. 3 ayrı diff preview sohbette (tek mesajda üç diff bloğu)
+3. Kullanıcı "hepsini onayla" veya "sadece X ve Y" diyebilmeli (AskUserQuestion çoklu seçim)
+4. Onaylananları yaz
+5. Binding coverage raporu 3 platforma göre ayrı
+
+### Detay 2 — Custom Component Mapping
+
+Sadece token değil, component → component eşleştirme isteniyorsa:
+1. `Read("skills/code-design-mapper/SKILL.md")`
+2. Figma component isim/key → kod dosyası path eşleştirmesi
+3. Çıktı: `.codeconnect.ts` veya benzeri mapping dosyası
+4. Token'lardan bağımsız ama tamamlayıcı iş
+
+### Detay 3 — Kod → Figma Import Mode
+
+Kod tarafında değişen bir token (örn. Git PR'da renk güncellemesi) Figma'ya geri yansıtılacaksa:
+1. Kod dosyasını parse et
+2. `figma_get_variables` ile mevcut Figma değerlerini al
+3. Diff: kod tarafı vs Figma tarafı
+4. Kullanıcıya göster: "Kod tarafında şu token'lar değişmiş, Figma'ya yansıtayım mı?"
+5. Onay → `figma_update_variable` / `figma_setup_design_tokens` ile yaz
+6. **Destructive mutation** → ortak protokol madde 5 gate (kullanıcı onayı)
+
+### Detay 4 — Platform Default Path Override
+
+Plan'daki defaultlar:
+```
+CSS      → src/styles/tokens.css
+Tailwind → tailwind.config.js
+Swift    → Sources/DesignTokens/Tokens.swift
+Compose  → app/src/main/java/.../DesignTokens.kt
+Sass     → src/styles/_tokens.scss
+```
+
+Kullanıcı'nın proje yapısı farklı olabilir. İlk sync'te:
+1. Default path'i sor: "Bu platform için token dosyası `<default>` yoluna yazılsın mı?"
+2. Kullanıcı alternatif verirse onu kullan
+3. İlk başarılı sync sonrası path `.claude/token-sync-log.md`'ye kaydedilir (opsiyonel cache)
+
+### Detay 5 — Error Recovery
+
+| Hata | Aksiyon |
+|---|---|
+| Dosya yazma permission | Kullanıcıya bildir, farklı path öner |
+| Mevcut kod formatı tanınmıyor | Örnek satır göster, formatı doğrulat |
+| `figma_get_variables` timeout | `verbosity="summary"` zaten default, retry |
+| Diff çok büyük (100+ değişiklik) | Özetle: "X color, Y spacing, Z typography token değişti, detay görmek ister misin?" |
+
+### Detay 6 — Platform-Specific Notes
+
+**Claude Code:**
+- `Write` / `Edit` tool'ları mevcut, doğrudan kod dosyasına yazılır
+- Cache: `.claude/token-sync-log.md` opsiyonel
+
+**Cursor:**
+- Aynı tool'lar mevcut, main context'te çalışır
+- `.cursor/rules/fmcp-orchestration.md` bu orchestrator'ı referans eder
+
+**Claude Desktop:**
+- **KRİTİK:** Filesystem MCP eklenmediyse `Write` tool'u yok → sadece diff gösterebilir, kullanıcı manuel kopyalar
+- İlk prompt'ta manuel skill referansı zorunlu
+
+**Claude Web:**
+- Filesystem yok → tamamen plan-only mod
+- "Bu diff'i kopyala, tokens.css'e yapıştır" talimatı ver
+
+### Detay 7 — Yeni Platform Desteği (Skill Evolution)
+
+Kullanıcı "Flutter için export" isterse (mevcut 5 platformda yok):
+1. **Aşama 1:** Gap'i açıkla, "Flutter desteği eklemek istiyor musun?" sor
+2. **Aşama 2:** `design-token-pipeline` skill'ine Flutter eklentisi yap (edit) veya yeni bir skill (`fmcp-token-flutter-pipeline`) oluştur (create)
+3. Create → DRAFT banner + ikinci onay
+4. Edit → diff preview + onay

package/skills/generate-figma-library/SKILL.md

@@ -6,6 +6,44 @@ metadata:
   personas:
     - designops
     - designer
+required_inputs:
+  - name: source_type
+    type: enum
+    options:
+      - "Kod tabanı (path ver)"
+      - "Token JSON dosyası"
+      - "Mevcut tasarım sisteminden clone"
+      - "Sıfırdan (boş kütüphane)"
+    question: "Kütüphaneyi nereden inşa edelim?"
+    required: true
+  - name: source_path
+    type: string
+    question: "Kaynak path nedir? (örn: ./src/design-tokens veya ./tokens.json)"
+    required: false
+    skip_if: "source_type == 'Sıfırdan (boş kütüphane)'"
+  - name: library_name
+    type: string
+    question: "Kütüphane adı nedir? (örn: '❖ My DS')"
+    required: true
+  - name: components_to_generate
+    type: string_list
+    question: "Hangi bileşenleri üretelim? (örn: Button, Input, Card, Modal — 'all' veya virgülle ayır)"
+    required: false
+    default: "all"
+  - name: token_categories
+    type: string_list
+    question: "Hangi token kategorileri? (colors, spacing, typography, radius, shadow — 'all' veya seçili)"
+    required: false
+    default: "all"
+  - name: theme_support
+    type: enum
+    options:
+      - "Single theme (default)"
+      - "Light + Dark"
+      - "Multi-brand (3+ themes)"
+    question: "Tema desteği?"
+    required: false
+    default: "Single theme (default)"
 ---
 
 # Generate Figma Library — Koddan DS Kütüphanesi İnşa

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

@@ -6,6 +6,61 @@ metadata:
   personas:
     - designer
     - uidev
+required_inputs:
+  - name: device
+    type: enum
+    options:
+      - "iPhone 17 (402×874)"
+      - "iPhone 16 Pro Max (440×956)"
+      - "iPhone 16 (393×852)"
+      - "iPhone 13/14 (390×844)"
+      - "Android Compact (412×917)"
+      - "Android Medium (700×840)"
+      - "iPad Pro 11 (834×1194)"
+      - "iPad Pro 13 (1024×1366)"
+      - "Desktop (1440×1024)"
+      - "Custom (width×height ver)"
+    question: "Hangi device boyutunda olsun?"
+    required: true
+    default_source: ".claude/design-systems/last-intent.md#device"
+  - name: design_system
+    type: from_state
+    source: ".claude/design-systems/active-ds.md#Library Name"
+    fallback_question: "Hangi tasarım sistemi kullanılsın? (❖ SUI / Material / Apple HIG / Custom)"
+    required: true
+  - name: reference_benchmark
+    type: node_id_or_none
+    question: "Referans alınacak benchmark ekranı var mı? (Node ID veya Figma URL, yoksa 'yok')"
+    required: false
+    affects: ["screen_type", "sections"]
+  - name: screen_type
+    type: enum
+    options:
+      - "Dashboard / özet"
+      - "Liste / arama sonuçları"
+      - "Detay / profil"
+      - "Form / veri girişi"
+      - "Login / onboarding"
+      - "Confirmation / success"
+      - "Empty state"
+      - "Error / 404"
+    question: "Ne tür bir ekran?"
+    required: true
+    skip_if: "reference_benchmark != none"
+  - name: sections
+    type: string_list
+    question: "Hangi ana içerik bölümlerini istiyorsun? (örn: header, balance card, quick actions, transactions, bottom nav)"
+    required: true
+    skip_if: "reference_benchmark != none"
+  - name: variants
+    type: enum
+    options:
+      - "Tek varyant"
+      - "Light + Dark mode"
+      - "2-3 layout alternatifi"
+    question: "Kaç varyant istiyorsun?"
+    required: false
+    default: "Tek varyant"
 ---
 
 # Generate Figma Screen — Kod/Açıklamadan Figma Ekranı
@@ -43,6 +98,33 @@ Topluluk `figma-generate-design` skill'inden uyarlanmış, F-MCP Bridge araçlar
 
 **Bu adımları sırayla uygula. Adım atlama.**
 
+### Step 0: Aktif Tasarım Sistemi Kontrolü (ZORUNLU - v1.8.0+)
+
+**Ekran yapmaya başlamadan önce DS context'inin belirli olduğundan emin ol.**
+
+```
+1. Read .claude/design-systems/active-ds.md
+2. Status alanı:
+   ✅ Aktif        → Library Name'i not al, Step 1'e geç
+   ❌ Henüz seçilmedi → Kullanıcıya sor:
+     "Hangi tasarım sistemi ile ilerleyelim?
+      - ❖ SUI (varsa)
+      - Material Design
+      - Apple HIG
+      - Kendi DS'iniz (Figma library URL verin)
+      - Hiçbiri (ham Figma)"
+3. Kullanıcı yanıtladıktan sonra active-ds.md'yi update et:
+   - Status: ✅ Aktif
+   - Library Name: <seçim>
+   - Selected At: <bugün>
+4. Sonraki turlarda bu soruyu TEKRAR SORMA — active-ds.md zaten dolu.
+   Kullanıcı açıkça "DS değiştir" demediği sürece aynı DS'i kullan.
+```
+
+**Bypass:** Kullanıcı "DS'siz devam et" derse `Status: DS bypass mode` olarak işaretle. Token binding kuralı esnetilir ama yine de kullanıcıya hardcoded değer kullandığını bildir.
+
+Detay: [figma-canvas-ops SKILL Section 0 — Design System Context](../figma-canvas-ops/SKILL.md#0-design-system-context-zorunlu--v180).
+
 ### Step 1: Plugin Bağlantısını Doğrula
 
 ```
@@ -109,13 +191,31 @@ Proje kökünde `.fmcp-brand-profile.json` varsa:
 
 Üç şey gerekiyor: **bileşenler**, **variable'lar**, **stiller**.
 
-**CACHE-FIRST KURALI (ZORUNLU):** Figma API'ye gitmeden önce `.claude/libraries/<ds>.md` dosyasını kontrol et. Cache varsa VE `lastUpdated` 24 saatten eski değilse:
-- Text style key'leri → cache'den oku (API çağrısı yapma)
-- Variable key'leri → cache'den oku
-- Component key'leri + override notları → cache'den oku
-- Font ailesi → cache'den oku
+**⚠️ MCP TOOL SEÇİMİ (v1.8.0+):**
+- F-MCP plugin bağlıysa **`figma_search_assets`** veya **`figma_get_library_variables`** kullan
+- Resmi Figma MCP'nin **`search_design_system`** tool'unu **ÇAĞIRMA** — "Resource links not supported" / "file could not be accessed" hatası verir
+- Detay: FMCP_INSTRUCTIONS → "TOOL SELECTION" bölümü
+
+**CACHE-FIRST KURALI (MUTLAK ZORUNLU - PRE-FLIGHT BLOCKER):**
+
+Figma API'ye gitmeden önce `.claude/design-systems/<library-id>/` cache'ini kontrol et:
+
+```
+1. Read .claude/design-systems/<library-id>/_meta.md
+   ↓
+   ✅ Var, sync güncel (24h içinde) → cache'leri kullan, devam et
+   ❌ Yok / sync eski / yarım kalmış → Step 3a-3d'yi ÇALIŞTIR ve cache'i doldur,
+                                       ANCAK O ZAMAN ekran üretimine başla
+```
 
-Cache yoksa, eksikse VEYA 24 saatten eskiyse → keşif yap, sonucu cache'e yaz, `lastUpdated` alanını güncelle. **Bu, sonraki oturumlarda token tüketimini %60-70 düşürür.**
+**Cache eksik veya stale ise ekran üretimi BAŞLAYAMAZ** — önce keşif/cache, sonra üretim. Bu, hardcoded fallback'leri ve tekrar tekrar API çağrılarını engeller.
+
+- Text style key'leri → `.claude/design-systems/<library-id>/tokens.md` (text style key cache)
+- Variable key'leri → `.claude/design-systems/<library-id>/tokens.md`
+- Component key'leri + override notları → `.claude/design-systems/<library-id>/components.md`
+- Font ailesi + available weights → `.claude/design-systems/<library-id>/tokens.md` (Font Weights bölümü)
+
+Cache doldurulduktan sonra her oturumda 24 saat boyunca tekrar API'ye gitmeden okunabilir. **Bu, sonraki oturumlarda token tüketimini %60-70 düşürür.**
 
 **Cache Invalidation:** Cache dosyasının başına `lastUpdated: YYYY-MM-DD HH:mm` ekle. 24 saatten eski cache'ler otomatik yenilenmelidir. Kütüphane güncellendiğinde key'ler değişebilir.
 
@@ -231,6 +331,55 @@ Ekran oluşturmadan önce kullanılacak tüm DS token'larının **variable key'l
 
 Bu adımda toplanan key'ler, sonraki adımlarda `importVariableByKeyAsync` ile hedef dosyaya import edilecek.
 
+### Step 3.5: Clone Tool'u Tuzağı — Ne Zaman Clone, Ne Zaman Sıfırdan İnşa (v1.8.2+ ZORUNLU)
+
+`figma_clone_screen_to_device` tool'u v1.8.1'de eklendi ama **sadece dar bir use-case için** kullanılmalıdır. Yanlış kullanım, benchmark'ın mevcut yanlışlıklarını (hardcoded rectangle, eksik token binding, non-responsive layout) kopyalayarak disiplin ihlaline yol açar.
+
+#### Karar Matrisi
+
+| Kullanıcı isteği | Doğru yaklaşım | Tool |
+|---|---|---|
+| "Aynı ekranı iPhone 17'ye migrate et" (sadece boyut değişir) | Clone | `figma_clone_screen_to_device` |
+| "Aynı DS ile benzer ekran" (tek varyant) | Clone + validate | `figma_clone_screen_to_device` + Step 6.5 |
+| **"3 farklı alternatif tasarım"** | **Build from scratch** ⭐ | `figma_execute` + Step 4-5 |
+| **"Hero Card varyasyonu yap"** | **Build from scratch** | `figma_execute` + Step 4-5 |
+| **"Yeni ekran sıfırdan"** | **Build from scratch** | `figma_execute` + Step 4-5 |
+| **"Benchmark'tan ilham al, daha iyisini yap"** | **Build from scratch** (benchmark = inspiration only) | `figma_execute` + Step 4-5 |
+| "Mevcut ekranda DS uyumunu düzelt" | Apply-DS workflow | `apply-figma-design-system` SKILL |
+
+#### Kullanıcının Gerçek İstediği Nedir?
+
+Kullanıcı "3 alternatif tasarım" dediğinde **neredeyse her zaman** istediği:
+- Farklı layout/renk/tipografi yaklaşımları
+- Her biri gerçekten **AYRI** (sadece isim değil, içerik de)
+- Hepsinde DS uyumu (instance + token binding)
+- Hepsi responsive (auto-layout + FILL sizing)
+
+Bu **clone'un kapsamında DEĞİL**. Clone sadece "kopyala, isim değiştir" yapar. Sonuçta **3 identik kopya** + farklı isimler olur. Bu kullanıcının istediği **GERÇEK varyasyon değildir**.
+
+#### Doğru Akış: Build-from-Scratch (Step 4-5)
+
+Benchmark varsa:
+1. **Step 3.x'te benchmark'ı `figma_get_design_context` ile OKU** — yapısal anlayış için
+2. Benchmark'ta kullanılan SUI instance'ları not al (NavigationTopBar, PillTabs, vb.)
+3. Benchmark'ta **yanlış olan şeyleri kopyalama**:
+   - Hardcoded rectangle separator'lar → DS Divider component kullan
+   - Non-responsive iç frame'ler → auto-layout FILL'e çevir
+   - Missing token bindings → her yerde `setBoundVariable*` kullan
+4. **Step 4 + Step 5 akışını takip et** — sıfırdan, SUI kurallarıyla
+5. Her alternatif için benzersiz layout çözümü:
+   - Hero Card: bakiye kartı büyütülmüş, quick actions altta sade
+   - Liste Odaklı: hesap listesi dominant, özet sağ-altta
+   - Dark Header: root fill `Global/primary/default`, text'ler `on-primary` token
+6. Step 6.5 validate → skor ≥ 80
+
+#### Kısıtlama Kuralı
+
+**Kullanıcı şu kelimelerden birini kullandıysa → `figma_clone_screen_to_device` KULLANMA:**
+- "alternatif", "varyasyon", "farklı", "yeni", "tasarla", "iyileştir", "redesign"
+
+Intent Router bu kelimeleri algıladığında `approach = build-from-scratch` otomatik set eder ve Claude'u Step 4-5 rotasına yönlendirir.
+
 ### Step 4: Boş Alan Bul ve Wrapper Frame Oluştur
 
 ```js
@@ -418,6 +567,44 @@ Screen: VERTICAL, counterAxis=CENTER, layoutSizingVertical=HUG
 
 **Mode adı eşleşmesi DİKKAT:** `indexOf("Web")` "Mobil & Web Mobil"i de yakalar. `indexOf("Desktop")` kullan.
 
+### Step 5.17: Quality Gate — Her Bölüm Yazıldıktan Sonra (ZORUNLU — v1.8.2+)
+
+Her bölüm (`figma.createFrame()` sonrası) için **aşağıdaki checklist ZORUNLU**. Herhangi biri ❌ ise → bölümü **yeniden yaz**. Claude bu checklist'i kendi kendine uygulamakla yükümlüdür.
+
+```
+[ ] Frame'in layoutMode'u atandı mı? (ASLA "NONE" olmamalı — HORIZONTAL veya VERTICAL)
+[ ] primaryAxisSizingMode doğru mu? (Hug: AUTO, Fixed width: FIXED)
+[ ] counterAxisSizingMode doğru mu?
+[ ] Tüm fills setBoundVariableForPaint ile DS token'a bağlı mı? (hardcoded SOLID YASAK)
+[ ] Tüm padding (top/bottom/left/right) setBoundVariable ile DS spacing token'a bağlı mı?
+[ ] itemSpacing setBoundVariable ile DS spacing token'a bağlı mı?
+[ ] cornerRadius (varsa) setBoundVariable ile DS radius token'a bağlı mı?
+[ ] Her text node setTextStyleIdAsync ile DS text style'a bağlı mı? (ASLA sadece fontSize hardcoded)
+[ ] Text fills setBoundVariableForPaint ile DS text color token'a bağlı mı?
+[ ] Bölüm içinde en az 1 DS INSTANCE var mı? (importComponentByKeyAsync ile). 
+    İstisna: Sadece text + frame olan bölümler (ör. başlık row) — bu durumda yine spacing/padding/renk token'ları zorunlu.
+[ ] Tüm child'lar appendChild sonrası layoutSizingHorizontal = "FILL" mi? (text istisna: HUG)
+[ ] Hiçbir node'un fills'i raw hex literal ile atandı mı? (grep: `{r:`, `color:` literal)
+```
+
+**Otomatik kontrol örneği:**
+
+```js
+// Her createFrame sonrası Claude bu kontrolü yapar:
+if (frame.layoutMode === "NONE") throw new Error("Quality Gate FAIL: NO_AUTO_LAYOUT");
+if (!frame.boundVariables || !frame.boundVariables.paddingLeft) {
+  console.warn("Quality Gate WARN: padding token binding eksik");
+}
+```
+
+**Quality Gate FAIL olursa ne yap?**
+1. Bölümü sil: `frame.remove()`
+2. Eksik token/instance'ı `figma_search_assets` + `figma_get_library_variables` ile ara
+3. Bölümü **yeniden yaz** — bu sefer tüm kuralları uyarak
+4. Tekrar kontrol et
+
+**Skor hedef:** `figma_validate_screen` sonrası ≥ 80 (Step 6.5). Quality Gate çalışırsa validate zaten geçer.
+
 ### Step 5.2: Instance Override Rehberi (ZORUNLU)
 
 **Component PROPERTY (TEXT/BOOLEAN/VARIANT tipi) → `setProperties`:**
@@ -478,6 +665,56 @@ Estetik yön belirlendiyse (Step 2.5), bölüm inşa sırasında şu detaylar ek
 
 > **NOT:** Bu öneriler DS bileşen kütüphanesi varsa DS'nin izin verdiği ölçüde uygulanır. DS token'ları dışında hardcoded değer eklenmez.
 
+### Step 5.6: Dark Mode / Theme Variants Workflow (ZORUNLU — v1.9.0+)
+
+Intent router `variants` input'unda "Light + Dark mode" seçildiyse (veya kullanıcı açıkça dark+light istiyorsa), Step 6'ya geçmeden önce bu alt adımı uygula.
+
+**Ön koşul:** DS'de theme modlar tanımlı bir variable collection var. SUI için tipik: `Colors` collection + `Light` mode + `Dark` mode.
+
+**Akış (4 adım):**
+
+1. **Light ekranı doğrula (Step 5 sonu):** Wrapper frame ID'sini al. Tüm fill/stroke/background'lar `setBoundVariableForPaint` ile bağlı olmalı (Step 5.17 Quality Gate zaten sağladı). Eğer hardcoded değer varsa Step 5'e dön, düzelt.
+
+2. **Klon oluştur:**
+```javascript
+// figma_execute
+const lightFrame = await figma.getNodeByIdAsync("<wrapper_id>");
+const darkFrame = lightFrame.clone();
+figma.currentPage.appendChild(darkFrame);
+darkFrame.x = lightFrame.x + lightFrame.width + 80;  // sağda, 80px boşluk
+darkFrame.name = lightFrame.name + " — Dark";
+return { darkFrameId: darkFrame.id };
+```
+
+3. **Dark mode'u klon frame'e uygula:**
+```javascript
+// figma_execute (ayrı çağrı)
+const collections = await figma.variables.getLocalVariableCollectionsAsync();
+const colorCol = collections.find(c => c.name === "Colors" || c.name.toLowerCase().includes("color"));
+if (!colorCol) throw new Error("Theme collection bulunamadı — DS'de mode tanımlı değil");
+const darkMode = colorCol.modes.find(m => m.name.toLowerCase().includes("dark"));
+if (!darkMode) throw new Error("Dark mode bulunamadı — DS tek modlu");
+
+const darkFrame = await figma.getNodeByIdAsync("<darkFrameId>");
+darkFrame.setExplicitVariableModeForCollection(colorCol, darkMode.modeId);
+return { status: "dark mode applied", mode: darkMode.name };
+```
+
+   **Sihir burada:** `setExplicitVariableModeForCollection` ile tüm bound variable'lar otomatik olarak dark mode değerleri kullanır. Manuel swap gerekmez — tek bir API çağrısı tüm renkleri günceller. **Bu yüzden Step 5.17'de her fill/stroke mutlaka variable'a bağlı olmalı** — hardcoded kalanlar dark mode'da güncellenmez, light rengini taşır.
+
+4. **Her iki frame'i ayrı validate et:**
+```javascript
+figma_validate_screen(nodeId: <lightFrameId>, minScore: 80)
+figma_validate_screen(nodeId: <darkFrameId>, minScore: 80)
+```
+   İkisi de ≥80 olmalı. Biri fail ederse hardcoded değerler kaldı demektir — Step 5.17 Quality Gate'e dön.
+
+**Edge case:** DS'de dark mode yoksa (sadece light), `variants: "Light + Dark"` seçimi kullanıcıya hata raporla: "Aktif DS'de dark mode tanımlı değil, sadece light üretildi. Dark mode için DS'nin `Colors` collection'ında `Dark` modu eklenmelidir."
+
+**Responsive + theme kombinasyonu:** `variants: ["Light + Dark", "Mobile + Web"]` seçilirse matris oluşur (Light+Mobile / Light+Web / Dark+Mobile / Dark+Web = 4 frame). Her biri için ayrı wrapper, ayrı mode/device binding, ayrı validate. Turn budget'e dikkat — 4 frame için 4 turn harca (inter-screen checkpoint gate Step 6.6).
+
+**Known limitation:** `figma_validate_screen` skorlama algoritması **dark mode variable binding coverage'ını ayrıca ölçmez** (plugin-side: f-mcp-plugin/code.js). Dark frame'de hardcoded renk kalmış olsa bile skor ≥80 alabilir. Bu yüzden Step 5.17 Quality Gate ve Step 5.6 adım 4'teki manuel binding kontrolü zorunludur — scora tek başına güvenme.
+
 ### Step 6: Görsel Doğrulama
 
 ```
@@ -498,6 +735,123 @@ Screenshot'ı incele:
 
 Sorun varsa hedefli `figma_execute` ile düzelt.
 
+### Step 6.5: Self-Audit Mandate (ZORUNLU — v1.8.1+)
+
+**Ekranı kullanıcıya sunmadan ÖNCE kendi kendini denetle.** Bu adım **atlanamaz** — screenshot yeterli değil çünkü Claude görsel olarak "güzel" görünen ama token/bileşen disiplininden uzak ekranları fark edemez.
+
+#### Adım 1 — `figma_validate_screen` çağır
+
+```
+figma_validate_screen(nodeId="wrapper-frame-id", expectedDs="❖ SUI", minScore=80)
+```
+
+Tool şunu döner:
+```json
+{
+  "score": 92,
+  "passed": true,
+  "minScore": 80,
+  "breakdown": {
+    "instanceCoverage": 85,
+    "libraryInstanceCount": 7,
+    "autoLayoutCoverage": 100,
+    "tokenBindingCoverage": 90
+  },
+  "violations": [],
+  "recommendation": "Score 92/100 passed minimum 80. Screen is DS-compliant."
+}
+```
+
+#### Adım 2 — Skor değerlendirmesi
+
+| Skor | Karar | Davranış |
+|---|---|---|
+| **≥ 80** | ✅ Passed | Kullanıcıya sun, rapor et |
+| **60-79** | ⚠️ Kısmi | Violations listesini oku, targeted fix'ler uygula, tekrar validate et |
+| **< 60** | ❌ Failed | **Ekranı sil** (`figma_execute` → `node.remove()`), Step 3-5'e dön, DS bileşenleriyle yeniden inşa et |
+
+#### Adım 3 — Retry Loop (max 3 deneme)
+
+Eğer ilk denemede score < 80 ise:
+1. Violations listesini oku (en kritik 5'i)
+2. Her bir violation için `figma_execute` ile targeted fix uygula:
+   - `HARDCODED_FILL` → `figma_bind_variable` ile binding ekle
+   - `NO_AUTO_LAYOUT` → `layoutMode = "VERTICAL"` ekle
+3. Tekrar `figma_validate_screen` çağır
+4. **Max 3 deneme.** 3. denemede de fail ise:
+   - Ekranı sil
+   - Kullanıcıya rapor et: "3 denemede de minimum skoru yakalayamadım. Muhtemel sebepler: [list]. Elle düzeltmek mi, farklı yaklaşım mı denemek istersiniz?"
+
+#### Adım 4 — Pass sonrası raporlama
+
+Validation passed ise kullanıcıya özet çıkar:
+```
+✅ Ekran hazır: "Vadesiz TL - iPhone 17"
+   📊 DS Compliance Score: 92/100
+   🧩 Library Instances: 7
+   🎨 Token Bindings: 24
+   📐 Auto-Layout Coverage: 100%
+   ⏱️ Süre: 18 saniye
+```
+
+#### Anti-patterns (Self-Audit atlamak)
+
+❌ **YANLIŞ:** "Screenshot güzel görünüyor, validate'e gerek yok" → Bu bir **disiplin kaçırmasıdır**
+✅ **DOĞRU:** Screenshot güzel olsa bile validate çalıştır. Token binding eksikliği gözle görülmez.
+
+❌ **YANLIŞ:** Score 75 → "yeterince iyi, kullanıcıya sun"
+✅ **DOĞRU:** Score < 80 → retry loop, ekranı düzelt
+
+❌ **YANLIŞ:** Self-audit'i opsiyonel sayma
+✅ **DOĞRU:** generate-figma-screen akışının **tamamlanma koşulu** bu adımdır. Validate çalıştırılmadan akış TAMAMLANMIŞ sayılmaz.
+
+### Step 6.6: Inter-Screen Checkpoint Gate + Turn Budget (ZORUNLU — v1.8.2+)
+
+Kullanıcı birden fazla alternatif istediğinde (N > 1), her alternatif **ayrı bir turn** olmalıdır. Tek turn'de 2+ alternatif yapmak **YASAK** — tool-use limit'e takılır, chat donar.
+
+#### Turn Budget Kuralı
+
+**Her turn'ün bütçesi:**
+- Maksimum **90 saniye** toplam süre
+- Maksimum **2 başarısız tool call** (timeout/error)
+
+Eğer turn içinde:
+- 2 başarısız tool call (timeout/error) olursa, **VEYA**
+- 60+ saniye geçti ve sonuç gelmediyse
+
+→ **Turn'ü "FAILED" olarak işaretle.** Orphan cleanup uygula (fmcp-intent-router Tool Failure Recovery Protocol). Kullanıcıya checkpoint sorusunu sor.
+
+#### Checkpoint Gate (Her Turn Sonrası)
+
+Alternatif N tamamlandığında (başarılı veya fail), kullanıcıya `AskUserQuestion` ile sor:
+
+```
+✅/⚠️ Alternatif N/M ({name}) tamamlandı
+   Node ID: 173:xxxxx
+   Skor: XX/100
+   Library instances: X
+   Token bindings: Y
+   Süre: Xs
+
+Ne yapayım?
+[✅ Beğendim, Alternatif N+1'e geç]
+[✏️ Revize et (ne değişsin söyle)]
+[🛑 Dur, bu yeter]
+```
+
+**Kullanıcı yanıtı gelmeden bir sonraki alternatife GEÇME.** Turn boundary kuralı budur.
+
+#### Yasaklar
+
+❌ **YANLIŞ:** Tek turn'de 3 alternatifi de yap, en sonda tek özet
+✅ **DOĞRU:** Her alternatif ayrı turn, her biri sonunda checkpoint
+
+❌ **YANLIŞ:** Turn içinde 3+ retry (sonsuz döngü)
+✅ **DOĞRU:** 2 retry max, sonra Turn FAILED + kullanıcıya sor
+
+❌ **YANLIŞ:** Alternatif N başarısız, sessizce N+1'e geç
+✅ **DOĞRU:** N başarısız olunca orphan cleanup + rapor + checkpoint
+
 ### Step 7: Güncelleme Senaryosu
 
 Mevcut bir ekranı güncellerken: