Make Indigo theme opt-in instead of opt-out (the current default theme)

[mariajgrimaldi]

Description

Currently, Tutor installs Indigo as the default theme, which makes all sandbox and local installations run with Indigo enabled by default. During the Ulmo release discussions, the BTR and Design Working Groups members raised several concerns about this setup.

The main issues are:

• Design tokens: Indigo does not yet use the new design token system that Paragon 23 supports. This makes it inconsistent with the current theming approach recommended for Open edX MFEs.
• Accessibility: Some concerns were raised that Indigo’s overrides may reduce accessibility compared to the base Paragon components, which are designed to meet accessibility standards.
• Testing and maintenance: Running release testing with Indigo enabled can hide base-style issues in the MFEs, leading to bugs that go unnoticed until later. It also means Indigo’s issues sometimes get reported as platform issues.
• Adopter impact: Most large adopters (edX, MIT, WGU, etc.) do not use Indigo, so making it default gives a false sense of what the platform looks like "out of the box."

Aproach

Make Indigo an optional theme in Tutor instead of the default.

• New Tutor installations should use the default base theme by default.
• During installation or configuration, operators can explicitly opt into Indigo.
• Sandbox testing and release testing should use the default theme to ensure core platform visuals and accessibility work as intended.

Alternatives

• Keeping Indigo as default but disabling it manually in each environment. This adds friction and doesn’t solve the testing consistency issue.
• Waiting for Indigo to be fully updated with design token support before changing the default, but that delays fixing current issues.
• Running separate sandboxes for Indigo and default themes, which could help comparison testing but is heavier to maintain.

Additional Context

