> ## 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.

# Частые вопросы и обмен темами

> Ответы на частые вопросы по созданию тем, способы экспорта и импорта, а также шаблон публикации темы.

## Частые вопросы

> [accordion] Нужно знать программирование?
>
> Для визуального редактора — нет. Для адресных изменений достаточно основ CSS из этого руководства; JavaScript писать не нужно.

> [accordion] Можно создать тему только цветами?
>
> Да: 20 цветов палитры, свечение и дополнительные цвета статусов настраиваются визуально.

> [accordion] Можно менять шрифты?
>
> Да, по имени установленной гарнитуры или файлом через редактор. Некоторые редакторы кода используют собственную гарнитуру.

> [accordion] Можно использовать изображения и видео?
>
> Да, штатный фон поддерживает оба вида. Через CSS можно использовать изображения для подходящих свойств/иконок. Для переноса локального медиа нужен сам ресурс, удобнее архив темы.

> [accordion] Можно сделать светлую тему?
>
> Да. Выберите светлый режим и согласуйте весь набор поверхностей и текста; не ограничивайтесь одним фоном.

> [accordion] Можно оформить каждую страницу отдельно?
>
> Да, с контекстом data-page или собственным маркером компонента. Портальные окна выбирайте отдельно.

> [accordion] Можно менять размеры?
>
> Да, но фиксированные размеры, масштаб текста и позиционирование могут сломать размещение. Начните с локальных правок и проверьте минимум окна.

> [accordion] Почему некоторые элементы не меняются?
>
> Они используют другой токен, собственный цвет/inline-стиль либо другой документ/canvas. Смотрите Computed и структуру.

> [accordion] Почему тема перестала работать после обновления?
>
> Условия отображения, вложенность и внутренние узлы библиотек могут меняться. Публичные ID/data-адреса защищены контрактом API v1; проверка `test:theme-api` обнаруживает их удаление. Сравните также каскад и контекст страницы.

> [accordion] Можно поделиться темой?
>
> Да: экспортировать CSS с папкой ресурсов или локальный `.xntheme`; облачный перенос тоже остаётся доступен. Официальная публичная площадка тем этим кодом не подтверждена.

> [accordion] Как восстановить стандартный дизайн?
>
> Выберите Core. В редакторе доступен отдельный сброс к тёмной базе, который нужно сохранить.

> [accordion] Как проверить, что тема не сломана?
>
> Пройдите список проверок качества, сохраните, перезапустите и проверьте фокус, диалоги, загрузку и ошибки.

> [accordion] Можно использовать CSS других проектов?
>
> Только после адаптации. Чужие `.button` и `.card` не создают соответствующие элементы в Xneon Launcher; проверьте URL, лицензии ресурсов и реальные адреса.

> [accordion] Что требует изменения исходников?
>
> Новые действия, IPC, вкладки, данные, алгоритмы запуска и отрисовка содержимого 3D-превью. Обычная тема не меняет эту логику.

> [accordion] Как перенести тему на другое устройство?
>
> Экспортируйте `.xntheme` на карточке темы и импортируйте архив в настройках другого лаунчера.

## Обмен темами и шаблон публикации

### Текст CSS

Для обмена отдельными правилами скопируйте их из встроенного редактора. Для переноса всей темы используйте архив `.xntheme`.

### Локальный архив и облачный перенос

На карточке своей темы нажмите «Экспорт .xntheme». Для установки на другом устройстве нажмите «Импорт .xntheme» и выберите архив. Он сохраняется как отдельная тема с новым ID, записывается в локальную папку и сразу выбирается. Это отличается от облачного импорта, после которого тему выбирают отдельно.

Архив переносит также CSS статей и зависимости вложенных локальных таблиц стилей.

В текущей реализации вход в перенос находится в **«Облако»**: подключите поддерживаемое хранилище, откройте загрузку, выберите вкладку **«Темы»**, затем нужную свою тему. Лаунчер создаёт `.xntheme` в папке `themes` провайдера. Подписи могут быть «Выбрать»/«Загрузить» в зависимости от этапа UI. Этот путь можно использовать наряду с прямым локальным экспортом.

