Темна тема, яка не виглядає дешево — правильна система токенів

Як з’являється «дешева» темна тема (і як це проявляється)

Темна тема, що виглядає дешево, має послідовний набір режимів відмови. Ви можете впізнати їх так само, як досвідчений інженер на виклику впізнає невдалий деплой:
все «технічно працює», але відчуття неправильні і канал інцидентів починає нагріватися.

Сигнал №1: Усе однакове сіре

Якщо ваш фон, поверхня та підняті поверхні відділені крихітними дельтами (або випадковими дельтами), інтерфейс стає плоскою калюжею. У світлому режимі
ви часто можете дозволити собі недбале підняття поверхонь, бо тіні та навколишнє світло частково це компенсують. У темному режимі ваші поверхні мають нести
ієрархію.

Сигнал №2: Контраст тексту в порядку, але читаність погана

Співвідношення контрасту WCAG не гарантує комфорту. Темні інтерфейси можуть досягати цільових значень контрасту, водночас спричиняючи гало — яскравий текст, який здається вібруючим.
Виправлення не в «зменшити контраст, поки не провалиться», а в уникненні чистого білого та чистого чорного і в контролі кроків нейтралів.

Сигнал №3: Брендові кольори виглядають неоновими або брудними

Насичені акценти на темних поверхнях можуть виглядати як дешеві світлодіодні вивіски. Навпаки, якщо просто затемнити той самий брендовый відтінок, він перетворюється на синяк.
Потрібні окремі значення токенів для кожної теми для акцентів, з обмеженнями, прив’язаними до контрасту та сприйнятої яскравості, а не «помножити на 0.8».

Сигнал №4: Компоненти «втрачають характер» у крайніх станах

Hover, active, focus, disabled і error стани виявляють, чи ви побудували систему, чи колаж. Темний режим особливо карає:
кільце фокусу, що працювало у світлому режимі, може зникнути; неактивний текст може стати не відрізняним від звичайного; бордюри можуть виглядати як випадкові волосіні.

Сигнал №5: У кожної команди є власна інтерпретація

Якщо токени існують, але кожен продукт використовує їх по-своєму, це не темізація; це «спільна лексика» без спільного значення.
Виправлення — семантичні токени, відображені з примітивів, з чіткими призначеннями й запобіжними засобами.

Одна операційна істина: чим більше у вас додатків, тим більше ви маєте ставитись до темізації як до платформи. Це не просто «кольори». Це контракт сумісності.

Жарт №1: Темна тема складна не тому, що кольори хитрі. Вона складна тому, що ваша організація трактує «#121212» як стратегію.

Корисні факти та історичний контекст (щоб ви не повторювали історію)

• Ранні «темні UI» не були естетичним вибором. Багато терміналів мали світлий текст на темному тлі через фосфорні дисплеї та обмеження енергії — це було практично.
• «Інвертувати кольори» завжди підводило. Ранні інструменти доступності намагалися інверсію і стикалися з хаосом у зображеннях і брендових кольорах; сучасна темізація ще це виправляє.
• OLED змінив розмову. Темні пікселі можуть зекономити енергію на OLED; на LCD заощадження менші та іноді незначущі залежно від яскравості.
• Material Design популяризував структуроване піднесення. Воно нормалізувало мислення в термінах поверхонь і шарів замість «фон + якісь картки», що важливіше в темному режимі.
• Співвідношення контрасту WCAG — це математика, а не комфорт. Вони вимірюють контраст люмінансів, а не сприйнятий блік чи читабельність протягом часу.
• Дизайнерські токени стали відповіддю на стандартизацію. Коли бібліотеки компонентів росли, командам потрібен був переносимий, незалежний від інструментів спосіб кодувати рішення дизайну.
• Системна перевага стала першочерговою. OS-level prefers-color-scheme перетворив тему на runtime-питання, а не лише вибір при складанні стилів.
• «Темна тема скрізь» створила заборгованість по зображеннях/іконках. Іконки, ілюстрації та графіки часто покладалися на припущення світлого фону; темізація змусила робити свідомі рішення.

Якщо взяти одну настанову з історії: кожного разу, коли команди трактували темну тему як «світлий режим, але темніший», вони в підсумку створювали другий UI — просто не визнаючи цього. Визнайте це рано. Побудуйте систему.

Модель токенів: примітиви, семантика та компоненти

Системи токенів провалюються, коли їх організують як відра з фарбою, а не як API. Хороша система токенів виглядає нудно, бо вона передбачувана.
Передбачуваність — те, що вам потрібно о 2-й ночі, коли хотітися зробити хотфикс без візуальних регресій.

Шар 1: Примітивні токени (сировина)

