Skip to main content
Version: 4.0 preview

Host-Adaptation Stylesheets (anti-bleed CSS)

Version
4.0 preview
Updated
View markdown

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
FileLoaded when
joomla-admin.cssJoomla backend, any admin template
joomla-admin-atum.cssJoomla 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.cssJoomla backend when the active admin template is Isis (the J3 default)
wordpress-admin.csswp-admin (single theme — WP's admin colour schemes only re-tint accents, so no theme variant is probed)
wordpress-site.cssWordPress frontend requests rendering a CBX view (block-theme bleed fixes)
magento-admin.cssLegacy — 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.cssMagento 2 backend (the Magento/backend theme is fixed)
magento2-site.cssMagento 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. 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 — 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.
Last updated on