This document is a work in progress

Table of Contents

Background

This document captures reported challenges with using comprehensive theming in the Eucalyptus release, along with some initial recommendations as to how matters might be improved.

Use Cases

Use case 1: Changing fonts

Quote from Florian Haas (Unlicensed):

How do we change the default sans-serif font from the default `"Open Sans" ,Verdana, Geneva, sans-serif`? ... My goal is being able to select my preferred sans-serif font myself, rather than being locked into Open Sans. That, quite frankly, seemed like a trivial goal but it now seems like a Herculean task. I'm still hoping that the actual difficulty is somewhere *between* trivial and Herculean.

Having the Ability to change fonts, as a user setting, particularly for paragraph text, would be beneficial to some learners who have reading difficulties. Ideally changes would be persistent across courses.

Ability to override text display characteristics (line height, space following paragraphs, letter spacing, word spacing) is a WCAG 2.1 AA requirement. I assume this could be accomplished through custom user stylesheets but a user settings UI would be much more likely to be used.

Use case 2: Managing the color palette

Quote from J'aime Ohm:

I’m theming an iOS application based on a themed web application and our front-end web developer is out today. I’m interested in quickly gleaning the color palette and fonts used in this application. Can someone tell me if there is a central/primary “colors” or “fonts” or similar file in edx-platform?

WCAG 2.1 AA color luminance contrast requirements are a crude heuristic that probably makes a site usable to a the vast majority of people who have print reading ability. However, enabling learner customization could take us a step closer to universal usability. For example, some learners would prefer light blue or yellow text on a black background. Some learners may have difficulty seeing any yellows or reds (not necessarily related to to red/green anomaly.)

High Contrast Mode in Windows and in Chrome (through Google's supported High Contrast extension) is frequently useful but not necessarily optimal. A brand-optimized High Contrast mode theme may be a step up for usability.

WCAG 2.1 has color luminance contrast requirements for infographics that may prove to be difficult to implement just because they constrain the available design space too much. A learner-selectable line pattern/color scheme system might allow more freedom for designers by supporting learner flexibility in the presentation. Example: WCAG 2.1 constrains the designer to (I'm guessing) 4 line colors for a line chart. With use of 3 or 4 line styles in addition to colors, the designer could still have as many as 16 colors available to use. Learners who have color contrast perception issues could switch to the High Contrast chart/infographics palette.

Use case 3: Overriding JavaScript templates

Quote from jjmirandad:

Talking about frustration. Its possible to use .underscore templates in theme folder??? How its this possible, because in all my test this files its loading from lms/templates!

Quotes from MIke Bifulco:

the underscore template thing really is a surprise. That means that several pages on thegymnasium.com will have a significant regression in theme functionality when we move from Birch→Dogwood/Eucalyptus

and:

I'm surprised [logistration] made it through to production without considering theming

Use Case 4: Theming the wiki

It has been reported that comprehensive theming does not work for the wiki. This appears to be because the wiki uses Django Templates, while comprehensive theming works with Mako.

CRI-53 - Getting issue details... STATUS

Challenges

Mako templating is badly implemented

themes don't gracefully inherit from main platform because of a recursive bug (possible fix: https://github.com/Stanford-Online/edx-platform/pull/535/files)
difficult to arbitrarily inject html from a theme

edX platform Sass is poorly structured

The current platform Sass has a lot of duplication of fonts and colors making it very difficult to change every usage
There is a whole host of color variables in the SASS (probably too many), but the lms SASS doesn't use them consistently
When new features are added, they add yet more duplication, and so the themes become broken
The Pattern Library has variables for the fonts that can be overridden once, but very few pages are using it so far

Pages are a mixture of pattern library and non-pattern library

The pattern library was intended to simplify the process of theming
Unfortunately the current partial migration means that the old styles must be themed and then the Pattern Library must be themed too
The v1 and v2 naming convention is not clearly explained for scss files

The pattern library is inconsistent about how theming is supported

Recent changes to the color palette broke the ability to provide a single base theme color
The pattern library is itself not consistent about using variables to allow for simple overriding
The pattern library does not have an example theme that demonstrates that all the patterns can be themed
There is an epic to resolve these issues:
- FEDX-235 - Getting issue details... STATUS

JavaScript templates cannot be overridden using comprehensive theming

Comprehensive theming works with the Django Pipeline to override Mako templates
Underscore files are bundled into JavaScript files and so are not affected by the pipeline

It isn't clear how to ensure that themes work with both LTR and RTL files

Some advice has folks overriding lms-main-v1.scss but that won't affect the RTL version

Platform is not responsive

some people may want to do it through theming, but it's not powerful enough to do so

Compiling assets with multiple themes is very slow

Currently 19 minutes of an edxapp production build is spent gathering assets for themes
9 minutes of sandbox builds (possibly more, measurement is less precise here) is spent on this (fewer themes)
This impacts developer velocity

Note that you can use the --themes options with paver update_assets to specify only the themes you would like to compile to speed up the development cycle.

paver update_assets lms --themes=example

Theme integration into the build process is opaque

The intersection of edx-microsites.git and edx-themes.git in the build process is very unclear

Recommendations

Update the example theme to demonstrate all the use cases
- This example theme should work for pattern library pages as well as for legacy pages
- The process of implementing some of these (e.g. changing the font family) will expose the issues
Make extensive use of variables in Sass, rather than hard-coding colors, fonts etc into every file
- This means that the variable can be overridden once, rather than having to override every file.
- These variables would themselves be documented so that their purpose is clear for theme authors
Update the pattern library documentation to include an example theme
Address any issues with theming the pattern library
Convert major pre-existing pages to the pattern library
Use the pattern library for all new front end features
Determine an approach for overriding JavaScript templates
- A long term solution is to use HTTP/2 and then stop bundling JavaScript files
- Maybe there could be a way to build theme versions of each JavaScript bundle (or at least those that have overridden templates)
Make an OEP that describes how to create themable front end interfaces
The default theme should be the only theme within edx-platform. EdX should dogfood theming by applying edx.org's themes through the same mechanisms as the rest of the community.
Extend the set of themed variables to include settings needed to support WCAG 2.1 AA requirements.
Implement a Dark Mode (not necessarily High Contrast) with any theme.
Prompt the learner to automatically switch to Dark Mode if they have the OS in Dark Mode (once detection from the browser becomes possible).
Implement a toggle for Dark Mode in the LMS learner settings.
Implement a standard edX High Contrast theme (possibly independent of the Dark Mode of the regular theme, though they could be the same).
Prompt the learner to automatically switch to High Contrast theme if they are in High Contrast mode (Windows or Chrome).
Implement UI for learner customization of text and color attributes for Headings, paragraphs (particularly as needed for WCAG 2.1 conformance), interactive elements, and charts/infographics.

Browser not supported