> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xneon.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Ошибки, проверка качества и безопасность тем

> Таблица типичных проблем тем, рекомендации по проверке качества и основы безопасности CSS.

## Поиск и исправление ошибок

Таблица использует формат **симптом → причина → проверка → решение**. Файловые ошибки показываются вверху раздела тем; исправление ресурса или CSS вызывает повторное чтение. Пометка Xneon означает подтверждённую особенность проекта, CSS — общий принцип.

| Симптом | Вероятная причина | Способ проверки | Решение |
| - | - | - | - |
| CSS целиком не действует | Xneon: не нажато применение, снят переключатель или открыта другая тема | Применить диагностическую рамку, проверить имя темы и переключатель | Включить CSS, применить и сохранить |
| Селектор не находит элемент | CSS/Xneon: опечатка, другая вкладка, меню закрыто | Инспектор на открытом нужном экране | Скопировать адрес заново; открыть состояние |
| Переменная не меняет элемент | CSS: узел её не читает или использует локальное значение | Computed и реальное правило свойства | Найти потребляемый токен либо задать адресное свойство |
| Действует чужое правило | CSS: специфичность, слой, порядок, inline | Перечёркнутые объявления в Styles | Уточнить селектор, устранить дубли; точечный `important` при обосновании |
| Даже `important` не помог | CSS: неверный адрес/свойство, другой важный слой или элемент внутри webview | Проверить совпадение и документ | Исправить адрес/границу документа, а не добавлять новые `important` |
| Ошибка формата редактора | Xneon: текст не похож на CSS | Проверить скобки и минимальное рабочее правило | Удалить посторонний текст, восстановить правило |
| Часть объявления игнорируется | CSS: неверное имя свойства/значение | Styles, последовательное удаление последней правки | Исправить синтаксис; не считать принятие редактором полной валидацией |
| Цвет в миниатюре отличается | Xneon: не-HEX, второй `:root` или адресное правило | Первый `:root` и визуальная палитра | Для палитры использовать HEX в первом блоке; CSS-эффект проверять на странице |
| После отключения CSS цвет остался | Xneon: он перенесён в палитру | Посмотреть визуальный цвет | Восстановить цвет палитры или выбрать Core |
| Шрифт не появился | CSS/Xneon: отсутствует файл/гарнитура или имя отличается от FontFace | Computed font-family, Network | Выбрать файл штатным способом, проверить имя и запасную гарнитуру |
| Изображение не загрузилось | Xneon: ресурс отсутствует, вышел за папку CSS или неверен `xnl-theme` | Сообщение в разделе тем, Network, источник | Положить ресурс рядом с CSS/в подпапку либо выбрать его штатным способом |
| Работает в dev, ломается в сборке | Xneon: пути http/file отличаются | Проверить `url` и `base` относительно dist | Не использовать корневые веб-пути/локальный путь машины; штатное медиа |
| Прогресс застыл после правки | Xneon: переопределены inline-ширина/transform | Удалить правило размера полосы | Менять цвет/тень, сохранить управление шириной и движением |
| Правило исчезает при перерисовке | Xneon: правка сделана только в DOM | Сравнить CSS темы и DevTools | Сохранить правило в теме; не редактировать классы вручную |
| Работает на одной странице | Xneon/CSS: контекст `data-page` либо другой компонент | Сравнить маркеры обеих страниц | Добавить правила для второго реального контейнера |
| Элемент появляется поздно | Xneon: запрос данных, lazy или виртуализация | Дождаться загрузки/прокрутить список | Оформить шаблон, не фиксировать позиции конкретных элементов |
| После перезапуска пропало | Xneon: предпросмотр/DevTools без сохранения | Закрыть редактор и проверить выбранную тему | Нажать Сохранить; проверить успешную запись настроек |
| Скопированная тема потеряла фон | Xneon: передан только CSS без `.assets` либо без настроек визуального фона | Проверить состав переданных файлов | Передать CSS вместе с `.assets` либо экспортировать полный `.xntheme` |
| Пропала прокрутка | CSS: overflow/height/display у родителя | Откатить последнюю геометрию | Вернуть штатную высоту и overflow; изменять ближайший контейнер |
| Кнопки перекрывают друг друга | CSS: fixed/absolute, transform, ширина, z-index | Осмотреть рамки узлов и контексты | Убрать глобальное позиционирование, ограничить правило |
| Текст плохо виден | CSS: фон/текст одной яркости или opacity у предка | Проверить итоговые цвета, disabled, hover | Согласовать пары фон/текст, прозрачность задавать фону |
| Окно не получает правило страницы | Xneon: портал находится в `body` | DOM-родители диалога | Использовать адрес самого окна/панели |
| Ползунок выглядит неверно | Xneon: изменены current/min/max или не тот тип input | Посмотреть inline переменные и type | Вернуть данные диапазона, оформлять thumb/track отдельно |
| Меню агента выглядит иначе | Xneon: отдельный CSS и портальная область | Открыть меню после загрузки страницы | Уточнить `.agent-composer-popover` и приоритет |
| Анимация мешает кликам | CSS: постоянно движется контрол, перекрывающий слой | Отключить последнюю animation | Уменьшить длительность, убрать бесконечное движение, учитывать `reduced-motion` |
| Скрытый фон продолжает грузиться | Xneon/CSS: display скрывает отрисовку, не источник | Очистить фон визуально и сравнить | Удалить источник в настройках, а не только скрыть узел |