Примітивні токени — це ваша палітра і одиниці виміру: кроки сірого, брендові відтінки, одиниці відступів, радіуси, шкали типографіки. Вони відповідають:
«Які кольори існують?» а не «Куди їх розміщувати?»

Правила, що тримають примітиви в порядку:

• Використовуйте кроки, а не відчуття. Визначайте нейтрали як драбину (наприклад, neutral-0…neutral-1000) з послідовними дельтами світності.
• Тримайте примітиви залежними від теми. Можна мати окремі набори примітивів для світлої та темної тем (особливо для нейтралів і акцентів).
• Примітиви не повинні проникати в продуктний код. Якщо продуктний код використовує neutral-900 напряму, ви вже втратили консистентність.

Шар 2: Семантичні токени (значення й намір)

Семантичні токени представляють ролі: bg, surface, text-primary, border-subtle, focus-ring,
danger, success, link.

Семантика відповідає: «Для чого цей токен?» Семантичний токен має вузьке призначення і стабільний контракт. Значення можуть змінюватися на тему і бренд.
Саме значення — ні.

Сильні думки, що вас врятують:

• Визначте глосарій семантичних токенів. Запишіть призначення використання та «не використовувати для X».
• Розділяйте контент і контейнер. Текстові токени не повинні повторно використовуватися для бордерів, бо хтось подумав «це той самий сірий».
• Включіть токени станів і взаємодій. Hover/active/focus/disabled — не післядумки; саме там темна тема ламається.
• Включіть семантику для візуалізації даних рано. Графіки стають нерозбірливими в темному режимі, якщо ви не передбачите токени для осей, сітки, серій і підказок.

Шар 3: Токени компонентів (тонке налаштування на фінальному етапі)

Токени компонентів потрібні там, де компонент потребує спеціального налаштування без забруднення глобальної семантики: наприклад, button-primary-bg,
tooltip-bg, modal-overlay.

Фішка: токени компонентів мають за замовчуванням посилатися на семантичні токени й відхилятися лише за реальною причиною.
Якщо кожен компонент визначає свої кольори, ви побудуєте другу палітру з гіршим управлінням.

Іменування, яке не руйнується

Уникайте іменування токенів за кольорами (blue-500), коли ви маєте на увазі призначення (link). Називайте за наміром. Завжди.
Якщо мусите зберегти кольорові назви (для примітивів), тримайте їх подалі від продуктного коду.

Практична схема іменування:

• Примітиви: color.neutral.0, color.neutral.900, color.brand.primary.600
• Семантика: color.bg, color.surface, color.text.primary, color.border.subtle
• Компоненти: color.button.primary.bg, color.input.border.focus

Якщо віддаєте перевагу CSS-змінним, відобразіть у --color-bg, --color-text-primary тощо. Та сама ідея, менше крапок.

Поведінка кольору в темному UI: контраст, світність і чому «просто інвертувати» не працює

Темна тема — це не просто «світлий режим з іншими hex-ами». Ви працюєте проти людського сприйняття і фізики пристроїв.
Ставтеся до цього як до планування ємності: числа важливі, але справжня історія в формі кривої.

Вибирайте «майже чорний», а не чорний