• Design WG and Paragon WG are discussing Indigo’s alignment with Paragon 23 and the design token architecture.
• A PR already exists to update Indigo to Paragon 23 compatibility, but it still uses SCSS overrides instead of token-based styling (edly-io/brand-openedx#40). See Slack thread.
• The Ulmo release is planned for Thursday, October 30. If the change cannot be made before then, the release will proceed as before with Indigo as default.
• However, the recommendation of the BTR and attendees of the October 27 meeting is to make Indigo opt-in and run release testing on the default theme.
• This request aims to make Tutor installations reflect that approach and allow theme maintainers to continue improving Indigo independently.

[regisb]

This issue is about two different things:

1. Disabling Indigo in the Ulmo sandbox: this is already the case. After discussing with the BTR, we have disabled the Indigo theme on the sandbox server: https://ulmo.demo.edly.io/ It's as simple as running tutor plugins disable indigo. This is what the platform currently looks like:

(ignore the mention of "teak", this is actually the master branch running)

2. Making Indigo opt-out instead of opt-in: are we revisiting the conversation from last year? What has changed since then? As far as I know the alternative to Indigo (the default theme) is still horrible.

[sdaitzman]

We discussed this at the Paragon WG, and I think it’s worth considering some tradeoffs we noted (some of which came up in response to the initial proposal to apply the Indigo theme by default).

In the interest of facilitating an open discussion about the underlying tradeoffs, I’ll try to summarize a few themes I’ve heard:

1. Open edX / Paragon has base styles, which are not a theme

The base styles are minimal visual styling intended to pair with specific Paragon components. Paragon components are maintained alongside base styling, and should be tuned to work well out-of-box for Open edX. Their use in the default-configured platform should match the doc site. Themes applied on top of the base styles should not have to fix UI issues, they should be able to focus primarily on branding.

2. Indigo is currently architected as overrides, not primarily a set of tokens

Based on discussion at Paragon WG yesterday, my understanding is that the Indigo design token support PR applies overrides that reference underlying base style design tokens. From a thread in #wg-build-test-release:

With design tokens, theme styles are defined as tokens (either in .json or .toml) and then deep merged with base tokens before they are processed, transformed, and formatted into .css (or other formats such as those used for Android and iOS apps).

The PR updating Indigo still defines styles in .scss, and directly imports base .scss used by Paragon components.

This is not a supported/encouraged/best-practice theming approach, and should not be applied by default.

3. Some improvements in Indigo should be applied to base styles

Indigo makes major improvements in layout and visual hierarchy. Some of these improvements should be brought into the base styles, which are due for modernization. Themes should be primarily oriented around theming, not fixing UI issues or making layout/functional adjustments. Applying a specific theme on top of the base styles by default obscures these issues, including in testing:

4. Testing and/or releasing on a theme will obscure some issues

Applying a default theme layer that overrides some (but not all) base styles adds an additional layer of complexity and burden to Paragon, MFE, and theme maintainers. Frontend UI issues may be missed in the base styles because they are caused by base styles, but Indigo fixes them.

5. Core platform features developed with the base styles may have compatibility issues with Indigo

New feature areas like Content Libraries have been AC-tested using Open edX base styles, and should ideally work with all themes. A theme that is developed as a set of base design token overrides that can be deep-merged with the original design tokens should handle new features like this more gracefully.

Building and testing with only the base styles ensures that themes should primarily affect branding/colors/general look-and-feel, and generally tend to support new features more easily. We’ve seen some compatibility issues with Indigo and Content Libraries. These individual issues can be patched with additional hardcoded overrides in Indigo, but this theming approach requires constant maintenance burden for all theme maintainers.

---

At a visual level, there are major improvements in Indigo that are worth applying to the base styles. I think there are issues worth resolving within both base styles and Indigo, including Indigo theme accessibility issues like unclear :hover/:active/:focus states.

I want to give consideration to those improvements, and also make sure we are making platform default-install decisions guided by community input. There’s another brief discussion about this planned for next week at the Design Working Group, and I hope we can have an open community conversation about this to move toward resolving some of these long-running questions.

[mariajgrimaldi]

Based on the points raised here and in the Paragon WG discussion, it seems we share similar concerns and priorities:

• Release testing should confirm that the base MFEs and styles work correctly out of the box, without relying on a theme.
• Indigo provides visual improvements, but since it’s currently implemented through style overrides rather than design token extensions, it can mask issues in the base styles that we should surface and fix upstream.
• Some of Indigo’s layout and hierarchy improvements could be moved into the base styles, allowing themes to focus mainly on branding.
• The ongoing Indigo update for Paragon 23 and the discussions in the Design and Paragon working groups are good next steps to align on the theming direction.

As next steps, we could:

1. Use the Ulmo release to decide whether Indigo should stay optional for now.
2. Continue the discussion here after the Design WG meeting on November 6, once there’s more context from that review.
3. Revisit this for Ulmo.1 / Verawood, aiming for a clearer plan around theming, design tokens, and testing practices.

Does this approach sound reasonable for now? What do you think, @regisb @ahmed-arb?

[regisb]

Thanks for the detailed comment @sdaitzman! I'm looking forward to a detailed discussion with the design working group.

Prior to this meeting I'd like to note the following items:

1. What you are asking is not to make Indigo "optional", but whether it should be opt-in or opt-out. Indigo is already optional. It is currently opt-out. You are suggesting that it is opt-in. I will edit the title of this issue to reflect that.
2. Branding is not theming: design tokens allow us to modify variable values, and that's branding. Theming involves changing some visual elements, as you noted. Indigo is a theme, not a brand. It is crucial that Open edX enables theming, which is required by basically all our clients. Currently, design tokens are not sufficient to enable theming, as I have noted multiple times in different meetings with stakeholders.
3. The default theme (not brand) is terrible. Making Indigo opt-in would mean that the user experience is terrible by default.
4. It is only very recently that the team behind tokens has considered the implications of their work on Indigo. My personal feeling is that the team has worked so far with the assumption that it would be the role of the Indigo team to catch up with the work of the frontend design team. I have tried multiple times to alert the frontend design working group that design tokens would not help Indigo in any way. My alerts have been completely ignored. I wish the frontend design working group had more considerations for downstream users and the maintainers of the most popular Open edX extension out there, and the only production-ready, free and open source theme available on the market. I'm looking forward to creative solutions that will come from the working group on how to improve Indigo.

As next steps, we could:

1. Use the Ulmo release to decide whether Indigo should stay optional for now.
2. Continue the discussion here after the Design WG meeting on November 6, once there’s more context from that review.
3. Revisit this for Ulmo.1 / Verawood, aiming for a clearer plan around theming, design tokens, and testing practices.

@mariajgrimaldi yes, I agree with your suggestions -- with the caveat that "optional" is not the right word here. Step 1 should be to decide whether Indigo remains opt-out. My position is that yes, it should, as long as the default theme is terrible (and it still is in Ulmo). I will join the Nov. 6 meeting.