Адаптивные цвета и комментарии в ресурсах Android: как писать так, чтобы через полгода не гадать «что это было»

Цвета в Android живут в "res/values/colors.xml" — и со временем этот файл превращается в свалку: "purple_200", "color1", "blue_temp", "myColor". Через полгода невозможно понять, что где используется и что можно менять. Разберём систему, которая этого не даёт.

Семантические имена вместо цветовых


Главное правило: имя ресурса должно отвечать на вопрос «для чего этот цвет», а не «какого он оттенка».

Плохо:
<color name="purple_500">#6200EE</color>
<color name="blue_dark">#1A237E</color>
<color name="gray_light">#F5F5F5</color>

Хорошо:
<color name="primary">#6200EE</color>
<color name="primary_variant">#3700B3</color>
<color name="surface">#FFFFFF</color>
<color name="background_secondary">#F5F5F5</color>
<color name="text_primary">#212121</color>
<color name="text_secondary">#757575</color>
<color name="error">#B00020</color>

Почему это важно: если завтра дизайнеры скажут «меняем фиолетовый на синий», при цветовых именах вам придётся переименовывать ресурсы и править все ссылки. При семантических — меняется только hex-значение в одном месте, а весь код остаётся нетронутым.

Структура палитры: Базовые роли плюс специфические


Рабочая схема для большинства приложений — две группы.

Первая — семантические роли по Material-подходу: primary, on_primary (цвет текста поверх primary), secondary, surface, background, error. Это «скелет» темы.

Вторая — специфические цвета, у которых есть бизнес-смысл: status_success, status_warning, badge_unread, chart_line_1. Они могут ссылаться на базовые:
<color name="status_success">@color/success</color>
<color name="badge_unread">@color/accent</color>

Такая связка позволяет переопределить цвет в одной точке — например, для тёмной темы — и он обновится везде.

Поддержка тёмной темы без дублирования кода


Механизм прост: одинаковые имена файлов в разных папках values. Система сама подставит нужный набор:
<!-- res/values/colors.xml — светлая тема -->
<color name="background">#FFFFFF</color>
<color name="text_primary">#212121</color>

<!-- res/values-night/colors.xml — тёмная тема -->
<color name="background">#121212</color>
<color name="text_primary">#EEEEEE</color>

В коде и разметке вы всегда ссылаетесь на @color/background — и на ночных устройствах цвет подменяется автоматически. Ни одного if (isDarkTheme) в коде.

Комментарии: Договоритесь о формате


XML-комментарии в ресурсах — недооценённый инструмент. Хороший комментарий к цвету отвечает на три вопроса: где используется, почему именно это значение, с чем сочетается.
<!--
    Основной цвет бренда. Используется: кнопки FAB, активные табы,
    акцентные элементы. Не использовать для текста — контраст недостаточен.
    Сочетать с @color/on_primary для текста поверх.
-->
<color name="primary">#6200EE</color>


Полезные шаблоны для комментариев


  • Назначение: «цвет заголовков на главном экране», «фон карточек в списке».
  • Ограничения: «не использовать для мелкого текста», «только для лайт-темы».
  • Происхождение: «из макета figma/главный экран/v2», чтобы через полгода понимать, откуда взялось значение.
  • Зависимости: «всегда используется парой с @color/on_primary».

Один нюанс: комментарии в values-night и values легко разъезжаются. Если цвет существует в обеих темах, комментарий пишите только в основном файле — ночной файл оставляйте «чистым», со ссылкой на основную документацию.

Проверка себя: Быстрый чек-лист


Перед коммитом изменений в цвета полезно прогнать короткий список:
  • Нет ли в файле имён, описывающих оттенок вместо роли (purple_500 — повод задуматься);
  • Нет ли дублирующихся значений с разными именами (два #FFFFFF под разными названиями — один из них лишний);
  • Обновлены ли пары цвет + on_color, если вы меняли основной;
  • Проверены ли оба режима (светлый и тёмный) — не осталось ли «белого текста на белом».
Автор:  20.11.2026 07:15:54 am