> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/all-out-docs/ru/ui/uidoc-game-ui-kit.md).

# Игровой UI-kit UIDoc

***

UI-набор Game UI — это нарисованный вручную набор интерфейса команды художников (`$AO/ui/kit/Game UI/**`): модальные окна, кнопки, вкладки, полосы прогресса, баннеры, иллюминаторы, слоты предметов, флажки и переключатели. Движок поставляет соответствующий stylesheet, так что любой ресурс UIDoc может принять внешний вид набора без копирования CSS.

**Применяйте набор как финальный этап стилизации.** Сначала постройте экран — разметку, привязки, события, поведение viewport — проверьте, что всё работает, и только потом оформляйте его. Стилизация набора — это краска и отступы; она никогда не должна быть средством исправления разметки.

## Включение набора

Добавьте одну строку в `index.css`:

```css
@import "game-ui-kit";
```

Во время bake-этапа движок подставляет `res/ui/kit/kit.css` вместо импорта, поэтому ставьте импорт первым, а свои правила — ниже него: ваши правила выигрывают при равенстве в каскаде. Импорт сочетается с утилитами Tailwind. Изменение stylesheet движка заново выпекает импортирующие ресурсы при следующей сборке; UIDoc всё ещё не делает hot reload в запущенной игре.

## Единственный паттерн, который нужно знать

У UIDoc нет bitmap CSS-фонов, поэтому арткит попадает через обычные `img` элементы. Каждый контейнер набора — это позиционированный элемент, у которого первый дочерний элемент — `.kit-bg` изображение; div отвечает за форму и разметку, изображение только рисует, с девятисрезом через настройки ресурса, которые идут в комплекте с набором:

```html
<div class="kit-modal">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <!-- content -->
</div>
```

`.kit-bg` это `object-fit: fill` для арта с девятисрезом (модальные окна, кнопки, вкладки, полосы, баннеры). Арт с фиксированным соотношением сторон (флажки, переключатели, иллюминаторы, иконки слотов) использует `.kit-bg--contain` и собственные width/height контейнера.

Используйте `.kit-bg--shadow` на самом подложечном изображении `img` когда арт должен отбрасывать тень. Он использует учитывающий альфу `drop-shadow(...)`, так что прозрачные углы и результат девятисреза, нарисованный в изображении, определяют силуэт. А `box-shadow` вместо этого следует за прямоугольной рамкой контейнера, тогда как размещение `drop-shadow(...)` на контейнере также включит в тень его текст и других потомков.

Помещайте видимый текст кнопки/вкладки на передний план, в элемент-метку после арта. Сырой текст, принадлежащий контейнеру, может рисоваться под его дочерним изображением:

```html
<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_green1.png">
  <span class="kit-btn-label">PLAY</span>
</button>
```

Набор оптически опускает прямые подписи кнопок на 5px, чтобы они совпадали с артом. Для составного foreground, например иконки плюс цена, оберните весь foreground в `.kit-btn-content` чтобы иконка и текст двигались вместе:

```html
<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_green1.png">
  <span class="kit-btn-content price">
    <img src="coin.png">
    <span class="kit-btn-label">300</span>
  </span>
</button>
```

## Справочник классов

