Design Systems және олардың құжаттамасы

1) Дизайн-жүйе дегеніміз не және ол не үшін қажет

Дизайн-жүйе - интерфейске арналған бірыңғай шындық көзі: UX болжамдылығын, әзірлеу жылдамдығы мен масштабталуын қамтамасыз ететін токендер, компоненттер, тәжірибелер мен құжаттамалар жиынтығы.

• Барлық өнімдердегі көрнекі және мінез-құлық қабатының үйлесімділігі.
• Жылдамдық: компоненттерді қайта пайдалану, ревьге жұмсалатын шығындар аз.
• Сапасы: A11y жалпы үлгілері, оқшаулау, тесттер, контент стандарттары.
• Басқарылуы: нақты жауапкершілік, релиздер, жол картасы.

2) Дизайн-жүйе архитектурасы (қабаттары)

1. Дизайн-токендер (foundation): түстер, типографика, өлшемдер, радиустар, көлеңкелер, шегіністер, жай-күйлер, сондай-ақ семантикалық токендер ('color. surface. warning`, `space. xs`).
2. UI компоненттері: кнопкалар, енгізу өрістері, модальді терезелер, дропдаундар, кестелер, тосттар, баннерлер, алерттар, бос қалыптар, скелетондар.
3. Паттерндер мен композициялар: KYC формалары, төлем флоу, нөлдік нәтижелер, қадамдық шеберлер, контент карточкалары.
4. Контент-гид (microcopy): тон, терминдер сөздігі, қате/табыс үлгілері, push/баннерлер.
5. Инфрақұрылым: A11y, тестілеу, оқшаулау, нұсқалар, салымшылар (contributing) бойынша нұсқаулық.

3) Дизайн-токендер: қағидаттар

Семантика> «шикі» стиль. 'color' пайдаланыңыз. text. '#6B7280' орнына muted '.
Тақырыптау және платформалар. Токендер көзі → платформалық маппингтер (Web, iOS, Android, email).
Ашық/қараңғы тақырып және WCAG бойынша токендер деңгейіндегі қарама-қарсылық.
'space. 2`, `radius. md`, `elevation. 1`, `opacity. disabled`.
Токендерді нұсқалау: өзгерістер - deprecation policy және көші-қон жазбалары арқылы.

4) Компоненттер: құжаттамадағы талаптар және парақ құрамы

• Сипаттамасы және мақсаты. Қашан пайдаланылады/пайдаланылмайды.
• Параметрлер/жағдайлар. Өлшемдері, түрлері (primary/secondary/ghost), disabled, loading, destructive.
• Қол жетімділік. Рөлі, пернетақта навигациясы, 'aria-', қарама-қарсылық, фокус сақинасы.
• Мәтін және microcopy мысалдары. Валидті лейблдер/плейсхолдер, қателер, көмек.
• Кодтың мысалдары. Ең аз API, controlled/uncontrolled.
• Нысандармен және i18n интеграциясы. Ұзын жолдардың кейстері, сандар/валюта/күндер.
• Қарсы мысалдар. Қате пайдалану үлгілері.
• Тест-матрица. Визуалды снапшоттар, unit/interaction, скринридерлер.

5) Композиция үлгілері (Recipes)

Тіркеу/АЖК нысандары: қадамдық шебер, прогресс, валидация inline + summary, қате үлгілері.
Төлем флоу: әдісті таңдау, комиссиялар, мерзімдер, same-method ережесі, растау және мәртебе.
Бос күйі: контексті + құндылығы + CTA, нөлдік іздеу нәтижелері.
Жетістік/қате хабарлары: мәртебе иерархиясы, көрнекі белгілер, тосттар/баннерлер/модальдар.
Навигация және сүзгілер: жаһандық іздеу, жылдам пресеттер, тегтер.
Паттерндер беттері microcopy және A11y-аңғартпалары бар көшіруге дайын компоненттерден жасалған композицияны көрсетуі тиіс.

6) Контент-гид (voice & tone, microcopy)

Дауыс: кәсіби, айқын; тон контекстке байланысты (онбординг, төлем, қауіпсіздік).
Терминдердің бірыңғай сөздігі: төлемдер, бонустар, лимиттер, KYC - өнім бойынша бір мән.
Үлгілер: CTA, қателер, ескертулер, табыстар, бос күй, ескертулер.
Локализация-first: аймақ бойынша жолдар, сандар/валюталар/күндер ұзындығына арналған қор.
A11y-лексика: айқын лейблдер, ария-сипаттамалар, екі мағыналы емес.

7) Accessibility (A11y) жүйе стандарты ретінде

