UX Copy Guidance — Yazarlık ve Marka Sesi Rehberi

Overview

Bu skill, arayüz metinlerini (microcopy) tasarım prensipleri ve marka sesiyle uyumlu şekilde üretir veya değerlendirir. Figma text node'larına doğrudan uygulayabilir.

Okuma + Yazma — Onay ile Figma text node'larını güncelleyebilir.

Prerequisites

• F-MCP Bridge plugin bağlı olmalı (Figma entegrasyonu için)
• İsteğe bağlı: Proje kökünde .fmcp-brand-profile.json (marka kişiselleştirmesi)

F-MCP skill koordinasyonu

• Referans veren skill'ler:
  • ai-handoff-export → İçerik Spesifikasyonları bölümü bu skill'e yönlendirir
  • figma-screen-analyzer → Copy kalitesi değerlendirmesinde bu skill'in prensiplerini uygular
  • component-documentation → Bileşen label/placeholder copy'si bu skill'in kalıplarını kullanır
  • generate-figma-screen → Text node oluştururken bu skill'in kalıplarını kullanır
• Profil oluşturma: Bu skill profil yoksa otomatik oluşturma akışı başlatır

5 Temel Prensip

Her arayüz metni bu 5 prensibe uygun olmalıdır:

Kopya Kalıpları

CTA (Call to Action)

Formül: Fiille başla + spesifik ol + sonuca eşle

Kurallar:

• Max uzunluk: .fmcp-brand-profile.json → copyRules.maxCTALength (varsayılan: 24 karakter)
• Kaçınılacak kelimeler: .fmcp-brand-profile.json → copyRules.avoidWords
• Tercih edilecek kelimeler: .fmcp-brand-profile.json → copyRules.preferWords

Hata Mesajları

Formül: Ne oldu + Neden + Nasıl düzeltilir

"Ödeme reddedildi. Bankanız kartı onaylamadı. Farklı bir kart deneyin veya bankanızla iletişime geçin."
 ─────────────    ──────────────────────    ─────────────────────────────────────────────────────
  Ne oldu           Neden                    Nasıl düzeltilir

Ton: .fmcp-brand-profile.json → copyRules.errorTone

• empathetic-actionable (varsayılan): Empatik + çözüm odaklı
• technical: Doğrudan teknik bilgi
• minimal: Sadece gerekli bilgi

Boş Durumlar (Empty State)

Formül: Bu ne + Neden boş + Nasıl başlanır

"Henüz proje yok. İlk projenizi oluşturarak ekibinizle çalışmaya başlayın."
 ──────────────    ──────────────────────────────────────────────────────
  Bu ne + neden boş     Nasıl başlanır

Onay Diyalogları

Formül: Eylemi netleştir + sonuçları belirt + butonlara eylem fiili

Başlık: "3 dosya silinsin mi?"
Açıklama: "Bu işlem geri alınamaz. Silinen dosyalar çöp kutusuna taşınmaz."
Butonlar: [ Dosyaları sil ] [ Vazgeç ]
                ✓ Eylem fiili     ✓ Net
           YANLIŞ: [ Tamam ] [ İptal ]

Başarı Mesajları

Formül: Kısa kutla + sonraki adım (isteğe bağlı)

Yükleme Durumları

Formül: Ne yapılıyor + beklenti süresi (uzunsa)

Ses ve Ton Rehberi

Varsayılan Ton Matrisi

Marka Profili ile Kişiselleştirme

Proje kökünde .fmcp-brand-profile.json varsa:

1. voiceTone.personality → Ton kalibrasyonu:
   • ["samimi", "cesur"] → kısa, direkt, enerjik
   • ["profesyonel", "güvenilir"] → formel, ölçülü, sakin
   • ["playful", "genç"] → emoji uygun, günlük dil, cesur kısaltmalar
2. voiceTone.formality → Kelime seçimi:
   • formal: "İşleminiz başarıyla tamamlanmıştır."
   • semi-formal: "İşlem tamamlandı."
   • casual: "Tamam, bitti!"
3. voiceTone.humor → Humor seviyesi:
   • none: Asla espri veya şaka tonu
   • subtle: Hafif sıcaklık, ince humor ("Harika iş!")
   • playful: Emoji, şakacı ton ("Boom! Proje hazır 🚀")
4. voiceTone.examples → Gerçek örnekleri ton referansı olarak kullan

Profil Yoksa: Otomatik Oluşturma Akışı

.fmcp-brand-profile.json dosyası bulunamadığında, kullanıcıya 3 soru sor:

Soru 1: "Markanız bir insan olsa nasıl konuşurdu? 3 sıfatla tanımlayın."

• Örnek: samimi, cesur, profesyonel

Soru 2: "Formallik seviyesi?"

• Formal (kurumsal, mesafeli)
• Yarı-formal (profesyonel ama sıcak)
• Casual (arkadaşça, günlük)

Soru 3: "Bir başarı mesajı örneği verin (uygulamanızda kullanılmış veya hayal ettiğiniz)."

• Örnek: "Harika! Profilin güncellendi."

Cevaplardan minimal .fmcp-brand-profile.json oluştur ve proje köküne kaydet.

Çok Dilli / i18n Kuralları

Çoklu dil desteği olan projelerde copy üretirken:

Metin Uzunluğu Farkları

Kural: En uzun dili (.fmcp-brand-profile.json → i18n.longestLocale) baz alarak tasarımda truncation planla.

RTL (Sağdan Sola) Desteği

• Arapça, İbranice, Farsça: layout tamamen ayna
• İkonlar: yön belirten ikonlar (ok, geri/ileri) ters çevrilmeli
• Sayılar: RTL dillerde de soldan sağa yazılır (istisna)

Kültür-Nötr Dil

• Metafor ve deyimlerden kaçın ("taşı gediğine koymak" → "düzeltmek")
• Kültüre bağlı emoji dikkatli kullan (🙏 bazı kültürlerde "teşekkür", bazılarında "dua")
• Tarih formatı: yerelleştir (TR: 07.04.2026, US: 04/07/2026, ISO: 2026-04-07)
• Para birimi: sembol + format yerelleştir (₺1.234,56 vs $1,234.56)

Figma Entegrasyonu

Tekli Text Node Güncelleme

// figma_execute — Tek text node'a copy uygula
const node = await figma.getNodeByIdAsync("<TEXT_NODE_ID>");
await figma.loadFontAsync(node.fontName);
node.characters = "Yeni copy metni";
return { updated: node.id, text: node.characters };

Toplu Copy İnceleme ve Güncelleme

1. Ekrandaki tüm text node'ları listele:

const root = await figma.getNodeByIdAsync("<SCREEN_NODE_ID>");
const textNodes = root.findAll(n => n.type === "TEXT");
const copyList = textNodes.map(n => ({
  id: n.id,
  name: n.name,
  current: n.characters,
  fontSize: n.fontSize,
  parent: n.parent?.name || "—"
}));
return { totalTextNodes: copyList.length, nodes: copyList.slice(0, 50) };

2. Kullanıcıya tablo olarak sun:

3. Kullanıcı onayı al — onaylanan node'ları toplu güncelle:

const updates = [
  { id: "<ID_1>", text: "Hesap oluştur" },
  { id: "<ID_2>", text: "E-posta adresi geçersiz. @ işareti olmalı." }
];

for (const u of updates) {
  const node = await figma.getNodeByIdAsync(u.id);
  await figma.loadFontAsync(node.fontName);
  node.characters = u.text;
}

return { updatedCount: updates.length };

ONAY KURALI: Text node güncellemeleri kullanıcı onayı olmadan yapılmaz. Önce tablo sun, onay al, sonra uygula.

Required Workflow

Step 1: Plugin Bağlantısını Doğrula

figma_get_status()

Step 2: Marka Profili Kontrol

Proje kökünde .fmcp-brand-profile.json ara.

• Varsa: Oku, voiceTone ve copyRules alanlarını not al.
• Yoksa: Kullanıcıya "Marka profili bulunamadı. Oluşturmak ister misiniz?" sor.
  • Evet → 3 soru akışı → profil oluştur
  • Hayır → varsayılan ton matrisiyle devam et

Step 3: Hedef Belirle

Kullanıcının isteğine göre:

A) Tek copy üretimi: CTA, hata mesajı, boş durum vb. → ilgili kalıbı uygula, 3 alternatif sun.

B) Ekran copy incelemesi: Figma ekranındaki tüm text node'ları tara → mevcut copy'yi değerlendir → öneriler sun.

C) Copy spec üretimi: Bir bileşen veya ekran için tüm copy kurallarını dokümante et (karakter limitleri, truncation, durum metinleri).

Step 4: Copy Üret / Değerlendir

• 5 temel prensibe uygunluk kontrolü
• Marka profili varsa ton kalibrasyonu
• Her copy için 2-3 alternatif sun (kullanıcı seçsin)
• i18n gerekiyorsa en uzun dili baz al

Step 5: Figma'ya Uygula (İsteğe Bağlı)

Kullanıcı isterse text node'ları güncelle (onay akışı ile).

Step 6: Copy Spec Çıktısı

İstenirse yapılandırılmış copy spec raporu üret:

## Copy Spec — [Ekran Adı]

### CTA'lar
| Buton | Copy | Max Karakter | Alternatifler |
|-------|------|-------------|---------------|
| Ana CTA | "Hesap oluştur" | 24 | "Kaydol", "Ücretsiz başla" |

### Hata Mesajları
| Alan | Mesaj | Ton |
|------|-------|-----|
| E-posta | "Geçerli bir e-posta girin" | empathetic-actionable |

### Boş Durumlar
| Ekran | Mesaj |
|-------|-------|
| Proje listesi | "Henüz proje yok. İlk projenizi oluşturun." |

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:

Son adım: Üretilen tüm Türkçe metinleri karakter kontrolünden geçir.

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.

Evolution Triggers

• Yeni copy kalıbı ihtiyacı (notification, tooltip, placeholder) eklenebilir
• Marka profili şeması genişletilirse alan okuma güncellenmeli
• AI ile otomatik copy kalite skoru (5 prensibe uyum puanı) eklenebilir
• Çoklu dil desteği genişletilirse dil bazlı kalıp varyantları eklenebilir