Component Documentation

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: figmagetcomponentfordevelopment + figmagetdesigncontext (depth=3, full) + figmaget_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.

1. Bileşen description güncelleme: Bileşenin description ve link alanlarını güncelle (bkz. "Bileşen Description Kuralları").
2. KULLANICIYA FORMAT SEÇ: Aşağıdaki 2 seçeneği içerik özetiyle sun. Onay olmadan frame OLUŞTURMA.
3. Seçime göre frame oluştur. Eski aynı isimli frame varsa sil.
4. Height bug fix: primaryAxisSizingMode FIXED→AUTO toggle.
5. 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:

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ı

Hata Yonetimi

1. Plugin baglanti hatasi: figma_get_status() ile kontrol et. Bagli degilse kullaniciya Figma'da F-MCP ATezer Bridge plugin'ini acmasini soyler.
2. Tool timeout: Bir kez tekrar dene. Basarisizsa kapsami daralt (daha az node, daha dusuk depth).
3. Bos yanit: Hedef node veya sayfa var mi kontrol et. Kullaniciya net bilgi ver.
4. Rate limit (REST tool'lar): figma_get_rest_token_status() ile kontrol et. Limit dolduysa bekle.
5. Beklenmeyen hata: Hata mesajini kullaniciya goster, alternatif yaklasim oner.

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: atezer
• Source: atezer/FMCP
• License: MIT
• Homepage: https://www.npmjs.com/package/@atezer/figma-mcp-bridge

Install and usage instructions live in the source repository linked above.