> [!WARNING]
>
> Если собственный CSS закрыл доступ к настройкам, интерфейсного аварийного режима или горячей клавиши полного сброса темы в исследованном коде не обнаружено. Не экспериментируйте со скрытием всей оболочки. В dev можно временно удалить `style#theme-custom-css` через DevTools, затем восстановить тему и сохранить её через UI. Не удаляйте всю БД ради сброса оформления: там хранятся и другие данные.

## Проверка качества

Сохраняйте резервную рабочую версию, меняйте по одному небольшому блоку и добавляйте поясняющие комментарии. Палитру держите отдельно от адресных правил. Ограничивайте селекторы нужной областью, сохраняйте видимый фокус и различия обычного/наведённого/отключённого состояния. Не скрывайте ошибки, загрузку и важные действия.

Перед публикацией пройдите главную, сборки, каталоги и детали сборки, серверы и их вкладки, аккаунты, оба раздела скинов, статистику, логи, настройки, облако и AI. Откройте Select, подтверждение удаления, диалог, центр уведомлений и контекстное меню. Проверьте пустые списки, загрузку, ошибку и длинные подписи; доступные состояния зависят от данных.

Проверьте клавиатуру Tab/Shift+Tab, минимум окна 960×640, повторное открытие приложения, работу без сети для локальной темы и системное уменьшение движения. Для системного цветового режима проверьте оба варианта. Сохраните читаемость важного текста и умеренную стоимость теней/blur на больших списках.

## Безопасность CSS

CSS предназначен для оформления, но произвольная таблица стилей не является полноценной песочницей безопасности. Она может скрыть важную кнопку или предупреждение, перекрыть область ввода, сделать текст нечитаемым и нарушить взаимодействие. `display: none` не отключает связанную функцию приложения и не отменяет выполняющийся запрос.

`url()`, `@import`, изображения и шрифты могут инициировать внешние запросы. Такой ресурс зависит от чужого сервера и может раскрывать сетевые метаданные, например IP-адрес. Перед использованием чужой темы просмотрите URL и необычные глобальные правила. Укажите внешние зависимости в описании публикации.

В текущем коде CSS помещается в `style.textContent`, а не выполняется как JavaScript. При этом полноценного фильтра разрешённых селекторов, URL и свойств в CSS-редакторе нет: проверка формата не заменяет проверку содержимого. Ограничения нормализации темы и проверка структуры архива не доказывают безвредность оформления.

`xnl-theme` ограничивает локальные медиа папкой и именами по хешу. `.xntheme` проверяет пути, размер и контрольные суммы медиа. Эти проверки защищают конкретный путь переноса файлов; они не превращают произвольный CSS в безопасный. Не используйте CSS для обхода механизмов безопасности и не обещайте, что чужая тема не повлияет на работу лаунчера.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.