Adapt supports user-defined themes, a special kind of plugin that lets you style your course in a variety of ways. Themes are written in Less — all CSS syntax is supported, plus variables and nested rules. Templates use JSX (recommended for new work) or Handlebars (still supported).

A basic theme, adapt-contrib-vanilla, is included in the framework's src/theme folder. Visit the Vanilla wiki for a detailed exploration of its structure and styles.

Only one theme is included in a build at a time. To switch to a different theme, uninstall the current one and install the new one:

adapt uninstall adapt-contrib-vanilla
adapt install some-other-theme
grunt build

The theme's LESS files are organised into four directories:

• _defaults/ — Variables and mixins (start here for customisation)
• core/ — Styles for built-in UI elements (navigation, drawer, notify, pages, blocks, etc.)
• plugins/ — Plugin-specific style overrides, one subdirectory per plugin
• project/ — Course-level customisation (per-project block, component, and page overrides)

Simple customisation is possible by changing the built-in variables in Vanilla's less/_defaults/ folder. This directory contains all configurable variables for colours, fonts, spacing, animations, and button styles.

For example, open less/_defaults/_colors.less and change the base colour definitions:

@blue: #DC143C;

Save your file, rebuild the course, and preview in your browser. Elements that reference @blue — such as headings, interactive items, and menu borders — now appear in crimson. Continue to modify the remaining variables in _defaults/ for further customisation.

@validation-error and @validation-success control the colours used for incorrect and correct answer feedback. Choose colours with strong contrast to ensure they attract the learner's attention.

The framework defines responsive breakpoint variables — @device-width-small, @device-width-medium, @device-width-large, and @device-width-xlarge. Use these in media queries to ensure your styles respond at the same breakpoints as the rest of the framework:

@media (min-width: @device-width-medium) {
  .my-element {
    padding: 0.5rem;
  }
}

Spacing variables are split across two files in _defaults/:

• _spacing-config.less — Margins, padding, and border radius for UI elements such as buttons, items, navigation, drawer, notify, and text margins at every content level (page, article, block, component)
• _spacing-containers.less — Container-level sizing and padding for pages, articles, blocks, components, menu items, and the drawer width

Font variables are split across two files in _defaults/:

• _font-config.less — Font families, weights, sizes, and line heights for all content levels (page titles, article/block/component headings, body text, buttons, icons, navigation labels, etc.)
• _font-mixins.less — Reusable typography mixins for applying consistent font styles

The navigation bar is fixed to the top of the browser window and contains icon buttons for features like back navigation and drawer access. Customise its colours through the @nav variables in _defaults/_colors.less (e.g. @nav, @nav-inverted, @nav-icon-hover). For structural changes, edit core/nav.less.

The drawer is a panel that slides out from the right of the browser window, used by extensions like Resources and Glossary. Customise its colours through the @drawer variables in _defaults/_colors.less (e.g. @drawer, @drawer-inverted, @drawer-item-hover). For structural changes, edit core/drawer.less.

Notify handles modal pop-ups such as question feedback dialogs. Customise its colours through the @notify variables in _defaults/_colors.less (e.g. @notify, @notify-inverted, @notify-btn-hover). For structural changes, edit core/notify.less.

Adapt uses an IcoMoon-generated icon font. Unlike the other styles on this page, icons are defined in the framework core rather than the theme, at src/core/less/_defaults/icons.less. Each icon is mapped to a class name (e.g. .icon-tick, .icon-chevron-right) with its Unicode code point. Icon size is controlled by the @icon-size variable. See the Vanilla Icons wiki page for the full list of available icons.

Buttons appear throughout Adapt — submit buttons on questions, menu item buttons, navigation icons, etc. Button colours and spacing are controlled through variables in _defaults/ (e.g. @btn-color, @btn-color-hover, @btn-padding), with dedicated mixins in _defaults/_buttonMixins/ for each UI area. For structural changes, edit core/button.less.

Adapt templates are stored in the framework at core/templates/ or in associated plugins at adapt-pluginName/templates/. Most templates now use JSX (since Framework v5.12.0), though some older components may still use Handlebars. Templates can be overridden in a theme by creating a file with the same name in adapt-themeName/templates/ (e.g. templateName.jsx or templateName.hbs).

It's important to understand how Adapt renders these templates before changing them significantly. For example, the block template contains a component-container element — removing it or changing the class name would mean that components would no longer render.

In JSX templates, use conditional rendering ({value && <element/>}) to ensure only the HTML that needs to be displayed is rendered. In Handlebars templates, use helpers for the same purpose.

The theme JavaScript files found in the js folder should be used to add any additional theming that cannot be done using just templates and CSS (.jsx/.hbs and .less). For example, you could add JavaScript to fade in an image when the page loads.

It's strongly recommended that the theme shouldn't be setting any attributes on Backbone models; you can, however, use classes if, say, you want an effect on a particular page.

You can use the core events to add an effect on, say, a page postRender event.

Place any assets required for your theme to display correctly in the assets folder. Any course related assets should be placed in the course folder (src/course/en/*) rather than here. Consider providing smaller sized assets for mobile devices to keep page weights down.

Next - Developing plugins