From ed293e30b17f5eb0ce084a19343672e9d6ce717e Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Tue, 14 May 2024 10:31:21 +1000 Subject: [PATCH] docs: update scope of paragon and brand for openedx --- docs/how_tos/theming.md | 86 ++++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/how_tos/theming.md b/docs/how_tos/theming.md index c7ff08084..c0ddda10a 100644 --- a/docs/how_tos/theming.md +++ b/docs/how_tos/theming.md @@ -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. @@ -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 @@ -49,14 +49,14 @@ 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", } } } @@ -64,31 +64,31 @@ Using either configuration mechanism, a `PARAGON_THEME_URLS` configuration setti ### 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 @@ -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', }, }, }, @@ -130,14 +130,14 @@ 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', }, }, }, @@ -145,34 +145,34 @@ MFE_CONFIG_OVERRIDES = { } ``` -### 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: { @@ -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', }, }, }, @@ -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.