Для восстановления откройте **«Облако → Темы»** и действие импорта у `.xntheme`. Тема добавляется в «Мои темы» с новым ID, не перезаписывая существующую. После импорта выберите её в настройках: обработчик импорта не выбирает её автоматически.

Архив содержит `theme.json` формата `xneon-theme`, версия 1, и локальные `assets/<hash>.<ext>`. В него входят структурированные настройки, CSS и обнаруженные локальные ресурсы `xnl-theme`. Внешние HTTP-ресурсы остаются ссылками и не скачиваются автоматически. Относительные ресурсы файловой темы предварительно материализуются в управляемые ссылки; вложенные CSS и их ресурсы включаются в архив.

Ограничения обработчика: манифест до 1 МиБ, один медиафайл до 128 МиБ, общий лимит медиа/архива 512 МиБ, не более 1024 записей. Проверяются имена, контрольные суммы и наличие упомянутых локальных ресурсов. Удаление темы из «Моих тем» не является удалением облачного архива; облачные файлы управляются отдельно.

### Шаблон описания

Скопируйте этот Markdown и заполните поля. Это шаблон публикации, не манифест импорта.

```markdown theme={null}
# Название темы

- Автор: имя или ссылка
- Версия темы: 1.0.0
- Совместимая версия Xneon Launcher: версия, на которой проверено
- Описание: настроение, особенности, тёмный/светлый режим
- Формат поставки: CSS с папкой .assets / локальный или облачный .xntheme
- Палитра: фон #......, текст #......, карточки #......, акценты #...... / #......
- Внешние ресурсы: нет / список URL и зачем они нужны
- Исходный код: ссылка, если опубликован
- Лицензия CSS и ресурсов: указать

## Установка

Для локального архива: Настройки → Темы → Импорт темы.
Для CSS передать также соседнюю папку .assets.
Для облачного архива: импортировать в облаке, затем выбрать тему.

## Удаление и восстановление

Выбрать Core; при необходимости удалить свою тему.
Облачный архив удаляется отдельно.

## Известные ограничения

Какие страницы/состояния не проверены, требуемые шрифты и сеть.

## Проверка

Перечислить версии, режимы, размеры окна и проверенные страницы.
Добавить снимки главной, диалога, настроек и списка сборок.

## История изменений

- 1.0.0 — первая публикация.
```

## Источники и проверка документации

Исследованы импорты CSS, все собственные CSS-файлы renderer и заставка, JSX в `src/` и `components/`, модель/парсер/реестр/редактор/превью тем, слой медиа и шрифтов, протокол локальных файлов, облачная упаковка и восстановление, настройки BrowserWindow и DevTools. В справочник вошли оболочка, главная, сборки и содержимое, каталоги, серверы и файлы, аккаунты, скины/Laby, логи, статистика, облако, настройки, onboarding, AI и общие контролы/диалоги.

Дополнительные ключевые источники:

