The Future of Simple Theme

Discussions - Public
1

I’ve been working on a couple of theming-related tasks together, and it’s made me question the approach I was taking towards Simple Theme.

This sprint I was working on a write-up about theming as a guide to theming the platform using design tokens. I was also working on fixing Simple Theme for Teak and finally, I was working on bringing design tokens to Simple Theme.

Simple Theme was originally designed as a comprehensive theme for edx-platform; however, when MFE added support for branding packages for theming MFEs, I worked on making it a hybrid package that can work as both a comprehensive theme and a branding package. This worked well enough, but now the MFE theming mechanism is undergoing another major change.

Our current system involves configuring theming variables in Grove, which are then compiled to a SCSS file with variables which is then used to compile a theme, which is then installed in edx-platform and the MFEs. The relevance of edx-platform as a frontend is waning. There is little to no UI it provides anymore. As I began implementing yet another layer on Simple Theme, making is a combination of Comprehensive Theme, Branding Package, and Design token Package, all of which work very differently and and broadly incompatible it started to make less sense.

At this point, there is a lot of code in Simple Theme that was implemented for a client we no longer have. There are features there that no client uses as far as I am aware. Given the nature of CSS and the platform it’s very hard to even judge bits of the theme that are no longer in use.

With that said, what I’m proposing is as follows:

  • We freeze the current simple theme as the version of install for edx-platform. There will likely be no changes to edx-platform that would require updating simple theme other than dropping more UI code, so we can avoid further work here.
  • For the MFE we refactor the theme as a Design Token package. This will work with Teak and beyond.

When I say refactor the theme, what I mean is we drop all prior compatibility and focus only on design tokens. We drop unnecessary optional code that isn’t used by any client.

I think working on writing a guide to design tokens, which would direct people to the best way to use them, made me realise that what I was implementing for Simple Theme was the opposite of that. I would love to hear everyone’s thoughts on this.

7 Likes
2

Makes sense to me.

3

This sounds quite reasonable. :+1:

This could even be an entirely new repository from scratch. Then we can retain and archive the “legacy” (edx-platform <= sumac) edx-simple-theme.

4

Some of the code will be retained so I feel it doesn’t make sense to throw away the entire history.

5

I’ve been going through simple theme and how clients use is, and it seems like a lot of the features are simply not in use. Since upgrading to design tokens will require reimplementing some of this CSS, this is a good time to get rid of that cruft and only reimplement it if if comes from a client requirement in the future.

A lot of what the simple theme was overriding is now directly possible through tokens but there are some specific things that will be removed. I will list them here and if anyone feels like one or more of these features should not be removed do tell me so I can ensure that they continue to be supported.

List of removed features:

  • All SCSS variables will be removed; all changes will apply via tokens
  • You can no longer specify the font size or weight for primary and secondary buttons.
  • You can no longer specify the border width for primary and secondary buttons
  • You can no longer customise the sign in or register buttons

I didn’t see any of these features in use by clients. Once everything is settled I’ll create a guide for using design tokens for overriding the things we currently do using SASS variables in grove.

3 Likes
6

@kshitij it is amazing that you started work on this! Would it be possible to make sure the new theme is compatible with Picasso? Example repo: GitHub - eduNEXT/ednx-saas-themes

7

@gabor Sorry for not responding sooner. I personally didn’t find the approach Picasso uses to align very well with how I wanted simple theme to work.

The original goal of simple theme was I think to reduce maintenance burden across upgrades. With design tokens and plugin slots that is now part of the core platform, so I don’t see as much need for simple theme at all. However, we still need a simple theming mechanism that allows us to just provide a few theme variables and have that reflect on the site. For that, I’ve now created a new tutor plugin ‘grove-simple-theme’ as part of the grove plugin collection.

With this new mechanism, creating a new simple theme can be done directly from the theme config as follows:

GROVE_THEMES:
  core:
    size.border.radius.base: 0
    size.border.radius.lg: 0
    size.border.radius.sm: 0
  light:
    color.btn.bg.primary: '#aabbcc'
    colors:
      brand: '#ff0080'
      primary: '#00ffaa'

With this change tutor will now pull in the simpel theme repo, copy over the token variable build the theme and deploy it. This works well for single theme instance but can also potentially work for instances that need multiple themes. It will deploy the theme with the MFE and you can then use the MFE config API to simply change the default theme for each instance.

1 Like
8

The new Simple Theme is here! All PRs are merged, except for one small upstream PR that will simplify some things.

In my own spare time and partially just to explore it, I wrote up a frontend customisation guide in the form of an interactive text. You can check it out here. If it’s useful I’ll look into improving it, or alternatively incorporating it into more traditional documentation.

6 Likes
9

@kshitij

Thanks for all the work here. I will check it out soon to try and understand how the new themes structure works.

However for now though, the new changes seems to break Grove based deployments with a couple of issues:

  1. Grove still expects the legacy file structure which it fails to find if the instance is configured to use the master branch of edx-simple-theme.
    As a temporary workaround, I created this branch: kaustav/legacy_theme, which can be used till fixes are pushed in Grove. Not sure if we want to invest time in fixing Grove now though, since its about to be deprecated. If not, we could continue to use my branch till we move to the new stack.

  2. MFE builds seems to be failing when the newly introduced build steps are executed out of turn. See this failed job (private ref).

1 Like
10

The new version of simple theme is ONLY for MFEs. For comprehensive theming, you should use prior branches. Once we’re at the next release we can remove the code for install simple theme as a branding package as well.

So basically Grove will deal with an older release branch of Simple Theme, and the Simple Theme plugin will deal with the newer versions.

I will fix this ASAP. I think for now we can exclude the simple theme plugin from being used unless explicitly enabled. Also it (hopefully temporarily) needs a build step that grove will not perform. It’s a pretty small fix. CC: @Fox

1 Like