Чистий чорний (#000000) виглядає різко в багатьох контекстах і підсилює контраст з текстом та ефектами піднесення. Більшість високоякісних тем використовують майже чорний,
зазвичай трохи відтінений (холодний або теплий), щоб виглядати цілеспрямовано й зменшувати бендинг.

Використовуйте не зовсім білий текст

Чистий білий на темних фонах може спричиняти гало: сприйняте сяйво і напругу очей. Використовуйте не зовсім білий для основного тексту і знижуйте для вторинного та неактивного.
Тримайте кроки послідовними.

Піднесення в темному режимі — це здебільшого легше поверхні

У світлому режимі підняті поверхні часто отримують темніші тіні. У темному режимі тіні не читаються однаково; зазвичай поверхню трохи освітлюють,
і використовують тонкі тіні або бордери помірно, щоб сигналізувати розділення.

Не повторюйте логіку бордерів зі світлого режиму

Бордери у світлому режимі часто трохи темніші за поверхню. У темному режимі бордери можуть потребувати бути трохи світлішими за поверхню,
або вони зникають. Це класична помилка «копіювати відповідність токенів».

Акцентні кольори потребують налаштування під тему

Той самий брендовый колір виглядає інакше на темних поверхнях. Зазвичай вам потрібні:

• трохи яскравіший (вища світність) акцент для темних фонів,
• варіант обведення/фокусу, що лишається видимим і на акценті, і на фоні,
• і приглушений варіант для ненав’язливих фонів (бейджі, підсвітка), що не виглядає як синяк.

Цитата, бо вона все ще влучна

«Надія — не стратегія.» — Рік Пейдж

Якщо ваша тема покладається на те, що компоненти «імовірно виглядають нормально», ви відправите регресії в продакшн. Інструментуйте це.

Продуктова архітектура темізації

Ви хочете систему тем, яка може робити три речі без драм:
(1) надійно перемикати теми, (2) зберігати консистентність компонентів, (3) підтримувати кілька брендів або продуктів без форків світу.

Рішення: Де зберігати токени?

Помістіть токени в один версіонуємий пакет. Генеруйте виходи для платформ, які вам важливі (CSS-змінні, JSON, TS-тайпи).
«Джерело істини» має бути в одному форматі, а не в трьох руками редагованих копіях.

Рішення: Як застосовувати теми?

Використовуйте один кореневий атрибут і CSS-змінні:

• data-theme="light" і data-theme="dark" на <html> або <body>
• Визначайте набори змінних, обмежені цим атрибутом

Це запобігає «напівтематизованій» сторінці, де деякий піддерево застрягає на старих значеннях. Це також робить це вимірним: ви можете перевірити наявність атрибута.

Рішення: Як токени відображаються між темами?

Розглядайте відображення як матрицю. Кожний семантичний токен має мати значення для кожної теми (і для кожного бренду, якщо потрібно). Якщо семантичний токен не має
значення в темній темі, це має бути помилкою на етапі збірки, а не рантайм сюрпризом.

Рішення: Як обробляти перевагу користувача та збереження?

Використовуйте системну перевагу як за замовчуванням (prefers-color-scheme), але зберігайте явні вибори користувача. Зробіть це детерміністично:

• Порядок: перевизначення користувача → збережена перевага → системна перевага → дефолт
• Застосовуйте атрибут теми якнайраніше, щоб уникнути спалахів

Продуктивність: запобігайте ривкам при перемиканні теми

Перемикання тем зачіпає обчислені стилі. Велика DOM робить це дорогим. Тримайте набори змінних неглибокими (root-scoped), уникайте інлайн-стилів на компонентах
і не анімуйте все під час зміни теми.

Жарт №2: Якщо ваш перемикач тем анімує 300 CSS-властивостей, вітаємо — ви винайшли симулятор розряду батареї.

Тестування: ставте тему як релізну поверхню

Справжня система тем має:

• тести повноти токенів (немає відсутніх відображень),
• тести контрасту для ключових пар (текст/фон, іконки/поверхні, кільця фокусу),
• тести візуальних регресій для репрезентативних скринів,
• правила лінтингу, що забороняють продуктному коду використовувати примітиви напряму.

Робочі процеси та управління: як токени не перетворюються на скриньку мотлоху

Токени провалюються повільно. Спочатку команда «просто потребує одного особливого сірого». Потім ще одна команда додає «трохи іншу» поведінку hover. Через шість місяців
темна тема виглядає як клаптикова ковдра, і ніхто не може пояснити чому. Управління — це не бюрократія; це спосіб тримати систему дешевою в експлуатації.

Визначте власність і шлях зміни

Оберіть невелику групу (design systems + один інженер продукту) як опікунів. Решта змін подається через передбачуваний процес:

• Запит: яку UI-проблему ви вирішуєте?
• Запропонований семантичний токен: чому він заслуговує на існування?
• Відображення: значення для світлої + темної (і брендів), включно з нотатками про контраст
• План розгортання: як ми мігруємо старе використання?

Зробіть «семантичний дрейф» видимим

Створіть невеликий звіт про використання токенів у CI:

• Які семантичні токени не використовуються?
• Які примітиви згадуються поза пакетом токенів?
• Які компоненти визначають кастомні кольори замість використання семантики?

Плануйте міграції так само, як міграції сховищ

Інженери сховищ розуміють це рано: ви не мігруєте дані просто «змінивши шлях». Ви робите подвійний запис, валідуєте, розгортаєте поступово.
Токени подібні. Вводьте нові семантичні токени, відображайте їх, мігруйте компоненти, позначайте старі як застарілі з попередженнями, а потім лише видаляйте.

Зупиняйте баги теми на межі

Запровадьте правило: продуктний код споживає лише семантичні токени (або токени компонентів), а не примітиви.
Якщо команді потрібен новий відтінок, це запит на зміну токена, а не локальний хак.

Практичні завдання з командами: інспектувати, вимірювати, вирішувати (12+)

Найшвидший спосіб покращити темну тему — трактувати її як операційну поверхню. Спочатку виміряйте. Потім вирішіть.
Нижче реальні, запускаємі завдання, які ви можете використати в репозиторії, що зберігає токени і поставляє CSS-змінні.
Я покажу команди, приклади виводу, що вони означають, і рішення, які треба ухвалити.

Завдання 1: Знайти пряме використання примітивних токенів в продуктному коді

cr0x@server:~$ rg -n "neutral\.(?:[0-9]{1,4})|--color-neutral-[0-9]{1,4}" apps/ packages/
apps/web/src/components/Banner.css:14:  color: var(--color-neutral-50);
apps/admin/src/pages/Settings.tsx:92:  background: var(--color-neutral-950);

Значення виводу: Продуктний код використовує примітиви напряму, обходячи семантику.

Рішення: Відкрити задачу на рефактор: замінити на семантичні токени (--color-text-secondary, --color-surface тощо) і додати правило лінтингу, щоб запобігти повторенню.

Завдання 2: Перевірити, чи кожен семантичний токен має значення в темній темі

cr0x@server:~$ jq -r '.semantic | keys[]' tokens/semantic.json | wc -l
148

cr0x@server:~$ jq -r '.themes.dark.semantic | keys[]' tokens/theme-dark.json | wc -l
146

Значення виводу: Темна тема не має 2 семантичних мапінгів.

Рішення: Провалити збірку, доки відсутні ключі не будуть замаплені. Відсутні токени в темній темі стають рантаймовими «випадковими кольорами», і саме так стає дешево.

Завдання 3: Показати відсутні семантичні ключі

cr0x@server:~$ comm -3 \
  <(jq -r '.semantic | keys[]' tokens/semantic.json | sort) \
  <(jq -r '.themes.dark.semantic | keys[]' tokens/theme-dark.json | sort)
color.focus.ring
color.table.row.hover

Значення виводу: Дві ролі не мають визначень для темного режиму: кільце фокуса і hover рядка таблиці.

Рішення: Визначити їх явно для теми dark. Не «позичайте» значення зі світлого режиму.

Завдання 4: Перевірити, що CSS-змінні дійсно існують у збудованому артефакті

cr0x@server:~$ npm run build:css
...output...
dist/tokens.css  34.2kb

cr0x@server:~$ rg -n "--color-focus-ring" dist/tokens.css | head
211:  --color-focus-ring: #7aa2ff;

Значення виводу: Токен присутній у збудованому CSS.

Рішення: Якщо відсутній, ваш pipeline збірки відкидає токени або ім’я не співпадає. Виправте генератор або невідповідність імен.

Завдання 5: Перевірити дублікати або конфліктні визначення токенів

cr0x@server:~$ rg -n "--color-text-primary:" dist/tokens.css
54:  --color-text-primary: #e7eaf0;
912: --color-text-primary: #f6f7fb;

Значення виводу: Токен визначений двічі — ймовірно, дві теми перекриваються або помилка злиття.

Рішення: Переконайтесь, що змінні скоповані під [data-theme="dark"] і [data-theme="light"], а не дублюються в корені.

Завдання 6: Підтвердити правильність scoping теми (лише кореневий атрибут)

cr0x@server:~$ rg -n "\[data-theme=" dist/tokens.css | head -n 20
1:[data-theme="light"] {
401:[data-theme="dark"] {

Значення виводу: Існують лише дві області. Добре.

Рішення: Якщо ви бачите багато розкиданих областей, консолідуйте в корінь, щоб уникнути часткової темізації і проблем з продуктивністю.

Завдання 7: Виміряти регресію розміру бандла токенів (не шліть тему як роман)

cr0x@server:~$ ls -lh dist/tokens.css
-rw-r--r-- 1 cr0x cr0x 34K Feb  4 09:12 dist/tokens.css

Значення виводу: Базовий розмір помірний.

Рішення: Якщо він різко зріс, дослідіть вибух токенів (часто через переопреділення на рівні компонентів). Розмір — це не лише трафік, а й час парсингу.

Завдання 8: Запустити швидкий аудит контрасту для критичних пар (скриптом)

cr0x@server:~$ node scripts/contrast-audit.mjs tokens/theme-dark.json | head
PASS color.text.primary on color.bg ratio=12.8
PASS color.text.secondary on color.bg ratio=7.1
FAIL color.text.disabled on color.surface ratio=2.3
FAIL color.focus.ring on color.bg ratio=2.0

Значення виводу: Неактивний текст і кільце фокусу мають занадто низький контраст на своїх поверхнях.

Рішення: Налаштуйте семантичні значення (не хак компонентів). Визначте мінімальні співвідношення для ролей (наприклад, кільце фокусу має бути видимим, неактивний текст має залишатися читабельним, коли потрібно).

Завдання 9: Виявити «випадкові чисті чорні/білі»

cr0x@server:~$ rg -n "#000000|#ffffff" tokens/ dist/ packages/ | head
tokens/theme-dark.json:22:    "color.bg": "#000000"
tokens/theme-light.json:18:   "color.text.primary": "#ffffff"

Значення виводу: У вас є чистий чорний фон і чисто білий текст — класичний рецепт блиску.

Рішення: Замініть на майже чорний та не зовсім білий, потім перевірте контраст і сприйнятий комфорт.

Завдання 10: Знайти токени, ідентичні між темами (часто ознака відсутності дизайну)

cr0x@server:~$ node scripts/diff-themes.mjs tokens/theme-light.json tokens/theme-dark.json | head
SAME color.link.visited = #6b7cff
SAME color.chart.grid = #2a2f3a
DIFF color.bg light=#ffffff dark=#0f1115

Значення виводу: Деякі токени незмінні між темами. Іноді це правильно; часто це ліниве відображення.

Рішення: Перевірте кожен «SAME» токен. Посилання й сітки графіків рідко поводяться однаково у світлих і темних контекстах.

Завдання 11: Перевірити поведінку prefers-color-scheme у скомпільованому CSS

cr0x@server:~$ rg -n "prefers-color-scheme" dist/app.css
122:@media (prefers-color-scheme: dark) {

Значення виводу: У додатку є підтримка системної переваги.

Рішення: Переконайтесь, що системна перевага не перевизначає явний вибір користувача. Якщо це відбувається, ваша тема буде «перемикатися назад» і користувачі подадуть баг-репорти з великими літерами.

Завдання 12: Перевірити на спалах неправильної теми (FOUC) у серверному HTML

cr0x@server:~$ curl -sS -D- http://localhost:3000/ | head -n 30
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
...
<html lang="en">
<head>
...
</head>
<body>

Значення виводу: HTML повернуто, але ми ще не побачили атрибут теми.

Рішення: Якщо тему застосовують лише через пізній JS, ви отримаєте спалахи. Виправте, встановивши data-theme на сервері або через невеликий inline-скрипт у head.

Завдання 13: Підтвердити наявність атрибута теми під час виконання (headless-перевірка)

cr0x@server:~$ node scripts/check-theme-attribute.mjs http://localhost:3000/
OK html[data-theme] present value=dark

Значення виводу: Тема застосована досить рано, щоб бути відчутною.

Рішення: Якщо відсутній, виправте SSR або ранній bootstrap. Не покладайтеся на «воно швидко оновиться». Користувачі помічають.

Завдання 14: Знайти «одиночні» обхідні випадки компонентів, що обходять токени

cr0x@server:~$ rg -n "background:\s*#|color:\s*#" apps/ packages/ | head
apps/web/src/components/Tag.css:8:  background: #1d2533;
apps/web/src/components/Tag.css:9:  color: #cfe1ff;

Значення виводу: У продуктних компонентах є хардкодні hex-значення.

Рішення: Замініть на семантичні/компонентні токени. Жорстко закодовані кольори складно тестувати в масштабі й вони будуть розходитися між темами.

Плейбук швидкої діагностики: швидко знайти вузьке місце

Коли темна тема виглядає неправильно в продакшні, вам потрібен шлях триажу швидший за дизайн-рев’ю. Ось порядок, який швидко знаходить корінні причини.

Почніть: підтвердьте селектор теми та область дії

• Чи встановлено data-theme правильно на кореневому елементі?
• Чи визначені CSS-змінні лише в кореневих селекторах теми?
• Чи є піддерева, що перевизначають змінні?

Якщо це неправильно, все інше — шум. Виправте область ще перед тим, як чіпати кольори.

Другий крок: перевірте повноту токенів і fallback-и

• Є відсутні семантичні ключі у відображенні теми dark?
• Є CSS-змінні, на які посилаються, але які не визначені?
• Є небажані fallback-и на кшталт var(--x, #fff), що йдуть у продакшн?

Відсутні токени спричиняють «випадкову» поведінку, що змінюється на різних сторінках і компонентах. Це не випадковість. Це невизначена поведінка з кращим брендингом.

Третій крок: ідентифікуйте роль, що відмовляє, а не компонент

• Проблема читабельності тексту? Тоді перевірте color.text.*.
• Проблема ієрархії? Перевірте токени bg/surface/elevation.
• Проблема видимості станів? Перевірте ролі hover/active/focus/disabled.

Виправляйте ролі на семантичному рівні. Латка одного компонента — шлях до накопичення боргу темізації.

Четвертий крок: виміряйте контраст і блік відносно призначених поверхонь

Запустіть аудит контрасту і перегляньте пари, що мають значення. Не витрачайте час на теоретичні пари, якими ніхто не користується.

П’ятий крок: перевірте рендеринг та симптоми продуктивності

• Перемикач теми викликає ривки? Підозрівайте занадто багато змін стилів на вузлах або транзицій.
• Оновлюються лише деякі компоненти? Підозрівайте межі shadow DOM, iframe або вкладені області теми.
• Іконки виглядають неправильно? Підозрівайте пайплайн активів та fill/stroke у SVG.

Три корпоративні міні-історії (аніонімізовано, технічно точно)

Міні-історія №1: Інцидент через неправильне припущення

Середній SaaS зробив реліз темної теми під час «platform week». У них була бібліотека компонентів, пакет токенів і впевнений PM.
План був простий: замапити старі семантичні токени світлого режиму в темніші hex-значення, випустити, святкувати.

Неправильне припущення: «Бордери — це просто текст з меншим контрастом». У світлому режимі вони використовували трохи темніший сірий для бордерів і випадково повторно використали текстовий токен, бо виглядало нормально. Вони перенесли цей шорткат у темний режим.

У продакшні поля форм «зникли» для частини користувачів. Не для всіх — лише для користувачів з дешевими панелями ноутбуків з поганими чорними рівнями і для тих, хто зменшив яскравість. Тікети підтримки описували це як «відсутні інпут-бокси», що звучало як баги лейаута.

Інженери триажили CSS. Лейаут був нормальний. DOM був нормальний. Потім хтось увімкнув оверлей налагодження, що виділяв фокусовані елементи: інпути були на місці,
але бордер-токен в темному режимі був замаплений на значення, занадто близьке до поверхні. Помилка була системною: десятки компонентів залежали від тієї ролі.

Виправлення не було «зробити бордери яскравішими». Виправлення — запровадити правильне семантичне розділення: color.border.subtle,
color.border.default, color.text.secondary — і заборонити повторне використання текстових токенів для бордерів у код-рев’ю.
Темна тема не зламала їхній UI. Зламалися їхні припущення.

Міні-історія №2: Оптимізація, що повернулася бумерангом

Інша компанія хотіла миттєвого перемикання теми без спалахів і з мінімальним CSS. Інженер запропонував хитру оптимізацію:
згенерувати лише набір CSS-змінних і «обчислювати» темну палітру на клієнті шляхом трансформації світлої палітри.
Менше токенів, менше CSS, швидші збірки. Звучало акуратно.

Вони випустили це за флагом. Це працювало… поки не перестало. Брендові кольори стали жахливими, бо трансформація не зберігала сприйняту світність.
Кольори попереджень і помилок стали неоднозначними. Кольори графіків стикалися. Кільця фокусу блякли на деяких поверхнях.

Операційний біль був гіршим за естетику. Баги важко відтворити, бо обчислена палітра залежала від рантайм-математики, округлення в браузері
і іноді від масштабу сторінки. QA не могли «задіфити» тему, бо це не був статичний артефакт.

Постмортем був прямий: вони оптимізували не те. Кількість токенів і розмір CSS не були їхнім вузьким місцем; коректність і передбачуваність — так.
Вони відкотилися до явних відображень тем зі зменшеною семантичною поверхнею і використали звичну мінімізацію для зменшення розміру.

Цей паттерн відкату поширений: «розумні» трюки з темізацією додають приховану складність. У продакшн-системах прихована складність виставляє рахунок пізніше, з відсотками.

Міні-історія №3: Нудна, але правильна практика, що врятувала день

Велика організація тримала кілька продуктів на спільній системі дизайну. Вони запровадили правило, що здавалося набридливим: кожна зміна токена вимагала
оновлення тесту-снімка токенів і невеликого набору тверджень про контраст. Інженери бурчали; дизайнери зітхали.

Потім сталося ребрендування. Новий акцент. Нові нейтрали. Усі очікували, що темна тема буде в клопотах. Утримувачі токенів змінювали примітиви,
оновлювали семантичні відображення, і CI загорівся як панель під час поганого деплоя.

Тести миттєво впіймали дві проблеми: контраст кільця фокусу впав нижче внутрішнього порога на найтемнішій поверхні, і неактивний текст став тьмяним
на поширеному фоні таблиці. Жодна з проблем не була очевидною при швидкому погляді, і обидві стали б клієнтськими багами протягом годин.

Вони виправили відображення перед релізом. Рол-аут пройшов нудно. Нудьга — найвища похвала, яку можете зробити зміні теми в продакшні.

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

Поширені помилки: симптом → корінна причина → виправлення

1) Симптом: «Усе виглядає сірим і пласким»

Корінна причина: Токени поверхонь не кодують піднесення; фон, поверхня і підняті поверхні занадто схожі.

Виправлення: Визначте шкалу поверхонь: bg, surface, surface-2, surface-3 з виміряними кроками світності в темній темі. Використовуйте бордери/тіні економно й послідовно.

2) Симптом: «Текст проходить контраст, але здається, що світиться»

Корінна причина: Використання чистого білого або майже білого на майже чорному; великий контраст викликає гало і напругу очей.

Виправлення: Використовуйте не зовсім білий для основного тексту і трохи підніміть світність фону. Тримайте контраст достатнім, але не екстремальним; перевіряйте на реальному читанні, а не лише за коефіцієнтами.

3) Симптом: «Неактивні контролі невидимі»

Корінна причина: Токени для disabled були похідними шляхом рівномірного зниження непрозорості; у темному режимі це руйнує відмінності.

Виправлення: Створіть спеціальні семантичні токени для неактивного тексту, іконок і бордерів. Перевірте на найтемнішій поширеній поверхні і на піднятих поверхнях.

4) Симптом: «Кільця фокусу зникають на деяких компонентах»

Корінна причина: Токен кільця фокусу не враховує фони; він занадто близький до поверхні та акцентів.

Виправлення: Використовуйте колір кільця фокусу з достатнім контрастом як до bg, так і до surface. Розгляньте подвійні кільця (зовнішнє + внутрішнє), використовуючи два токени.

5) Симптом: «Бордери виглядають занадто яскравими або важкими»

