@atezer/figma-mcp-bridge 1.7.23 → 1.7.25

package/skills/SKILL_INDEX.md

@@ -0,0 +1,194 @@
+# F-MCP Skill Dizini
+
+## Workspace kökü (önemli)
+
+Cursor, Claude Code veya VS Code'da **klasör / workspace kökü olarak bu repoyu** (`FCM`, yani `package.json` bu kökte görünecek şekilde) açın. Skill'ler `skills/<skill>/SKILL.md` dizinindedir. Eski `.cursor/skills/f-mcp/` yolu da symlink ile desteklenir.
+
+## Personalar
+
+| Kısaltma | Persona | Açıklama |
+|---|---|---|
+| `designer` | **Tasarımcı** | Bileşen tasarımı, DS kullanarak ekran çizimi, custom UI |
+| `designops` | **DesignOps** | DS yönetimi, etki analizi, token yönetimi, kalite kontrolü |
+| `uidev` | **UI Geliştirici** | iOS/Android/Web arayüz geliştirme, Figma'dan kod üretme |
+| `po` | **PO/PM/SEM** | UI analiz, tasarım durumu raporlama, karar alma |
+
+## Kişiselleştirme — Marka Profili
+
+Tüm skill'ler `.fmcp-brand-profile.json` dosyasını okuyarak marka ses/ton, tipografi, estetik yön ve copy kurallarını otomatik uygular. Detay: [BRAND_PROFILE_SCHEMA.md](BRAND_PROFILE_SCHEMA.md)
+
+**Oluşturma:** `ux-copy-guidance` skill'i profil yoksa otomatik 3-soru akışı başlatır. Manuel olarak da proje köküne `.fmcp-brand-profile.json` dosyası eklenebilir.
+
+## Skill Listesi (20 skill)
+
+### Temel Kurallar
+
+| Skill | Dosya | Personalar | Kısa açıklama |
+|---|---|---|---|
+| `fmcp-project-rules` | [fmcp-project-rules/SKILL.md](fmcp-project-rules/SKILL.md) | designer, designops, uidev, po | Design Token Kuralı, Bağlı Token Kuralı, kütüphane yönetimi, otomatik yanıt kuralları — tüm skill'ler için geçerli |
+
+### Dokümantasyon ve İçerik
+
+| Skill | Dosya | Personalar | Kısa açıklama |
+|---|---|---|---|
+| `component-documentation` | [component-documentation/SKILL.md](component-documentation/SKILL.md) | designer, designops, uidev | Bileşen kullanım kılavuzu oluşturma (Standard/Compact format, durumlar, copy spec, endüstri standartları referansı) |
+| `ux-copy-guidance` | [ux-copy-guidance/SKILL.md](ux-copy-guidance/SKILL.md) | designer, uidev, po | UX yazarlık rehberi — CTA, hata mesajı, boş durum, onay diyaloğu kalıpları + marka ses/ton kişiselleştirmesi |
+
+### Tuval Yazma ve Oluşturma
+
+| Skill | Dosya | Personalar | Kısa açıklama |
+|---|---|---|---|
+| `figma-canvas-ops` | [figma-canvas-ops/SKILL.md](figma-canvas-ops/SKILL.md) | designer, designops | `figma_execute` güvenli kullanım kılavuzu (zorunlu önkoşul) |
+| `generate-figma-screen` | [generate-figma-screen/SKILL.md](generate-figma-screen/SKILL.md) | designer, uidev | Kod/açıklamadan Figma'da ekran oluşturma |
+| `generate-figma-library` | [generate-figma-library/SKILL.md](generate-figma-library/SKILL.md) | designops, designer | Koddan DS kütüphanesi inşa (5 fazlı) |
+| `figjam-diagram-builder` | [figjam-diagram-builder/SKILL.md](figjam-diagram-builder/SKILL.md) | designer, designops, po | FigJam diyagram/süreç şeması |
+
+### DS Denetim ve Düzeltme
+
+| Skill | Dosya | Personalar | Kısa açıklama |
+|---|---|---|---|
+| `audit-figma-design-system` | [audit-figma-design-system/SKILL.md](audit-figma-design-system/SKILL.md) | designer, designops, po | Tuval içi DS denetimi (salt okunur) |
+| `fix-figma-design-system-finding` | [fix-figma-design-system-finding/SKILL.md](fix-figma-design-system-finding/SKILL.md) | designer, designops | Tek audit bulgusunu dar kapsamda düzelt |
+| `apply-figma-design-system` | [apply-figma-design-system/SKILL.md](apply-figma-design-system/SKILL.md) | designer, designops | Ekran geneli DS reconcile |
+
+### Token ve Kod Senkronu
+
+| Skill | Dosya | Personalar | Kısa açıklama |
+|---|---|---|---|
+| `design-token-pipeline` | [design-token-pipeline/SKILL.md](design-token-pipeline/SKILL.md) | uidev, designops | Figma ↔ kod token dönüşümü (çift yönlü) |
+| `code-design-mapper` | [code-design-mapper/SKILL.md](code-design-mapper/SKILL.md) | uidev, designops | Figma bileşen ↔ çoklu platform kod eşlemesi |
+| `design-system-rules` | [design-system-rules/SKILL.md](design-system-rules/SKILL.md) | designops, uidev | Platforma özel DS kuralları üretimi |
+
+### Implementasyon ve Teslim
+
+| Skill | Dosya | Personalar | Kısa açıklama |
+|---|---|---|---|
+| `ai-handoff-export` | [ai-handoff-export/SKILL.md](ai-handoff-export/SKILL.md) | uidev, po | HANDOFF şablonu + manifest + executive summary |
+| `implement-design` | [implement-design/SKILL.md](implement-design/SKILL.md) | uidev | Figma → iOS/Android/Web production kod |
+
+### Doğrulama ve Analiz
+
+| Skill | Dosya | Personalar | Kısa açıklama |
+|---|---|---|---|
+| `design-drift-detector` | [design-drift-detector/SKILL.md](design-drift-detector/SKILL.md) | uidev, designops, po | Kod ↔ Figma token/değer drift tespiti |
+| `visual-qa-compare` | [visual-qa-compare/SKILL.md](visual-qa-compare/SKILL.md) | uidev, designops | Figma vs kod görsel/pixel karşılaştırma |
+| `figma-a11y-audit` | [figma-a11y-audit/SKILL.md](figma-a11y-audit/SKILL.md) | designops, uidev, designer | Erişilebilirlik denetimi (WCAG, VoiceOver, TalkBack, ARIA) |
+| `figma-screen-analyzer` | [figma-screen-analyzer/SKILL.md](figma-screen-analyzer/SKILL.md) | po, designer | PO/PM/SEM için UI analiz raporu |
+| `ds-impact-analysis` | [ds-impact-analysis/SKILL.md](ds-impact-analysis/SKILL.md) | designops, po | DS değişiklik etki analizi ve risk skoru |
+
+## Persona Bazlı Önerilen Akışlar
+
+### Tasarımcı (designer)
+
+```
+1. figma-canvas-ops (önkoşul)
+2. generate-figma-library (DS kütüphanesi yoksa)
+   VEYA generate-figma-screen (ekran oluşturma — tasarım yönü belirleme adımı dahil)
+3. ux-copy-guidance (ekran text node'ları için copy kalitesi)
+4. component-documentation (bileşen kullanım kılavuzu — durumlar ve copy spec dahil)
+5. audit-figma-design-system (kalite kontrol — DS eksiksizlik çerçevesi dahil)
+6. fix / apply (düzeltme gerekiyorsa)
+7. figma-a11y-audit (erişilebilirlik kontrol — WCAG çerçevesi dahil)
+```
+
+### DesignOps
+
+```
+1. audit-figma-design-system (DS sağlık kontrolü — DS eksiksizlik çerçevesi: token kategorileri, bileşen durumları, pattern kapsamı)
+2. ds-impact-analysis (değişiklik öncesi etki analizi)
+3. apply-figma-design-system (DS hizalama)
+4. design-token-pipeline (token senkronu — motion token'lar dahil)
+5. design-system-rules (kural üretimi — DS prensipleri ve pattern katmanı dahil)
+6. figma-a11y-audit (erişilebilirlik denetimi — WCAG 2.1/2.2 AA hızlı referans dahil)
+7. generate-figma-library (DS kütüphanesi inşa/güncelleme — motion/shadow token, durum kapsamı dahil)
+8. ux-copy-guidance *(isteğe bağlı)* (marka sesiyle uyumlu copy kuralları — token isimlendirme, bileşen açıklamaları)
+```
+
+### UI Geliştirici (uidev)
+
+```
+1. ai-handoff-export (handoff paketi — etkileşim spec, içerik spec, uç durumlar, a11y spec dahil)
+2. implement-design (Figma → kod — durum/etkileşim kapsamı kontrolü dahil)
+3. design-token-pipeline (token dosyaları üret)
+4. code-design-mapper (bileşen eşleme)
+5. visual-qa-compare (görsel doğrulama)
+6. design-drift-detector (token parity — motion token drift dahil)
+7. figma-a11y-audit (a11y attribute'ları)
+8. ux-copy-guidance (hata mesajı, boş durum, CTA copy kalıpları)
+```
+
+### PO/PM/SEM (po)
+
+```
+1. figma-screen-analyzer (ekran analizi — ilk izlenim testi + kritik çerçevesi dahil)
+2. audit-figma-design-system --executive (DS uyum raporu)
+3. ds-impact-analysis (değişiklik etki ve risk skoru)
+4. design-drift-detector (kod-tasarım parity durumu)
+5. ux-copy-guidance (marka sesi ve copy tutarlılık kontrolü)
+6. ai-handoff-export (implementasyon durumu)
+7. figjam-diagram-builder (süreç haritası)
+```
+
+## Uçtan Uca Akış (Özet)
+
+Ayrıntı: [audit-figma-design-system/SKILL.md](audit-figma-design-system/SKILL.md) içinde **"Önerilen uçtan uca akış"** ve **"Zincir performansı"**.
+
+1. **Kişiselleştirme:** `.fmcp-brand-profile.json` oluştur veya kontrol et ([BRAND_PROFILE_SCHEMA.md](BRAND_PROFILE_SCHEMA.md))
+2. **Tuval hazırlık:** `figma-canvas-ops` (zorunlu önkoşul)
+3. **Oluşturma:** `generate-figma-library` (motion/shadow token dahil) → `generate-figma-screen` (tasarım yönü belirleme dahil)
+4. **İçerik:** `ux-copy-guidance` (marka sesiyle uyumlu copy)
+5. **Dokümantasyon:** `component-documentation` (bileşen kılavuzu — durumlar, copy spec dahil)
+6. **Denetim:** `audit-figma-design-system` (DS eksiksizlik çerçevesi dahil) → `fix-figma-design-system-finding` *veya* `apply-figma-design-system`
+7. **Token:** `design-token-pipeline` → isteğe bağlı `code-design-mapper`
+8. **Teslim:** `ai-handoff-export` (etkileşim/içerik/uç durum/a11y spec dahil) → `implement-design` (durum kapsamı kontrolü dahil)
+9. **Doğrulama:** `visual-qa-compare` + `design-drift-detector` (motion token drift dahil) → gerekirse `design-system-rules` (DS prensipleri dahil)
+10. **Kalite:** `figma-a11y-audit` (WCAG çerçevesi dahil) + `figma-screen-analyzer` (ilk izlenim + kritik çerçevesi dahil)
+11. **Etki:** `ds-impact-analysis` (değişiklik öncesi)
+
+**FigJam** (`figjam-diagram-builder`) bu zincirle zorunlu sırada değildir.
+
+## Referans Dosyalar
+
+| Dosya | Açıklama |
+|---|---|
+| [TOOL_MAPPING.md](TOOL_MAPPING.md) | Resmi Figma MCP ↔ F-MCP Bridge araç eşleme tablosu |
+| [BRAND_PROFILE_SCHEMA.md](BRAND_PROFILE_SCHEMA.md) | Marka profili (`.fmcp-brand-profile.json`) şema tanımı ve skill entegrasyon tablosu |
+| `reference_industry_design_standards.md` | Endüstri standartları hafıza dosyası (M3, HIG, WCAG, shadcn/ui, Tailwind) — Claude memory'de |
+
+## MCP
+
+Tüm bu skill'ler `metadata.mcp-server: user-figma-mcp-bridge` öngörür; bağlantı ve kurulum için repo kökünde `KURULUM.md` ve `docs/` dosyalarına bakın.
+
+### Araç adı doğrulaması (CI / lokal)
+
+Skill dosyalarında geçen `figma_*` adları, kaynakta `registerTool` ile tanımlı araçlarla otomatik karşılaştırılır:
+
+```bash
+npm run validate:fmcp-skills
+```
+
+Kaynak birleşimi: `src/local.ts`, `src/local-plugin-only.ts`, `src/core/figma-tools.ts`. Script: [`scripts/validate-fmcp-skills-tools.mjs`](../../../scripts/validate-fmcp-skills-tools.mjs) (repo köküne göre). **GitHub:** `master` / `main` push ve PR'larda [`.github/workflows/ci.yml`](../../../.github/workflows/ci.yml) bu komutu çalıştırır.
+
+## Persona metadata
+
+Her skill'in YAML frontmatter'ında `personas` alanı bulunur:
+
+```yaml
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - designer
+    - designops
+    - uidev
+    - po
+```
+
+Bu alan, AI agent'ın kullanıcı persona'sına göre doğru skill'i önermesini sağlar.
+
+## Evolution Triggers (genel)
+
+Her skill dosyasında `## Evolution Triggers` bölümü bulunur. Bu bölüm:
+
+- Bridge'e yeni araç eklendiğinde hangi adımların güncellenmesi gerektiğini belirtir
+- Persona geri bildirimine göre hangi çıktı formatlarının eklenmesi gerektiğini işaret eder
+- `validate:fmcp-skills` betiğinin yeni araç adlarını doğrulayacağını hatırlatır

