Skip to content

style-guide.uk.md

Latest commit

 

History

History
154 lines (108 loc) · 13.4 KB

style-guide.uk.md

File metadata and controls

154 lines (108 loc) · 13.4 KB

Sergeant — Content Style Guide (UA)

Last validated: 2026-05-31 by audits-runner workflow. Next review: 2026-08-29. Status: Active

Канонічні правила tone-of-voice для всієї UA-копії в продукті — UI strings, toast-и, error messages, empty states, onboarding, FTUX, settings. Витяг із i18n-каталогу apps/web/src/shared/i18n/uk.ts (PR-30 / PR-31 — uxroast 2026-Q2) + урок-кейси з аудит-проходів.

Звідки взято. Цей документ закриває PR-X3 з docs/90-work/audits/2026-05-06-ux-roast-pr-plan.md. Машинно-перевірне джерело правди для існуючих рядків — apps/web/src/shared/i18n/uk.ts; цей файл — людиночитна версія правил, до яких ці рядки приведені.

1. Hard rules (порушення = баг)

# Правило Так Ні
1 Звертання — ти, не Ви "Спробуй ще раз" "Спробуйте ще раз"
2 Action busy → 1-а особа однини "Входжу…", "Зберігаю…" "Виходимо…", "Зберігаємо…"
3 Не використовуй "Зачекайте" для action-busy "Підключаюсь…" "Зачекайте, підключаємось…"
4 Generic spinner → noun-form "Завантаження…" "Завантажую…" (тільки для action-button)
5 Помилки закривай action-prompt-ом "Спробуй ще раз" / "Перевір з'єднання" "Помилка." (без виходу)
6 Один знак "…" у кінці, не "..." "Завантажую…" (… = U+2026) "Завантажую..." (3 крапки)
7 Заголовки — без крапки "Створи акаунт" "Створи акаунт."
8 Лапки — «…» для цитат у тексті «Зачекайте» — погано "Зачекайте" — погано

ESLint sergeant-design/no-cyrillic-jsx-literal (warn) ловить нові кириличні JSX-літерали — обов'язково винеси у apps/web/src/shared/i18n/uk.ts до правильної групи.

2. Voice — звідки беремо особу і час

Контекст Особа Приклад
Action в процесі (button busy) 1-а однини: "що я зараз роблю" "Входжу…", "Виходжу…", "Реєструю…", "Підключаюсь…", "Завантажую транзакції…"
Generic spinner / page-loading Іменник: "що відбувається" "Завантаження…", "Завантаження сторінки"
Звертання до користувача 2-а однини: "ти" "Перевір пошту", "Спробуй ще раз", "Запроси новий лист"
Опис стану системи 3-я однини: нейтрально "Сервер тимчасово недоступний", "Цей email вже зареєстровано"
Ніколи 1-а множини ("ми…"), 2-а множини / формальне "Ви" —

Чому 1-а однини для action-button-ів. Юзер кликнув кнопку — програма виконує його команду; "я" — це програма, що звітує. "Ми" створює дистанцію (команда vs. one-app), "Виходимо" — звучить як охоронець, що проводжає тебе.

Чому 2-а однини для звертань. Sergeant — це personal coach app. "Ти" — це товариський (не панібратський) tone, який добре лежить у вузькій niche-аудиторії 25+ engineers/builders, що користуються продуктом. "Ви" створює офіційну дистанцію, недоречну для daily-use tool.

3. Error messages — структура

[Що сталося.] [Що зроби.]
Ситуація Копія
Network error "Не вдалось синхронізувати — перевір з'єднання."
5xx retryable "Сервер тимчасово не відповідає. Спробуй ще раз."
5xx non-retryable / rate-limit "Забагато спроб. Зачекай хвилину і спробуй ще раз."
Invalid token (reset link) "Посилання для скидання пароля невалідне або вже використане. Запроси новий лист на сторінці входу."
Generic auth fallback "Не вдалося завершити вхід. Спробуй ще раз."

Принципи:

  • Не звинувачуй юзера ("Ти ввів неправильно" → "Невірний пароль").
  • Скажи що сталося, але без stack-trace-у. "Сервер тимчасово недоступний" — не "ENETUNREACH".
  • Завжди закінчуй на дії, яку юзер може зробити прямо зараз. Якщо дії немає — повідомлення зайве (просто залишай UI у працездатному стані).

4. Action buttons — verbs у наказовій формі (2-а однини)

Жанр Так Ні
Primary CTA "Створи акаунт", "Увійди" "Створити акаунт", "Вхід"
Confirm "Підтверди", "Зберегти" "OK", "Готово"
Destructive "Видали" "Видалити"
Cancel "Скасуй" / просто × "Cancel"

Виняток для destructive у dialog-ах: "Видалити" (інфінітив) допустимо в confirm-діалогах для нейтральності тону — Apple HIG patten. Але кнопка primary action ВСЕ ОДНО — наказова: "Видали".

5. Empty states

[Що тут має бути.] [Як це сюди потрапить.]
Surface Копія
HubReports без даних "Ще немає даних за цей період. Додай тренування або транзакцію — і графік оживе."
Search no-results "Нічого не знайшов. Спробуй інакше."
Empty chat "Що ти хочеш зробити сьогодні?"

Завжди вказуй конкретну дію, яка наповнить екран. Не пиши "Пусто" або "Немає даних" без наступного кроку.

6. Toast notifications

  • Success: перфект, минулий час. "Транзакція збережена.", "Тренування додано."
  • Error: structure §3. Always actionable.
  • Info: present neutral. "Синхронізація триває…" (рідко — toast-и зайвий шум, краще inline-state).

Тривалість дефолту — 3 с. Destructive-action undo-toast — 5 с.

7. Заборонені слова та конструкції

Слово/конструкція Чому Заміна
"Зачекайте" / "Будь ласка, зачекайте" формальне множинне, дистанція "Завантажую…", "Підключаюсь…"
"Виходимо…" 1-а множинна "Виходжу…"
"Підключення…" (як button-state) noun без agency "Підключаюсь…"
"Помилка" як standalone не actionable "Не вдалось … — спробуй …"
"Будь ласка" calque з англ. "Please" прибери — наказова форма у нас не різка
"На жаль" passive-victim tone прибери, перейди до дії
"Ой!" infantile прибери
"Так точно" / "Так-так" bot-style "Готово" / "Зрозумів"

8. Числа, дати, валюта

  • Час дня — Europe/Kyiv ALWAYS. Формат HH:MM (24h). Ніколи AM/PM.
  • Дати — DD.MM для коротких міток ("Бесіда 31.05"), D MMM YYYY для повних.
  • Числа — український розділник: 12 345,67, не 12,345.67.
  • Валюта — ₴ після числа з нерозривним пробілом: 1 000 ₴. Не UAH 1000.
  • Плюрали — використовуй Intl.PluralRules('uk-UA'), не hardcoded if/else. UA має 4 форми: one/few/many/other.

9. Links, headings, microcopy

  • Заголовки H1/H2 — без крапки. "Налаштування модуля", не "Налаштування модуля.".
  • Заголовки таблиць — без крапки.
  • Підказки form-field-ів — повне речення з крапкою. "Пароль має бути не менше 8 символів."
  • Placeholder — без крапки, instructive. "Введи email" (не "Email", не "Email...").
  • Link text — descriptive, ніколи "сюди" / "тут" / "click here". "Відкрий налаштування модуля" не "Клікни сюди для налаштувань".

10. Як викликати оновлення цього документа

  • Якщо аудит виявив нову паттерн-помилку — додай у §7 або відповідну секцію.
  • Якщо нова масова заміна (ще один round of i18n cleanup) — додай рядок у apps/web/src/shared/i18n/uk.ts коментарем "PR-30 / §X з docs/90-work/audits/…" і за потребою новий блок тут.
  • Reviewer PR-30 / PR-31 — посилається на цей документ у review-нотатці на кожен новий кириличний рядок.

Related