Skip to content

Commit

Permalink
docs: update scope of paragon and brand for openedx
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcoa
dcoa committed May 14, 2024
1 parent df3c939 commit ed293e3
Showing 1 changed file with 43 additions and 43 deletions.
86 changes: 43 additions & 43 deletions docs/how_tos/theming.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Theming support with `@edx/paragon` and `@edx/brand`
# Theming support with `@openedx/paragon` and `@openedx/brand-openedx`

## Overview

This document serves as a guide to using `@edx/frontend-platform` to support MFE theming with Paragon using theme CSS loaded externally (e.g., from a CDN).

To do this, configured URLs pointing to relevant CSS files from `@edx/paragon` and (optionally) `@edx/brand` are loaded and injected to the HTML document at runtime. This differs than the consuming application importing the styles from `@edx/paragon` and `@edx/brand` directly, which includes these styles in the application's production assets.
To do this, configured URLs pointing to relevant CSS files from `@openedx/paragon` and (optionally) `@openedx/brand-openedx` are loaded and injected to the HTML document at runtime. This differs than the consuming application importing the styles from `@openedx/paragon` and `@openedx/brand-openedx` directly, which includes these styles in the application's production assets.

By serving CSS loaded externally, consuming applications of Paragon no longer need to be responsible for compiling the theme SCSS to CSS themselves and instead use a pre-compiled CSS file. In doing so, this allows making changes to the Paragon theme without needing to necessarily re-build and re-deploy all consuming applications.

