[DEPR] Branding without design tokens

[brian-smith-tcril]

Proposal Date

2024-07-19

Target Ticket Acceptance Date

2024-08-02

Earliest Open edX Named Release Without This Functionality

Teak - 2025-01

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

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

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.

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:

• 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.

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.