Overview

Paragon, the design system and React UI component library for the Open edX platform, now supports design tokens and CSS variables.

Getting Started

Migration guide

Using locally installed Paragon CSS

1. Import the compiled Paragon CSS into the SCSS entry point of your MFE.

Using externally hosted Paragon CSS

1. Configure external Paragon CSS URLs (e.g., from a hosted CDN).

   1. The quickest way to get started is to use jsDelivr, a global production-ready CDN that has deep integrations with NPM, and a $paragonVersion wildcard to rely on the same version of @openedx/paragon installed in your MFE. Configure the PARAGON_THEME_URLS in your MFE configuration (you can use either of the approaches explained below).
      Example:

      1.  

   2. Configuration approaches:

      1. JavaScript-based configuration

      2. MFE runtime configuration API

2. Import custom media breakpoints from Paragon into the SCSS entry point of your MFE.

   2. Note: you must utilize @use instead of @import with this file. The SASS team also discourages the continued use of @import, and plans to eventually remove it from the language entirely. See more information here.

Accounting for breaking changes

The design tokens release of Paragon is a complete re-architecting of Paragon’s styles system to go from sole reliance on SCSS variables to adopting an industry standard of design tokens and CSS variables. Such a large change means there are breaking changes along the way, though we’ve tried to minimize impact during the migration.

Remove all (almost) Paragon imports from the SCSS entry point in your MFE

Previously, to use Paragon’s styles in your MFE, you’d import various SCSS files from @edx/paragon in a particular order and your MFE’s build process would compile and bundle Paragon’s SCSS with your application’s CSS:

This approach had a few negative effects:

1. Each MFE had to re-compile Paragon’s SCSS whenever a theme change was made.

2. Users would need to re-download duplicate CSS from Paragon as they navigate across MFEs.

By externalizing the build process for Paragon’s SCSS, consuming MFEs can simply rely on CSS that’s already been compiled and hosted elsewhere, reducing build times and improving page performance for users by requiring less data to download over the network.

The only import from Paragon needed now is for its custom-media-breakpoints. This must be imported within your MFE in order to use the CSS media queries using Paragon’s defined breakpoints.

For example:

Replace all SCSS variables/mixins from Paragon with their CSS variables replacement

There should be a drop-in replacement design token and CSS variable for every previous SCSS variable available via Paragon. For example:

Some SCSS mixins are no longer available, so your styles may need to be refactored such that they utilize Paragon’s new CSS variables instead of the previous SCSS mixin.

Removal of previous deprecated components

There is a mapping of Deprecated -> Relevant component:

FontAwesome removal from Paragon

Removed from components:

• IconButton

• Icon

• SearchField

Paragon CLI Documentation

Paragon CLI is a powerful tool that provides various commands for working with design tokens, themes, and SCSS files. Below is a comprehensive guide on how to use the available commands.

Available Commands:

1. install-theme

This command is used to install a specific @edx/brand package. You can specify the theme to install using the theme parameter. By default, the latest version of @openedx/brand-openedx will be installed.

Example:

2. migrate-to-openedx-scope

This command is used for migrating from "@edx/paragon" to "@openedx/paragon":

• path: Path to the directory where to replace Paragon package name, default to root of the repository.

Example:

3. build-tokens

This command is used to build Paragon design tokens. You can customize the token build process using various options:

• -s, --source: Specify the source directory for design tokens.

• -b, --build-dir: Specify the build directory for the generated tokens.