Teak.1 + Design Tokens for the MFEs

Hey everyone!

Just a quick update to let you know that our team at eduNEXT has been working on updating the MFEs using the Teak.1 and design token branches. Here’s the list of MFEs we’ve already created:

If you have any questions or run into any issues with these, feel free to reach out!

Cheers,
The eduNEXT Team

cc: @brian.smith

4 Likes

I put the rest of the MFEs in the following comment:

I couldn’t do it because of the restriction on this account that only lets me put 5 links at the time.

I recommend merging a shared base Teak.1 design token package into a centralized library (if not already done) and documenting token usage patterns clearly—this way, any issues or updates can be managed in one place and reused across MFEs. Let me know if you’d like support aligning this!

Thank you so much for making these @Asespinel1!

I did notice that Comparing openedx:release/teak.1...eduNEXT:ednx-release/teak.master · openedx/frontend-app-account · GitHub seems to show some commits unrelated to design tokens support (chore: temporarily disabled notification preferences course dropdown … · openedx/frontend-app-account@5c5204f · GitHub for example).

I also noticed the branch is named ednx-release/teak.master, which implies to me these are “all the things we want for our teak releases” branches instead of “teak.1 with design tokens” branches.

My goal for creating teak-design-tokens branches on the upstream repos was to bring over only the changes required for design tokens support. If I’m misunderstanding the diff and that is the intention of these branches please let me know and I’ll happily create upstream teak-design-tokens branches based off them!

Thanks again for doing this, it really helps a ton!

@brian.smith Thanks for reaching out! We created the ednx-release/teak.master branches by merging the upstream teak.1 branches with the respective master-design-token branches. Our intention was specifically to bring in only the changes required for design tokens support.

The naming convention ednx-release/teak.master was chosen to reflect our internal naming style and to indicate that these branches were meant to support design tokens in our Teak-based releases. Since design tokens are already supported in teak, we didn’t need to introduce any custom changes beyond what’s already upstream.

Let us know if you have any more questions.

That is great to hear!

I’d like to clarify this a bit. The release/teak branches and the teak.1 tags of MFEs do not support design tokens. The current master branches of MFEs do support design tokens, and that support will make it into the Ulmo release.

There’s a slight issue with that strategy. The master-design-tokens branches were tracking master until they landed on master, meaning anything that landed on master between the creation of the teak branches and design tokens landing made it into the master-design-tokens branches.


Using frontend-app-account as an example:

That means that when you compare the commit on master where design tokens landed to the release/teak branch, you also see all the other commits that landed on master between April 28th and June 18th (25 of them).

What’s confusing to me now is how the ednx-release/teak.master branch got to a place where it is 14 commits ahead of release/teak.


If I were to make teak-design-tokens branches from scratch I would:

  • Create a new branch off release/teak or teak.1
  • Cherry-pick the feat!: add design tokens support commit
  • Fix any conflicts and get it building/working

