DRAFT |
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. |
TODO: docs/resources/context Some potential ideas:
|
Requirements:
OR
|
Import the compiled Paragon CSS into the SCSS entry point of your MFE.
// Within `src/index.scss` of your MFE @use "@openedx/paragon/dist/core.min.css" as paragonCore; @use "@openedx/paragon/dist/light.min.css" as paragonLight; // If using `@edx/brand` to customize the default Paragon theme, also include: @use "@edx/brand/dist/core.min.css" as brandCore; @use "@edx/brand/dist/light.min.css" as brandLight; // include the remaining SCSS for the MFE, now with access to the // CSS variables defined in Paragon. |
I believe it may still be an open question on how consumers relying on locally installed Paragon CSS in this manner will be able to take advantage of a future @openedx/paragon/dist/dark.min.css to account for theme switching.
@import "@openedx/paragon/dist/light.min.css" (prefers-color-scheme: light);
@import url("@openedx/paragon/dist/dark.min.css") (prefers-color-scheme: dark);
Using the externally hosted Paragon CSS via @edx/frontend-platform (see below) comes with a mechanism, i.e. const { paragonTheme: { setThemeVariant } } = useContext(AppContext);, to build a theme variant switcher baked in.
I believe it may still be an open question on how consumers relying on locally installed Paragon CSS in this manner will be able to take advantage of a future @openedx/paragon/dist/dark.min.css to account for theme switching.
@import "@openedx/paragon/dist/light.min.css" (prefers-color-scheme: light);
@import url("@openedx/paragon/dist/dark.min.css") (prefers-color-scheme: dark);
Using the externally hosted Paragon CSS via @edx/frontend-platform (see below) comes with a mechanism, i.e. const { paragonTheme: { setThemeVariant } } = useContext(AppContext);, to build a theme variant switcher baked in.
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 the PARAGON_THEME_URLS in your MFE configuration (you can use either of the approaches explained below).
Example:
{
"MFE_CONFIG_OVERRIDES": {
"<APP_ID>": {
"PARAGON_THEME_URLS": {
"core": {
"urls": {
"default": "https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css"
}
},
"defaults": {
"light": "light",
"dark": "dark"
},
"variants": {
"light": {
"urls": {
"default": "https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css"
}
},
"dark": {
"urls": {
"default": "https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/dark.min.css"
}
}
}
}
}
}
} |
Configuration approaches:
Import custom media breakpoints from Paragon into the SCSS entry point of your MFE.
// Within `src/index.scss` of your MFE @use "@openedx/paragon/styles/css/core/custom-media-breakpoints.css" as paragonCustomMediaBreakpoints; // If using `@edx/brand` to customize the default Paragon theme, also include: @use "@edx/brand/paragon/css/core/custom-media-breakpoints.css" as brandCustomMediaBreakpoints; |
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.
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.
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:
// src/index.scss @import "@my-brand/fonts.scss"; @import "@my-brand/variables.scss"; // Import the Paragon core after setting brand-themed variables. @import "@openedx/paragon/scss/core/core.scss"; // Import brand overrides after the Paragon core. @import "@my-brand/overrides.scss"; |
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:
// Within `src/index.scss` of your MFE
@use "@openedx/paragon/styles/css/core/custom-media-breakpoints.css" as paragonCustomMediaBreakpoints;
@use "@openedx/brand/paragon/css/core/custom-media-breakpoints.css" as brandCustomMediaBreakpoints;
@media(--min-pgn-size-breakpoint-md) {
.my-element {
color: red;
}
} |
There should be a drop-in replacement design token and CSS variable for every previous SCSS variable available via Paragon. For example:
$primary-500 -> var(--pgn-color-primary-500) |
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.
There is a mapping of Deprecated -> Relevant component:
CheckBox --> Form.Checkbox CheckBoxGroup --> Form.CheckboxSet RadioButtonGroup --> From.RadioSet Fieldset --> cannot be fully replaced, docs say that this component is not needed anymore. Instead just use Form.Group, Form.Row and Form.Col to group form fields Input, InputSelect, InputText --> Form.Control ListBox --> SelectableBox Modal --> ModalDialog StatusAlert --> Alert Table --> DataTable ValidationFormGroup --> Form.Group |
Removed from components:
IconButton
Icon
SearchField
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:
paragon install-theme --theme @custom/brand-theme@latest |
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:
paragon migrate-to-openedx-scope . |
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:
paragon build-tokens --build-dir ./styles/css |
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:
paragon replace-variables -p src -t usage paragon replace-variables -p src -t definition |
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:
paragon build-scss --corePath ./styles/scss/core/core.scss --themesPath ./styles/css/themes --outDir ./dist/css --defaultThemeVariants light |
help
You can display help for any specific command by using the help command followed by the command name.
Example:
paragon help paragon help build-tokens |
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.