Єдина мова інтерфейсів

1) Що таке єдина мова інтерфейсів і навіщо вона потрібна

Єдина мова інтерфейсів (ЕЯІ) - це загальна система понять, візуальних правил і взаємодій, яку поділяють дизайнери, інженери, аналітики та автори контенту.

• Узгодженість: однакові компоненти і терміни в різних продуктах і командах.
• Швидкість: швидкі збірки, менше холіварів, швидше онбординг.
• Якість: консистентні патерни UX, доступність «за замовчуванням».
• Масштабованість: безпечна еволюція без розпаду на «зоопарк UI».

2) Шари єдиної мови

1. Токени (колір, типографіка, розміри, тіні, відступи, радіуси, анімації).
2. Компоненти (кнопки, поля вводу, таблиці, графіки, модалки, тости, вкладки).
3. Патерни (форми, валідація, покрокові майстри, списки/таблиці, повідомлення).
4. Контент (мікрокопірайтинг, термінологія, повідомлення про помилки).
5. Іконографія та ілюстрації (сімейство, стиль, розміри та лінії).
6. Доступність і i18n/RTL (правила A11y, перекладність, локалі).
7. Процеси (версії, гайдрайли, рев'ю, лінтери, вітрини і приклади).

3) Дизайн-токени (основа виразності)

Токени - це названі значення, що використовуються у всіх продуктах.

3. 1 Структура токенів (приклад)

json
{
"color": {
"bg": { "base": "#FFFFFF", "subtle": "#F7F8FA" },
"fg": { "primary": "#11131A", "muted": "#656D76" },
"accent": { "primary": "#2F6BFF", "warning": "#FF9F1A", "critical": "#E53935", "success": "#2EAE60" }
},
"space": { "xs": 4, "sm": 8, "md": 12, "lg": 16, "xl": 24, "2xl": 32 },
"radius": { "sm": 8, "md": 12, "lg": 16, "pill": 1000 },
"shadow": { "sm": "0 1px 2px rgba(0,0,0,.08)", "md": "0 4px 12px rgba(0,0,0,.10)" },
"font": { "family": "Inter, system-ui", "size": { "sm": 12, "md": 14, "lg": 16, "xl": 20 } },
"motion": { "duration": { "fast": 120, "base": 200, "slow": 320 }, "curve": { "inout": "ease-in-out" } }
}

3. 2 Неймінг токенів

Від загального до приватного: `color. accent. primary`, не `primaryBlue`.
Без прив'язки до бренду в неймінгу (бренд - це тема, не ім'я токена).
Градації: `fg. muted`, `fg. primary`, `fg. inverse`. Не кодуйте яскравість у назві («blue500») без системи.

3. 3 Токени-теми

Світла, темна, контрастна: змінювати значення, не імена.
Теми - шар перевизначення, UI залишається консистентним.

4) Компоненти: контракт, стани, доступність

Компонент = візуал + поведінка + контракт пропсів + A11y.

4. 1 Приклад контракту кнопки

ts type ButtonProps = {
kind: "primary"      "secondary"      "tertiary"      "danger";
size: "sm"      "md"      "lg";
icon?: "plus"      "download"      "trash";
disabled?: boolean;
loading?: boolean;
ariaLabel?: string;
onClick?: (e: MouseEvent) => void;
};

Стани: `default/hover/active/focus/disabled/loading`.
Доступність: фокус-кільце, розміри таргета ≥ 40-48 px,'aria-pressed'для toggle.

4. 2 Гарантії компонентів

Стабільні розміри (line-height, paddings).
Доступність з коробки (ролеї/aria, клавіатура, контраст).
Інваріанти: помилка всередині поля завжди знизу і з'aria-describedby'.

5) Патерни UX (повторювана логіка)

Форми: лейбл зліва/зверху, placeholder ≠ label, помилки поруч + у зведенні, маски введення і підказки.
Модалки: один головний CTA,'Esc'закриває, пастка фокусу, повернення фокусу.
Таблиці/списки: сортування, sticky-заголовок, посторінковість, експорт.
Фільтри: явна кнопка «Застосувати», скидання, збережені пресети.
Сповіщення: tост ≤ 3-5 с, пауза при фокусі,'role = «status/alert»'.
Дашборди: top insights → контекст → графіки → CTA.

6) Єдина термінологія та мікрокопірайтинг

6. 1 Глосарій

Ведіть єдиний глосарій бізнес-і UX-термінів. Кожна стаття інтерфейсу посилається на нього.
Для дублетів - вибрати одне слово («гаманець» vs «баланс»), друге - як синонім у пошуку.

6. 2 Правила тексту

Коротко і по справі; уникати жаргону.
Помилки - пояснювати що зробити: «Вкажіть дату у форматі ГГГГ-ММ-ДД».
Заголовки - іменники; кнопки - дієслова («Зберегти», «Скасувати»).
Консистентні одиниці: дата/час в UTC або локалі, валюти з кодом (EUR, USD).

7) Іконографія та ілюстрації

Сімейство ізоморфне: єдиний кут, товщина лінії, сітка 24 × 24.
Статуси та семантика: колір - вторинний; форма/іконка + текст - первинні.
Масштабування: піктограми не «пливуть» в різних щільностях (1 ×/2 ×/3 ×).

8) Доступність (A11y) і локалізація (i18n/RTL)

Компоненти проходять WCAG AA: контраст, навігація з клавіатури, фокус,'prefers-reduced-motion'.
Перекладаються рядки - в ресурсах, не в коді. Плейсхолдери і формат чисел/дат - локалізовані.
RTL: дзеркалювання іконок, коректний порядок Tab, логіка DnD з клавіатури.

