Scaling Paragon's styles architecture with design tokens
- Adam Stankiewicz
Context
The Paragon design system provides a core theme for the Open edX platform. The theme helps give our applications a consistent look and feel universally across the platform. The theme includes things like colors, typography, spacing, and component-specific styles.
Paragon’s styles are largely built on top of and/or adapted from Bootstrap 4. Paragon modifies both Bootstrap and custom SCSS variables to create the core Open edX theme. Consumers of Paragon (e.g., edX.org) then override the core SCSS variables with custom values per their own brand requirements.
However, there are some challenges with scaling Paragon’s current approach to its styles architecture:
On theme changes, all its consuming applications must be upgraded, re-built, and re-deployed.
Because Paragon currently heavily relies on SCSS variables for its theme, when any SCSS variable(s) are changed, every application consuming that theme needs to upgrade to the new version, be re-built, and get re-deployed.
With applications needing to be rebuild/redeployed, it’s a significant effort to upgrade all applications to the new theme, especially if trying to do all applications at once.
With runtime theming, when a change is made to the theme, only the theme itself should need to get re-built, and the styles should automatically get applied to all consuming applications without needing to explicitly upgrade, re-build, and re-deploy those applications.
Supporting both system-wide themes and organizational themes.
The primary theming use case for Paragon is largely around system-wide theming, where all applications in the Open edX ecosystem share the same theme.
However, there are use cases for organizational themes, too (i.e., updating the colors for specific partners/organizations, enterprise customers, etc.).
This is not well supported today and largely requires overriding CSS classes from Paragon (anti-pattern) rather than the desired approach of overriding underlying CSS variable(s).
Dependence on Bootstrap’s internal styles.
Since Paragon is largely built on top of Bootstrap 4, it relies heavily on Bootstrap’s styles for many core aspects of Paragon themes. However, Bootstrap 4 itself doesn’t support runtime theming nor
Paragon styles are not platform agnostic nor a single source-of-truth.
The styles associated with Paragon themes are largely only accessible in environments that support SCSS as pretty much all Paragon’s style properties are baked into SCSS variables.
Ideally, the style properties would be defined in a platform agnostic way such that they can be transformed for various platforms, like iOS and Android apps or even a Figma integration.
Note: these additional platform support ideas is more of a longer-term vision for how we could extend the design tokens work further in the future.
Design tokens
Due to these challenges, we are working towards moving the style definitions for Paragon themes from SCSS variables to a JSON schema, representing design tokens. Design tokens can be thought of as the single source of truth for style values representing various design decisions across the design system (e.g., colors, typography, spacing, etc.), with the idea being that you only need to change the design token value in one place and it propagates out automatically across the platform ecosystem.
Our newly introduced JSON files representing the design tokens schema are then transformed by style-dictionary (docs) for various platforms (e.g., CSS variables, CSS utility classes, iOS/Android app compatible files, automated documentation, etc.).
Demo
Showcases current state of design tokens implementation.
Utilizes a pre-release of Paragon installed into various MFEs (
v21.0.0-alpha.7)
Next steps
Soliciting feedback from various stakeholders on the implementation (e.g., the JSON schema itself, the resulting CSS variables).
Drafting solid documentation about design tokens along with an upgrade guide.
Looking for feedback on best ways to de-risk / QA the upgrade in consuming micro-frontends (both from design & engineering perspectives) and establish a process to do so.
Seeking input on the theme authoring experience with design tokens.