Open edX theming improvements and simplification

Hi everyone,

I’m Giovanni from OpenCraft.

We faced many issues in the past when dealing with theming Open edX instances,
specially because there are so many theming systems and not all of them work in
the same way or are very consistent.

To deal with that, we built a simple theme that fixes most inconsistencies on
the platform and adds a few variables to allow easy customization and offer a
more streamlined experience for new users that is easy to customize and offers
a good amount of customizations.

We think that these improvements might help the community and offer an easy way
to customize the platform without requiring much HTML/CSS/SASS knowledge to

Now for the technical bits:

We built this theme around the Comprehensive theming system, that allows a more
direct customization to the platform’s files.

Using the same CSS selectors that exist on the platform, we have created a common,
base SASS file with all the styles with additional variables that allow us to
customize things as we need. These styles we have created are an exact copy-paste
in almost all the cases - we use the same selector and CSS property and just use
a variable there to easily override colors.

The idea is to be able to customize colors in various common parts of the interface
easily using specific SASS variables instead of having to write custom SASS
which works across two types of styling.

We did that for our simple theme, but we want to incorporate those changes into
the platform while the microfrontends and officially supported theming system lands.

We wish to have these variables merged upstream and use the configuration role
linked below to pass the variables to the platform.

Can you take a look at the PR’s and give feed back on the changes?
What to we need to change to land this?

What do you think of this idea?

Here are the links to the theme and role pull requests:

And here is an internal discovery that we did to implement this change:


@giovannicimolin This is interesting, could you please post a few screenshots of the theme in action?

@regis Sure! I’ll spawn a sandbox with some theming options and ad a few screenshots to the post before the end of the week.

1 Like

@regis Sorry for the delay. Here are a two samples of the theme:

I might not have picked the best colors, but the screenshots show what can be done using the theme.
In addition to foot and header colors, it’s also possible to:

  • Add a border with a different color on header and footer (see customize-header-border and customize-footer-border on the repo)
  • Configure the homepage hero
  • Individually pick colors for buttons on header, footer, login and courseware pages
  • Set different link and text colors for header and footer

Inconsistencies between pages themed using bootstrap and other technologies are mostly fixed.
The aim for the repo is to have the right balance of customization and ease of configuration. We want to merge these improvements upstream to help the community until the microfrontends and supported theming system are released.

If you want to check other pages, here is the link to test instance (beware of ssl certificate issue). The usual test users work staff, honor, verified, etc.

Hey @giovannicimolin! I like what I am seeing. In particular, I like the fact that you managed to customise the appearance through the use of SASS variables.
I wonder if you have given any thought to the customisation of template content? Just to pick the most obvious example, most users will want to change the “It works! Powered by Open edX©” line. I have worked on this in my own custom theme branch, but I have not found a satisfactory solution, yet.

1 Like

@regis We’re still working on a solution to that. Static pages such as TOS and privacy policy can be overwritten using SiteConfiguration (via this method). But not all elements are customizable yet.

Please post your ideas here if you find a way to include customizable, translatable text elements inside a template :slight_smile:

1 Like

I should have mentioned this earlier: we’ll have a quick demo of this theming at today’s community hangout:

1 Like

Here is the link to the presentation from the Community Hangout:

1 Like

Too bad I missed the hangout! I didn’t catch the date change, but I’ll be sure the watch the video.

Hi all,

Just to give it a signal boost, I added some comments to the PR over in GitHub:

1 Like

@djoy Thank you for the pass of comments!

CC @giovannicimolin @guruprasad who will want to chip in on the points you have brought up on the PR.

@djoy, thanks for the review and providing a lot of details on what’s being worked on and what’s in store for the future! :slight_smile:

I have replied on the PR with some concerns and questions.

@abutterworth, (CC @marcotuts) in the discussion on our PR for this -, you had mentioned that the removal of the pattern library from the platform was scheduled to be done and that eduNEXT will be working on it.

The community page for this project,, has some details but has nothing about the timelines or the expected completion dates.

We, at OpenCraft, are very much interested in the platform theming story (uniformly theming the platform across various theming and frontend systems) and would like to know if you or @Felipe have any details that you can share regarding the timelines for this work.

Hey @guruprasad, the work to remoe the pattern-library is underway and progressing very nicely.

Those community pages have been created just recently so they still don’t have much info in them.

You can see the Jira Epic here:

I circled back with the main dev on this and some of the statutes have not been changed (we don’t have access to that), but you will find comments in each of them stating the current situation.

@Felipe, thanks for the update and the link to the Jira epic. I am very happy and glad to see that the work is progressing very nicely :smiley:

@djoy, @nimisha, do we have a plan/roadmap for (comprehensively) theming the MFEs? If yes, can you share some details, references so that we can follow the progress? If no, when would be a good time and where would be a good place to start a conversation on this?

CC @braden @xitij2000, @antoviaque

@djoy, @nimisha, ping! Did you get a chance to check my question out?

@guruprasad Thank you for pinging again.

As an update:

  • completed Pattern Library deprecation: @abutterworth and @Felipe’s team have completed the effort on removing Pattern Library (per DEPR-62).

  • starting Bootstrap upgrade: They are now planning to upgrade the alpha version of Bootstrap to the latest major version (4.5.x).

  • update on Theming proposal: @abutterworth will soon post an update on his latest thoughts on MFE theming - given recent efforts and in-preparation for edX’s own rebranding efforts.