Design Systems və onların sənədləşdirilməsi

1) Dizayn sistemi nədir və niyə lazımdır

Dizayn sistemi interfeys üçün vahid həqiqət mənbəyidir: UX-in proqnozlaşdırıla biləcəyini, inkişaf sürətini və miqyaslanmasını təmin edən tokenlər, komponentlər, təcrübələr və sənədlər.

• Bütün məhsullarda vizual və davranış qatının uyğunluğu.
• Sürət: komponentlərin təkrar istifadəsi, daha az revyu xərcləri.
• Keyfiyyət: ümumi A11y nümunələri, lokalizasiya, testlər, məzmun standartları.
• Nəzarət: aydın məsuliyyət, buraxılışlar, yol xəritəsi.

2) Dizayn sisteminin arxitekturası (laylar)

1. Dizayn-tokenlər (foundation): rənglər, tipoqrafiya, ölçülər, radiuslar, kölgələr, girintilər, hallar və semantik tokenlər ('color. surface. warning`, `space. xs`).
2. UI komponentləri: düymələr, giriş sahələri, modal pəncərələr, damcılar, cədvəllər, tostlar, bannerlər, alertlər, boş vəziyyətlər, skeletlər.
3. Nümunələr və kompozisiyalar: KYC formaları, ödəniş floları, sıfır nəticələr, addım-addım ustaları, məzmun kartları.
4. Məzmun bələdçisi (microcopy): ton, terminlər lüğəti, səhv/uğur şablonları, push/bannerlər.
5. Infrastruktur: A11y, test, lokalizasiya, versiyalar, əmanətçilər (contributing).

3) Dizayn-tokenlər: prinsiplər

Semantika> «xam» stil. 'color istifadə edin. text. '#6B7280' əvəzinə muted '.
Temizasiya və platformalar. Token mənbə → platforma mappinqləri (Web, iOS, Android, email).
Açıq/qaranlıq mövzu və token səviyyəsində WCAG kontrastı.
Qlobal və kontekstli şkalalar: 'space. 2`, `radius. md`, `elevation. 1`, `opacity. disabled`.
Tokenlərin versiyası: dəyişikliklər - deprecation policy və miqrasiya qeydləri vasitəsilə.

4) Komponentlər: sənədlərdə tələblər və səhifə tərkibi

• Təsviri və təyinatı. Nə zaman istifadə etmək/istifadə etmək.
• Variantlar/şərtlər. Ölçüləri, növləri (primary/secondary/ghost), disabled, loading, destructive.
• Əlçatanlıq. Rol, klaviatura naviqasiyası, 'aria-', kontrast, fokus-ring.
• Mətn və microcopy nümunələri. Valid etiketlər/pleysholders, səhvlər, kömək.
• Kod nümunələri. Minimum API, controlled/uncontrolled.
• Formalar və i18n ilə inteqrasiya. Uzun sətir, nömrə/valyuta/tarix halları.
• Anti-nümunələr. Səhv istifadə nümunələri.
• Test matrisi. Vizual snapshotlar, unit/interaction, skrinriders.

5) Kompozisiya nümunələri (Recipes)

Qeydiyyat formaları/KOS: addım-addım master, tərəqqi, inline + summary validasiya, səhv şablonları.
Ödəniş flow: metodu seçin, komissiyalar, şərtlər, qaydası same-method, təsdiq və status.
Boş hallar: kontekst + dəyər + CTA, sıfır axtarış nəticələri.
Müvəffəqiyyət mesajları/səhvlər: status iyerarxiyası, vizual tokenlər, tostlar/bannerlər/modallar.
Naviqasiya və filtrlər: qlobal axtarış, sürətli presetlər, etiketlər.
Nümunə səhifələri microcopy və A11y qeydləri ilə kopyalamağa hazır olan komponentlərin kompozisiyasını göstərməlidir.

6) Məzmun bələdçisi (voice & tone, microcopy)

Səs: professional, aydın; ton kontekstdən asılıdır (bağlama, ödəniş, təhlükəsizlik).
Terminlərin vahid lüğəti: ödənişlər, bonuslar, limitlər, KYC - məhsul üzrə bir qiymətdir.
Şablonlar: CTA, səhvlər, xəbərdarlıqlar, uğurlar, boş hallar, bildirişlər.
Lokalizasiya-first: Bölgə üzrə sətirlərin uzunluğu, ədədlər/valyutalar/tarixlər üçün ehtiyat.
A11y-leksika: aydın etiketlər, aria-təsvirlər, qeyri-müəyyən.

