[DEPR] Branding without design tokens

[brian-smith-tcril]

RFC Start Date

2024-07-19

Target Plan Accepted Date

2024-08-02

Target Transition Unblocked Date

2025-05-22

Earliest Breaking Changes Unblocked Date

2025-06-18

Earliest Open edX Named Release Without This Functionality

Ulmo - 2025-05

Rationale

https://github.com/openedx/paragon/blob/master/docs/decisions/0019-scaling-styles-with-design-tokens.rst
https://github.com/openedx/paragon/tree/alpha?tab=readme-ov-file#design-tokens

Removal

from https://github.com/openedx/paragon/blob/master/docs/decisions/0019-scaling-styles-with-design-tokens.rst#implications-for-theme-authors-eg-edxbrand-packages

Currently, theme authors largely modify SCSS variables from core Paragon by creating a _variables.scss file and importing it after the core Paragon SCSS styles in consuming applications (e.g., micro-frontends). Doing so, SCSS will override the original variables' values defined by core Paragon with the new SCSS from the @edx/brand theme.

Replacement

• See Also: Implications for Theme Authors

With design tokens, theme authors will instead override core Paragon tokens by defining their own JSON tokens that get deep merged alongside the core Paragon tokens, thus overriding any tokens that were defined by the theme author.

• Note: Existing themes packages will not work once this change has landed, see the Migration section for how to migrate.

Deprecation

There is no plan to mark the code for deprecation. This will be a one time switch.

Migration

There are plans to create a how-to document for migrating existing brand packages to design tokens, as well as discussions being had around building out automated tooling to assist in the process.

As of writing, the following information is available:

• Theming With Design Tokens
• Compiling CSS from design tokens (Paragon readme)
• Implications for theme authors (Paragon ADR)
• Comparisons between design tokens (Paragon design tokens directory) and pre-design tokens Paragon styles (Paragon scss directory)
• Comparisons between brand-edx.org design tokens and brand-edx.org scss.
• docs: create how to work with design tokens #26

Additional Info

No response

Task List

There are 3 main phases:

1. frontend-platform documentation (step by step guide to migration)
2. mfe upgrades - upgrade every MFE to use design tokens
3. tooling for tutor - tooling for building and hosting CSS variables

Additionally work has already been done to upgrade paragon to support design tokens, and frontend-app-discussions has been built on a pilot branch to use design tokens, proving out the system.

These MFEs are considered out of scope for the conversion:

openedx/frontend-app-admin-portal
openedx/frontend-app-enterprise-public-catalog
openedx/frontend-app-learner-portal-enterprise
openedx/frontend-enterprise
openedx/frontend-app-learner-portal-programs
openedx/frontend-app-ecommerce
openedx/frontend-app-payment
openedx/frontend-component-ai-translations
openedx/frontend-app-shell

[brian-smith-tcril]

The comment period has ended. In Teak pre-design-tokens brand packages will no longer be supported.

[robrap]

[inform/request] This ticket was accepted under the old DEPR process. The updated Process States in OEP-21 help add clarity to communications and timing regarding the introduction of breaking changes. This ticket must move to Transition Unblocked before moving to Breaking Changes Unblocked. The default minimum time to wait in Transition Unblocked is 1 month, so early deployers have time to prepare. If you wish to make breaking changes in less than 1 month, please initiate discussions to negotiate a date as soon as possible. Thank you!

[sarina]

Pulling in @adamstankiewicz here. I believe 2U is prepared already for this transition. I have seen the Elm theme working with Design Tokens.

[brian-smith-tcril]

The Transition Unblocked documentation states

Both old and new implementations operate in parallel

I'd like clarification on this. I believe the master-design-tokens branches of MFEs satisfy this requirement, as site operators can deploy those branches instead of deploying from the MFE master branches before we (simultaneously) land all of the master-design-tokens branches on the MFE master branches.

This doesn't quite fit with

Feature flags/toggles control which implementation is active

but I believe in this scenario configuring a deploy process to use different branches of MFEs effectively provides site operators the ability to "control which implementation is active."

[robrap]

@brian-smith-tcril:

1. I'll try to get someone on this ticket to ensure your understanding that those branches are enough. My understanding is that is the best that can be done for this.
2. Let's assume it does, and you are ready for Transition Unblocked. Do you have a clear date in mind for the breaking changes? Is that in less than a month or more than a month?
   Thank you.