Expand All @@ -26,11 +26,11 @@ If your use case necessitates additional variants beyond the default supported `

There is also a meaningful improvement in performance as loading the compiled theme CSS from an external CDN means micro-frontends (MFEs) can include cached styles instead of needing to load essentially duplicate theme styles included in each individual MFE as users navigate across the platform.

However, as the styles from `@edx/paragon` and `@edx/brand` get loaded at runtime by `@edx/frontend-platform`, the associated CSS files do not get processed through the consuming application's Webpack build process (e.g., if the MFE used PurgeCSS or any custom PostCSS plugins specifically for Paragon).
However, as the styles from `@openedx/paragon` and `@openedx/brand-openedx` get loaded at runtime by `@edx/frontend-platform`, the associated CSS files do not get processed through the consuming application's Webpack build process (e.g., if the MFE used PurgeCSS or any custom PostCSS plugins specifically for Paragon).

### Falling back to styles installed in consuming application

If any of the configured external `PARAGON_THEME_URLS` fail to load for whatever reason (e.g., CDN is down, URL is incorrectly configured), `@edx/paragon` will attempt to fallback to the relevant files installed in `node_modules` from the consuming application.
If any of the configured external `PARAGON_THEME_URLS` fail to load for whatever reason (e.g., CDN is down, URL is incorrectly configured), `@openedx/paragon` will attempt to fallback to the relevant files installed in `node_modules` from the consuming application.

## Technical architecture

Expand All @@ -49,46 +49,46 @@ Using either configuration mechanism, a `PARAGON_THEME_URLS` configuration setti
```json
{
"core": {
"url": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css"
"url": "https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css"
},
"defaults": {
"light": "light",
},
"variants": {
"light": {
"url": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css",
"url": "https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css",
}
}
}
```

### Configuration options

The `PARAGON_THEME_URLS` configuration object supports using only the default styles from `@edx/paragon` or, optionally, extended/overridden styles via `@edx/brand`. To utilize `@edx/brand` overrides, see the `core.urls` and `variants.*.urls` options below.
The `PARAGON_THEME_URLS` configuration object supports using only the default styles from `@openedx/paragon` or, optionally, extended/overridden styles via `@openedx/brand-openedx`. To utilize `@openedx/brand-openedx` overrides, see the `core.urls` and `variants.*.urls` options below.

The `dark` theme variant options are optional.

| Property | Data Type | Description |
| -------- | ----------- | ----------- |
| `core` | Object | Metadata about the core styles from `@edx/paragon` and `@edx/brand`. |
| `core.url` | String | URL for the `core.css` file from `@edx/paragon`. |
| `core.urls` | Object | URL(s) for the `core.css` files from `@edx/paragon` CSS and (optionally) `@edx/brand`. |
| `core.urls.default` | String | URL for the `core.css` file from `@edx/paragon`. |
| `core.urls.brandOverride` | Object | URL for the `core.css` file from `@edx/brand`. |
| `core` | Object | Metadata about the core styles from `@openedx/paragon` and `@openedx/brand-openedx`. |
| `core.url` | String | URL for the `core.css` file from `@openedx/paragon`. |
| `core.urls` | Object | URL(s) for the `core.css` files from `@openedx/paragon` CSS and (optionally) `@openedx/brand-openedx`. |
| `core.urls.default` | String | URL for the `core.css` file from `@openedx/paragon`. |
| `core.urls.brandOverride` | Object | URL for the `core.css` file from `@openedx/brand-openedx`. |
| `defaults` | Object | Mapping of theme variants to Paragon's default supported light and dark theme variants. |
| `defaults.light` | String | Default `light` theme variant from the theme variants in the `variants` object. |
| `defaults.dark` | String | Default `dark` theme variant from the theme variants in the `variants` object. |
| `variants` | Object | Metadata about each supported theme variant. |
| `variants.light` | Object | Metadata about the light theme variant styles from `@edx/paragon` and (optionally)`@edx/brand`. |
| `variants.light.url` | String | URL for the `light.css` file from `@edx/paragon`. |
| `variants.light.urls` | Object | URL(s) for the `light.css` files from `@edx/paragon` CSS and (optionally) `@edx/brand`. |
| `variants.light.urls.default` | String | URL for the `light.css` file from `@edx/paragon`. |
| `variants.light.urls.brandOverride` | String | URL for the `light.css` file from `@edx/brand`. |
| `variants.dark` | Object | Metadata about the dark theme variant styles from `@edx/paragon` and (optionally)`@edx/brand`. |
| `variants.dark.url` | String | URL for the `dark.css` file from `@edx/paragon`. |
| `variants.dark.urls` | Object | URL(s) for the `dark.css` files from `@edx/paragon` CSS and (optionally) `@edx/brand`. |
| `variants.dark.urls.default` | String | URL for the `dark.css` file from `@edx/paragon`. |
| `variants.dark.urls.brandOverride` | String | URL for the `dark.css` file from `@edx/brand`. |
| `variants.light` | Object | Metadata about the light theme variant styles from `@openedx/paragon` and (optionally)`@openedx/brand-openedx`. |
| `variants.light.url` | String | URL for the `light.css` file from `@openedx/paragon`. |
| `variants.light.urls` | Object | URL(s) for the `light.css` files from `@openedx/paragon` CSS and (optionally) `@openedx/brand-openedx`. |
| `variants.light.urls.default` | String | URL for the `light.css` file from `@openedx/paragon`. |
| `variants.light.urls.brandOverride` | String | URL for the `light.css` file from `@openedx/brand-openedx`. |
| `variants.dark` | Object | Metadata about the dark theme variant styles from `@openedx/paragon` and (optionally)`@openedx/brand-openedx`. |
| `variants.dark.url` | String | URL for the `dark.css` file from `@openedx/paragon`. |
| `variants.dark.urls` | Object | URL(s) for the `dark.css` files from `@openedx/paragon` CSS and (optionally) `@openedx/brand-openedx`. |
| `variants.dark.urls.default` | String | URL for the `dark.css` file from `@openedx/paragon`. |
| `variants.dark.urls.brandOverride` | String | URL for the `dark.css` file from `@openedx/brand-openedx`. |

### JavaScript-based configuration

Expand All @@ -100,14 +100,14 @@ To use this JavaScript-based configuration approach, you may set a `PARAGON_THEM
const config = {
PARAGON_THEME_URLS: {
core: {
url: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
url: 'https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css',
},
defaults: {
light: 'light',
},
variants: {
light: {
url: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
url: 'https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css',
},
},
},
Expand All @@ -130,49 +130,49 @@ MFE_CONFIG_OVERRIDES = {
'profile': {
'PARAGON_THEME_URLS': {
'core': {
'url': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
'url': 'https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css',
},
'defaults': {
'light': 'light',
},
'variants': {
'light': {
'url': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
'url': 'https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css',
},
},
},
},
}
```

### Locally installed `@edx/paragon`
### Locally installed `@openedx/paragon`

If you would like to use the same version of the Paragon CSS urls as the locally installed `@edx/paragon`, the configuration for the Paragon CSS urls may contain a wildcard `$paragonVersion` which gets replaced with the locally installed version of `@edx/paragon` in the consuming application, e.g.:
If you would like to use the same version of the Paragon CSS urls as the locally installed `@openedx/paragon`, the configuration for the Paragon CSS urls may contain a wildcard `$paragonVersion` which gets replaced with the locally installed version of `@openedx/paragon` in the consuming application, e.g.:

```shell
https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css
https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css
https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css
https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css
```

In the event the other Paragon CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN url throws a 404), `@edx/frontend-platform` will attempt to fallback to injecting the locally installed Paragon CSS from the consuming application into the HTML document.

## Usage with `@edx/brand`
## Usage with `@openedx/brand-openedx`

The core Paragon design tokens and styles may be optionally overriden by utilizing `@edx/brand`, which allows theme authors to customize the default Paragon theme to match the look and feel of their custom brand.
The core Paragon design tokens and styles may be optionally overriden by utilizing `@openedx/brand-openedx`, which allows theme authors to customize the default Paragon theme to match the look and feel of their custom brand.

This override mechanism works by compiling the design tokens defined in `@edx/brand` with the the core Paragon tokens to generate overrides to Paragon's default CSS variables, and then compiling the output CSS with any SCSS theme customizations not possible through a design token override.
This override mechanism works by compiling the design tokens defined in `@openedx/brand-openedx` with the the core Paragon tokens to generate overrides to Paragon's default CSS variables, and then compiling the output CSS with any SCSS theme customizations not possible through a design token override.

The CSS urls for `@edx/brand` overrides will be applied after the core Paragon theme urls load, thus overriding any previously set CSS variables and/or styles.
The CSS urls for `@openedx/brand-openedx` overrides will be applied after the core Paragon theme urls load, thus overriding any previously set CSS variables and/or styles.

To enable `@edx/brand` overrides, the `PARAGON_THEME_URLS` setting may be configured as following:
To enable `@openedx/brand-openedx` overrides, the `PARAGON_THEME_URLS` setting may be configured as following:

```js
const config = {
PARAGON_THEME_URLS: {
core: {
urls: {
default: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
brandOverride: 'https://cdn.jsdelivr.net/npm/@edx/brand-edx.org@#brandVersion/dist/core.min.css',
default: 'https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css',
brandOverride: 'https://cdn.jsdelivr.net/npm/@openedx/brand-openedx-edx.org@#brandVersion/dist/core.min.css',
},
},
defaults: {
Expand All @@ -181,8 +181,8 @@ const config = {
variants: {
light: {
urls: {
default: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
brandOverride: 'https://cdn.jsdelivr.net/npm/@edx/brand-edx.org@$brandVersion/dist/light.min.css',
default: 'https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css',
brandOverride: 'https://cdn.jsdelivr.net/npm/@openedx/brand-openedx-edx.org@$brandVersion/dist/light.min.css',
},
},
},
Expand All @@ -192,13 +192,13 @@ const config = {
export default config;
```

### Locally installed `@edx/brand`
### Locally installed `@openedx/brand-openedx`

If you would like to use the same version of the brand override CSS urls as the locally installed `@edx/brand`, the configuration for the brand override CSS urls may contain a wildcard `$brandVersion` which gets replaced with the locally installed version of `@edx/brand` in the consuming application, e.g.:
If you would like to use the same version of the brand override CSS urls as the locally installed `@openedx/brand-openedx`, the configuration for the brand override CSS urls may contain a wildcard `$brandVersion` which gets replaced with the locally installed version of `@openedx/brand-openedx` in the consuming application, e.g.:

```shell
https://cdn.jsdelivr.net/npm/@edx/brand@$brandVersion/dist/core.min.css
https://cdn.jsdelivr.net/npm/@edx/brand@$brandVersion/dist/light.min.css
https://cdn.jsdelivr.net/npm/@openedx/brand-openedx@$brandVersion/dist/core.min.css
https://cdn.jsdelivr.net/npm/@openedx/brand-openedx@$brandVersion/dist/light.min.css
```

In the event the other brand override CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN is down), `@edx/frontend-platform` will attempt to fallback to injecting the locally installed brand override CSS urls from the consuming application into the HTML document.

0 comments on commit ed293e3

Please sign in to comment.