7) Accessibility (A11y) sistem standart kimi

Əsas meyarlar: WCAG 2. kontrast üçün 1 AA, diqqət həmişə görünür, klaviatura ilə naviqasiya.
Rollar və atributlar: komponentlər 'role', 'aria-label', 'aria-describedby', tost/alert üçün canlı bölgələri təsvir edir.
Ekran oxucuları: ifadələr nümunələri, oxu qaydası, düzgün statuslar ('assertive/polite').
Test prosedurları: avtomatik yoxlamalar + əl ssenariləri.

8) Lokalizasiya və beynəlmiləlləşmə

komponent kodu + kontekstin təsviri yanında i18n-açarları.
Formatlaşdırma utilitləri vasitəsilə ədədlər/valyutalar/tarixlər; şablonlarda mətni sərtləşdirməyin.
Uzunluq testləri: «uzun Alman», «dar mobil», RTL variantları.
Dillərdə ton: kritik addımlar üçün tone-map (ödənişlər/təhlükəsizlik).

9) Sənədləşmə: struktur və naviqasiya

1. Giriş: missiya, prinsiplər, məsuliyyət sahələri.

2. Tokenlər: rənglər, tipoqrafiya, şəbəkə, ölçülər, kölgələr, hallar, mövzular.

3. Komponentlər: filtrli kataloq (rola görə, platformaya görə, A11y üzrə).

4. Nümunələr: ssenarilər (formalar, ödənişlər, boş hallar, uğur/səhvlər).

5. Məzmun bələdçisi: səs və ton, lüğət, microcopy şablonları.

6. Accessibility: standartlar, yoxlama vərəqləri, test halları.

7. Lokalizasiya: bazarlar üzrə prinsiplər, nümunələr, sözlər.

8. İnteqrasiya və kod: quraşdırma, versiyalar, nümunələr, «how-to migrate».

9. Contributing: depozit prosesləri, dizayn review, kod review, definition of done.

10. Changelog və Roadmap: relizlər, deprecations, inkişaf planı, known issues.

10) İdarəetmə və proseslər (governance)

Rollar: sistem sahibi (DesignOps/UX Platform), meynteynerlər (dizayn/FE), məsləhətçilər (BE, A11y, lokalizasiya).
Dəyişiklik Komitəsi: sorğuların qiymətləndirilməsi, prioritetləşdirilməsi, API/tokenlərin razılaşdırılması.
Proseslər: RFC yeni komponentlər, daxili issue formaları, SLA baqajları.
Definition of Done: dizayn (Figma) kodu (UI-paketi), Dock (nümunə + guid) testlər.

11) Contributing: necə əlavə etmək/dəyişdirmək

RFC şablon: problem → variantları → seçilmiş həll → A11y → i18n → miqrasiya → risklər.
Flow PR: dizayn-review → kod-review → UX-copyright → A11y-check → release-notes.
Əks uyğunluq qaydaları: dağıdıcı olmayan minor/patch, major - mümkün olan yerlərdə deprecation və avtomatik miqrasiya ilə.

12) Version, relizlər, miqrasiya

Paketlər üçün SemVer ('@company/ds-core', '@company/ds-forms', '@company/ds-charts').
Release notes: token dəyişikliyi, komponentlərin API, default davranış, breaking changes, miqrasiya qaydaları.
Deprecations: rıhtımda işarələr, linter qaydaları, kütləvi əvəz üçün kod modları.
Design-tokens pipeline: vahid mənbə (JSON/YAML) → platforma binaları (CSS vars, iOS, Android).

13) Keyfiyyət testi

Vahid davranış və vəziyyət testləri.
Vizual snapshotlar (mövzuların/halların reqressiyası).
A11y testləri: avtomatik + əl screenrider ssenariləri.
kritik flow üçün E2E-cases (qeydiyyat, ödənişlər, KYC).
Perf-büdcələr: bandl/render limitləri və ağır asılılıq qadağaları.

14) Dizayn sisteminin yetkinlik metrikası

Adoption:% DS istifadə ekranlar/anbarlar.
Velocity: Mizanpajdan çatdırılmaya qədər olan vaxt.
Quality: 1 buraxılış üçün UI/A11y qüsurları.
Consistency: DS xaricində «birdəfəlik» komponentlərin/üslubların sayı.
Docs: Dock komponentləri əhatə, NPS daxili auditoriya (dizaynerlər/tərtibatçılar/analitiklər).

15) Anti-nümunələr

