Scaling the Paragon design system's theming and styles architecture with design tokens


In collaboration between 2U and Raccoon Gang, we would like to share an update on an ongoing project intended to help scale the styles architecture for the design system and React UI component library for the Open edX platform (Paragon).

Paragon is utilized by all React micro-frontends (and some legacy UIs) across the Open edX platform. Paragon is responsible for providing these applications with an extensible theme representing the desired look-and-feel of a custom brand (e.g., colors, typography, spacing, layout, etc.).

However, as the Open edX platform continues to move to independently deployed micro-frontends (MFEs), there are some scaling issues with how Paragon theme is managed. For example, the Paragon theme relies on SCSS variables which much be compiled at build time whenever a change is made to the theme. After rebuilding, the application must then be re-deployed to production for the theme to be updated for users. Having to re-build each MFE on any theme change is non-trivial, especially as more and more micro-frontends are created throughout the Open edX platform.

By moving Paragon to design tokens via the tool style-dictionary, we will be re-defining style properties (SCSS variables) as proper design tokens represented in JSON. The benefit of using such a tool as style-dictionary is that it can be configured to transform design tokens to support many different platforms and output formats. To start, we are transforming design tokens as CSS variables and re-working the core Paragon theme and its React components to use those CSS variables.

The result is that when the theme changes, only the theme needs to get re-built rather than needing to re-build all the consuming micro-frontend applications like how it is today. The output CSS file from the theme re-build could be hosted on a CDN and consuming MFEs can point to it. As such, when the theme changes, only the CSS file needs to get re-built, and its changes would be instantly applied across the platform.

In the future, the design tokens may be transformed into other platforms to bring the Paragon design system to the iOS and Android mobile applications or even the Figma design tool, for example.

This is a significant (and breaking) change to Paragon’s current styles/theming architecture and approach, but we feel it sets the Paragon design system up for longer term success with a more extensible theming system for its applications.

We have been actively working on migrating Paragon over to the design tokens approach for the last few months. You may install the current (in-progress) design tokens release by running npm i @edx/paragon@alpha into a consuming micro-frontends. The end result is that the micro-frontend should look exactly the same but, under-the-hood, it’s using CSS variables instead of SCSS variables, thus enabling runtime theming.

Please refer to the following Architectural Decision Record (ADR) for more details:

We are looking forward to your questions and feedback! :smile:


This is a great step forward. Thanks for the write-up, @AdamStankiewicz, and here’s to the swift adoption of Design Tokens!

1 Like