package/skills/TOOL_MAPPING.md

@@ -0,0 +1,111 @@
+# F-MCP Bridge ↔ Resmi Figma MCP Araç Eşleme Tablosu
+
+> Yeni skill yazarken veya topluluk skill'lerini uyarlarken bu tabloyu referans alın.
+> Kaynak doğrulama: `npm run validate:fmcp-skills`
+
+## Tuval Yazma ve Çalıştırma
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| `use_figma` | `figma_execute` | Aynı amaç: JS çalıştırma. F-MCP'de `code` parametresi ile Plugin API kodu gönderilir. |
+| — | `figma_instantiate_component` | Resmi MCP'de yok; F-MCP'ye özel bileşen instance oluşturma aracı. |
+| — | `figma_set_instance_properties` | Resmi MCP'de yok; F-MCP'ye özel instance property ayarlama. |
+| — | `figma_arrange_component_set` | F-MCP'ye özel; variant grid düzenleme. |
+
+## Dosya ve Yapı Okuma
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| `get_metadata` | `figma_get_file_data` | Yapı ve metadata. F-MCP'de `depth` parametresi ile derinlik sınırlanır. |
+| `get_design_context` | `figma_get_design_context` | Aynı ad, benzer çıktı. F-MCP'de `includeCodeReady` parametresi mevcut. |
+
+## Görsel Doğrulama
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| `get_screenshot` | `figma_capture_screenshot` | Node bazlı ekran görüntüsü. |
+
+## Tasarım Sistemi Keşfi
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| `search_design_system` | `figma_search_components` + `figma_get_design_system_summary` | İki araç birlikte aynı kapsamı karşılar. `figma_search_components` bileşen arar; `figma_get_design_system_summary` genel DS özeti döner. |
+
+## Değişkenler ve Token'lar
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| (use_figma ile) | `figma_get_variables` | Verbosity: `summary` / `full`. |
+| — | `figma_refresh_variables` | Önbellek temizleme. |
+| — | `figma_get_token_browser` | Token tarayıcı; kategoriye göre filtreleme. |
+| — | `figma_create_variable` | Tekil variable oluşturma. |
+| — | `figma_create_variable_collection` | Collection oluşturma. |
+| — | `figma_batch_create_variables` | Toplu variable oluşturma. |
+| — | `figma_batch_update_variables` | Toplu variable güncelleme. |
+| — | `figma_update_variable` | Tekil güncelleme. |
+| — | `figma_delete_variable` / `figma_delete_variable_collection` | Silme. |
+| — | `figma_rename_variable` / `figma_rename_mode` / `figma_add_mode` | İsimlendirme ve mod yönetimi. |
+| — | `figma_setup_design_tokens` | Toplu token kurulum aracı. |
+
+## Stiller
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| (use_figma ile) | `figma_get_styles` | Paint, text, effect stilleri. |
+
+## Bileşenler
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| — | `figma_get_component` | Tekil bileşen detayı. |
+| — | `figma_get_component_image` | Bileşen SVG/PNG export. |
+| — | `figma_get_component_for_development` | Geliştirici odaklı bileşen bilgisi. |
+
+## Code Connect
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| `get_code_connect_suggestions` | **yok** | Bridge'de kayıtlı değil. FUTURE.md'de planlı. |
+| `send_code_connect_mappings` | **yok** | Bridge'de kayıtlı değil. |
+
+## Dosya Yönetimi
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| `create_new_file` | **yok** | Bridge'de kayıtlı değil. |
+| `whoami` | **yok** | Bridge'de kayıtlı değil. |
+| `generate_figma_design` | **yok** | Web-only paralel piksel referansı; bridge'de yok. |
+| `create_design_system_rules` | **yok** | F-MCP'de `design-system-rules` skill'i AI tabanlı üretim yapar. |
+
+## Bağlantı ve Durum
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| — | `figma_get_status` | Plugin bağlantı durumu. |
+| — | `figma_list_connected_files` | Bağlı dosya listesi. |
+| — | `figma_clear_console` | Konsol temizleme. |
+
+## Doğrudan Node Düzenleme
+
+> Node düzenleme işlemleri `figma_execute` ile Plugin API kodu çalıştırılarak yapılır.
+> Ayrıca `figma_create_frame`, `figma_create_rectangle`, `figma_create_text`, `figma_create_group` özel araçları mevcuttur.
+
+## Tasarım–Kod Parity
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| — | `figma_check_design_parity` | Tasarım–kod uyum kontrolü (plugin-only). |
+
+## REST API ve Tanılama
+
+| Resmi Figma MCP | F-MCP Bridge | Fark / Not |
+|---|---|---|
+| — | `figma_rest_api` | Doğrudan Figma REST API çağrısı (token gerekir). |
+| — | `figma_set_rest_token` / `figma_get_rest_token_status` / `figma_clear_rest_token` | REST token yönetimi. |
+| — | `figma_set_port` | Bridge port değiştirme (5454-5470). |
+| — | `figma_plugin_diagnostics` | Plugin bağlantı tanılama. |
+| — | `figma_search_assets` | Kütüphane bileşen arama. |
+| — | `figma_export_nodes` | Node export (SVG/PNG/JPG/PDF). |
+| — | `figma_set_description` | Node açıklama ayarlama. |
+| — | `figma_watch_console` | Konsol izleme. |
+| — | `figma_get_console_logs` | Konsol çıktıları. |