Корінна причина: Токени бордерів були скопійовані з логіки світлого режиму або замаплені з текстових токенів.

Виправлення: Визначте ролі бордерів окремо (subtle, default, strong) і налаштуйте під тему. Ніколи не повторно використовуйте текстові токени для бордерів.

6) Симптом: «Брендовий колір виглядає неоновим на темному»

Корінна причина: Акцент використовується без змін; насиченість і сприйнята яскравість «вибухають» на темних фонах.

Виправлення: Забезпечте значення акценту для темної теми. Додайте семантичні токени для accent-on-surface і accent-on-accent кольорів тексту.

7) Симптом: «Тільки деякі частини сторінки перемикаються темою»

Корінна причина: Токени scoped у багатьох місцях або перевизначені усередині стилів компонентів; межі shadow DOM/iframe не оброблені.

Виправлення: Змінні на кореневому рівні. Для iframe/shadow roots явно передавайте атрибут теми і інжектьте змінні консистентно.

8) Симптом: «Перемикач теми викликає ривки»

Корінна причина: Зміна теми тригерить дорогі перерахунки по великій DOM; транзиції застосовані глобально; інлайн-стилі на компонентах.

Виправлення: Тримайте змінні на корені. Зменшіть кількість транзицій під час зміни теми. Уникайте оновлення сотень вузлів; оновіть один атрибут.