That isn’t the only option, and I’m not opposed to using a different strategy, but seeing this commit (chore: temporarily disabled notification preferences course dropdown (#1246)), in the diff between ednx-release/teak.master and release/teak makes me worry the current strategy resulted in unintended changes from master making it in.

:tada: teak-design-tokens have been created upstream! :tada:

Thank you so much @Asespinel1 for putting these branches together!

:information_source:
This information is now available here: https://openedx.atlassian.net/wiki/spaces/BPL/pages/5050499077/Using+Teak+Design+Tokens+branches

Original post

The branches


Using these branches in Tutor

  1. Install and enable the following plugin
from tutormfe.hooks import MFE_APPS

@MFE_APPS.add()
def _use_design_tokens(mfes):
    for mfe_name, mfe in mfes.items():
        mfe["version"] = "teak-design-tokens"
    return mfes

  1. Rebuild the mfe image
tutor images build mfe

Note: if you run into issues rebuilding the mfe image you can try using --no-cache.


Using design tokens based brand packages

Using npm aliasing

  1. Install and enable the following plugin
from tutor import hooks

hooks.Filters.ENV_PATCHES.add_item(
    (
        "mfe-dockerfile-post-npm-install",
        """
RUN npm install '@edx/brand@YOUR_ALIAS_HERE'
"""
    )
)

To test this with a simple example brand package you can replace YOUR_ALIAS_HERE with github:brian-smith-tcril/brand-example-purple#174be977c9f8c7aa11591f4c6887506da72d8191.

  1. Rebuild the mfe image
tutor images build mfe

Note: if you run into issues rebuilding the mfe image you can try using --no-cache.

Using jsdelivr

  1. Install and enable the following plugin
import json
from tutor import hooks

paragon_theme_urls = {
    "variants": {
        "light": {
            "urls": {
                "default": "https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css",
                "brandOverride": "YOUR_BRAND_OVERRIDE_URL"
            }
        }
    }
}

fstring = f"""
MFE_CONFIG["PARAGON_THEME_URLS"] = {json.dumps(paragon_theme_urls)}
"""

hooks.Filters.ENV_PATCHES.add_item(
    (
        "mfe-lms-common-settings",
        fstring
    )
)

To test this with a simple example brand package you can replace YOUR_BRAND_OVERRIDE_URL with https://cdn.jsdelivr.net/gh/brian-smith-tcril/brand-example-purple@bb6b7797e629c96192d0676a2cbd879b11488fa0/dist/light.min.css

Using the tutor-contrib-paragon plugin

  1. :building_construction: Coming soon!

Creating a design tokens based brand package

For information on how to create a design tokens based brand package see brand-openedx/docs/how-to/design-tokens-support.rst at master · openedx/brand-openedx · GitHub

2 Likes

@brian.smith I tried to use the design tokens with the example you provided, but I’m facing some issues while trying to customize the authn MFE.

Only the brand colors are changing, the rest of the layout doesn’t change.

Note: I forked the GitHub - openedx/brand-openedx to customize and frontend-app-authn (teak design tokens) for design tokens support in local development.

In frontend-app-authn/src/index.scss at teak-design-tokens · openedx/frontend-app-authn · GitHub , we have

@import "sass/style";

which I believe, loads the default styling in frontend-app-authn/src/sass at teak-design-tokens · openedx/frontend-app-authn · GitHub .

Now I wanted to change the styling of my frontend-app-authn MFE by tweaking the .main-content class background color in my custom brand (to avoid breaking the frontend-app-authn d during updates) https://github.com/sowibrahima/ws-brand/blob/efa8187e756851d5bc1b25e0b66768012d4dd31e/paragon/mfe-overrides/\_authn.scss#L12, but it’s not reflected in my MFE. Only the primary color https://github.com/sowibrahima/ws-brand/blob/efa8187e756851d5bc1b25e0b66768012d4dd31e/paragon/\_variables.scss#L9 is getting updated.

Sorry if it’s a “nooby” question, I’m new to the Open edX ecosystem.

tutor version: 20.0.0

Enabled plugins:

mfe :white_check_mark: enabled 20.0.0
mybrand-jsdelivr :white_check_mark: enabled /home//.local/share/tutor-plugins/mybrand-jsdelivr.py
use-design-tokens :white_check_mark: enabled /home//.local/share/tutor-plugins/use-design-tokens.py

@Ibrahima in your post you mentioned using .scss files. With design tokens, styles should be defined using tokens (.json or .toml files), and then the Paragon CLI can be used to transform the tokens into CSS variables.

Relevant documentation:

The package.json file in brand-openedx also includes a build-tokens script:

    "build-tokens": "paragon build-tokens --source ./paragon/tokens/ --build-dir ./paragon/build -t light",

The example brand package I mentioned in my previous comment is indeed quite minimal (it just changes the brand color). A good real world example of a Paragon 23/design tokens based brand package is 2U’s Elm theme.

Hopefully this helps!

@brian.smith thanks for your quick response.
I indeed finally went with GitHub - edx/elm-theme: This project contains branding assets and themes for edx.org. It is an updated implementation of the branding interface defined in the package @edx/elm. and was able to generate the css variables from the tokens.

That’s great news!

This question is out of scope for this thread. Please create a new post for this and add as much detailed information as possible to your question there.

1 Like

@brian.smith will do, thank you!

1 Like