You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/how_tos/theming.md
+43-43
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
-
# Theming support with `@edx/paragon` and `@edx/brand`
1
+
# Theming support with `@openedx/paragon` and `@openedx/brand-openedx`
2
2
3
3
## Overview
4
4
5
5
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).
6
6
7
-
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.
7
+
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.
8
8
9
9
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.
10
10
@@ -26,11 +26,11 @@ If your use case necessitates additional variants beyond the default supported `
26
26
27
27
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.
28
28
29
-
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).
29
+
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).
30
30
31
31
### Falling back to styles installed in consuming application
32
32
33
-
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.
33
+
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.
34
34
35
35
## Technical architecture
36
36
@@ -49,46 +49,46 @@ Using either configuration mechanism, a `PARAGON_THEME_URLS` configuration setti
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.
67
+
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.
68
68
69
69
The `dark` theme variant options are optional.
70
70
71
71
| Property | Data Type | Description |
72
72
| -------- | ----------- | ----------- |
73
-
|`core`| Object | Metadata about the core styles from `@edx/paragon` and `@edx/brand`. |
74
-
|`core.url`| String | URL for the `core.css` file from `@edx/paragon`. |
75
-
|`core.urls`| Object | URL(s) for the `core.css` files from `@edx/paragon` CSS and (optionally) `@edx/brand`. |
76
-
|`core.urls.default`| String | URL for the `core.css` file from `@edx/paragon`. |
77
-
|`core.urls.brandOverride`| Object | URL for the `core.css` file from `@edx/brand`. |
73
+
|`core`| Object | Metadata about the core styles from `@openedx/paragon` and `@openedx/brand-openedx`. |
74
+
|`core.url`| String | URL for the `core.css` file from `@openedx/paragon`. |
75
+
|`core.urls`| Object | URL(s) for the `core.css` files from `@openedx/paragon` CSS and (optionally) `@openedx/brand-openedx`. |
76
+
|`core.urls.default`| String | URL for the `core.css` file from `@openedx/paragon`. |
77
+
|`core.urls.brandOverride`| Object | URL for the `core.css` file from `@openedx/brand-openedx`. |
78
78
|`defaults`| Object | Mapping of theme variants to Paragon's default supported light and dark theme variants. |
79
79
|`defaults.light`| String | Default `light` theme variant from the theme variants in the `variants` object. |
80
80
|`defaults.dark`| String | Default `dark` theme variant from the theme variants in the `variants` object. |
81
81
|`variants`| Object | Metadata about each supported theme variant. |
82
-
|`variants.light`| Object | Metadata about the light theme variant styles from `@edx/paragon` and (optionally)`@edx/brand`. |
83
-
|`variants.light.url`| String | URL for the `light.css` file from `@edx/paragon`. |
84
-
|`variants.light.urls`| Object | URL(s) for the `light.css` files from `@edx/paragon` CSS and (optionally) `@edx/brand`. |
85
-
|`variants.light.urls.default`| String | URL for the `light.css` file from `@edx/paragon`. |
86
-
|`variants.light.urls.brandOverride`| String | URL for the `light.css` file from `@edx/brand`. |
87
-
|`variants.dark`| Object | Metadata about the dark theme variant styles from `@edx/paragon` and (optionally)`@edx/brand`. |
88
-
|`variants.dark.url`| String | URL for the `dark.css` file from `@edx/paragon`. |
89
-
|`variants.dark.urls`| Object | URL(s) for the `dark.css` files from `@edx/paragon` CSS and (optionally) `@edx/brand`. |
90
-
|`variants.dark.urls.default`| String | URL for the `dark.css` file from `@edx/paragon`. |
91
-
|`variants.dark.urls.brandOverride`| String | URL for the `dark.css` file from `@edx/brand`. |
82
+
|`variants.light`| Object | Metadata about the light theme variant styles from `@openedx/paragon` and (optionally)`@openedx/brand-openedx`. |
83
+
|`variants.light.url`| String | URL for the `light.css` file from `@openedx/paragon`. |
84
+
|`variants.light.urls`| Object | URL(s) for the `light.css` files from `@openedx/paragon` CSS and (optionally) `@openedx/brand-openedx`. |
85
+
|`variants.light.urls.default`| String | URL for the `light.css` file from `@openedx/paragon`. |
86
+
|`variants.light.urls.brandOverride`| String | URL for the `light.css` file from `@openedx/brand-openedx`. |
87
+
|`variants.dark`| Object | Metadata about the dark theme variant styles from `@openedx/paragon` and (optionally)`@openedx/brand-openedx`. |
88
+
|`variants.dark.url`| String | URL for the `dark.css` file from `@openedx/paragon`. |
89
+
|`variants.dark.urls`| Object | URL(s) for the `dark.css` files from `@openedx/paragon` CSS and (optionally) `@openedx/brand-openedx`. |
90
+
|`variants.dark.urls.default`| String | URL for the `dark.css` file from `@openedx/paragon`. |
91
+
|`variants.dark.urls.brandOverride`| String | URL for the `dark.css` file from `@openedx/brand-openedx`. |
92
92
93
93
### JavaScript-based configuration
94
94
@@ -100,14 +100,14 @@ To use this JavaScript-based configuration approach, you may set a `PARAGON_THEM
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.:
150
+
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.:
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.
158
158
159
-
## Usage with `@edx/brand`
159
+
## Usage with `@openedx/brand-openedx`
160
160
161
-
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.
161
+
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.
162
162
163
-
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.
163
+
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.
164
164
165
-
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.
165
+
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.
166
166
167
-
To enable `@edx/brand` overrides, the `PARAGON_THEME_URLS` setting may be configured as following:
167
+
To enable `@openedx/brand-openedx` overrides, the `PARAGON_THEME_URLS` setting may be configured as following:
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.:
197
+
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.:
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 commit comments