Чеклісти / покроковий план

Покроково: побудувати темну тему, що витримує

1. Спочатку визначте семантичні ролі. Перелічіть ролі, які потрібні вашому UI: фони, поверхні, рівні тексту, бордери, іконки, стани, фокус, оверлеї, графіки.
2. Створіть нейтральну драбину для темної теми. Виберіть майже чорний фон і розбийте поверхні вгору з виміряними різницями.
3. Задайте рівні тексту явно. Основний, вторинний, третій, неактивний. Використовуйте не зовсім білий для основного.
4. Визначте токени станів. Hover/active/focus/disabled для загальних контролів, включно з тонкими варіантами.
5. Замапте семантику на примітиви для кожної теми. Не авто-трансформуйте; визначайте значення навмисно.
6. Генеруйте платформні виходи. CSS-змінні + JSON + тайпи з одного джерела.
7. Запровадьте правила споживання. Продуктний код не повинен звертатися до примітивів; тільки до семантики/токенів компонентів.
8. Додайте перевірки в CI. Повнота, дублікати, перевірки контрасту для критичних пар, сніпшот для виводу токенів.
9. Запустіть візуальні регресії на репрезентативних екранах. Авторизація, налаштування, таблиці, модали, форми, пусті стани, стани помилок.
10. Розгортайте поступово. Фічар-флаг, вимірюйте тікети підтримки, моніторьте відгуки сесій, потім розширюйте.

Чекліст: «Чи виглядає ця темна тема дорого?»

• Поверхні показують ієрархію без опори на товсті бордери.
• Текст читається для тривалих сесій; немає ефекту «сяйва».
• Фокус помітний на кожній поверхні й компоненті.
• Неактивні стани чітко позначені, а не невидимі.
• Помилки/попередження/успіх відрізняються і не надто насичені.
• Графіки лишаються читабельними; сітки й осі не зникають.
• У продуктному коді немає хардкодних hex-значень.
• Перемикання тем швидке і не спалахує неправильною темою.

Чекліст: управління токенами, що не перетворюється на комітет

• Одна група-власник для джерела правди токенів.
• Чіткі критерії для додавання семантичного токена.
• Процес депрекоції з попередженнями і міграціями.
• Автоматизований звіт про витік примітивів і невживані токени.
• Ноти релізу для змін токенів, що впливають на семантику UI.

Питання й відповіді

1) Чи маю я мати окремі примітивні палітри для світлої і темної тем?

Для нейтралів: так, зазвичай. Для бренд-акцентів: часто так. Спроба використовувати один набір примітивів для обох тем найчастіше дає мутні нейтрали або неонові акценти.
Тримайте семантику стабільною; дозволяйте примітивам відрізнятися для різних тем.

