# Host-Adaptation Stylesheets (anti-bleed CSS)

> > Scope: the per-platform/per-theme stylesheets under assets/css/hosts/ — how they load, what > belongs in them, and their naming convention · Last reviewed:…

Source: CBX documentation, version 4.0 preview (unreleased). Canonical page: https://docs.configbox.at/docs/4.0-preview/technical/host_stylesheets. Last updated 2026-08-25.

---
> **Scope:** the per-platform/per-theme stylesheets under `assets/css/hosts/` — how they load, what
> belongs in them, and their naming convention · **Last reviewed:** 2026-08-02

**Who this is for:** anyone fixing a host-CSS bleed into CBX output, or adjusting host chrome
around CBX, on any of the supported platforms.

CBX renders inside a host shell it does not control — the Joomla administrator, wp-admin, the
Magento backend, a site's frontend theme. Those shells ship their own global CSS, and some of it
**bleeds** into CBX output: a host rule matches an element inside `.cb-content` and out-guns
CBX's own stylesheet, either by specificity or simply by loading later. The reverse also needs
handling: sometimes CBX must adjust the host's chrome around itself (hide a host page title,
paint the page background, fix a z-index against the host's menu).

Both concerns live in one mechanism: **host-adaptation stylesheets** under `assets/css/hosts/`,
loaded conditionally per **platform**, **area** (admin/site) and — where the host has interchangeable
themes — the **active host theme**. All paths in this doc are relative to
`docroot/components/com_configbox/`.

---

## 1. How the loading works

```
KenedoView::getStyleSheetUrls()                          external/kenedo/classes/KenedoView.php
  └─ KenedoPlatform::p()->getHostStyleSheetUrls()        per-platform, InterfaceKenedoPlatform
       └─ KenedoPlatform::buildHostStyleSheetUrls([...]) external/kenedo/classes/KenedoPlatform.php
```

- **`getHostStyleSheetUrls()`** is an `InterfaceKenedoPlatform` method. Each platform class
  (`external/kenedo/platforms/<platform>/general.php`) decides which stylesheet *base names* apply to
  the current request and passes them to the shared resolver.
- **`KenedoPlatform::buildHostStyleSheetUrls($baseNames)`** maps each base name to
  `assets/css/hosts/<baseName>.css` and returns full URLs **only for files that exist**. That makes
  theme-specific files optional by design: a platform can always probe for
  `joomla-admin-<template>.css` and nothing happens until someone creates the file.
- **`KenedoView::getStyleSheetUrls()`** appends the host stylesheets **after** all regular CBX
  stylesheets (so the anti-bleed counters win the source-order battle against everything of ours) and
  **before** `custom.css` (so per-site customization keeps the last word). Because this sits in the
  regular view-stylesheet pipeline, the files load correctly on full page loads *and* XHR-injected
  views, get the `.min.css` twin substitution, and get cache busting — same as every other view
  stylesheet.

## 2. Naming convention

```
assets/css/hosts/<platform>-<area>[-<theme>].css
```

