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.

• --source-tokens-only: Include only source design tokens in the build.

• -t, --themes: Specify themes to include in the token build.

Example:

4. replace-variables

This command allows you to replace the SCSS variable's usages or definitions with CSS variables and vice versa in .scss files. You can specify the file or directory where the replacements should be made using the filePath parameter. Additional options include:

• -s, --source: Type of replacement: usage or definition.

• -t, --replacementType: Type of replacement: usage or definition.

• -d, --direction: Map direction: css-to-scss or scss-to-css.

Example:

5. build-scss

This command compiles Paragon's core and themes SCSS into CSS. You can customize the compilation process using various options:

• --corePath: Path to the theme's core SCSS file.

• --themesPath: Path to the directory that contains themes' files.

• --outDir: Directory where the resulting CSS files will be output.

• --defaultThemeVariants: Default theme variants.

Example:

6. help

You can display help for any specific command by using the help command followed by the command name.

Example:

Start your MFE application

1. Load up your MFE on your machine with npm start and open it in a browser. Your MFE should start, with identical styles as before prior to the upgrade.

2. Verify the styles (e.g., for a Button) in the devtools are now showing as using CSS variables instead of hardcoded values.

3. If you notice any style issues or discrepancies between the previous look and feel, please file a Github issue and/or reach out in the Paragon Working Group Slack channel.

   1. Work with your squad’s designer(s) to ensure no style regressions.