2) Чи варті семантичні токени витрат часу?

Якщо у вас більше однієї команди або більше одного продукту — так. Семантичні токени запобігають ситуації, коли кожен компонент стає власним експериментом з теорією кольору.
Вони також роблять баги темізації діагностованими: ви виправляєте роль, а не 40 компонентів.

3) Чи можна використовувати прозорість для неактивних станів?

Можна, але це крихке в темному режимі. Блендинг прозорості залежить від того, що позаду елемента, і може непередбачувано знищити контраст.
Віддавайте перевагу явним токенам для неактивного тексту/іконок/бордерів, перевіреним на поширених поверхнях.

4) Який найкращий фон для темного режиму?

Майже чорний із легким відтінком, підібраний разом зі ступенями поверхні. «Найкраще» значення — те, що підтримує ієрархію й читання довгих текстів без блиску.
Якщо оберете чистий чорний, ви витратите час на компенсації по всьому інтерфейсу.

5) Як обробляти зображення та ілюстрації?

Ставтесь до них як до активів з варіантами тем або робіть їх такими, що працюють на обох фонах. Для SVG-іконок віддавайте перевагу currentColor і семантичним токенам ікон.
Для ілюстрацій вирішіть, чи надавати темні варіанти, чи розміщувати їх у нейтральних контейнерах.