| File | Loaded when |
|---|---|
| `joomla-admin.css` | Joomla backend, any admin template |
| `joomla-admin-atum.css` | Joomla backend when the active admin template is Atum (the J4/J5 default). The platform probes `joomla-admin-<template>.css` with the lowercased template name, so e.g. a `joomla-admin-fancyadmin.css` would load on installs using that template — create the file and it works. |
| `joomla-admin-isis.css` | Joomla backend when the active admin template is Isis (the J3 default) |
| `wordpress-admin.css` | wp-admin (single theme — WP's admin colour schemes only re-tint accents, so no theme variant is probed) |
| `wordpress-site.css` | WordPress frontend requests rendering a CBX view (block-theme bleed fixes) |
| `magento-admin.css` | **Legacy — nothing can load it.** The base name says Magento 1, but no M1 platform exists (`external/kenedo/platforms/` holds `joomla`, `magento2`, `standalone`, `wordpress`) and the Magento 2 platform passes only `magento2-admin`/`magento2-site` (`platforms/magento2/general.php:499-508`), so no code path ever resolves this file. Kept on disk as inherited history; delete-candidate. |
| `magento2-admin.css` | Magento 2 backend (the `Magento/backend` theme is fixed) |
| `magento2-site.css` | Magento 2 storefront requests rendering a CBX view. Carries the same `--cbx-rem: 16px` declaration as the admin file. It is stated in **px, not rem**, precisely because the site theme is interchangeable and Magento themes disagree on the root font-size: Blank/Luma descendants set `html { font-size: 62.5% }` (1rem = 10px) while **Hyvä** leaves it at 16px. An absolute value is correct under either, where a relative `1.6rem` is correct only under the first and lands at 25.6px on the second. Everything else in this file must still hold for any theme. |

Standalone returns no host stylesheets — there is no host chrome to adapt to.

## 3. What belongs in a host stylesheet (and what does not)

**Belongs here:**

- **Anti-bleed counters** — re-assertions of CBX's intended values against a host rule that
  wins. Example (Atum): `.table tbody a:not(.badge):not(.btn):not(.dropdown-item)` re-colours and
  underlines CBX list links at specificity (0,5,2) and loads after our CSS;
  `joomla-admin-atum.css` counters it with one extra `.cb-content` class of specificity, using the
  same `--bs-*` / `--cb-*` tokens so light and dark mode both stay correct.
- **Host-chrome adjustments** — hiding the host's page title around CBX, painting the admin
  page background (`--cb-body-bg`), z-index fixes against host menus/toolbars. Hide *decoration*
  only: a rule that removes host **navigation** (top bar, user menu, link back to the site) strands
  the admin inside CBX, and a selector broad enough to be theme-neutral will eventually match
  a theme where the element is navigation rather than decoration. Scope those to the one theme they
  were written for — that is what the `-<theme>` file is for.
- **Platform-conditional UI hiding** — settings groups a given host doesn't use (e.g. Magento 2
  supplies maintenance mode and pricing itself, so `magento2-admin.css` hides CBX's own groups;
  the model property definitions reference the file).

**Does not belong here:**

- Platform-neutral admin styling — that is `admin.css` / `admin-theme.css` territory.
- Rules CBX needs on *every* platform, even when a `platform-*` body class would make the
  selector work everywhere. If it always loads, it is not host adaptation.
- Engine/feature CSS (configurator, editors, properties) — those have their own stylesheets.

**Writing a counter-rule well:** state *which host rule* you are countering and *why it wins*
(specificity or source order) in a comment; scope under `.cb-content`; prefer `inherit` or the
`--bs-*` / `--cb-*` tokens over hardcoded values so both colour schemes keep working.

## 4. History / provenance

- Before this mechanism, host fixes sat in labelled sections inside `admin.css`
  (`/* Joomla admin CSS changes - START */` …) and shipped to every platform. Those sections moved
  verbatim into the corresponding `hosts/` files; only genuinely platform-neutral rules stayed in
  `admin.css`.
- The WordPress adapter plugin used to enqueue its own `assets/css/adapter.css` (site-area
  block-theme fixes; the "rudimentary" predecessor of this system). Its rules are folded into
  `hosts/wordpress-site.css` and the adapter no longer enqueues anything — see the note in the
  adapter's `configbox.php`. One behavioural nuance: `adapter.css` loaded on *every* front-end
  request; `wordpress-site.css` loads with CBX views (which is where its rules matter).
- The colour-scheme side of host alignment (light/dark, `data-bs-theme`) is a separate mechanism:
  `assets/css/admin-theme.css` + `getAdminColorScheme()`, documented in
  [`com_configbox_admin_theming.md`](https://docs.configbox.at/docs/4.0-preview/technical/admin_theming). Host stylesheets consume those
  tokens but do not define any.

## 5. See also

- `../customization/com_configbox_assets_and_amd.md` — the asset pipeline these files ride
  (view stylesheets, `.min.css` twins, cache busting) and how a site adds its own CSS/JS,
  including `custom.css` (which deliberately loads *after* the host stylesheets).
- `../customization/com_configbox_admin_ui_migration.md` — the admin markup/CSS class changes a
  counter-rule targets; read it before writing selectors against admin markup.
- [`com_configbox_admin_theming.md`](https://docs.configbox.at/docs/4.0-preview/technical/admin_theming) — the admin light/dark/auto token
  layer (`--cb-*`) that host stylesheets consume: how each platform resolves the scheme, the full token
  set, and the rules for custom admin CSS.