@atezer/figma-mcp-bridge 1.7.23 → 1.7.25

package/skills/component-documentation/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: component-documentation
+description: Figma bileşeni için kullanım kılavuzu oluşturur. "bileşen dokümantasyonu", "component docs", "usage guidelines", "bileşen kılavuzu" ifadeleriyle tetiklenir.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - designer
+    - designops
+    - uidev
+---
+
+# Component Documentation
+
+> **Design Token Kuralı:** Bu skill'deki kod örneklerinde geçen font adları, renk kodları, piksel boyutları yalnızca FORMAT gösterimidir. Çalışma anında tüm design token değerleri (font, renk, boyut, spacing, radius, gölge) kayıtlı kütüphaneden (`figma_get_variables`, `figma_get_styles`) veya kullanıcıdan okunmalıdır. Hardcoded token değeri kullanma. Detay: `project-context.md` → "Design Token Kuralı".
+
+## Workflow
+
+1. **Standart kontrolü:** `reference_industry_design_standards.md` oku. "Son güncelleme" 1 yıldan eskiyse kullanıcıya güncelleme öner (kaynak listesi aşağıda).
+2. **Bileşen analizi:** figma_get_component_for_development + figma_get_design_context (depth=3, full) + figma_get_variables
+
+> **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.
+3. **Bileşen description güncelleme:** Bileşenin description ve link alanlarını güncelle (bkz. "Bileşen Description Kuralları").
+4. **KULLANICIYA FORMAT SEÇ:** Aşağıdaki 2 seçeneği içerik özetiyle sun. Onay olmadan frame OLUŞTURMA.
+5. Seçime göre frame oluştur. Eski aynı isimli frame varsa sil.
+6. Height bug fix: `primaryAxisSizingMode` FIXED→AUTO toggle.
+7. Viewport'u frame'e odakla.
+
+> **ONAY KURALI:** Bileşene herhangi bir ekleme veya değişiklik yapmadan önce (description, property, variant, child node, frame oluşturma vb.) yapılacak değişikliği açıkça belirt ve kullanıcıdan onay bekle. Sadece okuma/analiz işlemleri onaysız yapılabilir.
+
+---
+
+## Format Seçenekleri
+
+### Standard (~2800px, 780px geniş)
+
+| # | Bölüm | İçerik |
+|---|-------|--------|
+| 1 | Intro | Başlık (26px Bold) + 2 satırlık tanıtım |
+| 2 | Variantlar | Kart: gri bg, instance (130px fixed) + isim + açıklama (FILL) |
+| 3 | Durumlar | Grid: Default, Hover, Active, Disabled, Loading, Error, Focus — her durum gerçek instance ile gösterilir (mevcut variant'ın farklı state'leri) |
+| 4 | Kurallar | Do/Dont metin kutuları (yeşil/kırmızı, 3+3 madde) + görsel örnekler (gerçek instance'larla doğru/yanlış çift kartlar) |
+| 5 | Standartlar | Kaynak chip'leri (M3, HIG, WCAG, shadcn) + info kutu (touch, kontrast, hiyerarşi, boyut, states) |
+| 6 | Props | Satır bazlı: prop adı (mavi) + tip/default (gri) + açıklama (FILL) |
+| 7 | Copy Spec | Text node'lar için copy kuralları: max karakter, truncation davranışı, boş durum metni, placeholder. Bkz. [ux-copy-guidance](../ux-copy-guidance/SKILL.md) |
+| 8 | A11y | Info kutu: touch, focus, label, disabled |
+| 9 | Tokenlar | Renk + boyut token satırları, dark mode notu |
+| 10 | Kod | Tek koyu blok: React, SwiftUI, Compose |
+
+### Compact (~1300px, 720px geniş)
+
+| # | Bölüm | İçerik |
+|---|-------|--------|
+| 1 | Başlık | 24px Bold + tek satırlık tanıtım |
+| 2 | Variantlar | Satır bazlı: instance + "Name — açıklama" |
+| 3 | Kurallar | Do/Dont minimal: 3+3 madde (görsel örnek yok) |
+| 4 | Teknik | TEK KUTU: touch, kontrast, padding, states, props hepsi içinde |
+| 5 | Tokenlar | 2 satır, bullet-separated |
+| 6 | Kod | Tek koyu blok |
+
+> **NOT:** Copy Spec ve Durumlar bölümleri Compact formatta dahil değildir. Bu bölümler yalnızca Standard formatta yer alır.
+
+---
+
+## State Machine Geçiş Diyagramı (Sadece Standard)
+
+Etkileşimli bileşenler için durum geçiş diyagramı üretilir. Variant yapısından (`State` prop'u) otomatik çıkarılır:
+
+```mermaid
+stateDiagram-v2
+  [*] --> Default
+  Default --> Hover : onMouseEnter
+  Hover --> Active : onMouseDown / onTouchStart
+  Active --> Default : onMouseUp / onTouchEnd
+  Default --> Focus : onFocus (Tab)
+  Focus --> Default : onBlur
+  Default --> Disabled : disabled=true
+  Hover --> Default : onMouseLeave
+  Active --> Loading : async action
+  Loading --> Default : success
+  Loading --> Error : failure
+  Error --> Default : retry / dismiss
+```
+
+**Kurallar:**
+- Her durumdan `Disabled`'a geçiş mümkün (programatik)
+- `Loading` yalnızca async aksiyon tetikleyen bileşenlerde (Button, Form, Toggle)
+- `Error` yalnızca başarısız olabilecek aksiyonlarda
+- Geçiş tetikleyicileri (onMouseEnter, onFocus vb.) açıkça belirtilmeli
+- Statik bileşenler (Card, Badge, Divider) için diyagram üretilmez
+
+---
+
+## Görsel Do/Don't Örnekleri (Sadece Standard)
+
+Kurallar bölümüne metin kutularından SONRA eklenir. Her örnek çift kart (doğru + yanlış) yan yana:
+
+```
+HORIZONTAL row (FILL):
+  ├── Doğru kart: yeşil bg + border, gerçek instance'lar, kısa açıklama
+  └── Yanlış kart: kırmızı bg + border, gerçek instance'lar, kısa açıklama
+```
+
+Örnek çiftler (bileşen tipine göre adapte et):
+- Hiyerarşi doğru/yanlış: Primary+Secondary vs 2x Primary
+- Etiket doğru/yanlış: "Giriş Yap" vs "Tıkla"
+- Variant kullanımı doğru/yanlış: Primary+Outline+Ghost vs hepsi aynı
+
+Her kartta:
+- Başlık: 13px Bold, yeşil/kırmızı
+- Instance satırı: gerçek component instance'ları yan yana
+- Açıklama: 12px, tek satır
+
+---
+
+## Bileşen Description Kuralları
+
+### Description alanı
+- "Bu bileşen nedir ve ne amaçla kullanılır?" sorusuna **tek cümle** cevap ver
+- State listesi, yapı detayları, teknik kurallar gibi uzun bilgileri description'a EKLEME
+- Varsa bileşenin dokümantasyon sayfasını (Documentation frame) oku ve oradan özetle
+
+### Link alanı
+- Bileşenin dokümantasyon sayfası varsa Figma linkini `documentationLinks` olarak ekle
+- Format: `https://www.figma.com/design/{fileKey}/...?node-id={docNodeId}`
+
+### Örnek
+- **Doğru:** "File Upload bileşeni, kullanıcıların belgelerini sisteme yüklemesini sağlar. Buton aracılığıyla dosya seçimi yapılır."
+- **Yanlış:** "Dosya yükleme bileşeni (Mobil). States: empty, loading, loaded, disable. Yapısı: Label + Button + Belgeler listesi + Hint. Kurallar: Genişlik 358px, maks 10 dosya..."
+
+---
+
+## Ortak Kurallar
+
+### Dil
+- Sade, junior-friendly — teknik terimlerin yanına açıklama ekle
+- Her kural 1 satır — neden gerekliyse parantez içinde
+- "CTA" değil "ana aksiyon butonu"
+
+### Türkçe Karakter Kuralı (ZORUNLU)
+Tüm Türkçe metin içeriklerinde doğru Unicode karakterler kullanılmalıdır. ASCII karşılıkları YASAKTIR:
+ş (s değil), ı (i değil), ö (o değil), ü (u değil), ç (c değil), ğ (g değil), İ (I değil), Ş (S değil)
+Son adım: Üretilen tüm Türkçe metinleri karakter kontrolünden geçir.
+
+### Layout
+- Ana frame: VERTICAL, genişlik FIXED, yükseklik AUTO
+- Child'lar: `layoutSizingHorizontal = "FILL"`
+- Metinler: `textAutoResize = "HEIGHT"` — ASLA sabit yükseklik
+- Do/Dont: HORIZONTAL parent, FILL child'lar — ASLA sabit genişlik
+- Font: Inter (Regular, Medium, Semi Bold, Bold)
+
+### Token Bağlama Kontrolü
+Dokümantasyon üretirken bileşendeki bağlı olmayan değerleri tespit et ve uyar.
+Token bağlama kuralları için bkz: `generate-figma-library` skill'i.
+
+### Standart Referansı
+- Hafıza: `reference_industry_design_standards.md` (14 bölüm)
+- Bileşene uygun bölümler seçilir, tamamı yazılmaz
+- Chip'lerle kaynak göster: M3, HIG, WCAG 2.2, shadcn/ui
+
+---
+
+## Standart Güncelleme Kaynakları (Yıllık)
+
+| Kaynak | URL | Kontrol |
+|--------|-----|---------|
+| shadcn/ui | shadcn.com | Yeni bileşenler, tema tokenları |
+| Tailwind CSS | tailwindcss.com | Varsayılan değerler, breaking changes |
+| Radix UI | radix-ui.com | Yeni primitive'ler, a11y kalıpları |
+| Lucide Icons | lucide.dev | Grid/stroke değişiklikleri |
+| Material Design 3 | m3.material.io | M3 Expressive, bileşen specleri |
+| Apple HIG | developer.apple.com/design | Liquid Glass, platform kuralları |
+| WCAG | w3.org/TR/WCAG22 | Yeni SC'ler, hedef boyut |
+| W3C Design Tokens | designtokens.org | DTCG format, yeni tipler |
+| Carbon DS | carbondesignsystem.com | Bileşen checklist |
+
+---
+
+## Marka Profili Entegrasyonu
+
+`.fmcp-brand-profile.json` varsa:
+- `voiceTone` → Bileşen açıklama ve kullanım notlarının ton kalibrasyonu
+- `copyRules` → Copy Spec bölümünde CTA max karakter, kaçınılacak kelimeler referansı
+
+## Skill Koordinasyonu
+
+- Öncesi: `generate-figma-library` veya `figma-canvas-ops`
+- Sonrası: `ai-handoff-export`
+- İlişkili: `figma-a11y-audit`, `ux-copy-guidance`, `reference_industry_design_standards.md`

package/skills/design-drift-detector/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: design-drift-detector
+description: iOS, Android ve Web platformlarında mevcut kod ile Figma tasarımı arasındaki farkları (drift) tespit eder. Platform bazlı ve cross-platform drift raporları üretir. "check drift", "design drift", "platform drift", "tasarım sapması kontrol et", "parity check", "kod Figma uyuşuyor mu", "spacing doğrula", "token tutarlılık" ifadeleriyle tetiklenir. F-MCP Bridge plugin bağlantısı gerektirir. Bu özellik resmi Figma plugininde yoktur.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - uidev
+    - designops
+    - po
+---
+
+# Design Drift Detector (Multi-Platform)
+
+> **Design Token Kuralı:** Bu skill'deki kod örneklerinde geçen font adları, renk kodları, piksel boyutları yalnızca FORMAT gösterimidir. Çalışma anında tüm design token değerleri (font, renk, boyut, spacing, radius, gölge) kayıtlı kütüphaneden (`figma_get_variables`, `figma_get_styles`) veya kullanıcıdan okunmalıdır. Hardcoded token değeri kullanma. Detay: `project-context.md` → "Design Token Kuralı".
+
+## Overview
+
+Bu skill, implementasyon sonrasında oluşan kod-tasarım sapmalarını **iOS, Android ve Web** platformlarında ayrı ayrı ve cross-platform olarak tespit eder. Resmi Figma plugininde bu yetenek yoktur.
+
+**Drift türleri:**
+- **Token drift** — Figma'da token değeri değişti ama platformdaki dosyada güncellenmedi
+- **Component drift** — Figma component'i değişti (yeni variant, spacing değişikliği vb.) ama koddaki implementasyon güncellenmedi
+- **Platform gap** — Bir platform güncellenmiş ama diğerleri eski kalmış
+- **Cross-platform inconsistency** — Aynı token farklı platformlarda farklı değerde
+
+REST API veya Figma access token gerekmez.
+
+**Önemli:** Bu skill'in tüm karşılaştırma ve drift tespiti **AI agent tarafından** yapılır. MCP araçları (`figma_get_variables`, `figma_get_styles`, `figma_check_design_parity`) ham veri sağlar; drift analizi, raporlama ve düzeltme önerileri AI'ın çıkarımlarıdır.
+
+## Prerequisites
+
+- F-MCP Bridge plugin bağlı olmalı
+- Tercihen `.figma-mappings.json` mevcut olmalı (code-design-mapper skill'i ile oluşturulur)
+- Token dosyaları mevcut olmalı (design-token-pipeline skill'i ile oluşturulur)
+
+## F-MCP skill koordinasyonu
+
+**Bu skill’in yeri:** Kod ve Figma **parity** doğrulaması — tipik olarak **implement-design** veya mevcut kod tabanı üzerinde **sonra** çalıştırılır; handoff/implement **öncesi** “mutlaka drift” diye zorunlu değildir (henüz kod yoksa anlamsız olur).
+
+**Tipik sıra (kod hattı):** **design-token-pipeline** → isteğe bağlı **code-design-mapper** → **ai-handoff-export** → **implement-design** → **design-drift-detector** (parity). Tuvalde DS tutarsızlığı şüpheliyse önce **audit-figma-design-system** ve gerekirse **fix-figma-design-system-finding** / **apply-figma-design-system**; aksi halde drift raporu **yanlış pozitif** üretebilir.
+
+**Drift sonrası yönlendirme:**
+- Sapma **kodda** → kodu düzelt, ardından bu skill’i **yeniden** çalıştır.
+- Değişiklik etkisini ölçmek istiyorsan → **ds-impact-analysis**
+- PO/PM'e teknik olmayan özet sunmak istiyorsan → **figma-screen-analyzer**
+- Sapma **Figma tuvalinde** (instance/token) → **audit-figma-design-system** / **fix** / **apply**, sonra gerekirse tekrar drift veya implement.
+
+**Performans:** Aynı oturumda `figma_get_variables` + `figma_get_design_context` tekrarını azalt; önceki tool çıktısı geçerliyse yeniden çağırma. Zincir notları: **audit-figma-design-system** içindeki “Zincir performansı”.
+
+## Required Workflow
+
+### Step 1: Plugin Bağlantısını Doğrula
+
+```
+figma_get_status()
+```
+
+### Step 2: Kontrol Kapsamını Belirle
+
+3 kontrol modu var:
+
+**A) Hızlı Token Drift** — Sadece token değerlerini karşılaştır (en hızlı)
+**B) Platform Component Drift** — Belirli platformda component'leri kontrol et
+**C) Tam Cross-Platform Tarama** — Tüm platformlarda token + component drift (en kapsamlı)
+
+### Step 3: Veri Kaynaklarını Topla
+
+#### Figma tarafı:
+
+```
+figma_get_variables(verbosity="full")
+```
+
+```
+figma_get_styles(verbosity="full")
+```
+
+Component mapping varsa:
+
+`.figma-mappings.json` dosyasını oku → component listesini ve platform implementasyonlarını al
+
+Her component için:
+
+```
+figma_get_design_context(
+  nodeId="<NODE_ID>",
+  depth=2,
+  verbosity="full",
+  includeLayout=true,
+  includeVisual=true,
+  includeTypography=true
+)
+```
+
+#### Kod tarafı (her platform için):
+
+**iOS:**
+- `Colors.swift` veya Asset Catalog'dan renk değerlerini oku
+- `Typography.swift`'ten font değerlerini oku
+- `Spacing.swift`'ten spacing değerlerini oku
+- Component dosyalarındaki hardcoded değerleri ara
+
+**Android:**
+- `res/values/colors.xml` ve `res/values-night/colors.xml`'den renkleri oku
+- `res/values/dimens.xml`'den spacing/radius/font size'ları oku
+- `AppColors.kt`, `AppTypography.kt`, `AppSpacing.kt`'den Compose değerlerini oku
+- Component dosyalarındaki hardcoded değerleri ara
+
+**Web:**
+- `tokens.css` veya `_tokens.scss`'den CSS variable/Sass variable değerlerini oku
+- `tailwind.config.js`'den Tailwind token'larını oku
+- `tokens.ts`'den TypeScript constant'ları oku
+- Component dosyalarındaki hardcoded değerleri ara
+
+### Step 4: Token Drift Kontrolü
+
+Figma token'larını her platformdaki token dosyasıyla karşılaştır.
+
+**KRİTİK — Token Name Eşleşme Sorunu:**
+
+`figma_check_design_parity` token isimlerini **tam string eşleşme** ile karşılaştırır. Ancak platformlar arası isimlendirme farklıdır:
+
+| Figma Variable Adı | iOS | Android | Web |
+|---------------------|-----|---------|-----|
+| `color/primary/500` | `primary500` | `primary_500` | `--color-primary-500` |
+| `spacing/md` | `md` | `space_md` | `--space-md` |
+
+Bu yüzden **`codeTokens` içinde Figma'daki variable adını aynen kullanmalısın** — platform naming convention'ını değil:
+
+```
+figma_check_design_parity(
+  codeTokens='{"color/primary/500": "#3b82f6", "spacing/md": "16"}'
+)
+```
+
+`figma_check_design_parity` sadece token DEĞER karşılaştırması yapar. Platform kodundaki isimlendirmeyi kontrol etmez. Bu yüzden ek olarak platform dosyalarından değerleri kendin çıkarıp Figma ile karşılaştır:
+
+**Platform-spesifik token çıkarma (AI tarafından yapılır):**
+
+| Platform | Token Dosyası | Değer Çıkarma |
+|----------|--------------|---------------|
+| iOS | `Colors.swift` | `Color(hex: "#3B82F6")` → `#3B82F6` |
+| iOS | `Spacing.swift` | `static let md: CGFloat = 16` → `16` |
+| Android | `colors.xml` | `<color name="primary">#FF3B82F6</color>` → `#3B82F6` |
+| Android | `dimens.xml` | `<dimen name="space_md">16dp</dimen>` → `16` |
+| Android | `AppColors.kt` | `Color(0xFF3B82F6)` → `#3B82F6` |
+| Web | `tokens.css` | `--color-primary: #3b82f6` → `#3b82f6` |
+| Web | `tailwind.config.js` | `primary: '#3b82f6'` → `#3b82f6` |
+
+### Step 5: Component Drift Kontrolü
+
+**Önemli:** `figma_check_design_parity` component-level karşılaştırma yapmaz. Component drift kontrolünü AI agent olarak kendin yapmalısın:
+
+Her mapping'deki component için, her platformda:
+
+1. `figma_get_design_context(nodeId=..., includeLayout=true, includeVisual=true, includeTypography=true)` ile Figma'daki güncel component verisini al
+2. Platform kodunu oku (ör. `ButtonComponent.swift`, `ButtonComponent.kt`, `Button.tsx`)
+3. Aşağıdaki özellikleri karşılaştır:
+   - Renkler (background, text, border)
+   - Spacing (padding, margin, gap)
+   - Typography (font, size, weight, line-height)
+   - Border radius
+   - Boyutlar (width, height)
+   - Variant/prop tanımları
+
+Bu karşılaştırma tamamen AI tarafından yapılır — otomatik bir MCP aracı yoktur.
+
+### Step 5.5: Motion Token Drift Kontrolü
+
+Renk, tipografi ve spacing'e ek olarak **motion token'larını** da kontrol et:
+
+| Motion Token | Figma Değer | iOS | Android | Web |
+|-------------|-------------|-----|---------|-----|
+| `duration/fast` | 150 | withAnimation(.easeInOut(duration: 0.15)) | animateFloatAsState(150ms) | transition: 150ms |
+| `duration/normal` | 250 | 0.25 | 250ms | 250ms |
+| `duration/slow` | 400 | 0.4 | 400ms | 400ms |
+| `easing/standard` | ease-in-out | .easeInOut | FastOutSlowInInterpolator | ease-in-out |
+| `easing/decelerate` | ease-out | .easeOut | DecelerateInterpolator | ease-out |
+
+**Motion token drift kaynakları:**
+- Figma'da motion token tanımlı ama kodda hardcoded süre/easing
+- Platform bazında farklı easing curve'ler (Figma: ease-in-out, kod: linear)
+- Yeni eklenen motion token'ların koda yansıtılmamış olması
+
+> Motion token'ları Figma'da STRING variable olarak veya dokümantasyon sayfasında bulunabilir. `figma_get_variables(verbosity="full")` ile STRING type variable'ları kontrol et.
+
+### Step 6: Cross-Platform Tutarlılık Kontrolü
+
+Aynı token'ın 3 platformdaki değerini karşılaştır:
+
+```
+Cross-Platform Token Kontrolü:
+┌─────────────────┬───────────┬───────────┬───────────┬──────────┐
+│ Token           │ Figma     │ iOS       │ Android   │ Web      │
+├─────────────────┼───────────┼───────────┼───────────┼──────────┤
+│ primary         │ #2563EB   │ #3B82F6   │ #2563EB   │ #3b82f6  │
+│                 │           │ DRIFT!    │ OK        │ DRIFT!   │
+├─────────────────┼───────────┼───────────┼───────────┼──────────┤
+│ spacing-md      │ 16        │ 16 pt     │ 16 dp     │ 12 px    │
+│                 │           │ OK        │ OK        │ DRIFT!   │
+├─────────────────┼───────────┼───────────┼───────────┼──────────┤
+│ radius-md       │ 8         │ 8 pt      │ 8 dp      │ 8 px     │
+│                 │           │ OK        │ OK        │ OK       │
+└─────────────────┴───────────┴───────────┴───────────┴──────────┘
+```
+
+### Step 7: Drift Raporu Oluştur
+
+```markdown
+# Multi-Platform Design Drift Raporu
+**Tarih:** 2026-03-12
+**Figma Dosya:** Design System
+
+## Özet
+
+| Platform | Token Drift | Component Drift | Toplam |
+|----------|-------------|-----------------|--------|
+| iOS      | 3 divergent | 2 component     | 5      |
+| Android  | 1 divergent | 1 component     | 2      |
+| Web      | 5 divergent | 3 component     | 8      |
+| **Cross-platform** | **2 inconsistency** | — | **2** |
+
+**Kritik Seviye:** 5 (acil düzeltme gerekir)
+**Orta Seviye:** 8 (sprint içinde düzeltilmeli)
+**Düşük Seviye:** 4 (takip edilmeli)
+
+---
+
+## Token Drift — Platform Detayları
+
+### iOS (3 drift)
+
+| Token | Figma | iOS Kodu | Dosya | Önem |
+|-------|-------|----------|-------|------|
+| primary | #2563EB | #3B82F6 | Colors.swift:12 | KRİTİK |
+| spacing-lg | 24 | 20 | Spacing.swift:8 | YÜKSEK |
+| text-weight-bold | 700 | 600 | Typography.swift:5 | ORTA |
+
+**Önerilen düzeltme:** `Colors.swift`'te `primary` değerini `#2563EB` olarak güncelle.
+
+### Android (1 drift)
+
+| Token | Figma | Android Kodu | Dosya | Önem |
+|-------|-------|-------------|-------|------|
+| spacing-lg | 24 | 20 | dimens.xml:8, AppSpacing.kt:6 | YÜKSEK |
+
+### Web (5 drift)
+
+| Token | Figma | Web Kodu | Dosya | Önem |
+|-------|-------|---------|-------|------|
+| primary | #2563EB | #3b82f6 | tokens.css:5 | KRİTİK |
+| spacing-md | 16 | 12 | tokens.css:15 | YÜKSEK |
+| spacing-lg | 24 | 20 | tokens.css:16 | YÜKSEK |
+| radius-lg | 12 | 16 | tokens.css:22 | ORTA |
+| text-size-lg | 16 | 18 | tokens.css:28 | ORTA |
+
+---
+
+## Cross-Platform Inconsistency
+
+Aynı token'ın platformlar arasında farklı olduğu durumlar (Figma'dan bağımsız):
+
+| Token | iOS | Android | Web | Notlar |
+|-------|-----|---------|-----|--------|
+| primary | #3B82F6 | #2563EB | #3b82f6 | iOS ≠ Android (ikisi de eski) |
+| spacing-lg | 20 pt | 20 dp | 20 px | Hepsi eski ama tutarlı |
+
+---
+
+## Component Drift
+
+### Button (42:15)
+
+| Platform | Durum | Detay |
+|----------|-------|-------|
+| iOS | DRIFT | padding 12→16, font-weight 400→600 |
+| Android | OK | — |
+| Web | DRIFT | padding 12→16, border-radius 4→8 |
+
+### Card (42:20)
+
+| Platform | Durum | Detay |
+|----------|-------|-------|
+| iOS | OK | — |
+| Android | DRIFT | yeni variant "outlined" Figma'da var, kodda yok |
+| Web | OK | — |
+
+---
+
+## Önerilen Aksiyon Planı
+
+### Acil (Bu Sprint)
+1. `primary` rengini tüm platformlarda `#2563EB` olarak güncelle
+2. `spacing-md` ve `spacing-lg` değerlerini Web'de düzelt
+
+### Yüksek Öncelik
+3. Button component'ini iOS ve Web'de güncelle
+4. Card'a Android'de `outlined` variant'ı ekle
+
+### Orta Öncelik
+5. Typography font-weight değerlerini iOS'ta düzelt
+6. Border radius değerlerini Web'de düzelt
+
+### Otomasyon Önerisi
+- Token drift'leri için: `design-token-pipeline` skill'ini çalıştırarak tüm platformların token dosyalarını yeniden üret
+- Component drift'leri için: her drifted component'i `implement-design` skill'iyle yeniden implement et
+```
+
+### Step 8: Otomatik Düzeltme Seçenekleri
+
+Kullanıcıya düzeltme yollarını sun:
+
+**A) Token dosyalarını yeniden üret (tüm platformlar)**
+→ `design-token-pipeline` skill'ini çalıştır
+
+**B) Belirli platformun token'larını güncelle**
+→ `design-token-pipeline` skill'ini sadece o platform için çalıştır
+
+**C) Drifted component'leri yeniden implement et**
+→ `implement-design` skill'ini hedef platform + nodeId ile çalıştır
+
+**D) Sadece raporla**
+→ Raporu kaydet, takıma paylaş
+
+### Step 9: Mapping Durumlarını Güncelle
+
+Drift kontrolü sonrası `.figma-mappings.json`'daki durumları güncelle:
+
+- Drift yok → `status: "synced"`
+- Drift var → `status: "outdated"`
+- Düzeltme yapıldı → `status: "synced"`, `lastSync` güncelle
+- Coverage summary'yi güncelle
+
+## Periyodik Kontrol Önerileri
+
+- **Sprint sonu:** Tüm platformlarda tam tarama
+- **Design token güncellemesi sonrası:** Token drift kontrolü
+- **Platform release öncesi:** İlgili platformda component drift kontrolü
+- **Büyük Figma güncellemesi sonrası:** Cross-platform tarama
+
+## Examples
+
+### Örnek 1: Hızlı Token Kontrolü — Tüm Platformlar
+
+Kullanıcı: "Token'lar güncel mi kontrol et, tüm platformlarda"
+
+**Akış:**
+
+1. `figma_get_variables(verbosity="full")` → Figma'daki 48 token
+2. iOS'tan `Colors.swift` + `Spacing.swift` oku → 45 token
+3. Android'den `colors.xml` + `dimens.xml` oku → 43 token
+4. Web'den `tokens.css` oku → 48 token
+5. Her platform için `figma_check_design_parity(...)` çağır
+6. Cross-platform karşılaştırma tablosu oluştur
+7. Rapor: "iOS'ta 3, Android'de 1, Web'de 5 drift tespit edildi"
+
+### Örnek 2: Tek Platform Component Kontrolü
+
+Kullanıcı: "Android component'leri Figma ile uyumlu mu?"
+
+**Akış:**
+
+1. `.figma-mappings.json`'dan Android mapping'lerini oku → 18 component
+2. Her component için Figma design context çek
+3. Android koduyla karşılaştır
+4. Rapor: "1 component drifted (Card — yeni variant eksik)"
+
+### Örnek 3: Belirli Component — Tüm Platformlar
+
+Kullanıcı: "Button tüm platformlarda güncel mi?"
+
+**Akış:**
+
+1. `.figma-mappings.json`'dan Button mapping'ini oku → 3 platform implementasyonu
+2. `figma_get_design_context(nodeId="42:15", ...)` → Figma'daki güncel Button
+3. iOS `ButtonComponent.swift` oku → karşılaştır
+4. Android `ButtonComponent.kt` oku → karşılaştır
+5. Web `Button.tsx` oku → karşılaştır
+6. Rapor: "iOS ve Web'de padding drift var, Android güncel"
+
+## Common Issues and Solutions
+
+### Sorun: Token dosyası bulunamıyor (platform hiç export etmemiş)
+
+**Çözüm:** Önce `design-token-pipeline` skill'ini çalıştırarak token dosyalarını oluştur. Drift kontrolü token dosyası yoksa o platformu "not initialized" olarak raporlar.
+
+### Sorun: Renk formatları farklı (hex case, alpha prefix)
+
+**Çözüm:** Karşılaştırma öncesi normalize et: `#3B82F6`, `#3b82f6`, `#FF3B82F6`, `Color(0xFF3B82F6)` hepsi aynı renktir. Alpha prefix'i (FF) kaldır, lowercase'e çevir.
+
+### Sorun: Platform projeleri farklı repo'da
+
+**Çözüm:** `.figma-mappings.json`'daki `platforms.*.rootDir` alanından her platformun yolunu al. Dosya okumaları bu path'e göre yapılır.
+
+### Sorun: False positive çok fazla
+
+**Çözüm:** Tolerans eşiği uygula:
+- Renk: Delta E < 3 ise "low priority"
+- Spacing: 1px fark ise "low priority"
+- Font size: tam eşleşme bekle (fark yok)
+
+## Evolution Triggers
+
+- Bridge'e yeni parity aracı eklenirse (ör. token karşılaştırma aracı) ilgili adımlar basitleştirilmeli
+- Yeni platform desteği (Flutter, .NET MAUI) eklenirse platform drift profilleri genişletilmeli
+- `figma_check_design_parity` parametreleri değişirse Step güncellemesi yapılmalı
+- Cross-platform drift raporunda CI entegrasyonu eklenirse JSON çıktı formatı standardize edilmeli