Migrating MFEs to Paragon design tokens and CSS variables
DRAFT
Overview
Paragon, the design system and React UI component library for the Open edX platform, now supports design tokens and CSS variables.
The design tokens are currently published under an alpha distribution channel on NPM, i.e. @openedx/paragon@alpha
.
Getting Started
TODO: docs/resources/context
Some potential ideas:
Brief description of design tokens (a few sentences)
Link to
style-dictionary
(docs)
Link to ADR
Create & link to the Paragon docs site page with a list of design tokens (TBD)
Create & link to the Paragon docs site page with a list of CSS variables (TBD)
Migration guide
Using locally installed Paragon CSS
Import the compiled Paragon CSS into the SCSS entry point of your MFE.
Using externally hosted Paragon CSS
Configure external Paragon CSS URLs (e.g., from a hosted CDN).
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 thePARAGON_THEME_URLS
in your MFE configuration (you can use either of the approaches explained below).
Example:Configuration approaches:
Import custom media breakpoints from Paragon into the SCSS entry point of your MFE.
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:
Each MFE had to re-compile Paragon’s SCSS whenever a theme change was made.
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:
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:
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:
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:
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:
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:
help
You can display help for any specific command by using the help command followed by the command name.
Example:
Start your MFE application
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.Verify the styles (e.g., for a
Button
) in the devtools are now showing as using CSS variables instead of hardcoded values.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.
Work with your squad’s designer(s) to ensure no style regressions.
I think we replace this sentence with
“Configure the
PARAGON_THEME_URLS
in your MFE configuration (you can use either of the approaches explained below)“Let me know your opinion