Brand-openedx package changes not reflecting in local Tutor (Ulmo) setup

[Mahendra (Mahendra Chaudhari (TitanEd))]

Hi Everyone,

I’m facing an issue with applying theme customizations using the brand-openedx package in my local Open edX setup and would appreciate some guidance.

Environment

• Open edX installed using Tutor 21.0.1
• Release: Ulmo
• Default setup working fine
• Default theme: Tutor Indigo

What I’m Trying to Do

I want to customize theme-related elements such as:

• CSS changes
• Fonts
• Colors

Specifically, I’m trying to apply changes to the Learner Dashboard MFE.

Steps I Followed

1. Mounted the learner dashboard MFE.

2. Cloned the brand repository: git clone https://github.com/edly-io/brand-openedx.git -b indigo-2.5.0

3. Installed it locally as a dependency: npm install @edx/brand@file:./brand-openedx

4. Current folder structure:

my-project/
    - frontend-app-learner-dashboard/
        - brand-openedx/

Issue

After installing the brand-openedx package, I do not see any Indigo theme changes reflected on the Learner Dashboard.

This exact setup was working correctly in the Teak release, but in Ulmo, the changes are not being applied.

Questions

• Is there any additional configuration required in Ulmo?
• Is there a new recommended way to override brand assets in Ulmo?
• What are the correct steps to set up brand-openedx in a local Tutor-based development environment?

Any guidance or updated documentation references would be greatly appreciated.

Thanks in advance!

[FarazM (Muhammad Faraz Maqsood)]

@Mahendra

This exact setup was working correctly in the Teak release, but in Ulmo, the changes are not being applied.

Yes, you are right. These steps used to work in teak when applying theme customizations using the brand-openedx. But in ulmo, we have design tokens & theme variants stuff.

We recently separated design tokens for dark theme in this PR(Link), and these theme variants are available to all MFEs through this piece of code(Link) in ulmo.

There were 2 approaches for development with brand-openedx that we had in mind,

1. Apply scss/css changes to brand-openedx. Run npm run build, commit the dist folder to github. Then copy the raw URL(https://raw.githubusercontent.com/edly-io/brand-openedx/refs/heads/ulmo/indigo/dist/dark.min.css) of our ulmo/indigo branch and paste it here in this code(Link).
   • There was an issue with this approach that with every change, we had to run npm run build, commit the dist folder to github, copy the raw URL of that dark.min.css of that particular commit, as due to some cache related issue. The changes were not reflecting.
2. The approach we followed, we used tutor-contrib-paragon plugin, I’ll write the exact steps

   • git clone https://github.com/openedx/openedx-tutor-plugins.git
     cd openedx-tutor-plugins/plugins/tutor-contrib-paragon
     pip install -e .
     

   • tutor plugins enable paragon
     

   • tutor images build paragon-builder
     

   • tutor dev do paragon-build-tokens
     

   • After these steps, you’ll notice below structure in your tutor env folder.

     

   • What you’ll do is, you will replace min.css URLs in tutor-indigo plugin.py file as shown in below image as using tutor-contrib-paragon plugin, we can host min.css files of PARAGON_THEMES. As using, localhost URLs, weren’t getting cache issue.

     

   • For development example after following above steps, I have made background color changes for learning MFE in both light & dark theme as an example, then run npm run build, you’ll notice dist folder is created again. And you have some changes in brand-openedx/dist/core.min.css file.

     
     

   • You’ll copy the file content from brand-openedx/dist/core.min.css file and paste it into your tutor_env/env/plugins/paragon/compiled-themes/themes/dark/dark.min.css & tutor_env/env/plugins/paragon/compiled-themes/themes/light/light.min.css files.
     

     

   • And run tutor config save && tutor images build mfe && tutor dev start -d, and changes will apply for learning MFE background color.

     
     

I know the steps could be a bit confusing, But thats what we had followed.

[Mahendra (Mahendra Chaudhari (TitanEd))]

Hi @FarazM

Thank you very much for your detailed response. It was extremely helpful and has given me the right direction for utilizing design tokens effectively. I truly appreciate your guidance.

I will follow your instructions and reach out if I need any further assistance. Thanks again for your support.

Also, could you please let me know if there is any documentation available on how to use brand-openedx, design tokens, and Paragon packages in both local and production environments?

Thanks in advance.

[FarazM (Muhammad Faraz Maqsood)]

Yes, sure. You can reach out if you have any queries.

@Mahendra

could you please let me know if there is any documentation available on how to use brand-openedx, design tokens, and Paragon packages in both local and production environments?

The steps I shared above are what we have right now for documentation OR what I know. And these are for local development.
For production(you don’t need paragon plugin), after you complete the development, you should push the dist folder and replace the links in this piece of code(Link) and also change the brand link/version(Link) if you are customizing something on top of indigo.