I previously wrote a guide to theming using design tokens, however, since then the mechanism for using design tokens has been greatly simplified for our use cases via the simple theme plugin for Tutor.
There are some caveats to be aware of, though, so I’ll explain how everything works here.
Originally, simple theme was a comprehensive theme set up via the Ansible scripts in the configuration repo. Then it was a hybrid comprehensive theme + branding package that was set up via Grove and installed via Tutor for both MFEs and edx-platform. Now it’s only a design tokens package and the comprehensive theming bits are provided by older versions of simple theme.
What this means is that when using the new simple theme plugin that is part of the Grove Tutor plugin, you need to do a few things.
Use an older version of simple theme in the grove.yml file. So in the themes configured via grove.yml set COMPREHENSIVE_THEME_VERSION to release/teak or some other older version.
Do not set GROVE_COMPREHENSIVE_THEME_BRAND_PACKAGE_NAME. This was designed for the branding package version of simple theme.
Enable the grove-simple-theme plugin. For compatibility, all other grove plugins are automatically enabled when you enable the grove plugin. However, since this conflicts with existing functionality, it needs to be explicitly enabled.
Configure the theme design tokens via GROVE_THEMES as explained here.
Note that core is a special base theme on which you can layer any number of other themes. The default theme is called light, however you can have other names as long as you also configure the theme via the MFE config API as described here. You’d just need to see the “default” key there. This can also be used to build multiple themes and then set different defaults for different sites.
Note, this mechanism doesn’t use a CDN, the theme is build with the MFE and hosted from the same place.
Expand for more details on decisions made
When branding packages were introduced for MFEs they shared many things in common with the old comprehensive theming mechanism. Both allowed customising the theme by changing SCSS variables or, in extreme cases, adding custom SCSS. As such, I was able to build a hybrid theme package that could be used as both a comprehensive package (which is what the original simple theme was) and a branding package for MFEs.
With design tokens though, MFEs are configured in a very different way than edx-platform, as such maintaining both mechanism in the same codebase didn’t make much sense. So now the simple theme repo is purely a design tokens package. Older versions of simple-theme are still there and are still usable as a comprehensive theme. The edx-platform is unlikely to require major changes to the way comprehensive themes work so we can use old frozen version of simple theme with those.
The original “simple theme” comprehensive theme was entirely set up by the configuration repo. However, with the move to Tutor and Grove, it now needed two tools. Grove would set up the comprehensive theme and inject the variables we wanted, and Tutor would then set up this theme in the instance.
As MFEs move to design tokens, though, we are also moving away from Grove, so it did not make too much sense to continue building the theme via Grove. So the new plugin does everything via tutor.
Ah got it, but how do we use this with the grove-simple-theme plugin? Do we have more docs? opencraft / dev / tutor-contrib-grove · GitLab shows how to set some theme variables inline, but how do we use an external repo?
I find this a little confusing - do you have examples of what this looks like with Grove/Tutor?
Because the comprehensive theming bits mostly remain unchanged over releases since edx-platform doesn’t see new UI development.
Whatever theme variables/overrides etc are needed for edx-platform need to be set here. You might not even need this if the theme isn’t customised since simple theme always defaults to the vanilla platform anyway. For clients where this is configured, it can be left untouched if using a custom source repo, or set to use the teak branch. AFAIK this now only affects small bits of the course instructor dashboard and XBlocks.
The values are not ignored, they should work as always until we switch away from grove, after that I don’t know.
I’m not sure what you mean by external repo? External repo for what? Do you mean a forked version of simple-theme? If so that repo should be a fork of the design tokens version. In which case you can set the GROVE_SIMPLE_THEME_REPO variable and GROVE_SIMPLE_THEME_BRANCH for the branch.
Essentially my question is, in Grove + tutor-contrib-grove, how do I say “use branch X of GitHub - open-craft/edx-simple-theme” for theming? How does the GROVE_THEMES variable with inline design token rules interact with that?
This sounds like what we need, but can this be documented please?
What do you mean by “work” though? What uses these variables now in grove, if the comprehensive theming is no longer being used since ulmo?
Likewise, what is actually needed for edx-platform overrides since ulmo?
Just so I understand, the theming part is the MFE_CONFIG[“PARAGON_THEME_URLS”] part and/or the GROVE_PARAGON_THEME_URLS? I’m struggling to understand how this relates to design tokens, the simple-theme repo, or GROVE_THEMES. Could you help clear that up?
Is the idea that we use paragon + the design tokens to build a css sheet. And this css sheet is referenced by the PARAGON_THEME_URLS above? Is there a mechanism in grove / tutor-contrib-grove / simple-theme that builds and configures that css from the provided simple-theme or inline design tokens?
Sorry for so many questions, but I’m just trying to understand how all this fits together and this will be important for the Ulmo upgrade. I think there’s opportunity for improved docs here too.
It is currently documented in the code only. I’ve started another discussion to generally improve the docs to move these from the code to readmes.
It will work in a similar way to simple theme in the past. i.e. it will take the existing repo and add the design tokens configured here to it and then build the theme.
Grove will put these variables in a SCSS file where they can be loaded by the theme and install the theme on edx-platform. Whatever bits of the UI that are served by edx-platform (e.g. instructor dashboard and XBlocks as I mentioned before) will be themed using this. For instances that don’t require theming for those, we can skip this.
Whatever customisations a client requires, such as branding colors, need to be applyed in two ways, first is the design tokens via simple theme and the other is via scss variables via this grove config. If no customisations are needed then this
In most cases you don’t need to do anything. You only need to touch MFE_CONFIG[“PARAGON_THEME_URLS”] if you have more advanced multi-theme requirements. I’ll remove this bit from the original post since it’s still untested and we can keep this focussed on standard single-theme deployments.
PARAGON_THEME_URLS is ONLY used for design-token-based themes. It tells the MFEs where to load the themes from. So in more complex setups you can build themes independent of the simple theme plugin, upload them to a CDN and configure this to tell it where to load the theme from. This is detailed in the guide I linked. The way it relates to simple theme is that that simple theme is the base theme you can configure using design tokens, and build and upload to a CDN, this was the way to do things before the simple theme plugin.
GROVE_THEMES is how you provide design tokens to tutor which will build these into toml files, install them over edx-simple-theme, and then build them and install them into MFEs. This is similar to how THEMES in grove.yml would provide variables to grove so it could build those variables into SCSS files add them to edx-simple-theme and install them into edx-platform.
If you’re using simple theme you don’t need to worry about any of that, it’s all done for you. When you add GROVE_THEMES it will use the to generate design tokens, place them in edx-simple-theme build it and install it into MFEs.
