{"type":"doc","content":[{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"DRAFT","type":"text"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"a3ccdac2-ca90-420f-b2a5-b91d8dcbd861"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"d47fc582-a9a3-4882-a8ba-a05599d2c23f"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"Paragon, the design system and React UI component library for the Open edX platform, now supports design tokens and CSS variables.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"bdef588c-428c-4279-a5ea-b11cda79460b"}},{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"efe9403f-6969-4fad-9417-9fe1ed6d0382"}}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The design tokens are currently published under an alpha distribution channel on NPM, i.e. ","type":"text"},{"text":"@openedx/paragon@alpha","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Getting Started","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"TODO: docs/resources/context","type":"text"}]},{"type":"paragraph","content":[{"text":"Some potential ideas:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Brief description of design tokens (a few sentences)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Link to ","type":"text"},{"text":"style-dictionary","type":"text","marks":[{"type":"code"}]},{"text":" (","type":"text"},{"text":"docs","type":"text","marks":[{"type":"link","attrs":{"href":"https://amzn.github.io/style-dictionary/"}}]},{"text":")","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Link to ","type":"text"},{"text":"ADR","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openedx/paragon/pull/1929"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Create & link to the Paragon docs site page with a list of design tokens","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openedx/paragon/issues/3083"}}]},{"text":" (TBD)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Create & link to the Paragon docs site page with a list of CSS variables","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openedx/paragon/issues/3084"}}]},{"text":" (TBD)","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Migration guide","type":"text"}]},{"type":"expand","attrs":{"title":""},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Requirements:","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b97f75eb-e916-421d-8de5-4b81a045a9bd"}}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"In case of conflicts with dependency versions, a temporary solution is to install modules using the ","type":"text"},{"text":"npm install --force","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"c08b6cde-6994-417d-a534-6bc84d87b771"}},{"type":"code"}]},{"text":" command.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"It should also be remembered that some components with the deprecated marker were removed in the alpha version of Paragon. Errors with imports are expected. In the future, these deprecated components will be replaced with new ones (See - ","type":"text"},{"text":"Removal-previous-deprecated-components","type":"text","marks":[{"type":"link","attrs":{"href":"https://openedx.atlassian.net/wiki/spaces/BPL/pages/3770744958/Migrating+MFEs+to+Paragon+design+tokens+and+CSS+variables#Removal-previous-deprecated-components"}}]},{"text":")","type":"text"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Install a compatible version of Paragon.","type":"text","marks":[{"type":"strong"}]},{"text":" Must support design tokens (currently, only ","type":"text"},{"text":"@openedx/paragon@alpha","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://github.com/openedx/paragon/tree/alpha"}},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"Example (","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"},{"type":"hardBreak"},{"text":"\"@openedx/paragon\": \"22.0.0-alpha.25\"","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Install a compatible version of ","type":"text","marks":[{"type":"strong"}]},{"text":"@edx/frontend-build","type":"text","marks":[{"type":"code"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Requires ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/openedx/frontend-build/pull/365"}},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Example (","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"},{"type":"hardBreak"},{"text":"\"@openedx/frontend-build\": \"github:edunext/frontend-build#dcoa/design-tokens-support\"","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Install a compatible version of ","type":"text","marks":[{"type":"strong"}]},{"text":"@edx/frontend-platform","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Requires","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"5403366c-042e-43fe-ba3e-b1417c02bfde"}}]},{"text":" ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/openedx/frontend-platform/pull/689"}},{"text":" ","type":"text"},{"type":"hardBreak"},{"text":"Example (","type":"text"},{"text":"module.config.js","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"}]}]}]}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"module.exports = {\n localModules: [\n { moduleName: '@edx/frontend-platform', dir: '../frontend-platform', dist: 'src' }\n ],\n};","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"Tutor","type":"text","marks":[{"type":"strong"}]},{"text":" add a mount in the next format:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"tutor mounts add ::/openedx/","type":"text"}]}]},{"type":"orderedList","attrs":{"order":4},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Install a compatible version of ","type":"text","marks":[{"type":"strong"}]},{"text":"@edx/frontend-component-header","type":"text","marks":[{"type":"code"}]},{"text":" (version/PR TBD).","type":"text","marks":[{"type":"strong"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OpenEdx Frontend-component-header - ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/openedx/frontend-component-header/pull/351"}},{"text":" ","type":"text"},{"type":"hardBreak"},{"text":"OR","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Edx Frontend-component-header - ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/edx/frontend-component-header-edx/pull/393"}},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Example (","type":"text"},{"text":"module.config.js","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"}]}]}]}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"module.exports = {\n localModules: [\n { moduleName: '@edx/frontend-platform', dir: '../frontend-platform', dist: 'src' },\n { moduleName: '@edx/frontend-component-header/dist', dir: '../frontend-component-header', dist: 'dist' }\n ],\n};","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"Tutor","type":"text","marks":[{"type":"strong"}]},{"text":" add a mount in the next format:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"tutor mounts add ::/openedx/","type":"text"}]}]},{"type":"orderedList","attrs":{"order":5},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Install a compatible version of ","type":"text","marks":[{"type":"strong"}]},{"text":"@edx/frontend-component-footer","type":"text","marks":[{"type":"code"}]},{"text":" (version/PR TBD).","type":"text","marks":[{"type":"strong"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OpenEdx Frontend-component-footer - ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/openedx/frontend-component-footer/pull/303"}},{"text":" ","type":"text"},{"type":"hardBreak"},{"text":"OR","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Edx Frontend-component-footer - ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/edx/frontend-component-footer-edx/pull/294"}},{"text":" .","type":"text"}]},{"type":"paragraph","content":[{"text":"Example (","type":"text"},{"text":"module.config.js","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"}]}]}]}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"module.exports = {\n localModules: [\n { moduleName: '@edx/frontend-platform', dir: '../frontend-platform', dist: 'src' },\n { moduleName: '@edx/frontend-component-header/dist', dir: '../frontend-component-header', dist: 'dist' },\n { moduleName: '@edx/frontend-component-footer/dist', dir: '../frontend-component-footer', dist: 'dist' }\n ],\n};","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"Tutor","type":"text","marks":[{"type":"strong"}]},{"text":" add a mount in the next format:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"tutor mounts add ::/openedx/","type":"text"}]}]},{"type":"orderedList","attrs":{"order":6},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"[Optional]","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text"},{"text":"Install a compatible version of the Brand. ","type":"text","marks":[{"type":"strong"}]},{"text":"Must support design tokens (currently, only ","type":"text"},{"text":"@edx/brand-edx.org@alpha","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://github.com/edx/brand-edx.org/tree/alpha"}},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Example (","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"},{"type":"hardBreak"},{"text":"\"@edx/brand\": \"npm:@edx/brand-edx.org@2.2.0-alpha.17\"","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"OR","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"module.exports = {\n localModules: [\n { moduleName: '@edx/frontend-platform', dir: '../frontend-platform', dist: 'src' },\n { moduleName: '@edx/frontend-component-header/dist', dir: '../frontend-component-header', dist: 'dist' },\n { moduleName: '@edx/frontend-component-footer/dist', dir: '../frontend-component-footer', dist: 'dist' },\n { moduleName: '@edx/brand', dir: '../brand-edx.org/' }\n ],\n};","type":"text"}]},{"type":"orderedList","attrs":{"order":7},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Replace ","type":"text","marks":[{"type":"strong"}]},{"text":"@edx/paragon","type":"text","marks":[{"type":"code"}]},{"text":" with ","type":"text","marks":[{"type":"strong"}]},{"text":"@openedx/paragon","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon migrate-to-openedx-scope .","type":"text"}]},{"type":"orderedList","attrs":{"order":8},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Replace SCSS variables usages or definitions with CSS variables","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon replace-variables -p . -t usage","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon replace-variables -p . -t definition","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Using locally installed Paragon CSS","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Import the compiled Paragon CSS into the SCSS entry point of your MFE.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"codeBlock","attrs":{"language":"css"},"content":[{"text":"// Within `src/index.scss` of your MFE\n@use \"@openedx/paragon/dist/core.min.css\" as paragonCore;\n@use \"@openedx/paragon/dist/light.min.css\" as paragonLight;\n\n// If using `@edx/brand` to customize the default Paragon theme, also include:\n@use \"@edx/brand/dist/core.min.css\" as brandCore;\n@use \"@edx/brand/dist/light.min.css\" as brandLight;\n\n// include the remaining SCSS for the MFE, now with access to the\n// CSS variables defined in Paragon.","type":"text"}]}]}]}]}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"@openedx/paragon/dist/dark.min.css","type":"text","marks":[{"type":"code"}]},{"text":" to account for theme switching.","type":"text"}]},{"type":"paragraph","content":[{"text":"@import \"@openedx/paragon/dist/light.min.css\" (prefers-color-scheme: light);","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"@import url(\"@openedx/paragon/dist/dark.min.css\") (prefers-color-scheme: dark);","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Using the externally hosted Paragon CSS via ","type":"text"},{"text":"@edx/frontend-platform","type":"text","marks":[{"type":"code"}]},{"text":" (see below) comes with a mechanism, i.e. ","type":"text"},{"text":"const { paragonTheme: { setThemeVariant } } = useContext(AppContext);","type":"text","marks":[{"type":"code"}]},{"text":", to build a theme variant switcher baked in.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Using externally hosted Paragon CSS","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"1e2cc5c7-757a-4e1a-9c64-b8b85ef43a6d"}}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Configure external Paragon CSS URLs (e.g., from a hosted CDN).","type":"text","marks":[{"type":"strong"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The quickest way to get started is to use ","type":"text"},{"text":"jsDelivr","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.jsdelivr.com/"}}]},{"text":", a global ","type":"text"},{"text":"production-ready","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.jsdelivr.com/documentation#id-ready-for-production"}}]},{"text":" CDN that has deep integrations with NPM, and a ","type":"text"},{"text":"$paragonVersion","type":"text","marks":[{"type":"code"}]},{"text":" wildcard to rely on the same version of ","type":"text"},{"text":"@openedx/paragon","type":"text","marks":[{"type":"code"}]},{"text":" installed in your MFE.","type":"text"},{"text":" ","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"8f402508-f9ab-458a-bbb3-55b2ee529cc9"}}]},{"text":"Configure the ","type":"text"},{"text":"PARAGON_THEME_URLS","type":"text","marks":[{"type":"code"}]},{"text":" in your MFE configuration (you can use either of the approaches explained below).","type":"text"},{"type":"hardBreak"},{"text":"Example:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"{\n \"MFE_CONFIG_OVERRIDES\": {\n \"\": {\n \"PARAGON_THEME_URLS\": {\n \"core\": {\n \"urls\": {\n \"default\": \"https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css\"\n }\n },\n \"defaults\": {\n \"light\": \"light\",\n \"dark\": \"dark\"\n },\n \"variants\": {\n \"light\": {\n \"urls\": {\n \"default\": \"https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css\"\n }\n },\n \"dark\": {\n \"urls\": {\n \"default\": \"https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/dark.min.css\"\n }\n }\n }\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Configuration approaches:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"JavaScript-based configuration","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openedx/frontend-platform/blob/ea99e3cd307838409c735adab5a967d1255656ba/docs/how_tos/theming.md#javascript-based-configuration"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"MFE runtime configuration API","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openedx/frontend-platform/blob/ea99e3cd307838409c735adab5a967d1255656ba/docs/how_tos/theming.md#mfe-runtime-configuration-api"}}]}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Import custom media breakpoints from Paragon into the SCSS entry point of your MFE.","type":"text","marks":[{"type":"strong"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"codeBlock","attrs":{"language":"css"},"content":[{"text":"// Within `src/index.scss` of your MFE\n@use \"@openedx/paragon/styles/css/core/custom-media-breakpoints.css\" as paragonCustomMediaBreakpoints;\n\n// If using `@edx/brand` to customize the default Paragon theme, also include:\n@use \"@edx/brand/paragon/css/core/custom-media-breakpoints.css\" as brandCustomMediaBreakpoints;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Note: you ","type":"text"},{"text":"must","type":"text","marks":[{"type":"strong"}]},{"text":" utilize ","type":"text"},{"text":"@use","type":"text","marks":[{"type":"code"}]},{"text":" instead of ","type":"text"},{"text":"@import","type":"text","marks":[{"type":"code"}]},{"text":" with this file. The SASS team also discourages the continued use of ","type":"text"},{"text":"@import","type":"text","marks":[{"type":"code"}]},{"text":", and plans to eventually remove it from the language entirely. See more information ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://sass-lang.com/documentation/at-rules/import"}}]},{"text":".","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Accounting for breaking changes","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remove all (almost) Paragon imports from the SCSS entry point in your MFE","type":"text"}]},{"type":"paragraph","content":[{"text":"Previously, to use Paragon’s styles in your MFE, you’d import various SCSS files from ","type":"text"},{"text":"@edx/paragon","type":"text","marks":[{"type":"code"}]},{"text":" in a particular order and your MFE’s build process would compile and bundle Paragon’s SCSS with your application’s CSS:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"css"},"content":[{"text":"// src/index.scss\n@import \"@my-brand/fonts.scss\";\n@import \"@my-brand/variables.scss\";\n\n// Import the Paragon core after setting brand-themed variables.\n@import \"@openedx/paragon/scss/core/core.scss\";\n\n// Import brand overrides after the Paragon core.\n@import \"@my-brand/overrides.scss\";","type":"text"}]},{"type":"paragraph","content":[{"text":"This approach had a few negative effects:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each MFE had to re-compile Paragon’s SCSS whenever a theme change was made.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Users would need to re-download duplicate CSS from Paragon as they navigate across MFEs.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"and improving page performance for users by requiring less data to download over the network.","type":"text"}]},{"type":"paragraph","content":[{"text":"The only import from Paragon needed now is for its ","type":"text"},{"text":"custom-media-breakpoints","type":"text","marks":[{"type":"code"}]},{"text":". This must be imported within your MFE in order to use the CSS media queries using Paragon’s defined breakpoints. ","type":"text"}]},{"type":"paragraph","content":[{"text":"For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"css"},"content":[{"text":"// Within `src/index.scss` of your MFE\n@use \"@openedx/paragon/styles/css/core/custom-media-breakpoints.css\" as paragonCustomMediaBreakpoints;\n@use \"@openedx/brand/paragon/css/core/custom-media-breakpoints.css\" as brandCustomMediaBreakpoints;\n\n@media(--min-pgn-size-breakpoint-md) {\n .my-element {\n color: red;\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Replace all SCSS variables/mixins from Paragon with their CSS variables replacement","type":"text"}]},{"type":"paragraph","content":[{"text":"There should be a drop-in replacement design token and CSS variable for every previous SCSS variable available via Paragon. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"css"},"content":[{"text":"$primary-500 -> var(--pgn-color-primary-500)","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Removal of previous deprecated components","type":"text"}]},{"type":"paragraph","content":[{"text":"There is a mapping of ","type":"text"},{"text":"Deprecated","type":"text","marks":[{"type":"code"}]},{"text":" -> ","type":"text"},{"text":"Relevant","type":"text","marks":[{"type":"code"}]},{"text":" component:","type":"text"}]},{"type":"codeBlock","content":[{"text":"CheckBox --> Form.Checkbox\nCheckBoxGroup --> Form.CheckboxSet\nRadioButtonGroup --> From.RadioSet\nFieldset --> 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\nInput, InputSelect, InputText --> Form.Control\nListBox --> SelectableBox\nModal --> ModalDialog\nStatusAlert --> Alert\nTable --> DataTable\nValidationFormGroup --> Form.Group","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"FontAwesome removal from Paragon","type":"text"}]},{"type":"paragraph","content":[{"text":"Removed from components:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IconButton","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Icon","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SearchField","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":3},"content":[{"text":"Paragon CLI Documentation","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Node 18","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Available Commands:","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"install-theme","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"This command is used to install a specific ","type":"text"},{"text":"@edx/brand","type":"text","marks":[{"type":"code"}]},{"text":" package. You can specify the theme to install using the theme parameter. By default, the latest version of ","type":"text"},{"text":"@openedx/brand-openedx","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"6648b404-88a1-4963-a32a-fae76829225c"}},{"type":"code"}]},{"text":" will be installed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon install-theme --theme @custom/brand-theme@latest","type":"text"}]},{"type":"orderedList","attrs":{"order":2},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"migrate-to-openedx-scope","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"This command is used for migrating from \"@edx/paragon\" to \"@openedx/paragon\":","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"path","type":"text","marks":[{"type":"code"}]},{"text":": Path to the directory where to replace Paragon package name, default to root of the repository.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon migrate-to-openedx-scope .","type":"text"}]},{"type":"orderedList","attrs":{"order":3},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"build-tokens","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"This command is used to build Paragon design tokens. You can customize the token build process using various options:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"-s, --source","type":"text","marks":[{"type":"code"}]},{"text":": Specify the source directory for design tokens.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"-b, --build-dir","type":"text","marks":[{"type":"code"}]},{"text":": Specify the build directory for the generated tokens.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"--source-tokens-only","type":"text","marks":[{"type":"code"}]},{"text":": Include only source design tokens in the build.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"-t, --themes","type":"text","marks":[{"type":"code"}]},{"text":": Specify themes to include in the token build.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example: ","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon build-tokens --build-dir ./styles/css","type":"text"}]},{"type":"orderedList","attrs":{"order":4},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"replace-variables","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"-s, --source","type":"text","marks":[{"type":"code"}]},{"text":": Type of replacement: usage or definition.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"-t, --replacementType","type":"text","marks":[{"type":"code"}]},{"text":": Type of replacement: usage or definition.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"-d, --direction","type":"text","marks":[{"type":"code"}]},{"text":": Map direction: css-to-scss or scss-to-css.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon replace-variables -p src -t usage\n\nparagon replace-variables -p src -t definition","type":"text"}]},{"type":"orderedList","attrs":{"order":5},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"build-scss","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"This command compiles Paragon's core and themes SCSS into CSS. You can customize the compilation process using various options:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"--corePath","type":"text","marks":[{"type":"code"}]},{"text":": Path to the theme's core SCSS file.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"--themesPath","type":"text","marks":[{"type":"code"}]},{"text":": Path to the directory that contains themes' files.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"--outDir","type":"text","marks":[{"type":"code"}]},{"text":": Directory where the resulting CSS files will be output.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"--defaultThemeVariants","type":"text","marks":[{"type":"code"}]},{"text":": Default theme variants.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon build-scss --corePath ./styles/scss/core/core.scss --themesPath ./styles/css/themes --outDir ./dist/css --defaultThemeVariants light","type":"text"}]},{"type":"orderedList","attrs":{"order":6},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"help","type":"text","marks":[{"type":"underline"},{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"You can display help for any specific command by using the help command followed by the command name.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"paragon help\n\nparagon help build-tokens","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Start your MFE application","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Load up your MFE on your machine with ","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"9d93279f-b93f-43e7-8e2c-0a15a8672cf1"}}]},{"text":"npm start","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"9d93279f-b93f-43e7-8e2c-0a15a8672cf1"}},{"type":"code"}]},{"text":" and open it in a browser.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"9d93279f-b93f-43e7-8e2c-0a15a8672cf1"}}]},{"text":" Your MFE should start, with identical styles as before prior to the upgrade.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Verify the styles (e.g., for a ","type":"text"},{"text":"Button","type":"text","marks":[{"type":"code"}]},{"text":") in the devtools are now showing as using CSS variables instead of hardcoded values.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you notice any style issues or discrepancies between the previous look and feel, please ","type":"text"},{"text":"file a Github issue","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openedx/paragon/issues/new?assignees=&labels=design+tokens&projects=openedx/43&projects=openedx/29&template=feedback_template.md"}}]},{"text":" and/or reach out in the Paragon Working Group Slack channel.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Work with your squad’s designer(s) to ensure no style regressions.","type":"text"}]}]}]}]}]}],"version":1}