| Класс                                                                               | Используйте                                                                                             |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `.kit-bg`, `.kit-bg--contain`, `.kit-bg--shadow`                                    | Изображение подложки арта, fit с фиксированным соотношением сторон и учитывающая альфу тень изображения |
| `.kit-fg`                                                                           | Общий слой foreground над `.kit-bg`                                                                     |
| `.kit-modal`                                                                        | Позиционированная панель flex-column с отступами набора                                                 |
| `.kit-modal-header`                                                                 | Центрированная безопасная зона заголовка, по 72px зарезервировано с каждой стороны                      |
| `.kit-modal-title`                                                                  | Центрированная строка заголовка; сочетайте с `.kit-text-header`                                         |
| `.kit-title-banner`                                                                 | `pointy_banner_*` подложка за заголовком модального окна, полностью внутри модалки                      |
| `.kit-header-band`                                                                  | `modal_header_*` полоса поперёк верхнего края, нарисованного у модалки                                  |
| `.kit-dim`                                                                          | Затемнение на весь экран позади модалки                                                                 |
| `.kit-btn`, `.kit-btn-label`, `.kit-btn-content`, `.kit-btn--<colour>`              | Арт кнопки плюс оптически опущенная метка/группа foreground с контуром в цвет кнопки                    |
| `.kit-tab-row`, `.kit-tab`, `.kit-tab-label`, `.kit-tab--active`                    | Строка навигации из табов-пилюль с метками на переднем плане                                            |
| `.kit-progress`, `.kit-progress-fill`, `.kit-progress--N`, `.kit-progress--compact` | Дорожка плюс привязанный fill; модификатор семейства выравнивает fill, а compact выбирает масштаб 30px  |
| `.kit-card`, `.kit-list-row`                                                        | Структурные контейнеры для карточек и строк на основе арта                                              |
| `.kit-close`                                                                        | Элемент закрытия на переднем плане, абсолютно закреплённый в правом верхнем углу модалки                |
| `.kit-slot`, `.kit-slot-icon`, `.kit-slot-qty`                                      | Квадрат инвентаря/магазина с иконкой и количеством                                                      |
| `.kit-porthole`                                                                     | Круглая рамка; укладывайте `*_back.png` под `*_ring.png`                                                |
| `.kit-checkbox`, `.kit-toggle`                                                      | Элементы управления состоянием с фиксированным соотношением сторон                                      |
| `.kit-text-header/body/body-dark/info`                                              | Четыре утверждённых текстовых стиля из art doc                                                          |

Размеры текста соответствуют art doc (65/55/45/40) при стандартном логическом viewport; переопределяйте в ресурсе, когда экрану нужен другой масштаб.

## Правила сборки

Это взято из документации Game UI команды художников и устоявшейся практики; классы кодируют большую часть из них, а шаблоны разметки покрывают остальное.

