|Authors||Ari Rizzitano <email@example.com>|
|Arbiter||Bill Filler <firstname.lastname@example.org>|
The Open edX community relies on the capability to customize the Open edX platform’s user interface. Providers, maintainers, and select members of the edX core contributor team all customize the appearance of Open edX instances to meet customer needs.
Over the Open edX platform’s lifetime, core contributors and community members have designed and built several systems to enable interface customization. Microsites theming , Stanford theming , and comprehensive theming  allow maintainers to modify both look-and-feel and interface content by overriding source files. The edX Pattern Library  strove to simplify the theming process by enabling stylistic overrides in a single place with mixed results . Most recently, an official move to Bootstrap styling has promised  theming simplification, but with low adoption, the initiative has not moved forward as quickly as hoped. The platform contains partial support for all these theming systems, but none is guaranteed to work consistently across the entire user interface.
None of the Open edX platform’s theming systems are officially supported or versioned. Existing theming systems attempt to cover two broad and orthogonal use cases: customizing look-and-feel (“style customization”) and modifying, adding, or removing interface elements themselves (“content overrides”). While community members rely heavily on style customization, most of the core team (with the notable exception of the White Label team) does not. Domain knowledge is sparse and siloed and documentation is poorly maintained.
Without an officially supported API, core contributors are largely unaware of what they can and cannot change. Fear of breaking existing theming systems paralyzes the core team’s ability to make crucial evolutionary changes to the platform’s frontend. Because existing theming systems rely so heavily on legacy Python template rendering, the platform frontend has been unable to evolve towards a modern, developer-friendly, client-rendered architecture, frustrating core contributors and community members alike.
Ironically, this same lack of awareness means undocumented breaking changes to theming source files still occur with every release. Without an official API, the Open edX community has no easy way to keep up with breaking changes to templates and source files, leading to widespread bugs and frustration. Many community members have abandoned Open edX’s frontend entirely in favor of building their own, indicating an absolute failure of existing theming systems for their use cases.
To guarantee continued core contributor support and full transparency to the open source community, the Open edX platform must introduce official support for both style customization and content overrides and deprecate legacy, poorly-supported systems.
Given that style customization and content overrides address separate end-user concerns and separate areas of the codebase (SASS vs. JS/HTML), they will henceforth be handled by separate systems and separate APIs. This OEP outlines proposed support for a style customization system. Content overrides will be supported as well, but will be addressed in a separate OEP. No existing theming systems will be deprecated until equivalent support exists for both style customization and content overrides.
Official support for style customization requires a more limited scope than has been allowed by prior theming systems. However, isolating customization mechanisms to a single system reduces cognitive load for both platform contributors and maintainers, facilitates communication of breaking changes, and enables bolder architectural innovation.