> 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/ui/uidoc-game-ui-kit.md).
# UIDoc Game UI Kit
***
The Game UI kit is the art team's hand-drawn UI set (`$AO/ui/kit/Game UI/**`): modals, buttons, tabs, progress bars, banners, portholes, item slots, checkboxes, and toggles. The engine ships a matching stylesheet so any UIDoc asset can adopt the kit look without copying CSS.
**Apply the kit as a final styling pass.** Build the screen first — layout, bindings, events, viewport behavior — verify it works, then skin it. Kit styling is paint and padding; it must never be the tool used to fix layout.
## Enabling the kit
Add one line to the asset's `index.css`:
```css
@import "game-ui-kit";
```
At bake time the engine splices `res/ui/kit/kit.css` in place of the import, so put the import first and your own rules below it — your rules win cascade ties. The import composes with Tailwind utilities. Editing the engine stylesheet re-bakes importing assets on the next build; UIDoc still does not hot reload in a running game.
## The one pattern to know
UIDoc has no bitmap CSS backgrounds, so kit art enters through ordinary `img` elements. Every kit container is a positioned element whose first child is a `.kit-bg` image; the div owns shape and layout, the image just paints, nine-slicing via asset settings that ship with the kit:
```html
```
`.kit-bg` is `object-fit: fill` for nine-sliced art (modals, buttons, tabs, bars, banners). Fixed-aspect art (checkboxes, toggles, portholes, slot icons) uses `.kit-bg--contain` and the container's own width/height.
Use `.kit-bg--shadow` on the actual backing `img` when the art should cast a shadow. It uses an alpha-aware `drop-shadow(...)`, so transparent corners and the painted result of nine-slicing define the silhouette. A `box-shadow` follows the container's rectangular border box instead, while putting `drop-shadow(...)` on the container would also include its text and other descendants.
Put visible button/tab copy in a foreground label element after the art. Raw text owned by the container can paint below its child image:
```html
```
The kit optically lowers direct button labels by 5px to match the art. For a compound foreground such as an icon plus a price, wrap the whole foreground in `.kit-btn-content` so the icon and copy move together:
```html
```
## Class reference
| Class | Use |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `.kit-bg`, `.kit-bg--contain`, `.kit-bg--shadow` | Art backing image, fixed-aspect fit, and alpha-aware image shadow |
| `.kit-fg` | Generic foreground layer above `.kit-bg` |
| `.kit-modal` | Positioned flex-column panel with kit padding |
| `.kit-modal-header` | Centered title safe area with 72px reserved on both sides |
| `.kit-modal-title` | Centered title row; combine with `.kit-text-header` |
| `.kit-title-banner` | `pointy_banner_*` backing behind a modal title, fully inside the modal |
| `.kit-header-band` | `modal_header_*` band across the modal's painted top edge |
| `.kit-dim` | Full-screen dim behind a modal |
| `.kit-btn`, `.kit-btn-label`, `.kit-btn-content`, `.kit-btn--` | Button art plus an optically lowered foreground label/group with a colour-matched outline |
| `.kit-tab-row`, `.kit-tab`, `.kit-tab-label`, `.kit-tab--active` | Pill-tab navigation row with foreground labels |
| `.kit-progress`, `.kit-progress-fill`, `.kit-progress--N`, `.kit-progress--compact` | Track plus bound fill; family modifier aligns the fill and compact selects the 30px scale |
| `.kit-card`, `.kit-list-row` | Structural containers for art-backed cards and rows |
| `.kit-close` | Foreground close control absolutely rooted at the modal's top-right |
| `.kit-slot`, `.kit-slot-icon`, `.kit-slot-qty` | Inventory/shop square with icon and count |
| `.kit-porthole` | Circular frame; stack `*_back.png` under `*_ring.png` |
| `.kit-checkbox`, `.kit-toggle` | Fixed-aspect state controls |
| `.kit-text-header/body/body-dark/info` | The art doc's four approved text styles |
Text sizes follow the art doc (65/55/45/40) at the standard logical viewport; override in the asset when a screen needs a different scale.
## Assembly rules
These come from the art team's Game UI documentation and established practice; the classes encode most of them, the markup patterns cover the rest.
* **Titles**: white, Heavy, black outline, drop shadow (`.kit-text-header`), set either straight on the modal, on a `.kit-title-banner` (dark banner backing, fully inside the modal — avoid the brown "yellow" pointy banner), or on a `.kit-header-band` when the colour pairing works: a saturated band on a light modal (red on white) reads well; muted-on-muted (gold on grey) does not. When unsure, plain title text is always safe.
* **Closable modal headers**: keep `.kit-close` as a direct child of `.kit-modal`, where it remains absolutely rooted at the top-right. Put the title or title banner inside `.kit-modal-header`; its symmetric 72px side reserves keep the title visually centered and clear of the close control. Budget modal width as the desired title/banner width plus both 72px reserves plus the panel's left and right padding. This deliberately makes closable modals a little wider than tightly fitted body content.
* **Art shadows**: `box-shadow` follows a rectangular border box. For irregular or nine-sliced kit art, put `.kit-bg--shadow` on the actual backing `img` so the shadow follows its painted alpha. Do not put the filter on `.kit-modal`, because that would include the modal's text and child art in the shadow silhouette.
* **Buttons**: text is white with a **colour outline** complementing the button art — never black. Put a plain label directly in `.kit-btn-label` so it paints above the art and receives the kit's 5px optical baseline offset. For icon-plus-text content, put both inside a direct `.kit-btn-content` child so the pair receives that offset together. Use `shiny_buttons` for purchases and special interactions, `basic_buttons` for everything else, and give text generous padding. The grey button is the disabled look.
* **Body text**: subtle 20%-opacity outline (`.kit-text-body`) on colour modals; plain dark text (`.kit-text-body-dark`) on white/grey modals.
* **Tabs**: a pill row *inside* the modal body, not attached to the top edge. Put copy in `.kit-tab-label`. Active tab uses a colour art variant (e.g. `tabs_blue`) with a matching text outline; inactive tabs use `tabs_black`. Use `tab_med.png` or `tab_large.png` for dynamic labels. The `tab_small.png` source files are inconsistent and some contain baked labels, so they are intentionally not nine-sliced.
* **Progress bars**: each `progress_bar_N` folder pairs a `backing.png` with a purpose-built `fill_*.png`, but the interior offsets differ by family and are often asymmetric because of the lower rim/drop shadow. Track art goes in `.kit-bg`; the matching family fill goes in `.kit-progress-fill`, which uses `object-fit: fill`; add the matching `.kit-progress--N` modifier to the container and bind `data-style-image-fill-amount`. Do not substitute a tinted icon or decorative transparent image: tint preserves source alpha, and `cover` can crop square art into gaps or diagonal wedges on a thin track. Preview the bar at `0`, `0.25`, `0.5`, and `1`; current diagnostics do not detect unsuitable texture alpha. The default component is 40px thick; add `.kit-progress--compact` for the proportionally scaled 30px form. For a custom thickness, set equal `font-size` and `height` values on the container so its em-based family insets scale with it. Kit tracks use `flex-shrink: 0`; choose the thickness explicitly instead of relying on a flex parent to compress the track, which can make the track and its fill resolve at different sizes.
* **Item slots**: colour squares (`inv_square_1.png`) for filled slots; `inv_square_empty2.png` is the designed EMPTY state.
* **Modal family art shares one scale** (37px corners, 6px outline in source pixels — the shipped slice insets already account for this). Pieces meant to composite, like a header band over a modal, align because they are drawn at the same scale; do not hand-edit individual slice values.
## Example: settings modal
Stripe modals (`modal_stripe_*`) carry a darker footer band — seat the action row on it by keeping it the last flow child.
```html
