Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
10 tasks done
Tracked by #246
adamstankiewicz opened this issue Feb 13, 2023 · 2 comments · Fixed by #2102
Closed
10 tasks done
Tracked by #246

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

adamstankiewicz opened this issue Feb 13, 2023 · 2 comments · Fixed by #2102
Assignees
@PKulkoRaccoonGang
Labels
engineering Engineering raccoon-gang

Comments

@adamstankiewicz
Copy link
Member

adamstankiewicz commented Feb 13, 2023 •
edited by viktorrusakov

Description

Currently, applications consuming @edx/paragon import its core SCSS in the top-most SCSS entry point (e.g., src/index.scss), along with any @edx/brand overrides:

// ... Any custom SCSS variables should be defined here
@import '~@edx/paragon/scss/core/core';
@import '~@edx/brand/paragon/fonts';
@import '~@edx/brand/paragon/variables';
@import '~@edx/paragon/scss/core/core';
@import '~@edx/brand/paragon/overrides';

With design tokens, the goal is to have the theme built independently of the consuming application so that any theme change does not require a re-build of each consuming application.

As such, consuming applications should no longer need to import SCSS directly from @edx/paragon or @edx/brand; instead, applications should import / inject an already-compiled CSS file. Note, this issue doesn't pertain to how applications will import/inject the compiled CSS file; this issue only relates to the generation of the CSS file itself.

In order to do this, Paragon will need to offer a way to compile the output CSS based on its design tokens and SCSS. Likewise, the @edx/brand NPM package(s) will also need a way to compile the output CSS.

This decision, of course, will have consequences for consuming applications, where SCSS variables or SCSS mixins from Paragon may no longer be used directly; instead, CSS variables or other alternatives will need to be used instead.

The proposal here is to have @edx/paragon generate core.css and light.css files. The contents of the light.css file would only contain the CSS variables pertaining to the light (default) theme variant. In the future, we could also generate a dark.css file for the CSS variables specific to dark mode. This way, consuming applications can choose which (and how) each stylesheet should be loaded and when (e.g., by dynamically creating/appending a <link> to the HTML <head>).

As such, the core.css file wouldn't necessary need to worry about which theme variant (e.g., light vs. dark) is active and simply use the CSS variables as needed (e.g., for component styles).

Acceptance Criteria

  • 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).
    • The output CSS should contain:
      • 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.
  • 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).
@adamstankiewicz adamstankiewicz added this to the Design tokens with style-dictionary milestone Feb 13, 2023
This was referenced Feb 13, 2023
Closed
Closed
Closed
@viktorrusakov viktorrusakov self-assigned this Feb 14, 2023
This was referenced Feb 24, 2023
Closed
Merged
@adamstankiewicz
Copy link
Member Author

Based on some feedback from our stakeholders, we ideally should support either using the compiled CSS output mentioned in the Acceptance Criteria above (i.e., core.css and light.css), likely pulled from an open source CDN like jsDelivr (at least for initial release), OR allow consuming applications to import from the locally installed versions of @edx/paragon and @edx/brand respectively. That way, applications would have an alternative to using a CDN to host a compiled CSS file.

For example, in the current state of @edx/paragon@alpha, I can either import the compiled dist/paragon.css file into my MFE via the CDN urls or I can still import @import "~@edx/paragon/scss/core/core"; to get the desired styles with CSS variables.

@PKulkoRaccoonGang PKulkoRaccoonGang mentioned this issue Feb 28, 2023
Merged
17 tasks
@PKulkoRaccoonGang
Copy link
Contributor

PKulkoRaccoonGang commented Feb 28, 2023 •
edited

PRs:

@adamstankiewicz adamstankiewicz linked a pull request Mar 3, 2023 that will close this issue
[BD-46] feat: Paragon theme CSS is built and published independently of consuming applications #2102
Merged
17 tasks
@arbrandes arbrandes mentioned this issue Mar 19, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@PKulkoRaccoonGang PKulkoRaccoonGang

Labels
engineering Engineering raccoon-gang
Projects
Frontend Working Group
Status: Closed
Paragon Working Group
Status: Done
Milestone
No milestone
3 participants
@adamstankiewicz @viktorrusakov @PKulkoRaccoonGang