Негізгі өлшемшарттар: WCAG 2. 1 AA контраст үшін, фокус әрқашан көрінеді, пернетақтадан навигация.
Рөлдер мен атрибуттар: компоненттер 'role', 'aria-label', 'aria-describedby', тосттар/алерттер үшін лайв-аймақтарды сипаттайды.
Экрандық ридерлер: сөз тіркестерінің мысалдары, оқу тәртібі, түзету мәртебелері ('assertive/polite').
Тест-процедуралар: автоматты тексеру + қол сценарийлері.

8) Оқшаулау және интернационалдандыру

i18n-кілттер компонент кодының қасында + контекстің сипаттамасы.
Пішімдеу утилиттері арқылы сандар/валюталар/күндер; үлгілердегі мәтінді хардкодтауға болмайды.
Ұзындық тестілері: «ұзын неміс», «тар ұялы», RTL-нұсқалар.
Тілдегі тон: сыни қадамдар үшін tone-map (төлемдер/қауіпсіздік).

9) Құжаттама: құрылым және навигация

1. Кіріспе: миссиясы, принциптері, жауапкершілік аймақтары.

2. Белгілер: түсі, типографиясы, торы, өлшемдері, көлеңкелері, жағдайлары, тақырыптары.

3. Компоненттер: фильтрлері бар каталог (рөлі бойынша, платформасы бойынша, A11y бойынша).

4. Паттерндер: сценарийлер (нысандар, төлемдер, бос жағдайлар, табыс/қателер).

5. Контент-гид: дауыс және тон, сөздік, microcopy үлгілері.

6. Accessibility: стандарттар, чек парақтары, тест-кейстер.

7. Оқшаулау: рыноктар бойынша принциптер, мысалдар, глоссарийлер.

8. Интеграция және код: орнату, нұсқалар, мысалдар, «how-to migrate».

9. Contributing: салым процестері, дизайн-ревю, код-ревю, definition of done.

10. Changelog және Roadmap: релиздер, deprecations, даму жоспары, known issues.

10) Басқару және процестер (governance)

Рөлдер: жүйенің иесі (DesignOps/UX Platform), мейнтейнерлер (дизайн/FE), консультанттар (BE, A11y, локализация).
Өзгерістер комитеті: сұрау салуларды бағалау, артықшылық беру, API/токендерді келісу.
Процестер: жаңа компоненттерге арналған RFC, ішкі issue пішіндері, багаж бойынша SLA.
Definition of Done: дизайн (Figma) код (UI-пакет) доктар (мысал + гайд), тесттер.

11) Contributing: қалай қосу/өзгерту

RFC үлгісі: проблема → нұсқалар → таңдалған шешім → A11y → i18n → көші-қон → тәуекелдер.
Флоу PR: дизайн-ревю → код-ревю → UX-копирайтер → A11y-чек → релиз-ноталар.
Кері үйлесімділік қағидалары: бұзбайтындар үшін minor/patch, major - мүмкін болған жерде автоматты көші-қонмен және deprecation.

12) Нұсқалау, релиздер, көші-қон

SemVer ('@company/ds-core', '@company/ds-forms', '@company/ds-charts').
Release notes: токендер, компоненттердің API өзгерістері, әдепкі мінез-құлық, breaking changes, көші-қон гайдтары.
Deprecations: доктағы белгілер, линтер-ережелер, жаппай ауыстыру үшін код-сән.
Design-tokens pipeline: бірыңғай дереккөз (JSON/YAML) → платформалық билдтер (CSS vars, iOS, Android).

13) Сапаны тестілеу

Мінез-құлық және жай-күй юнит-тестілері.
Визуалды снапшоттар (тақырыптардың/жағдайлардың регрессиясы).
A11y-тесттер: автоматты + қолмен скринридер сценарийлері.
E2E-сыни флоу үшін кейстер (тіркеу, төлемдер, KYC).
Perf-бюджеттер: бандл/рендерге лимиттер және ауыр тәуелділікке тыйым салу.

14) Дизайн-жүйенің жетілу өлшемдері

Adoption:% DS пайдаланатын экрандар/репозиторийлер.
Velocity: орналасудан жеткізу аралығы.
Quality: 1 релизге UI/A11y ақаулар.
Consistency: DS тыс «бір реттік» компоненттер/мәнерлер саны.
Docs: доктың компоненттерін жабу, ішкі аудиторияның NPS (дизайнерлер/әзірлеушілер/талдаушылар).

15) Қарсы үлгілер