9) Числа, дати, валюти і формати

Дати/час: ISO-8601, точка справжнього часу - UTC; користувачеві - локаль.
Валюта: minor units/десяткові рядки; завжди вказувати код (наприклад, "€12,34" або "12. 34 EUR" - по локалі).
Відсотки: «12,3%» і пункти «+ 1,2 п. п». розрізняти явно.
Округлення: до значущих розрядів; «k/m» для великих чисел.

10) Говернанс: ролі, артефакти, канали

Design Language Council (DLC): власники токенів/компонентів, стверджують RFC.

• Бібліотека компонентів (Figma/код) + живий каталог з прикладами.
• Документація: гайдрайли, патерни, A11y, контент-гайд.
• Чейнджлог з датами, рівнями (added/changed/deprecated/removed/fixed).
• Канали: щотижневий дизайн-сінк, Slack-канал, шоукейси впроваджень.

11) Версіонування та еволюція

SemVer для пакету компонентів: `MAJOR. MINOR. PATCH`.
MINOR - адитивно: нові токени, пропси з дефолтами, нові компоненти.
MAJOR — breaking: видалення пропсів, зміна семантики → міграційні гайди.
Депрекації: попередження, вікно ≥ 90 днів, прапори сумісності.

12) Лінтери та автоматичні перевірки

UI-лінтер: заборонені кольори поза токенами, анти-патерни (кнопка-див, відключений outline).
A11y-перевірки: контраст, ролі/aria, фокус, клавіатура.
i18n-лінтер: «жорсткі» рядки в коді, некоректні плейсхолдери.
Скріншот-тести: візуальні регресії компонентів.
Контракти API візуалізацій (якщо є): типи даних, діапазони, підписи.

13) Вітрина компонентів (storybook/пісочниця)

Живі приклади з контролями пропсів, кодом, станами, A11y-чекером.
«Рецепти»: форма реєстрації, майстер 3 кроки, таблиця + фільтри, модалка + тости.
«Пісочниця локалей»: переключення мови/форматів/RTL.

14) Шаблони неймінгу та структури

14. 1 Компоненти (ВЕМ/семантика, приклад CSS)

.btn/basic/
.btn--primary/view/
.btn--danger
.btn--lg/size/
.btn __ icon/part/

У коді - одноманітні імена пропсів: `size`, `kind`, `disabled`, `onClick`.

14. 2 Файлова структура бібліотеки

/tokens
/components
/button
/input
/modal
/patterns
/docs
/changelog

15) Анти-патерни

«Вільні» кольори/відступи поза токенами.
Дублі компонентів: «ButtonV2», «PrimaryButtonNew».
Плейсхолдер як єдина мітка поля.
Відключення outline і «дів-кнопки».
Непередбачувані hover/active/disabled.
Транслітеровані терміни замість нормального перекладу.
Відсутність міграційних гайдів при оновленнях.

16) Метрики якості єдиної мови

Coverage: частка екранів, що використовують бібліотеку компонентів.
Consistency Index: повторне використання токенів vs «ручні» стилі.
A11y Pass Rate: відсоток компонентів, що проходять WCAG AA.
Defect Escape: дефекти UI/контенту в проді на 1k комітів.
Time-to-Ship: час на реалізацію типового екрану до/після DLS.
Adoption: DAU вітрини, число PR з компонентами/патернами.

17) Чек-лист екрану

• Використані токени (колір/відступи/радіуси), а не «жорсткі» значення.
• Компоненти з бібліотеки; кастом - тільки при RFC.
• Доступність: клавіатура/фокус/контраст/ролеї/aria.
• Одиниці: дати/валюти/відсотки - по гайду форматів.
• Мікрокопи: кнопки = дієслова, помилки = дія для виправлення.
• Локалі/RTL не ламають макет.
• Стани: loading/empty/error передбачені.
• Тести візуальної регресії оновлені.

18) План впровадження (3 ітерації)

Ітерація 1 - Фундамент (2-3 тижні)

Токени (колір/типографіка/spacing/motion), базові компоненти (Button, Input, Select, Tooltip, Modal), контент-гайд (тон, лейбли, помилки).
Вітрина (storybook) і A11y-чекер, лінтер токенів.

Ітерація 2 - Патерни і локалізація (3-4 тижні)

Патерни форм/таблиць/фільтрів, іконпак 24 × 24, RTL/i18n-пісочниця, правила чисел/дат/валют.
SemVer, чейнджлог, процес RFC/міграцій, автотести (візуал + A11y).

Ітерація 3 - Масштаб і еволюція (безперервно)

Композиційні компоненти (Wizard, DataGrid, Chart primitives), темізація (світла/темна/контрастна), звіти по метриках якості, регулярні UX-аудити.

19) Міні-FAQ

Чи потрібно відразу «все і відразу»?
Ні, ні. Почніть з токенів і базових компонентів, потім додавайте патерни і процеси.

Як переконати команди використовувати ЕЯІ?
Покажіть виграш: швидкість, менше дефектів, готові рецепти екранів і A11y «з коробки».

Що робити з legacy-екранами?
План міграцій, мостові стилі через токени, пріоритетні екрани - першими.

Підсумок

Єдина мова інтерфейсів - це не тільки бібліотека компонентів. Це система правил і процесів, де токени задають виразність, компоненти - поведінку і доступність, патерни - повторюваність рішень, а говернанс і метрики - стійку еволюцію. Робіть мову ясною, перевіреною і розширюваною - і ваші продукти будуть виглядати і працювати однаково, швидко і надійно.