[BD-46] feat: Paragon theme CSS is built and published independently of consuming applications #2102

PKulkoRaccoonGang · 2023-02-28T12:54:35Z

Description

Paragon CLI

Ensure there is a Paragon CLI to compile Paragon's design tokens and SCSS styles to generated CSS files (e.g., perhaps similar to the build-scss.js Node script in www).

Core CSS

Core styles (i.e., foundation, layout, component styles, all the previously @include'd Bootstrap styles, CSS utility classes, usages of the CSS variables generated by the design tokens, etc.).

Light CSS

All CSS variable definitions for the core Paragon light theme variant.
Each generated CSS file could be output twice: once minimifed and once unminified. This would make debugging easier for our future selves and for consumers than only generating a minified CSS file.
Consider the impacts on the @edx/brand NPM packages for theme authors. The CLI to compile the CSS into the appropriate files should be exposed to @edx/brand theme authors.

NPM

Verify the output CSS files will be included in the published NPM package such that it can be hosted on a CDN (we should be able to use an open source CDN for initial release like jsdelivr or unpkg).
Ensure consuming applications can still optionally import the necessary styles for core/light from installed copies of @edx/paragon and/or @edx/brand at the versions defined in package.json should an application not want to pull from a CDN (e.g., still supporting @import "~@edx/paragon/scss/core/core"; as an alternative to core.css and light.css).

Issue: #2014

Merge Checklist

If your update includes visual changes, have they been reviewed by a designer? Send them a link to the Netlify deploy preview, if applicable.
Does your change adhere to the documented style conventions?
Do any prop types have missing descriptions in the Props API tables in the documentation site (check deploy preview)?
Were your changes tested using all available themes (see theme switcher in the header of the deploy preview, under the "Settings" icon)?
Were your changes tested in the example app?
Is there adequate test coverage for your changes?
Consider whether this change needs to reviewed/QA'ed for accessibility (a11y). If so, please add wittjeff and adamstankiewicz as reviewers on this PR.

Post-merge Checklist

Verify your changes were released to NPM at the expected version.
If you'd like, share your contribution in #show-and-tell.
🎉 🙌 Celebrate! Thanks for your contribution.

openedx-webhooks · 2023-02-28T12:54:43Z

Thanks for the pull request, @PKulkoRaccoonGang!

When this pull request is ready, tag your edX technical lead.

codecov · 2023-02-28T13:04:40Z

Codecov Report

Patch and project coverage have no change.

Comparison is base (6d6fa91) 90.76% compared to head (29b86a7) 90.76%.

Additional details and impacted files

@@           Coverage Diff           @@
##            alpha    #2102   +/-   ##
=======================================
  Coverage   90.76%   90.76%           
=======================================
  Files         213      213           
  Lines        3499     3499           
  Branches      843      843           
=======================================
  Hits         3176     3176           
  Misses        315      315           
  Partials        8        8

Impacted Files	Coverage Δ
src/utils/breakpoints.js	`100.00% <ø> (ø)`

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

viktorrusakov

@PKulkoRaccoonGang left initial feedback, I think we can also improve build-tokens.js file more, I'll take a look a little later

tokens/style-dictionary.js

build-css.js

tokens/build-tokens.js

build-css.js

tokens/build-tokens.js

adamstankiewicz · 2023-03-03T12:49:47Z

scss/core/_utilities.scss

@@ -15,7 +15,7 @@
 @import "~bootstrap/scss/utilities/stretched-link";
 @import "~bootstrap/scss/utilities/visibility";
 @import "./bootstrap-override/utilities";
-@import "css/utility-classes";
+@import "css/light/utility-classes";


[curious/clarification] Given that _utilities.scss is imported into core.scss which is compiled to core.css, should we be including anything related to a specific theme variant (e.g., light) in this file? Or should these utilities classes be imported into the light.css file instead?

yeah, makes sense, we moved it to to the light.css file

adamstankiewicz · 2023-03-03T12:51:03Z

build-scss.js

+const compileThemeStyleSheets = (themeVariant) => {
+  fs.writeFileSync(
+      `./dist/${themeVariant}.css`,
+      compileStyleSheet(`./scss/core/css/${themeVariant}/variables.css`).css


[consideration] We may want to generate these CSS files based on the tokens outside of the scss directory (i.e., its beginning to feel a bit odd to generate CSS files in a folder that intends to be for SCSS files haha).

True, I had similar thoughts haha. I've refactored our styles structure by creating new root styles directory with separate css and scss subdirectories there, this is a breaking change for the consumers, but so is almost every change in alpha branch, so I think that's ok. (it just didn't feel right to create a separate css directory without grouping it with scss, I think introducing styles directory is more intuitive)

I think introducing a styles directory makes sense! ~~Would it contain both a scss and css directory?~~

adamstankiewicz · 2023-03-03T13:40:40Z

build-scss.js

@@ -12,12 +11,35 @@ var tildaImporter = function(url, prev, done) {
  return { file: url };
 };

+const compileStyleSheet = (path, output = 'expanded') => {
+  return sass.renderSync({


[curious] Does compileStyleSheet also generate map files when its output file is compressed? Say an MFE has loaded the core.min.css file, but wants to debug it. Given its minified, it won't be all that useful for debugging unless we ensure to also ship with an associated *.css.map file. According to the Dart SASS docs, it generates map files by default.

It didn't generate map files at first, but now it does 🙂 Good suggestion, thanks!

adamstankiewicz · 2023-03-03T13:43:29Z

build-scss.js

@@ -12,12 +11,35 @@ var tildaImporter = function(url, prev, done) {
  return { file: url };
 };

+const compileStyleSheet = (path, output = 'expanded') => {
+  return sass.renderSync({


Looks like sass.renderSync may be deprecated. This might be a good time to try to move away from renderSync in favor of what Dart SASS recommends for its replacement (i.e., compile - docs).

Let's at least do discovery to see if we can replace; if not, defer for now.

Turns out we can pretty easily, I don't know why I thought it wasn't possible 🤦. Updated, thanks!

adamstankiewicz · 2023-03-03T13:45:15Z

scss/core/core.scss

-@import "css/custom-media-breakpoints";
+@import "css/core/variables";
+@import "css/core/custom-media-breakpoints";
+@import "css/light/variables";


[curious/clarification] Similar question to the css/light/utility-classes import above, should core.scss be including the css/light/variables or only the css/core/variables given the light variables are also defined in light.css itself.

We've updated these import too, good catch!

adamstankiewicz · 2023-03-03T13:55:26Z

scss/core/core.scss

-@import "css/variables";
-@import "css/custom-media-breakpoints";
+@import "css/core/variables";
+@import "css/core/custom-media-breakpoints";


[curious] Have we been able to verify the new @custom-media CSS media queries are usable solely based on the output core.css and light.css files?

We did add the postcss-custom-media PostCSS plugin to @edx/frontend-build to ensure the Webpack config for MFEs can transform @custom-media definitions into native CSS. While this is useful for MFEs (e.g., they can define/use their own @custom-media queries), I realized it may not be as relevant if MFEs are injecting an already compiled CSS file into the app. This is because the already-compiled CSS file would not be going through Webpack; it's injected at runtime, not build time.

Given this, I wonder if we may need to look into whether we need to either:

Only compile SCSS -> CSS with PostCSS (and any necessary plugins like postcss-custom-media) instead of Dart SASS.

Compile SCSS -> CSS with Dart SASS and then take the output from Dart SASS and run it through PostCSS.

We've chosen to go with second approach for now to first compile SCSS with Dart SASS and then process resulting CSS with PostCSS.

We could probably install a bunch of plugins to allow PostCSS compile SCSS and drop Dart SASS this way, but I think PostCSS is intended to work with CSS files only and mixing SCSS here would be messy (at least for me haha). I like the separation of concerns we introduce be leavng Dart SASS, i.e. Dart SASS is responsible only for SCSS compilation and PostCSS is responsible for transforming resulting CSS files.

I completely agree here :)

openedx-webhooks · 2023-04-07T13:25:00Z

@PKulkoRaccoonGang 🎉 Your pull request was merged! Please take a moment to answer a two question survey so we can improve your experience in the future.

edx-semantic-release · 2023-04-07T13:44:55Z

🎉 This PR is included in version 21.0.0-alpha.18 🎉

The release is available on:

Your semantic-release bot 📦🚀

…of consuming applications (openedx#2102)

edx-semantic-release · 2023-09-01T12:56:53Z

🎉 This PR is included in version 22.0.0-alpha.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

openedx-semantic-release-bot · 2024-05-14T15:52:55Z

🎉 This PR is included in version 23.0.0-alpha.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

openedx-webhooks added the blended PR is managed through 2U's blended developmnt program label Feb 28, 2023

PKulkoRaccoonGang force-pushed the Peter_Kulko/paragon-css-build branch 4 times, most recently from c39ee86 to 1eb1263 Compare February 28, 2023 13:03

PKulkoRaccoonGang mentioned this pull request Feb 28, 2023

Ensure core Paragon theme CSS is built and published independently of consuming applications #2014

Closed

10 tasks

PKulkoRaccoonGang force-pushed the Peter_Kulko/paragon-css-build branch from 1eb1263 to 3740366 Compare February 28, 2023 17:04

PKulkoRaccoonGang requested a review from viktorrusakov February 28, 2023 21:03

PKulkoRaccoonGang force-pushed the Peter_Kulko/paragon-css-build branch from 3740366 to ba8dd0a Compare February 28, 2023 21:04

viktorrusakov reviewed Mar 1, 2023

View reviewed changes

PKulkoRaccoonGang requested a review from viktorrusakov March 1, 2023 17:43

PKulkoRaccoonGang changed the title ~~[BD-46] DRAFT: Paragon theme CSS is built and published independently of consuming applications~~ [BD-46] : Paragon theme CSS is built and published independently of consuming applications Mar 3, 2023

PKulkoRaccoonGang changed the title ~~[BD-46] : Paragon theme CSS is built and published independently of consuming applications~~ [BD-46] feat: Paragon theme CSS is built and published independently of consuming applications Mar 3, 2023

adamstankiewicz reviewed Mar 3, 2023

View reviewed changes

adamstankiewicz linked an issue Mar 3, 2023 that may be closed by this pull request

Ensure core Paragon theme CSS is built and published independently of consuming applications #2014

Closed

10 tasks

PKulkoRaccoonGang changed the title ~~[BD-46] feat: Paragon theme CSS is built and published independently of consuming applications~~ [BD-46] DRAFT: Paragon theme CSS is built and published independently of consuming applications Mar 6, 2023

PKulkoRaccoonGang force-pushed the Peter_Kulko/paragon-css-build branch from ced516b to e986834 Compare March 9, 2023 00:25

PKulkoRaccoonGang self-assigned this Mar 9, 2023

PKulkoRaccoonGang changed the title ~~[BD-46] DRAFT: Paragon theme CSS is built and published independently of consuming applications~~ [BD-46] feat: Paragon theme CSS is built and published independently of consuming applications Mar 17, 2023

PKulkoRaccoonGang force-pushed the Peter_Kulko/paragon-css-build branch from 8cd4d48 to 2c2d961 Compare April 7, 2023 07:49

PKulkoRaccoonGang and others added 8 commits April 7, 2023 10:51

feat: dictionary compilation logic changes (core, light CSS files)

a58fc32

refactor: refactoring after review

d83e8a0

chore: update tokens build config

56240b4

fix: update tokens build command to account for usage by brand packages

554f224

refactor: code refactoring

3e07a61

refactor: added PostCSS custom-media-css

b12b52c

refactor: added postCSS plugins

3ee9288

refactor: update style files structure

060f943

viktorrusakov and others added 4 commits April 7, 2023 11:18

docs: update readme

7db6af3

chore: update build tokens script to build into new directory

d1ef1ce

feat: expose build-scss script

0cd1a6b

fix: fixed compilation of custom media variables

29b86a7

PKulkoRaccoonGang force-pushed the Peter_Kulko/paragon-css-build branch from 2c2d961 to 29b86a7 Compare April 7, 2023 08:33

adamstankiewicz approved these changes Apr 7, 2023

View reviewed changes

adamstankiewicz merged commit 4fbe4ac into openedx:alpha Apr 7, 2023

edx-semantic-release added the released on @alpha label Apr 7, 2023

monteri pushed a commit to raccoongang/paragon that referenced this pull request Aug 17, 2023

feat: [BD-46] Paragon theme CSS is built and published independently …

04dd06f

…of consuming applications (openedx#2102)

PKulkoRaccoonGang added a commit to raccoongang/paragon that referenced this pull request Aug 18, 2023

feat: [BD-46] Paragon theme CSS is built and published independently …

02e8a58

…of consuming applications (openedx#2102)

PKulkoRaccoonGang added a commit that referenced this pull request Aug 1, 2024

feat: [BD-46] theme CSS is built and published independently (#2102)

7151dac

PKulkoRaccoonGang added a commit that referenced this pull request Aug 4, 2024

feat: theme CSS is built and published (#2102)

cdf9c43

PKulkoRaccoonGang added a commit that referenced this pull request Aug 4, 2024

feat: theme CSS is built and published (#2102)

023aafa

PKulkoRaccoonGang added a commit that referenced this pull request Aug 5, 2024

feat: theme CSS is built and published (#2102)

8aa30e2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[BD-46] feat: Paragon theme CSS is built and published independently of consuming applications #2102

[BD-46] feat: Paragon theme CSS is built and published independently of consuming applications #2102

PKulkoRaccoonGang commented Feb 28, 2023 •

edited

Loading

openedx-webhooks commented Feb 28, 2023

codecov bot commented Feb 28, 2023 •

edited

Loading

viktorrusakov left a comment

adamstankiewicz Mar 3, 2023

viktorrusakov Mar 10, 2023

adamstankiewicz Mar 3, 2023

viktorrusakov Mar 10, 2023

adamstankiewicz Mar 24, 2023 •

edited

Loading

adamstankiewicz Mar 3, 2023

viktorrusakov Mar 10, 2023

adamstankiewicz Mar 3, 2023

adamstankiewicz Mar 3, 2023 •

edited

Loading

viktorrusakov Mar 10, 2023

adamstankiewicz Mar 3, 2023

viktorrusakov Mar 10, 2023

adamstankiewicz Mar 3, 2023

viktorrusakov Mar 10, 2023

adamstankiewicz Mar 24, 2023

openedx-webhooks commented Apr 7, 2023

edx-semantic-release commented Apr 7, 2023

edx-semantic-release commented Sep 1, 2023

openedx-semantic-release-bot commented May 14, 2024

[BD-46] feat: Paragon theme CSS is built and published independently of consuming applications #2102

[BD-46] feat: Paragon theme CSS is built and published independently of consuming applications #2102

Conversation

PKulkoRaccoonGang commented Feb 28, 2023 • edited Loading

Description

Paragon CLI

Core CSS

Light CSS

NPM

Merge Checklist

Post-merge Checklist

openedx-webhooks commented Feb 28, 2023

codecov bot commented Feb 28, 2023 • edited Loading

Codecov Report

viktorrusakov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adamstankiewicz Mar 24, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adamstankiewicz Mar 3, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openedx-webhooks commented Apr 7, 2023

edx-semantic-release commented Apr 7, 2023

edx-semantic-release commented Sep 1, 2023

openedx-semantic-release-bot commented May 14, 2024

PKulkoRaccoonGang commented Feb 28, 2023 •

edited

Loading

codecov bot commented Feb 28, 2023 •

edited

Loading

adamstankiewicz Mar 24, 2023 •

edited

Loading

adamstankiewicz Mar 3, 2023 •

edited

Loading