* **Заголовки**: белый, Heavy, чёрная обводка, тень (`.kit-text-header`), задавайте либо прямо на модалке, либо на `.kit-title-banner` (тёмная подложка-баннер, полностью внутри модалки — избегайте коричневого "yellow" pointy banner), либо на `.kit-header-band` если сочетание цветов работает: насыщенная полоса на светлой модалке (красный на белом) читается хорошо; приглушённое на приглушённом (золото на сером) — нет. Если сомневаетесь, обычный текст заголовка всегда безопасен.
* **Заголовки модалок с кнопкой закрытия**: держите `.kit-close` как прямого потомка `.kit-modal`, где он остаётся абсолютно закреплённым в правом верхнем углу. Поместите заголовок или баннер заголовка внутрь `.kit-modal-header`; его симметричные боковые резервы по 72px визуально центрируют заголовок и держат его вдали от кнопки закрытия. Планируйте ширину модалки как желаемую ширину заголовка/баннера плюс оба резерва по 72px плюс левый и правый padding панели. Это намеренно делает закрываемые модалки немного шире, чем плотно подогнанный body content.
* **Тени арта**: `box-shadow` следует за прямоугольной рамкой. Для нерегулярного или девятисрезного арта набора поместите `.kit-bg--shadow` на самом подложечном изображении `img` чтобы тень следовала его нарисованной альфе. Не помещайте фильтр на `.kit-modal`, потому что тогда в силуэт тени попадут текст модалки и дочерний арт.
* **Кнопки**: текст белый с **цветной обводкой** в тон арту кнопки — никогда не чёрной. Поместите обычную метку непосредственно в `.kit-btn-label` чтобы она рисовалась поверх арта и получала 5px оптического смещения базовой линии набора. Для контента с иконкой и текстом поместите оба элемента в прямого `.kit-btn-content` потомка, чтобы пара получила это смещение вместе. Используйте `shiny_buttons` для покупок и особых взаимодействий, `basic_buttons` для всего остального и давайте тексту щедрые отступы. Сероая кнопка — это вид в состоянии disabled.
* **Текст body**: тонкая обводка с прозрачностью 20% (`.kit-text-body`) на цветных модалках; обычный тёмный текст (`.kit-text-body-dark`) на белых/серых модалках.
* **Вкладки**: строка-пилюля *внутри* тела модалки, а не прикреплённая к верхнему краю. Помещайте текст в `.kit-tab-label`. Активная вкладка использует цветной вариант арта (например `tabs_blue`) с соответствующей цветной обводкой текста; неактивные вкладки используют `tabs_black`. Используйте `tab_med.png` или `tab_large.png` для динамических меток. Исходники `tab_small.png` непоследовательны, и некоторые содержат встроенные метки, поэтому они намеренно не девятисрезные.
* **Полосы прогресса**: каждая `progress_bar_N` папка содержит пару `backing.png` с специально созданным `fill_*.png`, но внутренние отступы отличаются у разных семейств и часто асимметричны из-за нижнего обода/тени. Арт дорожки помещается в `.kit-bg`; соответствующий fill семейства — в `.kit-progress-fill`, который использует `object-fit: fill`; добавьте соответствующий `.kit-progress--N` модификатор к контейнеру и привяжите `data-style-image-fill-amount`. Не подставляйте окрашенную иконку или декоративное прозрачное изображение: tint сохраняет исходную альфу, а `cover` может обрезать квадратный арт до щелей или диагональных клиньев на тонкой дорожке. Просматривайте полосу при `0`, `0.25`, `0.5`, и `1`; текущая диагностика не определяет неподходящую альфу текстуры. Компонент по умолчанию имеет толщину 40px; добавьте `.kit-progress--compact` для пропорционально масштабированной формы 30px. Для пользовательской толщины задайте одинаковые `font-size` и `height` значения на контейнере, чтобы его семейство внутренних отступов на основе em масштабировалось вместе с ним. Дорожки набора используют `flex-shrink: 0`; выбирайте толщину явно, а не полагайтесь на flex-родителя, который сожмёт дорожку, потому что тогда дорожка и её fill могут вычислиться в разных размерах.
* **Слоты предметов**: цветные квадраты (`inv_square_<colour>1.png`) для заполненных слотов; `inv_square_empty2.png` — это задуманное состояние EMPTY.
* **Арт семейства модалок использует один масштаб** (углы 37px, обводка 6px в исходных пикселях — уже поставляемые insets slice это учитывают). Элементы, которые должны композироваться, например полоска заголовка поверх модалки, выравниваются, потому что рисуются в одном масштабе; не редактируйте вручную отдельные значения slice.

## Пример: модалка настроек

Модалки с полосой (`modal_stripe_*`) имеют более тёмную нижнюю полосу — размещайте на ней ряд действий, оставляя его последним flow-потомком.

```html
<div class="kit-modal settings">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_stripe_blue1.png">
  <div class="kit-modal-header">
    <div class="kit-modal-title kit-text-header">НАСТРОЙКИ</div>
  </div>
  <button class="kit-close" data-on-click="event:settings:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="rows">
    <div class="row">
      <span class="kit-text-body">Музыка</span>
      <button class="kit-toggle" data-on-click="event:toggle:music">
        <img class="kit-bg kit-bg--contain" data-if="music.on" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_on.png">
        <img class="kit-bg kit-bg--contain" data-if="music.off" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_off.png">
      </button>
    </div>
    <div class="row">
      <span class="kit-text-body">Сезонный пропуск</span>
      <div class="kit-progress kit-progress--1 pass-progress">
        <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
        <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
             data-style-image-fill-amount="pass.progress">
      </div>
    </div>
  </div>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:settings:save">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">СОХРАНИТЬ</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:settings:reset">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">СБРОСИТЬ</span>
    </button>
  </div>
</div>
```

```css
@import "game-ui-kit";

.settings { width: 620px; }
.settings .rows { display: flex; flex-direction: column; gap: 18px; margin-bottom: 26px; }
.settings .row { display: flex; align-items: center; justify-content: space-between; gap: 20px; }
.settings .pass-progress { width: 260px; }
.settings .actions { display: flex; gap: 16px; justify-content: center; }
```