package/skills/ai-handoff-export/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: ai-handoff-export
+description: Figma tasarım verisini AI'nın kod üretimi için kullanabileceği tek bir handoff paketine dönüştürür (HANDOFF şablonu + JSON manifest). Node kimlikleri, design context özeti, token özeti, ekran görüntüsü referansları ve opsiyonel Code Connect haritası üretir. PO/PM için executive summary da içerir. "AI handoff", "handoff dosyası", "handoff export", "teslimat paketi", "figma handoff", "koda teslim özeti", "design handoff oluştur", "handoff al", "implementasyon paketi" ifadeleriyle tetiklenir. F-MCP Bridge plugin bağlantısı gerektirir.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - uidev
+    - po
+---
+
+# AI Handoff Export
+
+## Overview
+
+Bu skill, dağınık Figma çıktılarını tek bir teslimat formatında toplar:
+
+- `HANDOFF_TEMPLATE.md` (insan okunur)
+- `handoff.manifest.json` (makine okunur, schema tabanlı)
+
+**Önemli:** Tüm veriler plugin bridge üzerinden alınır. Şablon: repo kökünde `HANDOFF_TEMPLATE.md`; şema: `docs/handoff.manifest.schema.json`.
+
+## F-MCP skill koordinasyonu
+
+- **Önce:** Tuval DS uyumu için isteğe bağlı **audit-figma-design-system** / **apply-figma-design-system**; token isimleri için **design-token-pipeline** ile uyumlu manifest.
+- **Sonra:** **implement-design** ana tüketici; **code-design-mapper** özetini manifest’e işleyebilirsin.
+- **PO/PM akışı:** Teknik olmayan ekran özeti için **figma-screen-analyzer**; değişiklik etkisi için **ds-impact-analysis**
+
+## Required Workflow
+
+### Step 1: Plugin Bağlantısını Doğrula
+
+`figma_get_status()`
+
+### Step 2: Hedef node'ları netleştir
+
+- Kullanıcı URL verdiyse `node-id` değerini ayıkla.
+- Node belirsizse `figma_get_file_data(depth=1)` ile kapsam çıkar.
+
+### Step 3: Design context topla
+
+`figma_get_design_context` çağrısı:
+
+- `includeLayout=true`
+- `includeVisual=true`
+- `includeTypography=true`
+- `includeCodeReady=true`
+- `depth=2`
+
+### Step 4: Token ve component reuse özeti çıkar
+
+- `figma_get_variables`
+- `figma_search_components`
+- gerekiyorsa `figma_get_component_for_development`
+
+### Step 5: Code-Only Props Çıkar
+
+"Code only props" katmanı olan bileşenlerde, gizli property'leri spec data olarak çıkar:
+
+```js
+// figma_execute — Code-only props okuma
+const component = await figma.getNodeByIdAsync("<COMPONENT_ID>");
+const codeOnlyFrame = component.children.find(c => c.name === "Code only props");
+if (codeOnlyFrame) {
+  const props = codeOnlyFrame.children.map(c => ({
+    name: c.name,
+    type: c.type === "TEXT" ? "string" : "variant",
+    value: c.type === "TEXT" ? c.characters : null,
+    visible: c.visible
+  }));
+  return { codeOnlyProps: props };
+}
+```
+
+Handoff çıktısına ekle:
+```yaml
+## Code-Only Properties (Geliştirici İçin)
+| Property | Type | Default | Görünürlük |
+|----------|------|---------|-----------|
+| accessibilityLabel | string | "Button label" | Gizli |
+| as | enum (h1-h6) | h2 | Gizli |
+```
+
+### Step 6: Screenshot referansı ekle
+
+- `figma_capture_screenshot`
+
+### Step 7: Handoff dosyalarını üret
+
+1. `HANDOFF_TEMPLATE.md` içini doldur.
+2. `docs/handoff.manifest.schema.json` uyumlu `handoff.manifest.json` çıktısı oluştur.
+
+### Step 8: Platform Hedefi Belirle
+
+Handoff manifest'ine hedef platform(lar) eklenir:
+
+```json
+{
+  "targetPlatforms": ["ios", "android", "web"],
+  "platformDetails": {
+    "ios": { "framework": "SwiftUI", "minVersion": "16.0" },
+    "android": { "framework": "Compose", "minApiLevel": 24 },
+    "web": { "framework": "React", "styling": "Tailwind" }
+  }
+}
+```
+
+Platform bilgisi kullanıcıdan alınır veya proje yapısından çıkarılır.
+
+### Step 9: Self-healing sonucunu işle
+
+- İterasyon sayısını kaydet (`0-3`).
+- Açık kalan sapmaları `openIssues` alanına yaz.
+- Çözülemeyen fark varsa `manualReviewNeeded=true`.
+
+### Step 10: Executive Summary (PO/PM Modu)
+
+PO/PM persona algılandığında veya `--executive` flag ile teknik handoff'un yanında yönetici özeti eklenir:
+
+```markdown
+## Executive Summary — [Ekran Adı]
+
+### Genel Bakış
+- **Ekran:** Login Screen
+- **DS Uyum:** %92 (23/25 öğe)
+- **Tahmini İmplementasyon Süresi:** iOS: 4s, Android: 4s, Web: 3s
+- **Risk Seviyesi:** Düşük
+
+### Bileşen Dağılımı
+- DS instance: 18 (hazır)
+- Custom öğe: 2 (oluşturulması gerekli)
+- Token bağlı: 23/25
+
+### Platform Hazırlık Durumu
+| Platform | Token | Bileşen | Hazırlık |
+|---|---|---|---|
+| iOS | ✓ | %90 | Hazır |
+| Android | ✓ | %85 | Eksik: SegmentedControl |
+| Web | ✓ | %95 | Hazır |
+
+### Riskler ve Açık Noktalar
+1. Custom illustration asset'i henüz export edilmedi
+2. Animasyon spesifikasyonu eksik
+```
+
+## Handoff Prensipleri
+
+Her handoff paketi bu 4 prensibe uygun olmalıdır:
+
+1. **Varsayma, belirt** — Belirtilmeyen her şeyi geliştirici tahmin eder. Padding, radius, renk, davranış, hepsi açıkça yazılmalı.
+2. **Token kullan, değer değil** — `spacing-md` yaz, `16px` yazma. `color/primary` yaz, `#2563eb` yazma. Token ismi hem niyeti hem değeri taşır.
+3. **Tüm durumları göster** — Default, hover, active/pressed, disabled, loading, error, empty, focus. Gösterilmeyen durum "yok" demek değil, "bilinmiyor" demek.
+4. **Neden'i açıkla** — "Mobilde daraltılır" yerine "Mobilde daraltılır çünkü tek elle kullanım senaryosunda ekran alanı kısıtlı." Bağlam, geliştiricinin kenar durumlarında doğru karar vermesini sağlar.
+
+## Etkileşim Spesifikasyonları
+
+Step 5 (Code-Only Props) ile Step 6 (Screenshot) arasında üretilecek ek bölüm (Step 5.5):
+
+### Davranış Detayları
+
+| Öğe | Tıklama/Tap | Hover | Transition | Gesture |
+|-----|------------|-------|------------|---------|
+| CTA Buton | navigate("/dashboard") | scale(1.02), shadow-lg | 200ms ease-out | — |
+| Kart | navigate("/detail/:id") | border highlight | 150ms ease-in-out | swipe-left: sil |
+| Input | focus + keyboard | border-color change | 100ms | — |
+| Modal | — | — | enter: 300ms ease-out, exit: 200ms ease-in | swipe-down: kapat |
+
+### Animasyon Spesifikasyonları
+
+- **Giriş animasyonları:** fade-in + slide-up (stagger delay: 50ms per item)
+- **Çıkış animasyonları:** fade-out (150ms)
+- **Mikro etkileşimler:** buton press scale(0.97), toggle spring(damping: 15)
+- **Sayfa geçişleri:** push (iOS), shared-element (Android), fade (Web)
+
+## İçerik Spesifikasyonları
+
+Step 5 (Code-Only Props) çıktısına ek olarak:
+
+| Alan | Max Karakter | Truncation | Boş Durum | Yükleme Durumu |
+|------|-------------|-----------|-----------|---------------|
+| Sayfa başlığı | 60 | ellipsis | — | skeleton (200×24) |
+| Açıklama metni | 120 | 2 satır + "devamı" | "Henüz açıklama yok" | skeleton (full-width×16 ×2) |
+| CTA butonu | 24 | — | — | spinner |
+| Kullanıcı adı | 30 | ellipsis | "Anonim" | skeleton (120×16) |
+| Avatar | — | — | initials fallback | pulse circle |
+
+> **Copy kuralları** için bkz. [ux-copy-guidance](../ux-copy-guidance/SKILL.md) — hata mesajı formülü, boş durum kalıbı, CTA prensipleri
+
+## Uç Durumlar
+
+Step 8 (Self-healing) sonrasında değerlendirilecek:
+
+| Uç Durum | Tasarım Davranışı | Not |
+|----------|------------------|-----|
+| Min içerik (başlık 3 kelime) | Normal görünüm | Kart yüksekliği auto |
+| Max içerik (başlık 30 kelime) | Truncation: 2 satır + ellipsis | Tooltip ile tam metin |
+| Uluslararası metin (Almanca %30 uzun) | Truncation tetiklenir | i18n testinde en uzun locale kontrol |
+| RTL dil (Arapça) | Mirror layout | İkonlar ters, sayılar LTR kalır |
+| Yavaş bağlantı / offline | Skeleton → timeout mesajı (10sn) | "Bağlantı kurulamadı. Tekrar deneyin." |
+| Eksik veri (null avatar) | Initials fallback → generic ikon | İsim de yoksa "?" ikonu |
+| Eksik veri (isim yok) | "Anonim Kullanıcı" placeholder | Backend default ile uyumlu olmalı |
+
+## Erişilebilirlik Spesifikasyonları
+
+Handoff paketine a11y bilgisi eklenir. Detaylı denetim için bkz. [figma-a11y-audit](../figma-a11y-audit/SKILL.md).
+
+| Öğe | Fokus Sırası | ARIA Label/Role | Klavye Etkileşimi |
+|-----|-------------|----------------|-------------------|
+| Ana başlık | — (heading, fokuslanmaz) | role="heading" level=1 | — |
+| E-posta input | 1 | label="E-posta adresi" | Tab: giriş, Enter: submit |
+| Şifre input | 2 | label="Şifre" | Tab: giriş, Enter: submit |
+| Giriş butonu | 3 | role="button" label="Giriş yap" | Enter/Space: tetikle |
+| Google butonu | 4 | role="button" label="Google ile giriş" | Enter/Space: tetikle |
+
+**Ekran okuyucu duyuruları:**
+- Form submit sonrası: `aria-live="assertive"` — "Giriş başarılı" veya "Hatalı e-posta adresi"
+- Loading durumunda: `aria-busy="true"` — "Yükleniyor"
+- Modal açıldığında: fokus modal'a taşınır, `aria-modal="true"`
+
+## Marka Profili Entegrasyonu
+
+`.fmcp-brand-profile.json` varsa handoff paketine otomatik eklenir:
+- `voiceTone` → İçerik spesifikasyonlarında ton referansı
+- `copyRules` → CTA max karakter, kaçınılacak/tercih edilecek kelimeler
+- `i18n` → Uç durumlar bölümünde desteklenen diller ve en uzun locale
+
+## Rules
+
+- Hardcoded renk/font yerine mevcut token isimlerini yaz.
+- "Yeni component oluştur" kararı vermeden önce component araması yap.
+- Handoff dosyasında varsayımları açıkça "riskler" altında belirt.
+- Code Connect verisi yoksa alanı boş bırak; uydurma map yazma.
+- PO/PM persona'sı için executive summary'yi her zaman ekle.
+- Platform hedefini manifest'e her zaman yaz.
+
+## 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
+
+- Bridge'e yeni metadata araçları eklendiğinde handoff paketi zenginleştirilebilir
+- Yeni platform desteği (Flutter, .NET MAUI) eklenirse platformDetails şeması genişletilmeli
+- PO/PM geri bildirimine göre executive summary formatı güncellenmeli

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