* [Русские подписи UI](https://github.com/XneonTeam/Xneon-Launcher/blob/main/src/i18n/locales/ru/translation.json).
* [Типы темы](https://github.com/XneonTeam/Xneon-Launcher/blob/main/packages/xnlc-types/src/theme-types.ts).
* [Редактор](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/theme-editor.tsx), [список тем](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/settings-themes.tsx), [эффекты](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/theme-appearance-controls.tsx), [превью](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/theme-preview.tsx).
* [Палитры пресетов](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/data.ts).
* [Локальные медиа](https://github.com/XneonTeam/Xneon-Launcher/blob/main/electron/main/theme-files.ts), [облачный архив](https://github.com/XneonTeam/Xneon-Launcher/blob/main/electron/main/cloud/theme-bundle.ts), [облачные обработчики](https://github.com/XneonTeam/Xneon-Launcher/blob/main/electron/main/cloud/theme-handlers.ts), [облачный интерфейс](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/cloud/cloud-file-browser.tsx).
* [Читалка новостей и её отдельные стили](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/news-reader-modal.tsx).
* [Окно Electron](https://github.com/XneonTeam/Xneon-Launcher/blob/main/electron/main/window.ts), [режим разработки](https://github.com/XneonTeam/Xneon-Launcher/blob/main/electron/main/runtime.ts), [Vite](https://github.com/XneonTeam/Xneon-Launcher/blob/main/vite.config.mts).

Статические справочники воспроизводятся из корня репозитория командой:

```powershell theme={null}
node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/generate-themeguide-reference.mjs
```

Она перезаписывает только `docs/CSS_REFERENCE.md`, `docs/THEME_VARIABLES.md` и временную инвентаризацию `.tmp/themeguide/inventory.json`. Для работы нужны зависимости репозитория. При изменении числа записей обновите также числа в этом руководстве. Строки обычных CSS-правил подтверждают объявление, а не обязательное использование: например, старый `.log-line` может не совпадать с текущей разметкой страницы логов. Временная заставка и библиотечные Root/Portal отдельно помечены.

Основная проверка темы и её парсера:

```powershell theme={null}
pnpm run test:themes
```

Для проверки всего приложения в своей рабочей копии:

```powershell theme={null}
pnpm run build
pnpm run dev
```

Иллюстрированное обновление от 25 октября 2026 года проверено отдельно:

* Созданы и визуально просмотрены все **9 PNG** из настоящих компонентов в изолированном Electron.
* Все **40 CSS-примеров** разобраны PostCSS без синтаксических ошибок.
* Проверены файловые ссылки Markdown, включая все изображения: отсутствующих файлов нет.
* Сценарий воспроизведения иллюстраций: `node scripts/generate-theme-guide-images.mjs`; профиль и сборка находятся в `.tmp/theme-guide-images/`.

Следующий список сохранён из предыдущей редакции документации от 24 октября. Эти прогоны не повторялись при добавлении иллюстраций:

* `pnpm run build` — успешно, включая renderer, проверку TypeScript и Electron main.
* `pnpm run test:themes` — все 64 проверки прошли, включая порядок импортов и независимость файлов дубликатов.
* `pnpm run test:theme-files` — 19 проверок файловой библиотеки, ресурсов, IPC и наблюдателя.
* `pnpm run test:theme-integration` — 18 проверок: импорт/экспорт через React-интерфейс, внешняя правка, изменения из main, токены поверхностей и радиусов, общий CSS внутри настоящего webview.
* `pnpm run test:themes:cloud` — 10 проверок переноса и восстановления архивов.
* `pnpm run test:agent` — 91 проверка помощника, включая изменение тем через настройки.
* `pnpm run test:theme-api` — контроль сохранности публичных адресов API v1.
* Все 40 CSS-примеров разобраны PostCSS и приняты CSSStyleSheet в Electron.
* Локальные ссылки, явные якоря оглавления, переменные и ID примеров сверены с файлами и инвентаризацией.
* В изолированном скрытом окне Electron с отдельным временным профилем проверены цвета Midnight, радиусы кнопки и карточки, disabled, сохранение правила фокуса в CSSOM, повторный разбор/сериализация, отключение CSS и очистка при выборе Core. Использовались настоящие `src/index.css` и функции модели темы с небольшим тестовым DOM. Совокупно этот прогон содержит 55 проверок, включая принятие 40 примеров.

Полный интерактивный обход всех страниц настоящего лаунчера не выполнен. Наличие маркера в исходниках не гарантирует его доступность при любых данных. Наведение, клавиатурный фокус в активном окне, все варианты WebGL-превью и производительность на больших списках требуют ручного прохода из раздела «Проверка качества»; принятие правила фокуса в CSSOM не заменяет эту проверку. Файловая библиотека, стили статьи, токены и API селекторов добавлены вместе с обновлением этого руководства.


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