```csl
UI.uidoc_bind_bool("music.on", player.music_enabled);
UI.uidoc_bind_bool("music.off", !player.music_enabled);
UI.uidoc_bind_float("pass.progress", clamp(player.pass_progress, 0.0, 1.0));
```

## Пример: диалог подтверждения (боевой запрос)

Насыщенная полоса заголовка на светлой модалке, тёмный текст body и пара кнопок принятия/отклонения жёлтого/красного цвета.

```html
<div class="kit-modal battle">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_white1.png">
  <div class="kit-header-band">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_header_red1.png">
    <div class="kit-modal-header">
      <span class="kit-text-header band-title">БОЕВОЙ ЗАПРОС</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:battle:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="kit-porthole challenger">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/blue_back.png">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/gold_ring.png">
  </div>
  <span class="kit-text-body-dark message">{{challenger.name}} вызывает вас на бой!</span>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:battle:accept">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">ПРИНЯТЬ</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:battle:decline">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">ОТКЛОНИТЬ</span>
    </button>
  </div>
</div>
```

```css
@import "game-ui-kit";

.battle { width: 680px; align-items: center; }
.battle .band-title { font-size: 55px; }
.battle .challenger { margin-bottom: 10px; }
.battle .message { text-align: center; margin-bottom: 24px; }
.battle .actions { display: flex; gap: 16px; }
```

## Пример: ежедневная награда

Заголовок на баннерной подложке на серой модалке, слоты наград, полоса серии и блестящая кнопка получения.

```html
<div class="kit-modal reward">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <div class="kit-modal-header">
    <div class="kit-title-banner">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Horizontal Banners/pointy_banner_blue.png">
      <span class="kit-text-header banner-title">ЕЖЕДНЕВНАЯ НАГРАДА</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:reward:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <span class="kit-text-body-dark streak">День {{streak.day}} — не останавливайтесь!</span>
  <div class="slots">
    <div class="kit-slot" data-for="reward in rewards" data-for-key="reward.id">
      <img class="kit-bg kit-bg--contain" src="{{reward.back}}">
      <img class="kit-slot-icon" src="{{reward.icon}}">
      <span class="kit-slot-qty">{{reward.count}}</span>
    </div>
  </div>
  <div class="kit-progress kit-progress--1 streak-bar">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
    <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
         data-style-image-fill-amount="streak.progress">
  </div>
  <button class="kit-btn kit-btn--yellow claim" data-on-click="event:reward:claim">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_yellow1.png">
    <span class="kit-btn-label">ПОЛУЧИТЬ</span>
  </button>
</div>
```

```css
@import "game-ui-kit";

.reward { width: 600px; align-items: center; }
.reward .banner-title { font-size: 50px; }
.reward .streak { margin-bottom: 16px; }
.reward .slots { display: flex; gap: 12px; margin-bottom: 18px; }
.reward .streak-bar { width: 320px; margin-bottom: 22px; }
```

Заполненные слоты привязывают `reward.back` к `$AO/ui/kit/Game UI/Item Backs/inventory_squares_1/inv_square_blue1.png` (или другому цвету); пустые слоты используют `inv_square_empty2.png` без иконки.

## Покрытие арта

Отступы для девятисреза поставляются в `res/ui/kit/Game UI/.asset_settings` для: Basic Modals (simple, stripe, headers), basic и shiny buttons, medium/large modal tab pills и trapezoids, горизонтальные backings/fills полос прогресса (кроме сегментных спрайтов и фиксированного bar 12), горизонтальные pointy banners и горизонтальные внутренние панели. Элементы с фиксированным соотношением сторон — включая квадраты инвентаря, флажки, слайдеры и переключатели, иллюминаторы, вспомогательные masks и highlights — не требуют срезов. Другие семейства (карточки, облачка речи, fancy banners, ranking backings) есть в наборе, но пока не имеют настроенных insets — измеряйте их перед нарезкой и держите композитные элементы в одном общем масштабе.