[← Back to Home](Home)

# Custom Themes

MokoOnyx ships with **standard** light and dark palettes. You can create fully custom colour palettes by overriding CSS variables in dedicated files.

---

## How It Works

1. MokoOnyx loads a theme CSS file based on the `colorLightName` and `colorDarkName` template parameters
2. When set to **Standard**, it loads `light.standard.css` or `dark.standard.css`
3. When set to **Custom**, it loads `light.custom.css` or `dark.custom.css`
4. The theme file sets all CSS variables inside `:root[data-bs-theme="light"]` or `:root[data-bs-theme="dark"]`

---

## Creating a Custom Palette

### Step 1: Copy the Template

MokoOnyx ships starter templates in the `templates/` directory within the template source:

```
templates/mokoonyx/templates/light.custom.css
templates/mokoonyx/templates/dark.custom.css
```

These are full copies of the standard palettes -- every variable is included so you have a complete starting point.

### Step 2: Place Files in the Media Directory

Copy your customized files to the **media** directory (this location survives template updates):

```
media/templates/site/mokoonyx/css/theme/light.custom.css
media/templates/site/mokoonyx/css/theme/dark.custom.css
```

### Step 3: Select "Custom" in Template Settings

1. Go to **System → Site Templates → MokoOnyx**
2. Open the **Theme** tab
3. Under **Variables & Palettes**:
   - Set **Light Theme** to **Custom**
   - Set **Dark Theme** to **Custom**
4. Save

---

## File Locations

| File | Path | Purpose |
|------|------|---------|
| Light standard | `media/templates/site/mokoonyx/css/theme/light.standard.css` | Built-in light palette (do not edit) |
| Dark standard | `media/templates/site/mokoonyx/css/theme/dark.standard.css` | Built-in dark palette (do not edit) |
| Light custom | `media/templates/site/mokoonyx/css/theme/light.custom.css` | Your custom light palette |
| Dark custom | `media/templates/site/mokoonyx/css/theme/dark.custom.css` | Your custom dark palette |
| Light template | `templates/mokoonyx/templates/light.custom.css` | Starter template (copy from here) |
| Dark template | `templates/mokoonyx/templates/dark.custom.css` | Starter template (copy from here) |

---

## Key Variables to Customize

The most impactful variables to change for a quick rebrand:

```css
:root[data-bs-theme="light"] {
    /* Brand colours -- the foundation of the entire palette */
    --color-primary: #112855;
    --accent-color-primary: #3f8ff0;
    --accent-color-secondary: #6fb3ff;

    /* Body */
    --body-color: #22262a;
    --body-bg: #fff;

    /* Links */
    --color-link: #224FAA;
    --link-color: #224faa;
    --link-hover-color: #424077;

    /* Navigation */
    --mainmenu-nav-link-color: white;
    --nav-text-color: white;
    --nav-bg-color: var(--color-link);

    /* Header */
    --header-background-color: #adadad;
}
```

See the [CSS Variables](CSS-Variables) page for a complete reference of all available variables.

---

## Variable Sync on Update

When MokoOnyx is updated, the installer runs a **CSS variable sync** process. If new variables have been added to the standard palettes, they are automatically appended to your custom palette files with their default values. A notice is displayed in the admin panel telling you how many variables were added.

This ensures your custom palettes stay compatible with new template features without breaking existing customizations.

---

## Custom CSS and JavaScript

For additional overrides beyond theme variables, use these files (also update-safe):

| File | Path |
|------|------|
| Custom CSS | `media/templates/site/mokoonyx/css/user.css` |
| Custom JS | `media/templates/site/mokoonyx/js/user.js` |

---

*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*

---

*Repo: [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |