Theming and white-labeling

The CCX UI reads every colour it draws from a CSS custom property. To re-brand the UI you publish a small stylesheet that restates the properties you want to change, and point FE_EXTERNAL_CSS_URL at it. No application changes are needed, and a complete brand theme is typically 30–50 lines of CSS.

ccx:
  services:
    uiapp:
      env:
        FE_EXTERNAL_CSS_URL: "https://example.com/branding/acme.css"
        FE_REACT_APP_LOGO_URL: "https://example.com/branding/logo.svg"
        FE_REACT_APP_FAVICON_URL: "https://example.com/branding/favicon.png"

How the stylesheet is loaded

The URL is loaded as an ordinary <link rel="stylesheet"> and appended last in the document head when the application starts. Two consequences are worth knowing:

Your file needs no CORS headers. It is linked, not fetched, so any static host (S3, a CDN, your own web server) works as-is.
You never need !important. The application's own styles live in CSS cascade layers; your stylesheet does not. Unlayered author styles win over layered ones regardless of selector specificity, so a plain declaration in your file always takes effect.

If CCX is served over HTTPS, the stylesheet must also be served over HTTPS — browsers block mixed content and the file will silently fail to load.

The supported surface: theme tokens

These custom properties are the supported customisation surface. Everything in the UI derives its colour from them.

Token	Light default	Dark default	Controls
`--background`	`#ffffff`	`#171717`	Page background
`--foreground`	`#171717`	`#fafafa`	Default text colour
`--card`	`#ffffff`	`#262626`	Card and panel background
`--card-foreground`	`#171717`	`#fafafa`	Text on cards
`--popover`	`#ffffff`	`#262626`	Dropdown and popover background
`--popover-foreground`	`#171717`	`#fafafa`	Text in dropdowns and popovers
`--primary`	`#2b00ad`	`#7c3aed`	Primary buttons, links, active states
`--primary-foreground`	`#fafafa`	`#fafafa`	Text on primary surfaces
`--secondary`	`#f5f5f5`	`#3a3a3a`	Secondary buttons
`--secondary-foreground`	`#262626`	`#fafafa`	Text on secondary surfaces
`--muted`	`#f5f5f5`	`#3a3a3a`	Muted surfaces
`--muted-foreground`	`#636363`	`#a3a3a3`	Secondary and helper text
`--accent`	`#f5f5f5`	`#3a3a3a`	Hover and highlight surfaces
`--accent-foreground`	`#262626`	`#fafafa`	Text on hover/highlight surfaces
`--destructive`	`#e5484d`	`#e5484d`	Delete actions and error states
`--destructive-foreground`	`#fafafa`	`#fafafa`	Text on destructive surfaces
`--success`	`#2b9a3f`	inherits light	Success states
`--success-foreground`	`#fafafa`	inherits light	Text on success surfaces
`--warning`	`#e5a000`	inherits light	Warning states
`--warning-foreground`	`#262626`	inherits light	Text on warning surfaces
`--border`	`#e5e5e5`	`#404040`	Borders and dividers
`--input`	`#e5e5e5`	`#404040`	Form control borders
`--ring`	`#2b00ad`	`#7c3aed`	Keyboard focus ring
`--radius`	`0.5rem`	inherits light	Corner radius (not a colour)
`--sidebar-background`	`#1a0055`	`#1a0044`	Navigation sidebar background
`--sidebar-foreground`	`#f0f0f0`	`#f0f0f0`	Navigation sidebar text
`--sidebar-accent`	`#2b00ad`	`#3a0088`	Active navigation item
`--sidebar-accent-foreground`	`#fafafa`	`#fafafa`	Text on the active navigation item
`--sidebar-border`	`#2a0078`	`#2d0066`	Sidebar dividers

Defaults are shown as hex for readability. The shipped theme declares them in oklch() with a hex fallback; your overrides may use any CSS colour syntax.

--success, --warning and --radius are not redefined for dark mode — the light value carries over. Override them in :root if you want them changed everywhere, or in :root.dark as well if dark mode needs a different value.

Light and dark mode

Users choose light, dark, or "follow system" from the user menu, so both modes will be seen. CCX signals dark mode with a dark class on the <html> element.

Put values that are the same in both modes in :root, and dark-mode overrides in :root.dark. Note the selector: :root.dark outranks both the application's own .dark block and your own :root block, so it reliably wins in both directions. A bare .dark selector does not.

Template

Copy this, replace the values, and delete the properties you do not need. Anything you omit keeps its CCX default.

/* ============================================================
   ACME white-label theme for CCX
   Loaded at runtime via FE_EXTERNAL_CSS_URL.
   ============================================================ */

/* --- Values shared by light and dark mode ----------------- */
:root {
  --primary:                   #fd822c;
  --primary-foreground:        #ffffff;
  --ring:                      #fd822c;

  --sidebar-background:        #31323d;
  --sidebar-foreground:        #f0f0f0;
  --sidebar-accent:            #fd822c;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border:            #43444f;
}

/* --- Light mode only -------------------------------------- */
:root:not(.dark) {
  --accent:                    #fff1e6;
  --accent-foreground:         #31323d;
}

/* --- Dark mode only --------------------------------------- */
:root.dark {
  --primary:                   #fd9a52;
  --primary-foreground:        #1a1a1a;
  --ring:                      #fd9a52;

  --sidebar-background:        #25262e;
  --sidebar-border:            #3a3b45;

  --accent:                    #3a2c22;
  --accent-foreground:         #ffd9bd;
}

What is not supported

The token list above is the contract. The following will break without notice and are not covered by support:

Targeting class names. Class names in the CCX UI are internal implementation detail. They change whenever a component is refactored, and they are not stable across releases.
Selectors that depend on the DOM structure — element, descendant, or positional selectors such as nav li:last-child.
Layout properties. Restrict your stylesheet to colours, and to --radius if needed. Setting display, position, width, margin, padding, overflow or similar will break the responsive layout, and the result is not supportable.
!important. It is never necessary (see How the stylesheet is loaded), and it makes problems harder to diagnose.

Migrating a stylesheet written for the previous CCX UI

Stylesheets written for the previous CCX UI do not apply to the current one. They typically target Ant Design class names (.ant-btn, .ant-spin, .ant-breadcrumb) or hashed CSS-module class names ([class*='AppHeader_'], [class*='UserMenu_']). The current UI is built on a different component library and emits none of those class names, so such a file loads successfully but has no visible effect.

Converting one is usually straightforward: take the colours out of the old file and restate them as the tokens above. A typical old stylesheet of 60–80 lines becomes 30–40 lines of tokens, and it gains dark-mode support in the process. If you have an existing stylesheet you would like converted, send it to Severalnines support and we will produce the token version for you.

Logo and favicon

The logo and favicon are set separately, and are not part of the stylesheet:

FE_REACT_APP_LOGO_URL — shown at the top of the navigation sidebar and on the login, registration and password-reset pages. An SVG scales best.
FE_REACT_APP_FAVICON_URL — the browser tab icon.

Both are described in Frontend customization.

Operational notes

Cache-busting. Browsers and CDNs cache the stylesheet. When you change it, publish under a new filename or add a version query string (acme.css?v=3) and update FE_EXTERNAL_CSS_URL, otherwise users may keep the previous version for some time.
Check contrast. Each *-foreground token must remain readable against its matching background. Aim for a contrast ratio of at least 4.5:1 for text.
Test both modes before rolling out, by switching light and dark from the user menu.
Availability. If the URL is unreachable the UI still loads and renders with the default CCX theme, so an outage on your asset host degrades branding rather than breaking the application.