Page tree
Skip to end of metadata
Go to start of metadata

Table of Contents


  • Functionality must be delivered incrementally
  • Deliver capabilities with a dedicated project team
  • Convert edX applications to be responsive on mobile
  • Document and adopt a modern, consistent set of front end best practices
  • Provide an implementation and examples of using the UX team's revamped patterns
  • Provide reusable components embodying best practices to accelerate development
  • All components and patterns will be performant and accessible
  • Support theming of Open edX applications by site operators
  • Enable adoption by the Open edX developer community
  • i18n

Proposed Plan

Have a dedicated team applied that is large enough to make rapid progress.

Milestone 0: Reach agreement on the approach

  • Develop and agree fundamental approach to meeting stated goals above
  • Perform an audit of a handful of representative pages
    • at least a couple of Pattern Library pages and older pages
    • estimate the scope of the effort to update the pages
    • make recommendation as to pages to convert in milestone 1
  • Revise OEP-11:
  • Work with cross-functional team to finalize workflow
    • UX team owns the pattern library
    • Engineering owns the implementation of both the patterns and reusable components
    • A11y team owns the accessible behavior of patterns and reusable component
  • Upon completion:
    • OEP-11 is accepted
    • Community outreach to explain the purpose of the plan and to receive feedback
    • Develop a presentation for the engineering org
    • Create epics and stories for subsequent milestones
    • Staffing requirements will be decided
    • Names will be decided!
  • Open questions
    • Break OEP-11 into smaller pieces?


  • 1 sprint, 2 developers

Milestone 1: First Usage of Bootstrap 

  • See the results from the Bootstrap spike: Bootstrap spike findings
  • Choose between Bootstrap 3 and Bootstrap 4
  • Implement two Bootstrap themes: a vanilla (Open edX) theme, and an theme
    • Must eat our own dog food to ensure that theming is feasible for the community
    • Open question: 
  • Convert a page to use the new approach
    • A Studio page
    • An LMS page
    • A marketing site page
  • Convert a region of an existing page to use the new approach
    • Add to a Studio page
    • Add to an LMS page
    • Add to a marketing site page
    • This requires that the existing CSS doesn't clash with the Boostrap CSS


  • Demonstrated conversion of old and new pages using Bootstrap
  • Have two Bootstrap themes
  • Unlock development of reusable components
  • Unlock conversion of static and/or server-side edX application pages
  • Document process and cost of converting a page


  • 3 developers, 3 sprints

Open Questions

  • What is a good page to convert first?
    • Pick a page that doesn't have a lot of rich client-side requirements
      • We don't want to have to rewrite a lot of Backbone for this milestone
    • It might make sense to start with a marketing site page for a number of reasons
      • It is less disruptive as LMS already has two different CSS versions
      • It is a simpler code base than trying to integrate with LMS
    • Another option would be to pick an LMS pattern library page, e.g. certificates
  • Where should any JavaScript code go? UI Toolkit? New repo?
  • What happens with existing client-side code in pages that are converted?
    • Presumably it should be left as it is
    • Don't take on a large client-side refactoring before reusable components are available

Milestone 2: First Usage of Reusable Components

  • See Ari Rizzitano's proposal: Idea: UI toolkit modernization
    • Update UI Toolkit to support ES2015 and React
  • Build a single reusable component (e.g. forms) to prove out reusable components
  • Consume the reusable component as follows:
    • Used on a marketing site page
    • Used on a Studio page
    • Used on a non-Pattern Library LMS page
    • Used on a Pattern Library LMS page?
      • Maybe the effort would be better spent converting the page


  • 3 developers, 3 sprints


  • Demonstrate the ability to use reusable components in edX applications
  • Unlock conversion of rich client-side applications to use Bootstrap
  • Document process and cost of building a reusable component
  • Document process and cost of upgrading a page to support reusable components


  • Figuring out interaction between reusable components with existing pages (use web fragments?) 
  • How do the best practices keep up with changes in the JavaScript space?
  • We should build our solutions with the need to change in mind

Definition of Done

Needs fleshing out

  • need to consider which pages are under active development when choosing them for conversion
  • develop documentation for the community
  • create and give presentation both within edX and at Open edX conference

Open questions

  • does the dedicated team finish after milestone 2?
  • if not, how many pages should be converted before letting other teams take over?
    • choose just the high priority pages to convert
    • work with feature teams to help them do the conversion?
    • testing risk if converting a page that the team is not familiar with
  • is the dedicated team responsible for building an initial set of reusable components?

Future Initiatives

Initiative 1: Upgrade Studio

  • TBD


  • Studio reaches full a11y compliance
  • Studio is fully responsive

Initiative 2: Upgrade LMS

  • Implement ES2015 support in platform
  • Convert pages in priority order (see Highest Priority Pages below)
  • Implement the pages using existing reusable components, or introduce new ones as required
  • Ensure all converted pages are fully responsive, localizable, and accessible (preferably through use of reusable components)
  • Ensure all converted page support comprehensive theming


  • LMS is fully responsive