@@ -0,0 +1,104 @@
+---
+name: apply-figma-design-system
+description: Mevcut Figma ekranını yayınlanmış design system bileşenleri ve token'larıyla çok bölümlü şekilde hizalar; yedek, envanter, bölüm bölüm swap/compose. "ekranı ds'ye bağla", "kütüphaneye geçir", "design system apply", "tasarım sistemi uygula", "bileşenleri hizala", "token'ları bağla" ifadeleriyle tetiklenir. F-MCP Bridge ve figma_execute gerektirir.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  personas:
+    - designer
+    - designops
+---
+
+# Apply Figma Design System (geniş yazma)
+
+## Overview
+
+Mevcut bir frame/page **published design system** kullanmalıdır; detached layer, yerel wrapper ve tek seferlik kompozisyonlar hedeflenir.
+
+**Tek dar bulgu** için **fix-figma-design-system-finding** kullan; bu skill çok bölüm ve koordineli reconcile içindir.
+
+## Giriş Modları
+
+Bu skill iki farklı modda çalışabilir:
+
+1. **review-then-apply** *(varsayılan)* — Tam audit → envanter → bölüm sınıflandırması → onay → uygulama. İlk kez DS hizalaması yapılıyorsa veya kapsamlı tarama istendiğinde kullanılır.
+2. **apply-known-scope** — Kullanıcı hedef frame'leri ve stratejiyi zaten biliyorsa (ör. önceki audit'ten), audit adımları atlanır ve doğrudan uygulama başlar. Giriş: `{ frames: [{ id: "72:293", strategy: "exact-swap" | "compose-from-primitives" }] }`.
+
+Mod, kullanıcı girdisinden otomatik çıkarılır: frame ID + strateji belirtilmişse `apply-known-scope`, aksi halde `review-then-apply`.
+
+## %80 Uyum Eşiği
+
+Bölüm sınıflandırması sonrası uyum oranı hesaplanır:
+```
+uyumOranı = (already-connected + exact-swap + compose-from-primitives) / toplamBölüm
+```
+- `uyumOranı >= 0.80`: Otomatik uygulama önerilir.
+- `uyumOranı < 0.80`: Uyarı gösterilir — "67% (16/24) otomatik düzeltilebilir. Minimum %80 önerilir. Devam edilsin mi?" Kullanıcı onay vermeden uygulama başlamaz.
+
+## Bölüm sınıflandırması
+
+Her bölüm tam olarak biri:
+
+- `already-connected` — Zaten kütüphane instance veya kullanıcıca kabul görmüş kompozisyon
+- `exact-swap` — Tek bir library component/variant ile doğrudan değiştirilebilir
+- `compose-from-primitives` — Tek composite yok; yayınlanmış primitive’lerle yeniden kurulur
+- `blocked` — Kütüphane yok, import başarısız veya kasıtlı bespoke
+
+## F-MCP araç eşlemesi
+
+| Niyet | F-MCP Bridge |
+|--------|----------------|
+| Özet / sayfa yapısı | `figma_get_file_data`, `figma_get_design_system_summary` |
+| Görsel | `figma_capture_screenshot` |
+| Yapı envanteri | `figma_get_file_data`, `figma_get_design_context`, `figma_execute` (instance → mainComponent keşfi) |
+| Aday bileşen | Önce aynı dosyadaki referans ekranlar; sonra `figma_search_components` |
+| Token | `figma_get_variables`, `figma_get_styles` |
+| Yazma | `figma_execute` |
+
+## F-MCP skill koordinasyonu
+
+| Önce | Sonra |
+|------|--------|
+| Kapsam belirsiz | **audit-figma-design-system** (veya eşdeğer iç audit) — tek bulgu çıkarsa **fix-figma-design-system-finding**’e geç |
+| Token kodda da senkron olmalı | **design-token-pipeline** |
+| Kod-Figma parity | **design-drift-detector**, **code-design-mapper** güncellemesi |
+| Koda geçiş | **ai-handoff-export** veya **implement-design** |
+| Repo kuralları | **design-system-rules** |
+
+Uçtan uca önerilen sıra özeti: **audit-figma-design-system** skill’indeki “Önerilen uçtan uca akış” bölümüne bak.
+
+## Core kural
+
+Birkaç DS butonu içerdi diye bölüm “bağlı” sayılmaz. Bu skill **çok bölüm** reconcile içindir.
+
+## Required Workflow (özet)
+
+1. **Plugin bağlantısını doğrula:** `figma_get_status()` — bağlantı yoksa devam etme.
+3. **Kapsam:** Gerekirse audit; tek bulguya düşerse fix skill’e yönlendir.
+3. **Durum yakala:** `figma_get_file_data` (gerekirse düşük `depth`) + `figma_capture_screenshot`; isteğe bağlı `figma_get_design_context` (Code Connect uyarısı varsa araç talimatına uy).
+4. **Yedek:** Hedef frame/page çoğalt, sağa `Backup - …` adıyla koy; mümkünse ayrı `figma_execute`, oluşan id’yi dön.
+5. **Envanter:** `figma_execute` ile section instance’ları, `mainComponent`, remote/local, iç içe published kullanımı topla (Edenspiekermann örnek pattern’i referans: instance listesi JSON ile kısa dönüş).
+6. **Harita:** Önce dosya içi kanıt ekranları, sonra gerekirse `figma_search_components`. Variant seçimini orijinal görsel/ipuçlarına göre yap; varsayılan variant’a sessizce düşme.
+7. **Strateji:** Bölüm başına `exact-swap` vs `compose-from-primitives` vs `blocked` karar ver.
+8. **Uygula:** **Bölüm bölüm**, tek script ile tüm ekranı yıkma; auto-layout olmayan üstlerde x/y ve boyutları açıkça koru; drift uyarısı ver.
+9. **Import hata:** Dur; alakasız edit yapıp “bağlandı” deme; key doğrula, tekrar dene; olmazsa `blocked` raporla.
+10. **Doğrula:** Her bölüm sonrası screenshot; sonda tam ekran.
+
+## Import / layout kuralları
+
+- `importComponentSetByKeyAsync` / `importComponentByKeyAsync` başarısız → dur, net blocker.
+- Non-auto-layout parent: pozisyon ve boyut koru; swap sonrası kayma riskini kullanıcıya yaz.
+
+## Kapanış özeti
+
+`Swapped` / `Composed` / `Already connected` / `Blocked` (neden) listeleri. Hepsi blocked ise açıkça söyle.
+
+## İlişkili skill
+
+- Okuma-only ön kontrol: **audit-figma-design-system**
+- Tek bulgu: **fix-figma-design-system-finding**
+
+## Evolution Triggers
+
+- Bridge'e yeni swap/compose araçları eklendiğinde reconcile stratejisi güncellenmeli
+- `figma_search_components` kapasitesi değişirse bileşen eşleme adımları uyarlanmalı
+- Yeni DS standartları (multi-brand, white-label) desteklenirse iş akışı genişletilmeli