fix: brand overrides

docs: fix code example

docs: add missing comma

docs: update how to

Author: adamstankiewicz

docs/how_tos/theming.md

@@ -6,19 +6,25 @@ This document serves as a guide to using `@edx/frontend-platform` to support MFE
 
 ![overview of paragon theme loader](./assets/paragon-theme-loader.png "Paragon theme loader")
 
-## Theme URL configuration
+## Basic theme URL configuration
 
-Paragon supports 2 mechanisms for configuring the Paragon theme URLs:
+Paragon supports 2 mechanisms for configuring the Paragon theme urls:
 * JavaScript-based configuration via `env.config.js`.
 * MFE runtime configuration API via `edx-platform`
 
 Using either configuration mechanism, a `PARAGON_THEME_URLS` configuration setting must be created to point to the externally hosted Paragon theme CSS files, e.g.:
 
 ```json
 {
-    "core": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.css",
+    "core": {
+        "url": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css"
+    },
     "variants": {
-        "light": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.css"
+        "light": {
+            "url": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css",
+            "default": true,
+            "dark": false,
+        }
     }
 }
 ```
@@ -32,16 +38,22 @@ To use this JavaScript-based configuration approach, you may set a `PARAGON_THEM
 ```js
 const config = {
     PARAGON_THEME_URLS: {
-        core: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/paragon.css',
+        core: {
+            url: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
+        },
         variants: {
-            light: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/scss/core/css/variables.css',
+            light: {
+                url: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
+                default: true,
+                dark: false,
+            },
         },
     },
 };
+
 export default config;
 ```
 
-
 ### MFE runtime configuration API
 
 `@edx/frontend-platform` additionally supports loading application configuration from the MFE runtime configuration API via `edx-platform`. The configuration is served by the `http://localhost:18000/api/mfe_config/v1` API endpoint. For more information, refer to [this documentation](https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst) about the MFE runtime configuration API, please see these docs.
@@ -52,12 +64,18 @@ The application configuration may be setup via Django settings as follows:
 ENABLE_MFE_CONFIG_API = True
 MFE_CONFIG = {}
 MFE_CONFIG_OVERRIDES = {
-    # `APP_ID` defined in your MFE
+    # The below key represented the `APP_ID` defined in your MFE
     'profile': {
         'PARAGON_THEME_URLS': {
-            'core': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.css',
+            'core': {
+                'url': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
+            },
             'variants': {
-                'light': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.css',
+                'light': {
+                    'url': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
+                    'default': True,
+                    'dark': False,
+                },
             },
         },
     },
@@ -66,11 +84,57 @@ MFE_CONFIG_OVERRIDES = {
 
 ### Locally installed `@edx/paragon`
 
-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 fallback to injecting the locally installed Paragon CSS from the consuming application into the HTML document.
+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.:
+
+```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
+```
+
+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`
+
+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.
 
-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.:
+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.
+
+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.
+
+To enable `@edx/brand` 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',
+            },
+        },
+        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: true,
+                dark: false,
+            },
+        },
+    },
+};
+
+export default config;
+```
+
+### Locally installed `@edx/brand`
+
+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.:
 
 ```shell
-https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.css
-https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/scss/core/css/variables.css
+https://cdn.jsdelivr.net/npm/@edx/brand@$brandVersion/dist/core.min.css
+https://cdn.jsdelivr.net/npm/@edx/brand@$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.