6) Як уникнути спалаху неправильної теми при першому завантаженні?

Застосуйте data-theme до першого пейнту: рендерьте його на сервері, коли можливо, або виконайте маленький inline-скрипт у head, що читає збережену перевагу
і встановлює атрибут негайно.

7) Чи гарантує WCAG, що наша темна тема хороша?

WCAG допомагає не випустити нечитаємий текст. Він не гарантує комфорту або естетичної якості. Використовуйте перевірки контрасту як запобіжники, а потім оцінюйте блік, ієрархію
і видимість станів на реальних екранах з реалістичною яскравістю.

8) Як підтримувати кілька брендів без форкування всього?

Тримайте один спільний семантичний шар між брендами. Надайте бренд-специфічні примітивні палітри і семантичні відображення. Якщо бренди потребують різної семантики, поставте під сумнів це:
часто це запит на варіант компонента, а не новий семантичний контракт.

9) Чи варто анімувати перемикання теми?

Легко, якщо взагалі. Тонкий фонний фейд може бути приємним; анімація всіх змін токенів дорога і може створювати відчуття «танення» UI.
Віддавайте пріоритет коректності й швидкості; анімація — опціонально.

10) Яке найпростішe правило для code review?

«Жодних хардкодних кольорів у продуктному коді.» Якщо колір потрібен — він має бути токеном із семантикою. Це одне правило усуває величезний клас регресій.

Наступні кроки, які ви реально можете зробити цього тижня

1. Зробіть інвентаризацію семантичних токенів. Напишіть глосарій: що означає кожна роль і для чого її ніколи не слід використовувати.
2. Запустіть виявлення витоків. Знайдіть примітиви і хардкодні hex у продуктному коді; відкрийте беклог на міграцію.
3. Додайте два перевірки в CI негайно: (a) семантична повнота для кожної теми, (b) аудит контрасту для критичних пар.
4. Виправте три головні чинники сприйняття: майже чорний фон + не зовсім білий текст + видиме кільце фокусу на кожній поверхні.
5. Виберіть один «геройський екран» і один «найгірший екран». Зробіть їх ідеальними в темному режимі. Потім масштабуйтесь, компонент за компонентом.
6. Припиніть робити роботу з темами в компонентах. Відповідальність за відображення тем має бути в токенах. Компоненти споживають семантику. Тримайте контракт чистим.

Темна тема, що не виглядає дешево — це не дивовижна палітра. Це операційно правильна система: семантика, шари, тести і відмова випускати невизначену поведінку.
Будуйте її так, як ви будуєте надійну інфраструктуру — бо в масштабі саме це і є.