Theme Build Service#

The aim of this document is to explore a new mechanism for deploying theme changes to MFEs. Since our earlier discoveries, there have a large number changes to the platform that make a lot of previous observation irrelevant. As such this document will take a fresh look at the current state and how we can automate it.

Current State of Changing Themes#

The current system for theming works differently for edx-platform and MFEs. In the case of edx-platform it requires redeploying the entire platform from scratch. It is possible to switch between multiple themes on edx-platform by having them pre-installed on the server and then switching the theme by changing the theme for a particular site.

There is also a mechanism to preview a theme by associating a preview theme with a particular user, or by passing a query string. However, there is no way to dynamically adjust the parameters of an existing theme without a lot of technical knowledge.

At this point though, edx-platform theming is for the most part irrelevant. Most of the UI is now in MFEs, especially the bits that are user-focussed.

As of the Teak release MFEs can now be configured with a set of URLs from which the theme can be loaded. This mechanism favours heavy reuse the CSS across MFEs isolating the customisations to variables that allow overriding different aspects of the UI.

The customisability here is rather deep, there are thousands of variables that can be turned to customise the most minute aspects. The variable --pgn-color-tab-more-link-dropdown-toggle-border-focus for instance will control the focus color of the border around the dropdown toggle displayed when a tab list overflows. If even this is not sufficient you can still customise with your own SCSS and compile it down to a common theme that all MFEs use.

Since this can be deployed to and loaded from a separate CDN, you don’t need a redeployment to change the theme either. You can simply reupload your changes and the MFEs will pick them up.

Dynamic Theming for MFEs#

The theming situation on MFEs has recently being revamped with two major upgrades.

  1. Design tokens: Design tokens enable a new mechanism for theming MFE where instead of customising SCSS variables, you instead provide a JSON file with styling overrides and this is in turn compiled to different targets. For the web it would be SCSS or CSS variables, and for mobile apps it could be iOS or Android configuration.
  2. Common external theme/runtime theme: This is a very key development that builds on top of Design tokens by loading the theme for all MFEs from a single source that can be backed by a CDN. The theme can then be replaced or updated at this common location and the theme will automatically be updated for all MFEs without rebuilding them. The runtime configuration API (which is site-aware) can return the location of the theme css, allowing different sites to have different themes and also runtime replacement of themes.

Using these both we get a much simplified mechanism for theming MFEs. We can create a system that automatically build a new CSS variable file based on configured variables, and upload this to a CDN. In fact the file doesn’t even need to be on a CDN, it can be generated at runtime and served at a URL provided to the MFEs.

Dynamic Theming on edx-platform#

The work being done to introduce dynamic theming to MFEs can also be expanded to edx-platform, however this will likely need a lot of work since Paragon in MFE is soon to move to v23 while the platform is still at v2. Given that most UI has already migrated to MFEs it is likely not worth the effort.

Ideally if this is done, the platform will also load the theme from the same CDN, and replacements to the theme there will update the theme in the platform.

Theming flow#

  • We create a custom theme with customised design tokens. (Example MOE’s 50 themes for sites)
  • These customisations are built using the tools in Paragon to produce a CSS theme. (Example MOE’s CI setup to auto-build themes)
  • This file is uploaded to the CDN at a pre-configured location.
  • MFEs will automatically is configured to load the theme from this location.
  • If there are multiple sites, we build a different branding CSS for each of them and put it in their place in the CDN which is configured for each site.

Next steps#

For using runtime theming with clients we can move away from Grove building the theme to the theme being build using a CI using the copy of the simple theme repo which should have gitlab scripts for the same. It will simply need to be configured to deploy to the location configured for the particular instance.

Over time we can look into dropping some of the custom SCSS code we carry in the simple-theme repo since Paragon is quite felxible now. We can upstream some of the customisation hooks into Paragon instead.

For example, we have some custom code to allow changing the backgroud color of the header and footer. We can now push these to the header and footer components such that the simply theme needs only to supply a variable override. Likewise for the header border etc.