@atezer/figma-mcp-bridge 1.7.24 → 1.7.25
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +37 -0
- package/.cursor-plugin/plugin.json +21 -0
- package/README.md +4 -3
- package/agents/ds-auditor.md +29 -0
- package/agents/screen-builder.md +29 -0
- package/agents/token-syncer.md +26 -0
- package/assets/logo.png +0 -0
- package/commands/add-library.md +122 -0
- package/commands/ds-add.md +255 -0
- package/commands/ds-sync.md +314 -0
- package/commands/implement.md +43 -0
- package/commands/install-library.md +73 -0
- package/commands/setup.md +26 -0
- package/commands/test.md +39 -0
- package/commands/update.md +25 -0
- package/dist/core/response-guard.d.ts +1 -1
- package/dist/core/response-guard.js +1 -1
- package/dist/core/version.d.ts +1 -1
- package/dist/core/version.js +1 -1
- package/hooks/hooks.json +26 -0
- package/package.json +8 -1
- package/skills/BRAND_PROFILE_SCHEMA.md +113 -0
- package/skills/SKILL_INDEX.md +194 -0
- package/skills/TOOL_MAPPING.md +111 -0
- package/skills/ai-handoff-export/SKILL.md +254 -0
- package/skills/apply-figma-design-system/SKILL.md +104 -0
- package/skills/audit-figma-design-system/SKILL.md +278 -0
- package/skills/code-design-mapper/SKILL.md +370 -0
- package/skills/component-documentation/SKILL.md +190 -0
- package/skills/design-drift-detector/SKILL.md +407 -0
- package/skills/design-system-rules/SKILL.md +407 -0
- package/skills/design-token-pipeline/SKILL.md +619 -0
- package/skills/ds-impact-analysis/SKILL.md +266 -0
- package/skills/figjam-diagram-builder/SKILL.md +172 -0
- package/skills/figma-a11y-audit/SKILL.md +587 -0
- package/skills/figma-canvas-ops/SKILL.md +325 -0
- package/skills/figma-screen-analyzer/SKILL.md +235 -0
- package/skills/fix-figma-design-system-finding/SKILL.md +117 -0
- package/skills/fmcp-project-rules/SKILL.md +93 -0
- package/skills/generate-figma-library/SKILL.md +598 -0
- package/skills/generate-figma-screen/SKILL.md +689 -0
- package/skills/implement-design/SKILL.md +473 -0
- package/skills/ux-copy-guidance/SKILL.md +373 -0
- package/skills/visual-qa-compare/SKILL.md +166 -0
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: apply-figma-design-system
|
|
3
|
+
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.
|
|
4
|
+
metadata:
|
|
5
|
+
mcp-server: user-figma-mcp-bridge
|
|
6
|
+
personas:
|
|
7
|
+
- designer
|
|
8
|
+
- designops
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Apply Figma Design System (geniş yazma)
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
Mevcut bir frame/page **published design system** kullanmalıdır; detached layer, yerel wrapper ve tek seferlik kompozisyonlar hedeflenir.
|
|
16
|
+
|
|
17
|
+
**Tek dar bulgu** için **fix-figma-design-system-finding** kullan; bu skill çok bölüm ve koordineli reconcile içindir.
|
|
18
|
+
|
|
19
|
+
## Giriş Modları
|
|
20
|
+
|
|
21
|
+
Bu skill iki farklı modda çalışabilir:
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
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" }] }`.
|
|
25
|
+
|
|
26
|
+
Mod, kullanıcı girdisinden otomatik çıkarılır: frame ID + strateji belirtilmişse `apply-known-scope`, aksi halde `review-then-apply`.
|
|
27
|
+
|
|
28
|
+
## %80 Uyum Eşiği
|
|
29
|
+
|
|
30
|
+
Bölüm sınıflandırması sonrası uyum oranı hesaplanır:
|
|
31
|
+
```
|
|
32
|
+
uyumOranı = (already-connected + exact-swap + compose-from-primitives) / toplamBölüm
|
|
33
|
+
```
|
|
34
|
+
- `uyumOranı >= 0.80`: Otomatik uygulama önerilir.
|
|
35
|
+
- `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.
|
|
36
|
+
|
|
37
|
+
## Bölüm sınıflandırması
|
|
38
|
+
|
|
39
|
+
Her bölüm tam olarak biri:
|
|
40
|
+
|
|
41
|
+
- `already-connected` — Zaten kütüphane instance veya kullanıcıca kabul görmüş kompozisyon
|
|
42
|
+
- `exact-swap` — Tek bir library component/variant ile doğrudan değiştirilebilir
|
|
43
|
+
- `compose-from-primitives` — Tek composite yok; yayınlanmış primitive’lerle yeniden kurulur
|
|
44
|
+
- `blocked` — Kütüphane yok, import başarısız veya kasıtlı bespoke
|
|
45
|
+
|
|
46
|
+
## F-MCP araç eşlemesi
|
|
47
|
+
|
|
48
|
+
| Niyet | F-MCP Bridge |
|
|
49
|
+
|--------|----------------|
|
|
50
|
+
| Özet / sayfa yapısı | `figma_get_file_data`, `figma_get_design_system_summary` |
|
|
51
|
+
| Görsel | `figma_capture_screenshot` |
|
|
52
|
+
| Yapı envanteri | `figma_get_file_data`, `figma_get_design_context`, `figma_execute` (instance → mainComponent keşfi) |
|
|
53
|
+
| Aday bileşen | Önce aynı dosyadaki referans ekranlar; sonra `figma_search_components` |
|
|
54
|
+
| Token | `figma_get_variables`, `figma_get_styles` |
|
|
55
|
+
| Yazma | `figma_execute` |
|
|
56
|
+
|
|
57
|
+
## F-MCP skill koordinasyonu
|
|
58
|
+
|
|
59
|
+
| Önce | Sonra |
|
|
60
|
+
|------|--------|
|
|
61
|
+
| Kapsam belirsiz | **audit-figma-design-system** (veya eşdeğer iç audit) — tek bulgu çıkarsa **fix-figma-design-system-finding**’e geç |
|
|
62
|
+
| Token kodda da senkron olmalı | **design-token-pipeline** |
|
|
63
|
+
| Kod-Figma parity | **design-drift-detector**, **code-design-mapper** güncellemesi |
|
|
64
|
+
| Koda geçiş | **ai-handoff-export** veya **implement-design** |
|
|
65
|
+
| Repo kuralları | **design-system-rules** |
|
|
66
|
+
|
|
67
|
+
Uçtan uca önerilen sıra özeti: **audit-figma-design-system** skill’indeki “Önerilen uçtan uca akış” bölümüne bak.
|
|
68
|
+
|
|
69
|
+
## Core kural
|
|
70
|
+
|
|
71
|
+
Birkaç DS butonu içerdi diye bölüm “bağlı” sayılmaz. Bu skill **çok bölüm** reconcile içindir.
|
|
72
|
+
|
|
73
|
+
## Required Workflow (özet)
|
|
74
|
+
|
|
75
|
+
1. **Plugin bağlantısını doğrula:** `figma_get_status()` — bağlantı yoksa devam etme.
|
|
76
|
+
3. **Kapsam:** Gerekirse audit; tek bulguya düşerse fix skill’e yönlendir.
|
|
77
|
+
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).
|
|
78
|
+
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.
|
|
79
|
+
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üş).
|
|
80
|
+
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.
|
|
81
|
+
7. **Strateji:** Bölüm başına `exact-swap` vs `compose-from-primitives` vs `blocked` karar ver.
|
|
82
|
+
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.
|
|
83
|
+
9. **Import hata:** Dur; alakasız edit yapıp “bağlandı” deme; key doğrula, tekrar dene; olmazsa `blocked` raporla.
|
|
84
|
+
10. **Doğrula:** Her bölüm sonrası screenshot; sonda tam ekran.
|
|
85
|
+
|
|
86
|
+
## Import / layout kuralları
|
|
87
|
+
|
|
88
|
+
- `importComponentSetByKeyAsync` / `importComponentByKeyAsync` başarısız → dur, net blocker.
|
|
89
|
+
- Non-auto-layout parent: pozisyon ve boyut koru; swap sonrası kayma riskini kullanıcıya yaz.
|
|
90
|
+
|
|
91
|
+
## Kapanış özeti
|
|
92
|
+
|
|
93
|
+
`Swapped` / `Composed` / `Already connected` / `Blocked` (neden) listeleri. Hepsi blocked ise açıkça söyle.
|
|
94
|
+
|
|
95
|
+
## İlişkili skill
|
|
96
|
+
|
|
97
|
+
- Okuma-only ön kontrol: **audit-figma-design-system**
|
|
98
|
+
- Tek bulgu: **fix-figma-design-system-finding**
|
|
99
|
+
|
|
100
|
+
## Evolution Triggers
|
|
101
|
+
|
|
102
|
+
- Bridge'e yeni swap/compose araçları eklendiğinde reconcile stratejisi güncellenmeli
|
|
103
|
+
- `figma_search_components` kapasitesi değişirse bileşen eşleme adımları uyarlanmalı
|
|
104
|
+
- Yeni DS standartları (multi-brand, white-label) desteklenirse iş akışı genişletilmeli
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: audit-figma-design-system
|
|
3
|
+
description: Figma ekran veya bileşenini design system entegrasyonu açısından okuma-only denetler; eksik kütüphane instance'ları, yerel override'lar ve bağlanmamış token'ları raporlar. "figma ds audit", "design system audit", "kütüphane kullanımı kontrol", "token bağlı mı", "DS sağlık kontrolü", "ne kadar DS uyumlu", "tasarım durumu raporu", "ekran kalitesi" ifadeleriyle tetiklenir. F-MCP Bridge plugin bağlantısı gerektirir.
|
|
4
|
+
metadata:
|
|
5
|
+
mcp-server: user-figma-mcp-bridge
|
|
6
|
+
personas:
|
|
7
|
+
- designer
|
|
8
|
+
- designops
|
|
9
|
+
- po
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Audit Figma Design System (tuval içi)
|
|
13
|
+
|
|
14
|
+
## Overview
|
|
15
|
+
|
|
16
|
+
Bu skill **yalnızca okur**; Figma node'unun yayınlanmış design system ile ne kadar entegre olduğunu yapısal kanıta dayanarak denetler. Görsel tatmin değil, **instance / tekrar / ham değer / token bağlama** odaklıdır.
|
|
17
|
+
|
|
18
|
+
Yazma gerekiyorsa aşağıdaki skill’lerden birine yönlendir.
|
|
19
|
+
|
|
20
|
+
## F-MCP araç eşlemesi (resmi Figma MCP isimleri yerine)
|
|
21
|
+
|
|
22
|
+
| Niyet | F-MCP Bridge |
|
|
23
|
+
|--------|----------------|
|
|
24
|
+
| Design context | `figma_get_design_context` |
|
|
25
|
+
| Görsel doğrulama | `figma_capture_screenshot` |
|
|
26
|
+
| Variable / bağlılık | `figma_get_variables` (verbosity=`full`), gerekiyorsa `figma_get_styles` |
|
|
27
|
+
| Yapı / iç içe instance haritası | `figma_get_file_data` (düşük `depth`), hedef node için `figma_get_component` veya `figma_get_design_context`; büyük tahta için `figma_get_file_data` (timeout riski — dikkat). **Not:** Bridge’te ayrı bir “yalnızca metadata” MCP aracı yok; yapı bu üç araçla alınır. |
|
|
28
|
+
| Kod/dev spec ipucu | `figma_get_design_context` (`includeCodeReady=true`); uygunsa `figma_get_component_for_development` |
|
|
29
|
+
| Kütüphanede aday bileşen | `figma_search_components`, özet için `figma_get_design_system_summary` |
|
|
30
|
+
|
|
31
|
+
## F-MCP skill koordinasyonu
|
|
32
|
+
|
|
33
|
+
| Bulgu sonrası | Ne zaman |
|
|
34
|
+
|---------------|----------|
|
|
35
|
+
| **fix-figma-design-system-finding** | Tek net bulgu, tek node veya dar küme |
|
|
36
|
+
| **apply-figma-design-system** | Çoklu bulgu, ekran geneli veya bölüm bölüm reconcile |
|
|
37
|
+
| **design-token-pipeline** | Rapor “token export / kod tarafı senkron” gerektiriyorsa |
|
|
38
|
+
| **design-drift-detector** | Aynı ekranın **kod** ile parity’si de soruluyorsa (Figma audit’ten sonra) |
|
|
39
|
+
| **code-design-mapper** | Eşleştirilecek bileşen aileleri netleştikten sonra mapping güncellemesi |
|
|
40
|
+
| **figma-screen-analyzer** | PO/PM/SEM'e yönelik teknik olmayan ekran analizi ve DS uyum raporu |
|
|
41
|
+
| **ds-impact-analysis** | Bir token/bileşen değişikliğinin etki yarıçapını ölçmek istiyorsan |
|
|
42
|
+
| **ai-handoff-export** / **implement-design** | Audit “Pass” veya düzeltme sonrası koda geçiş |
|
|
43
|
+
|
|
44
|
+
### Önerilen uçtan uca akış (özet)
|
|
45
|
+
|
|
46
|
+
1. **audit-figma-design-system** (tuval DS uyumu)
|
|
47
|
+
2. **fix-figma-design-system-finding** (tek bulgu) *veya* **apply-figma-design-system** (çok bölüm)
|
|
48
|
+
3. **design-token-pipeline** (kod token dosyaları)
|
|
49
|
+
4. İsteğe bağlı **code-design-mapper**
|
|
50
|
+
5. **ai-handoff-export** → **implement-design**
|
|
51
|
+
6. **design-drift-detector** (kod–Figma parity)
|
|
52
|
+
7. Gerekirse **design-system-rules** ile repo kurallarını güncelle
|
|
53
|
+
|
|
54
|
+
**FigJam** ve bu zincir zorunlu sıralı değildir.
|
|
55
|
+
|
|
56
|
+
### Zincir performansı (tek oturum)
|
|
57
|
+
|
|
58
|
+
- Aynı zincirde **tekrarlı** `figma_get_variables(verbosity="full")` ve `figma_get_design_context` çağrılarını azalt: önceki adımın çıktısı hâlâ geçerliyse yeniden çağırma; mümkünse `verbosity="summary"` ile başla, orta detay için `"standard"`, tam detay için `"full"` kullan.
|
|
59
|
+
- `figma_search_components`: varsayılan **`currentPageOnly=true`**; `false` yalnızca gerektiğinde (büyük dosyada timeout riski).
|
|
60
|
+
|
|
61
|
+
## Çıktı Formatı
|
|
62
|
+
|
|
63
|
+
- Kullanıcı `--json` veya JSON isterse: şema altındaki JSON’u **markdown fence’siz**, ek metin yok.
|
|
64
|
+
- Sohbet ortamı veya `--markdown`: insan okunur markdown rapor.
|
|
65
|
+
- **Ortam bazlı otomatik tespit:** CI ortamı algılandığında (`CI=true`, `GITHUB_ACTIONS`, `GITLAB_CI` vb. ortam değişkenleri) varsayılan format **JSON** olarak ayarlanır. Etkileşimli sohbet ortamında varsayılan **markdown**’dır. Kullanıcı her iki durumda da `--json` veya `--markdown` flag’i ile tercihi geçersiz kılabilir.
|
|
66
|
+
- Belirsizse: markdown varsayılan.
|
|
67
|
+
|
|
68
|
+
## Required Workflow
|
|
69
|
+
|
|
70
|
+
1. **Girdi:** Figma URL veya `fileKey` + `nodeId`. `node-id=72-293` → `72:293` normalize et.
|
|
71
|
+
2. **Bağlantı:** `figma_get_status()`.
|
|
72
|
+
3. **Kanıt:** Hedef node için `figma_get_design_context`; `figma_capture_screenshot`; `figma_get_variables`. Büyük/hacimli yapıda `figma_get_file_data` (düşük `depth`) veya aynı node üzerinden `figma_get_component` / `figma_get_design_context`. Özel primitive için `figma_search_components`.
|
|
73
|
+
|
|
74
|
+
> **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.
|
|
75
|
+
|
|
76
|
+
> **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.
|
|
77
|
+
4. **İnceleme:** Yerel frame ile yeniden icat edilmiş primitive, tekrarlayan kardeş yapılar, tokenize eşlerin yanında ham hex/spacing/typography, navigasyon gibi yüksek etkili custom yapılar, variant sapması.
|
|
78
|
+
5. **Öneri:** Yalnızca `figma_search_components` ile **inandırıcı** aday bulunduğunda değiştirme öner; zayıf eşleşmede aday yazma.
|
|
79
|
+
6. **Çıktı:** Seçilen formatta rapor; ardından yukarıdaki koordinasyon tablosuna göre sonraki skill’i öner.
|
|
80
|
+
|
|
81
|
+
## Nielsen 10 Sezgisel Değerlendirme (İsteğe Bağlı)
|
|
82
|
+
|
|
83
|
+
`--heuristic` flag'i ile aktif edilir. DS denetiminin yanı sıra Jakob Nielsen'in 10 kullanılabilirlik sezgisel ilkesini DS bağlamında değerlendirir:
|
|
84
|
+
|
|
85
|
+
| # | İlke | DS Bağlamında Değerlendirme |
|
|
86
|
+
|---|------|-----------------------------|
|
|
87
|
+
| 1 | Sistem durumu görünürlüğü | Loading/progress state bileşenleri mevcut mu? |
|
|
88
|
+
| 2 | Sistem-gerçek dünya uyumu | Token isimlendirme kullanıcı diline uygun mu? (ör. `danger` vs `color-red-500`) |
|
|
89
|
+
| 3 | Kullanıcı kontrolü ve özgürlüğü | Undo/geri alma/iptal bileşenleri var mı? (dismiss, close, cancel) |
|
|
90
|
+
| 4 | Tutarlılık ve standartlar | DS bileşenleri platform konvansiyonlarına uyuyor mu? |
|
|
91
|
+
| 5 | Hata önleme | Validation, disabled state, form kısıtlama bileşenleri mevcut mu? |
|
|
92
|
+
| 6 | Tanıma > hatırlama | Bileşen isimleri açıklayıcı mı? Description'lar yeterli mi? |
|
|
93
|
+
| 7 | Kullanım esnekliği | Variant çeşitliliği farklı kullanım senaryolarını kapsıyor mu? |
|
|
94
|
+
| 8 | Estetik ve minimalist tasarım | Token sayısı gereksiz yere şişkin mi? Kullanılmayan variant var mı? |
|
|
95
|
+
| 9 | Hata tanıma ve kurtarma | Error state, empty state, fallback bileşenleri var mı? |
|
|
96
|
+
| 10 | Yardım ve dokümantasyon | Bileşen description'ları, kullanım notları yeterli mi? |
|
|
97
|
+
|
|
98
|
+
**Çıktı:** Rapora `heuristicEvaluation` bölümü eklenir (JSON veya markdown formatına göre). Her ilke için `pass` / `partial` / `fail` + açıklama.
|
|
99
|
+
|
|
100
|
+
## DS Eksiksizlik Çerçevesi
|
|
101
|
+
|
|
102
|
+
Audit sırasında yalnızca instance/token sayısı değil, DS'nin **yapısal eksiksizliği** de değerlendirilir.
|
|
103
|
+
|
|
104
|
+
### Token Kategorileri Kontrolü
|
|
105
|
+
|
|
106
|
+
Sağlıklı bir DS'de aşağıdaki token kategorilerinin tamamı bulunmalıdır:
|
|
107
|
+
|
|
108
|
+
| Kategori | Alt Kategoriler | Min Beklenen |
|
|
109
|
+
|----------|----------------|-------------|
|
|
110
|
+
| **Renkler** | Brand (primary, secondary, accent), Semantic (success, warning, error, info), Neutral (gray scale) | 15+ token |
|
|
111
|
+
| **Tipografi** | Scale (6+ kademe), Weights (regular, medium, semi-bold, bold), Line-heights | 10+ token |
|
|
112
|
+
| **Spacing** | Scale (4/8/12/16/24/32/48/64 vb.) | 6+ token |
|
|
113
|
+
| **Border** | Radius kademeleri (sm, md, lg, full), Genişlik (1, 2) | 4+ token |
|
|
114
|
+
| **Shadow** | Elevation seviyeleri (sm, md, lg, xl) | 3+ token |
|
|
115
|
+
| **Motion** | Duration (fast: 150ms, normal: 250ms, slow: 400ms), Easing (ease-in-out, spring) | 4+ token |
|
|
116
|
+
|
|
117
|
+
> **Sık eksik:** Motion token'ları — çoğu DS'de duration ve easing tanımlı değil. Audit raporunda bu eksiklik ayrıca belirtilmeli.
|
|
118
|
+
|
|
119
|
+
### Bileşen Eksiksizlik Kontrolü
|
|
120
|
+
|
|
121
|
+
Bir bileşenin "eksiksiz" sayılması için:
|
|
122
|
+
|
|
123
|
+
| Kriter | Açıklama | Kontrol Yöntemi |
|
|
124
|
+
|--------|----------|-----------------|
|
|
125
|
+
| **Variant'lar** | Primary, secondary, ghost/outline, destructive vb. | Component set'te variant prop sayısı |
|
|
126
|
+
| **Durumlar** | Default, hover, active, disabled, loading, error, focus | En az 4 durum olmalı |
|
|
127
|
+
| **Boyutlar** | sm, md, lg (en az 2) | Size prop veya ayrı variant |
|
|
128
|
+
| **Davranış spec'i** | Transition, animasyon, etkileşim notları | Description veya code-only props |
|
|
129
|
+
| **A11y spec'i** | Min touch target, fokus göstergesi, label | Description veya annotation |
|
|
130
|
+
|
|
131
|
+
> **Mevcut audit'ten farkı:** Mevcut audit instance/token sayar; bu çerçeve bileşenin **iç kalitesini** değerlendirir.
|
|
132
|
+
|
|
133
|
+
### Pattern Katmanı Kontrolü
|
|
134
|
+
|
|
135
|
+
Bileşen üstü pattern'ların varlığı (yoksa "DS olgunluk eksikliği" olarak raporla):
|
|
136
|
+
|
|
137
|
+
| Pattern | Bileşenler | Kontrol |
|
|
138
|
+
|---------|-----------|---------|
|
|
139
|
+
| **Forms** | Input grubu + validation görseli + submit akışı | Form-like frame'lerde input+button+error text birlikte mi? |
|
|
140
|
+
| **Navigation** | Sidebar, tabs, breadcrumb, bottom nav | Nav pattern'ı yayınlanmış bileşen mi yoksa ad-hoc frame mi? |
|
|
141
|
+
| **Data Display** | Tablo, kart listesi, liste | Tekrarlayan veri gösteriminde DS bileşeni mi kullanılıyor? |
|
|
142
|
+
| **Feedback** | Toast, modal, inline mesaj, snackbar | Geri bildirim mekanizmaları DS'de tanımlı mı? |
|
|
143
|
+
|
|
144
|
+
### DS Prensipleri
|
|
145
|
+
|
|
146
|
+
Audit raporunun sonuna bu prensipler bağlam olarak eklenir:
|
|
147
|
+
|
|
148
|
+
1. **Tutarlılık > Yaratıcılık** — DS, ekiplerin tekerleği yeniden icat etmemesi için var
|
|
149
|
+
2. **Kısıtlamalar içinde esneklik** — Bileşenler composable olmalı, rigid değil
|
|
150
|
+
3. **Belgelenmemiş = yok** — Dökümante edilmeyen bileşen/token kullanılmayacaktır → bkz. [component-documentation](../component-documentation/SKILL.md)
|
|
151
|
+
4. **Versiyonla ve migrate et** — Breaking change'lerde migration path sun → bkz. [ds-impact-analysis](../ds-impact-analysis/SKILL.md)
|
|
152
|
+
|
|
153
|
+
### Audit JSON Şemasına Ek Alan
|
|
154
|
+
|
|
155
|
+
`--json` çıktısına `dsCompleteness` objesi eklenir:
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"findings": [...],
|
|
160
|
+
"dsCompleteness": {
|
|
161
|
+
"tokenCategories": {
|
|
162
|
+
"colors": { "count": 24, "status": "complete" },
|
|
163
|
+
"typography": { "count": 12, "status": "complete" },
|
|
164
|
+
"spacing": { "count": 8, "status": "complete" },
|
|
165
|
+
"border": { "count": 5, "status": "complete" },
|
|
166
|
+
"shadow": { "count": 4, "status": "complete" },
|
|
167
|
+
"motion": { "count": 0, "status": "missing" }
|
|
168
|
+
},
|
|
169
|
+
"componentStates": {
|
|
170
|
+
"averageStatesPerComponent": 3.2,
|
|
171
|
+
"componentsWithAllStates": 5,
|
|
172
|
+
"componentsWithMissingStates": 8,
|
|
173
|
+
"missingStateDetails": [
|
|
174
|
+
{ "component": "Button", "missing": ["loading", "focus"] },
|
|
175
|
+
{ "component": "Input", "missing": ["error", "loading"] }
|
|
176
|
+
]
|
|
177
|
+
},
|
|
178
|
+
"patternCoverage": {
|
|
179
|
+
"forms": true,
|
|
180
|
+
"navigation": true,
|
|
181
|
+
"dataDisplay": false,
|
|
182
|
+
"feedback": false
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Ne işaretlenir / ne işaretlenmez
|
|
189
|
+
|
|
190
|
+
**İşaretle:** Ad-hoc frame ile yapılmış button/card/alert/chip vb.; tekrarlayan kardeş modüller; somut ham değer + tokenize komşular; global pattern’lerin custom olması; nominal component içi variant sapması.
|
|
191
|
+
|
|
192
|
+
**İşaretleme:** Saf estetik; copy; makul ölçüde ekrana özgü layout; zaten instance + token ile doğru olan tek seferlik kompozisyonlar; belgesiz varsayımlar.
|
|
193
|
+
|
|
194
|
+
## Kanıt standardı
|
|
195
|
+
|
|
196
|
+
Her bulgu için: (1) Figma yapısında somut ne gösteriyor? (2) Bakım, tutarlılık, tema veya ölçeklenebilirlik için neden önemli?
|
|
197
|
+
|
|
198
|
+
## JSON çıktı şeması ( `--json` )
|
|
199
|
+
|
|
200
|
+
Tek JSON obje; markdown veya ek prose yok:
|
|
201
|
+
|
|
202
|
+
```json
|
|
203
|
+
{
|
|
204
|
+
"findings": [
|
|
205
|
+
{
|
|
206
|
+
"title": "<= 80 karakter, emir kipi>",
|
|
207
|
+
"body": "Markdown açıklama",
|
|
208
|
+
"confidence_score": 0.0,
|
|
209
|
+
"priority": 0,
|
|
210
|
+
"code_location": {
|
|
211
|
+
"absolute_file_path": "/figma/<fileKey>/nodes/<nodeId>",
|
|
212
|
+
"line_range": { "start": 1, "end": 1 }
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
],
|
|
216
|
+
"overall_correctness": "ds compliant" | "ds non-compliant",
|
|
217
|
+
"overall_explanation": "1-3 cümle özet",
|
|
218
|
+
"overall_confidence_score": 0.0
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
- En az bir bulgu varsa `overall_correctness`: `"ds non-compliant"`.
|
|
223
|
+
- Bulgu yoksa `"ds compliant"`.
|
|
224
|
+
- `code_location.absolute_file_path`: en spesifik sorunlu node için `/figma/<fileKey>/nodes/<nodeId>`.
|
|
225
|
+
- `line_range` her zaman `1`.
|
|
226
|
+
|
|
227
|
+
## Öncelik ve güven skorları
|
|
228
|
+
|
|
229
|
+
- **priority:** 0 nit, 1 orta drift, 2 önemli primitive/token, 3 kütüphane/nav seviyesi kritik.
|
|
230
|
+
- **confidence_score:** 0.9–1.0 doğrudan yapısal kanıt; 0.7–0.89 güçlü çıkarım; 0.5–0.69 zayıf — tercihen bulgu yazma.
|
|
231
|
+
|
|
232
|
+
## Erişilebilirlik (a11y) Kontrol Noktaları
|
|
233
|
+
|
|
234
|
+
Audit sırasında aşağıdaki temel a11y kontrolleri de yapılır. Ayrıntılı a11y denetimi için **figma-a11y-audit** skill'ine yönlendir.
|
|
235
|
+
|
|
236
|
+
- **Renk kontrastı:** Metin/arka plan renk çiftlerinde WCAG AA minimum kontrastı (4.5:1 normal metin, 3:1 büyük metin) sağlanıyor mu?
|
|
237
|
+
- **Minimum boyut:** Etkileşimli öğeler (button, input, link) iOS için 44x44pt, Android için 48x48dp minimumunu karşılıyor mu?
|
|
238
|
+
- **Metin boyutu:** Body metin en az 14px (mobil) / 16px (masaüstü) mü?
|
|
239
|
+
|
|
240
|
+
Bu kontroller audit raporunda `[a11y]` etiketiyle ayrı bölümde gösterilir. Detaylı denetim (fokus sırası, VoiceOver/TalkBack, ARIA) için:
|
|
241
|
+
|
|
242
|
+
→ **figma-a11y-audit** skill'ini kullan.
|
|
243
|
+
|
|
244
|
+
## PO/PM Executive Rapor Modu
|
|
245
|
+
|
|
246
|
+
`--executive` flag veya PO/PM persona algılandığında teknik detay yerine yönetici özeti çıkar:
|
|
247
|
+
|
|
248
|
+
**Executive summary formatı:**
|
|
249
|
+
|
|
250
|
+
```markdown
|
|
251
|
+
## DS Uyum Raporu — [Ekran Adı]
|
|
252
|
+
|
|
253
|
+
- **DS Uyum Oranı:** %85 (17/20 öğe DS ile uyumlu)
|
|
254
|
+
- **Risk Seviyesi:** Orta
|
|
255
|
+
- **Kritik Bulgular:** 2 adet
|
|
256
|
+
- **Önerilen Aksiyon Süresi:** ~2 saat
|
|
257
|
+
|
|
258
|
+
### Bulgular (öncelik sırasıyla)
|
|
259
|
+
1. [Yüksek] Navigation bar custom yapılmış — DS NavBar bileşeni mevcut
|
|
260
|
+
2. [Orta] 3 renk token'a bağlı değil — tema değişikliğinde kopacak
|
|
261
|
+
|
|
262
|
+
### Sonraki Adım
|
|
263
|
+
→ apply-figma-design-system ile otomatik düzeltme önerilir
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## Tetik örnekleri
|
|
267
|
+
|
|
268
|
+
- "Bu ekranı design system entegrasyonu için denetle"
|
|
269
|
+
- "Bu board'da eksik component kullanımı var mı?"
|
|
270
|
+
- "Token'lar doğru bağlı mı — audit --json ile ver"
|
|
271
|
+
- "Tasarım durumu raporu ver" (PO/PM)
|
|
272
|
+
- "Ne kadar DS uyumlu bu ekran?" (PO/PM)
|
|
273
|
+
|
|
274
|
+
## Evolution Triggers
|
|
275
|
+
|
|
276
|
+
- Bridge'e yeni DS analiz aracı eklendiğinde kanıt toplama adımları güncellenmeli
|
|
277
|
+
- Yeni a11y standartları (WCAG 3.0) yayınlandığında kontrol noktaları güncellenmeli
|
|
278
|
+
- PO/PM geri bildirimine göre executive summary formatı genişletilmeli
|