Белгілер семантикасыз палитра ретінде («жай түс»).
Құжаттамасыз және соңғы жағдайлар мысалынсыз компоненттер.
A11y елемеу (фокус жоқ, төмен қарама-қарсылық, жоқ 'aria').
deprecation және көші-қон гайдынсыз бұзатын нұсқалау.
Компоненттердегі жасырын логика (UI тәртібінің орнына бизнес-ережелер).
Компоненттерді API кеңейтудің орнына тар кейстерге қайталау.

16) Чек парақтары

• Семантикалық атаулар және мақсаты.
• Екі тақырып бойынша да AA қарама-қайшылығы.
• Скейлдер мен пайдалану принциптері құжатталған.

• Нұсқалар/жағдайлар жабылған.
• A11y-сипаттамасы, 'aria-', фокус.
• Microcopy мысалдары (лейблдер, қателер, кеңестер).
• Кодтың және edge-кейстердің мысалдары (ұзын жолдар, жүктеу, бос).
• Unit/visual/A11y-тесттер жасыл.

• Release notes алдында/кейін мысалдары бар.
• Migration guide и deprecations.
• Сториз/демо жаңартылды, доктағы сілтемелер.

17) «дейін/кейін» мысалдары

• Түрлі бастапқы түймешіктер: түстер/радиустар/шегіністер сәйкес келмейді; әр түрлі CTA мәтіндері.

• 'Button' бірыңғай белгісімен: 'size = md', 'variant = primary', 'radius = lg', 'spacing = md', «әрекет + нысан» мәнеріндегі мәтін.

• Техникалық хабарламалар, кеңестер жоқ.

• ' Жарамсыз күн пішімі. КД пайдаланыңыз. ММ. ЖЖЖЖ. '+ авто-фокус.

18) Компонент бетінің үлгісі (скелет)

Атауы: Button

Сипаттамасы: әрекетті іске қосады; Экранға 1 негізгі.
Нұсқалары: primary, secondary, ghost, destructive; өлшемдері sm/md/lg.
Жай-күйлер: hover, focus, active, loading, disabled.
A11y: пернетақтадан қол жетімді; 'aria-pressed' қайта қосылатындар үшін.
Microcopy: «Өзгерістерді сақтау», «Тексеруді жалғастыру». «Жарайды» дегенді болдырмау.
Код (мысалы, API): 'Button {variant, size, icon, loading}'.
Қарсы мысалдар: иерархияның бір деңгейінде қос primary.
Тесттер: визуалды снапшоттар, контраст, focus-ring.

19) Дизайн-жүйені енгізу ойнатқышы (rollout)

1. Интерфейстердің аудиті: түстерді/типографияны/компоненттерді/паттерндерді түгендеу.
2. Токендер мен негізгі компоненттердің MVP: Button, Input, Select, Modal, Alert, EmptyState, Toast.
3. Құжаттама және сторибук: тірі мысалдар, код-сниппеттер, гайдтар.
4. Пилоттық өнім: виджеттерді ауыстыру, кері байланысты жинау.
5. Көші-қон гайды: код-сән, deprecation ережелері.
6. Теруді кеңейту: кестелер, пагинация, пішін форумдары, шебер қадамдары.

7. Масштабтау: азық-түлік үлгілері (төлемдер, KYC), аналитикамен интеграция және A/B

8. Қолдау: сұрақтар арнасы, SLA, ішкі воркшоптар.

20) Құжаттаманың жылдам үлгілері

• Атауы: 'color. border. warning`
• Мақсаты: Notice/Warning ескерту және баннерлер шеңберлері
• Қарама-қарсылық: 'color' аясындағы АА. surface. default`
• Ұсақ кегл мәтіні үшін пайдалануға болмайды
• Байланысты: 'color. surface. warning`, `icon. warning`

Үлгі үлгісі: Бос күйі (noResults)

Мақсат: «қате» сезімінсіз сұрауды түзету

Құрамы: тақырып (опц.) , мәтін (1-2 сөйлем), CTA, қайталама CTA, белгі/иллюстрация

Microcopy: «{query}» бағдарламасында ештеңе табылмады. Сүзгілерді ысырып тастаңыз немесе сұрауды нақтылаңыз"

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

Қорытынды шпаргалка

Семантикалық токендер + A11y пәні = база.
Компоненттердің беттері толық: мақсаты, нұсқалары, A11y, microcopy, коды, тестілері.
Паттерндер = дайын мәтіндері мен ережелері бар компоненттерден жасалған композициялар.
Docs - өнім: нұсқа, релиздер, көші-қон, салым процесі.
Жетілгендікті өлшеңіз: adoption, жылдамдық, ақаулар, консистенттілік, ішкі командалардың NPS.