Semantika olmadan palitra kimi tokenlər («sadəcə rəng»).
Sənədləşmədən və ekstremal hallar nümunələri olmadan komponentlər.
A11y görməməzlik (heç bir fokus, aşağı kontrast, heç bir 'aria').
deprecation və miqrasiya bələdçisi olmadan sındırıcı versiyası.
Komponentlərdə gizli məntiq (UI davranışı əvəzinə biznes qaydaları).
API genişləndirilməsi əvəzinə dar cases üçün komponentləri dublyaj.

16) Çek vərəqləri

• Semantik adlar və təyinat.
• Hər iki mövzuda AA kontrastı.
• Skeyllər və istifadə prinsipləri sənədləşdirilmişdir.

• Variantlar/hallar əhatə olunur.
• A11y-təsvir, 'aria-', fokus.
• Microcopy nümunələri (etiketlər, səhvlər, ipuçları).
• Kod nümunələri və edge cases (uzun sətirlər, yükləmə, boş).
• Unit/visual/A11y-testlər yaşıl.

• Release notes əvvəl/sonra nümunələri ilə.
• Migration guide и deprecations.
• Yenilənmiş hekayə/demo, liman linkləri.

17) Nümunələr «əvvəl/sonra»

• Müxtəlif ilkin düymələr: rənglər/radiuslar/girintilər uyğun deyil; müxtəlif CTA mətnləri.

• Vahid 'Button' işarələri ilə: 'size = md', 'variant = primary', 'radius = lg', 'spacing = md', «hərəkət + obyekt» üslubunda mətn.

• Texniki mesajlar, heç bir ipucu.

• Komponent ' Səhv tarix formatı. DD istifadə edin. MM. GGGG. '+ avtomatik fokus.

18) Komponent səhifə şablonu (skelet)

Adı: Button

Təsvir: hərəkəti başlatır; 1 əsas ekran.
Variantlar: primary, secondary, ghost, destructive; ölçüləri sm/md/lg.
Hallar: hover, focus, active, loading, disabled.
A11y: klaviatura ilə mövcuddur; 'aria-pressed' keçid üçün.
Microcopy: «Dəyişiklikləri saxla», «Yoxlamaya davam et». «OK» çəkinin.
Kod (API nümunəsi): 'Button {variant, size, icon, loading}'.
Anti-nümunələr: eyni səviyyəli iyerarxiya ikiqat primary.
Testlər: vizual snapshotlar, kontrast, focus-ring.

19) Dizayn sisteminin tətbiqi playbook (rollout)

1. interfeyslərin auditi: rənglərin/mətbəənin/komponentlərin/nümunələrin inventarlaşdırılması.
2. MVP tokenləri və əsas komponentləri: Button, Input, Select, Modal, Alert, EmptyState, Toast.
3. Sənədləşmə və hekayə: canlı nümunələr, kod-snippetlər, qaydalar.
4. Pilot məhsul: widgetların dəyişdirilməsi, rəylərin toplanması.
5. Hyde miqrasiya: kod-moda, deprecation qaydaları.
6. Dəsti genişləndirmək: cədvəllər, paginasiya, formalar formaları, usta addımları.

7. Miqyaslandırma: məhsul nümunələri (ödənişlər, KYC), analitika və A/B ilə inteqrasiya

8. Dəstək: suallar kanalı, SLA, daxili workshoplar.

20) Sürətli sənəd şablonları

• Adı: 'color. border. warning`
• Təyinat: Notice/Warning xəbərdarlıq və banner çərçivələri
• Kontrast: «color» fonunda AA. surface. default`
• Mümkün deyil: kiçik kegle mətni üçün istifadə
• Əlaqəli: 'color. surface. warning`, `icon. warning`

Nümunə şablonu: Boş vəziyyət (noResults)

Məqsəd: «səhv» hissi olmadan sorğu düzəliş

Tərkibi: Başlıq (ops.) , mətn (1-2 təklif), CTA, ikincil CTA, ikona/illüstrasiya

Microcopy: «{query}» üçün heç bir şey tapılmadı. Filtrləri sıfırlayın və ya sorğunu dəqiqləşdirin"

A11y: `role="status"`, `aria-live="polite"`

Yekun şparqalka

Semantik tokenlər + intizam A11y = baza.
Komponent səhifələri doludur: təyinat, variantlar, A11y, microcopy, kod, testlər.
Nümunələr = hazır mətnlər və qaydalarla komponentlərdən ibarət kompozisiyalar.
Docs - məhsul: versiya, buraxılışlar, miqrasiya, investisiya prosesi.
Yetkinlik ölçün: adoption, sürət, qüsurlar, tutarlılıq, daxili komandaların NPS.