Highest Priority Pages

The Open edX code base is very large, so this modernization plan will need to be incremental. The best approach seems to be to focus on two areas:

The following is a provisional recommendation for the list of pages to convert in priority order:


Traffic Rank

RationaleEffort (S/M/L)Notes

Home PageMako2Traffic, ThemingMUsed by white label and Open edX sites ( has a custom marketing site)

DiscussionsPattern Library
4Programs DashboardPattern Library5Traffic, UpgradeSHigh impact page that also uses the v1 Pattern Library

Web CertsPattern Library

WhitelabelPattern Library

CoursewareMako7TrafficLShould be implemented as part of the Course Outline feature
5Learner DashboardMako1TrafficLShould consider rebuilding as a more pluggable page

Course About PageMako
ThemingMNot used by

Course Info PageMako6Traffic

1Login PageMako3Traffic, ThemingSTop priority as high traffic and key page for theming
2Registration PageMako4Traffic, ThemingSTop priority as high traffic and key page for theming

Course Catalog PagesMako

Account Settings PageMako8TrafficM

Progress PageMako9TrafficM
3Password Reset PageMako10TrafficSShould be completed at the same time as login and registration

Open Questions

When will Bootstrap 4 be ready for adoption?

It is currently (as of November 2016) in alpha, but with a first beta release imminent. Given the amount of work necessary, it should at least be available as a beta in time.

Here's the Bootstrap 4 Beta 1 ship list:


  • a11y
  • RTL
  • theming
  • performance
  • responsive
  • extensibility / ease of overriding
  • modularity / scoping
  • Open edX community interest
  • how active is the library community?
  • integration with build systems
  • integration into existing pages

Appendex 1: 2016 status

  • UI Toolkit 1.0 released
    • API documentation:
    • Safe template utilities
    • Backbone paginated collections
    • Backbone views
      • Dropdown menu
      • Breadcrumbs
  • Pattern Library beta released
    • Living style guide published:
    • Fully responsive grid system
    • Accessible buttons, colors, icons
  • Modernization of edx-platform libraries
    • Upgraded to more modern versions of JQuery, Backbone, Backbone.Paginator, Underscore, RequireJS, Sinon
    • Improved test infrastructure by upgrading Jasmine, Jasmine JQuery, Sinon, and migrated to Karma from home grown JS-Test-Tool
    • Switched over to ESLint and published an edX rule set:
  • Pattern Library adoption within edx-platform
    • Implemented per-page ability to use Pattern Library
    • Pages converted:
      • Discussions
      • Web Certificates
    • New pages:
      • Programs
    • Pre-existing pages adapted to use Pattern Library shims
      • CAPA alerts
      • Buttons
  • Challenges in 2016
    • UX team Pattern Library champions left edX
    • The pace of front end modernization at edX in 2016 is too slow to see the desired benefits to developers
      • This was a natural fall-out from this being a background task for just a few teams
      • We expected to see all of engineering drive this forward but it didn't work out that way
    • No development resources to implement new shared components
      • Intention was that new functionality would be created as components but only one new component has been added
    • No technical documentation resources available to document the edX libraries
    • New user interfaces are not being built as plugins
      • XBlocks are being created by very few teams if at all
      • Instead new code is directly added to the edx-platform monolith
      • Programs was initially implemented as an external plugin, but subsequently was reverted to code in platform
    • the community is struggling with theming their instances
    • we need to update almost all of Studio and the instructor dashboard to make them accessible

Appendix 2: Why Bootstrap now?

  • Bootstrap 4 is the first version to support key requirements for the existing edX style guide
    • adoption of Sass for stylesheets (previous versions used Less)
    • a more flexible grid system that supports the types of layouts that edX requires
    • use of ems and rems for responsive typography
  • The edX front end community will benefit from using an industry standard
  • There are a large set of components available implemented in both JQuery and React
  • Theming works across all components, including those that will be added by the Open edX community
  • Many documented examples of sites using Bootstrap with both Backbone and React
  • Vast resources for documentation and training

See Also

  • No labels


  1. Andy Armstrong  I think the goals could be clearer that there are 2 things being developed here;

    1. CSS that implements UX's Pattern Library that can be/will be rolled out across the site quickly
    2. Reusable JS components that can be/will be rolled out across edx-platform gradually
  2. Andy Armstrong so far only edx-platform is mentioned (LMS, Studio, Open edX) but I assume both the theming solution and reusable components are intended to be able to be used in any edX IDA.

  3. Andy Armstrong in the interests of adding incremental value and reduced time to market I don't think we should rule out Backbone components. We are already proposing a combined Backbone/React approach so it may be worth considering delivering some high value components in Backbone, then swapping them out with React components.